feat: adopt directory-based docs versioning with Edge channel (#6202)

* feat: adopt directory-based docs versioning with Edge channel

Switch docs.crewai.com from navigation-only versioning (every version
selector entry rendered the same docs/<lang>/* source files) to
Mintlify's directory-based versioning so each version selector entry
renders its own snapshot. Add an "Edge" channel under docs/edge/<lang>/*
that always reflects main HEAD for unreleased work, eliminating
pre-release leakage onto frozen release labels. External links to
canonical /<lang>/* URLs are preserved via wildcard redirects that
always land on the current default version.

Layout:
- docs/edge/<lang>/*         rolling source (you edit here)
- docs/edge/enterprise-api.*.yaml
- docs/v<X.Y.Z>/<lang>/*     frozen, immutable snapshots
- docs/v<X.Y.Z>/enterprise-api.*.yaml
- docs/images/               shared, append-only
- docs/docs.json             nav + redirects

URLs follow the Mintlify-idiomatic shape: /edge/<lang>/<page> for
Edge, /v<X.Y.Z>/<lang>/<page> for every frozen snapshot. The wildcard
redirects /<lang>/:slug* -> /<default>/<lang>/:slug* keep stale links
working, and every freeze rewrites them (plus all per-section/per-page
redirects) so destinations always resolve to the current default
without depending on a second redirect hop.

Release flow integration (devtools release):
- New module crewai_devtools.docs_versioning.freeze() materialises
  docs/v<X.Y.Z>/ from docs/edge/, rewrites openapi: refs inside the
  snapshot, inserts the version into every language block in
  docs.json, and refreshes all redirect destinations.
- _update_docs_and_create_pr() in cli.py now calls that freeze during
  Phase 2 of devtools release. Edge changelogs are updated first (so
  the snapshot freeze picks them up), then the snapshot is staged
  alongside docs.json, branched as docs/freeze-v<X.Y.Z>, and the PR
  is titled [docs-freeze] docs: snapshot and changelog for v<X.Y.Z>
  — the title prefix the new CI guard reads.
- The PR still gates tag, GitHub release, PyPI publish, and the
  enterprise release as before; no new PRs are added.
- Pre-releases (1.X.YaN, 1.X.YbN, ...) skip the snapshot — they ride
  Edge — and the docs PR title omits the [docs-freeze] prefix.
- docs_check (AI-generated docs scaffolding) writes to
  docs/edge/<lang>/* so newly-generated unreleased docs land in Edge
  and never accidentally touch a frozen snapshot.

Migration scripts (one-shot):
- scripts/docs/freeze_historical_versions.py reconstructs all 16
  historical snapshots (v1.10.0 .. v1.14.7) from git tags via
  git archive | tar, rewriting openapi: MDX refs so each snapshot
  reads its own enterprise-api YAML rather than the live one.
- scripts/docs/prefix_version_paths.py one-shot-migrates docs.json:
  rewrites every page path in 16 versioned blocks to point under
  docs/v<X.Y.Z>/, inserts a new Edge entry per language, tags
  v1.14.7 as Latest (default), prunes pages whose target file
  doesn't exist in the snapshot (e.g. docs/ar/ didn't exist before
  v1.12.0), and writes the wildcard + per-section redirects.
- scripts/docs/freeze_current_edge.py is now a thin CLI wrapper
  around docs_versioning.freeze for manual one-off freezes (e.g.
  retroactively snapshotting a forgotten release).

CI guards (.github/workflows/docs-snapshots.yml):
- Frozen snapshots under docs/v[0-9]*/ are immutable; only PRs whose
  title contains [docs-freeze] (i.e. release-cut PRs generated by
  devtools release or the manual wrapper) may modify them.
- Images under docs/images/ are append-only since snapshots share a
  single image directory. Deleting or renaming an image breaks every
  historical snapshot that still references it.

Restored docs/images/crewai-otel-export.png from PR #3673; it was
deleted in PR #4908 but v1.10.0 / v1.10.1 snapshots still reference
it. Restoring instead of editing the snapshots preserves historical
rendering fidelity and validates the new append-only rule
retroactively.

Tests:
- lib/devtools/tests/test_docs_versioning.py covers the freeze: file
  copy, openapi rewrite, version insertion, default demotion, redirect
  upserts, per-section redirect rewriting, idempotency, and invalid
  inputs.

Verified locally with mintlify broken-links: 0 broken links across
the full site (Edge + 16 frozen versions, 4 locales).

AGENTS.md (repo root) is the contributor guide for the new model;
RELEASING.md is the release-cut runbook; README's Contribution
section links to both.

Co-authored-by: Cursor <cursoragent@cursor.com>

* style: resolve linter issues

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

AGENTS.md

@@ -0,0 +1,142 @@
+# Docs contributor guide
+
+The `docs/` directory is published at [docs.crewai.com](https://docs.crewai.com)
+by [Mintlify](https://www.mintlify.com/). 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](#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:
+
+```jsonc
+{ "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`](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/`:
+
+```bash
+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:
+
+```bash
+mintlify broken-links
+```
+
+CI runs the broken-links check on every PR that touches `docs/**` via
+[`.github/workflows/docs-broken-links.yml`](.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`](.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`](.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.

README.md

@@ -601,6 +601,19 @@ CrewAI is open-source and we welcome contributions. If you're looking to contrib
 - Send a pull request.
 - We appreciate your input!
 
+### Contributing to the docs
+
+The site at [docs.crewai.com](https://docs.crewai.com) is published from
+`docs/` by [Mintlify](https://www.mintlify.com/). The docs use directory-based
+versioning: edits to `docs/edge/<lang>/...` (e.g.
+`docs/edge/en/concepts/agents.mdx`) land under the **Edge** version selector
+immediately and are frozen into a new versioned snapshot under
+`docs/v<X.Y.Z>/` at the next release cut. Frozen snapshots are immutable — CI
+rejects PRs that modify them without a `[docs-freeze]` title prefix. The
+release CLI (`devtools release`) handles the freeze automatically; see
+[`AGENTS.md`](AGENTS.md) for the full contributor guide and
+[`RELEASING.md`](RELEASING.md) for the release-cut runbook.
+
 ### Installing Dependencies
 
 ```bash