crewAI/AGENTS.md

Docs contributor guide

The docs/ directory is published at docs.crewai.com by Mintlify. Mintlify watches docs/docs.json and the MDX files referenced from it.

TL;DR for editing docs

• Edit MDX under docs/edge/<lang>/... (e.g. docs/edge/en/concepts/agents.mdx).
• Your change ships under the Edge version selector the moment it merges to main. Edge follows main and is the channel for unreleased work.
• On release cut, the current Edge state is frozen into docs/v<X.Y.Z>/ and that snapshot becomes the new default version in the selector (tag: Latest). Canonical URLs (/<lang>/...) auto-redirect to the new default.
• Never modify files under docs/v*/. Those are frozen release snapshots and the docs-snapshots CI guard rejects writes. The only exception is a release-cut PR (auto-generated by devtools release or the manual scripts/docs/freeze_current_edge.py wrapper), which uses a [docs-freeze] title prefix to opt out.
• Never delete or rename files under docs/images/. Images are append-only. See Images below.

The version model

The site has one rolling channel (Edge) plus one frozen snapshot per release.

docs/
  edge/                  <-- Edge sources (you edit here)
    en/...
    pt-BR/  ko/  ar/
    enterprise-api.*.yaml

  v1.14.7/               <-- frozen snapshot of v1.14.7
    en/...
    pt-BR/  ko/  ar/
    enterprise-api.*.yaml
  v1.14.6/...
  ...

  images/                <-- shared, append-only
  docs.json              <-- Mintlify config: navigation + redirects

docs/docs.json lists one navigation block per version per language. Edge points at docs/edge/<lang>/...; every other version points at its own docs/v<X.Y.Z>/<lang>/... subtree. Mintlify scopes both the sidebar and the in-site search to whichever version the reader selects, so picking v1.10.0 genuinely shows the v1.10.0 docs (and only those).

URLs and canonical redirects

Each Mintlify version corresponds to its own URL prefix:

• Edge: /edge/<lang>/<page> (e.g. /edge/en/concepts/agents)
• Frozen: /v<X.Y.Z>/<lang>/<page> (e.g. /v1.14.7/en/concepts/agents)

External links to the old, unversioned /<lang>/<page> URLs would 404 under this layout. To keep them working, docs.json ships wildcard redirects:

{ "source": "/en/:slug*", "destination": "/v1.14.7/en/:slug*", "permanent": false }

The release-cut step rewrites the destination on every release so canonical /<lang>/... URLs always resolve to the latest stable docs.

Lifecycle

1. During development. You add or edit pages under docs/edge/<lang>/... in normal PRs. They land in Edge as soon as the PR merges. Both /edge/<lang>/<page> and the version selector's Edge entry reflect the change immediately.
2. Release cut. The release engineer runs devtools release X.Y.Z. As part of that flow the CLI opens a [docs-freeze] PR that copies Edge into docs/v<X.Y.Z>/, rewrites internal OpenAPI references, updates docs/docs.json to make v<X.Y.Z> the new default + Latest, and rewires the canonical-URL redirects to the new default. The PR must merge before the tag and PyPI publish run.
3. After release. Edge keeps rolling. Patch fixes to the just-released docs go into Edge and ship with the next release. We do not back-edit frozen snapshots.

See RELEASING.md for the full release runbook.

Images

Snapshots share a single docs/images/ directory. If an image is deleted or renamed, every frozen snapshot that referenced it breaks. So the rule is:

• Adding new images is always fine.
• Deleting or renaming an existing image fails CI unless the PR is a [docs-freeze] release-cut PR.
• If an asset is wrong, add a new file with a new name and reference the new name in the Edge MDX (docs/edge/<lang>/...). Leave the old file alone.

Local preview

Install the Mintlify CLI and run from docs/:

npm i -g mintlify
mintlify dev

Use the version selector at the top of the rendered page to switch between Edge and frozen versions.

To check links across every version:

mintlify broken-links

CI runs the broken-links check on every PR that touches docs/** via .github/workflows/docs-broken-links.yml.

Scripts

• scripts/docs/freeze_historical_versions.py — one-time migration that reconstructed docs/v1.10.0/ through docs/v1.14.7/ from git tags. You should not need to run this again.
• scripts/docs/prefix_version_paths.py — one-time migration that switched docs/docs.json to directory-based versioning, inserted Edge, and added the canonical-URL redirects. You should not need to run this again.
• scripts/docs/freeze_current_edge.py — thin CLI wrapper around crewai_devtools.docs_versioning.freeze. devtools release calls the same module during its docs PR step; this script is the manual escape hatch (e.g. retroactively freezing a forgotten release).

CI guards

• .github/workflows/docs-snapshots.yml enforces the two rules above (frozen snapshots immutable, images append-only). Both checks accept the [docs-freeze] PR-title escape hatch.
• .github/workflows/docs-broken-links.yml runs mintlify broken-links against the whole site, so adding a new page or moving a snapshot file that breaks a link will fail CI.