Skip to content

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

Merged
Lucas Gomide (lucasgomide) merged 3 commits into
mainfrom
luzk/docs-versioning-snapshots
Jun 17, 2026
Merged

Lucas Gomide (lucasgomide) merged 3 commits into
mainfrom
luzk/docs-versioning-snapshots

Conversation

@lucasgomide

@lucasgomide Lucas Gomide (lucasgomide) commented Jun 17, 2026 •

Copy link
Copy Markdown
Contributor

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

Layout:

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

Note

Low Risk
Documentation-only changes with no runtime or auth impact; risk is limited to contributor guidance accuracy.

Overview
Adds contributor documentation for the new Mintlify layout: edit only docs/edge/<lang>/..., freeze snapshots under docs/v<X.Y.Z>/ at release cut, keep docs/images/ append-only, and use [docs-freeze] / devtools release for the freeze PR. AGENTS.md is new and covers the version model, URL prefixes, canonical /<lang>/... redirects in docs.json, lifecycle, local mintlify preview, migration scripts, and CI (docs-snapshots, docs-broken-links).

README.md gains a Contributing to the docs subsection under Contribution that points readers to AGENTS.md and RELEASING.md for the same Edge vs frozen rules.

Reviewed by Cursor Bugbot for commit 399f761. Bugbot is set up for automated code reviews on this repo. Configure here.

@coderabbitai

coderabbitai Bot commented Jun 17, 2026 •

Copy link
Copy Markdown

Important

Review skipped

Too many files!

This PR contains 300 files, which is 150 over the limit of 150.

To get a review, narrow the scope:
• coderabbit review --type committed # exclude uncommitted changes
• coderabbit review --dir # limit to a subdirectory
• coderabbit review --base # compare against a closer base

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 86ced0bc-ea23-40f5-956d-89434a60ce2f

📥 Commits

Reviewing files that changed from the base of the PR and between d3c37c4 and 399f761.

📒 Files selected for processing (300)
  • AGENTS.md
  • README.md
  • docs/docs.json
  • docs/edge/ar/api-reference/inputs.mdx
  • docs/edge/ar/api-reference/introduction.mdx
  • docs/edge/ar/api-reference/kickoff.mdx
  • docs/edge/ar/api-reference/resume.mdx
  • docs/edge/ar/api-reference/status.mdx
  • docs/edge/ar/changelog.mdx
  • docs/edge/ar/concepts/agent-capabilities.mdx
  • docs/edge/ar/concepts/agents.mdx
  • docs/edge/ar/concepts/checkpointing.mdx
  • docs/edge/ar/concepts/cli.mdx
  • docs/edge/ar/concepts/collaboration.mdx
  • docs/edge/ar/concepts/crews.mdx
  • docs/edge/ar/concepts/event-listener.mdx
  • docs/edge/ar/concepts/files.mdx
  • docs/edge/ar/concepts/flows.mdx
  • docs/edge/ar/concepts/knowledge.mdx
  • docs/edge/ar/concepts/llms.mdx
  • docs/edge/ar/concepts/memory.mdx
  • docs/edge/ar/concepts/planning.mdx
  • docs/edge/ar/concepts/processes.mdx
  • docs/edge/ar/concepts/production-architecture.mdx
  • docs/edge/ar/concepts/reasoning.mdx
  • docs/edge/ar/concepts/skills.mdx
  • docs/edge/ar/concepts/tasks.mdx
  • docs/edge/ar/concepts/testing.mdx
  • docs/edge/ar/concepts/tools.mdx
  • docs/edge/ar/concepts/training.mdx
  • docs/edge/ar/enterprise/features/agent-control-plane/monitoring.mdx
  • docs/edge/ar/enterprise/features/agent-control-plane/overview.mdx
  • docs/edge/ar/enterprise/features/agent-control-plane/rules.mdx
  • docs/edge/ar/enterprise/features/agent-repositories.mdx
  • docs/edge/ar/enterprise/features/automations.mdx
  • docs/edge/ar/enterprise/features/crew-studio.mdx
  • docs/edge/ar/enterprise/features/flow-hitl-management.mdx
  • docs/edge/ar/enterprise/features/hallucination-guardrail.mdx
  • docs/edge/ar/enterprise/features/marketplace.mdx
  • docs/edge/ar/enterprise/features/pii-trace-redactions.mdx
  • docs/edge/ar/enterprise/features/rbac.mdx
  • docs/edge/ar/enterprise/features/secrets-manager/aws-workload-identity.mdx
  • docs/edge/ar/enterprise/features/secrets-manager/aws.mdx
  • docs/edge/ar/enterprise/features/secrets-manager/azure-workload-identity.mdx
  • docs/edge/ar/enterprise/features/secrets-manager/azure.mdx
  • docs/edge/ar/enterprise/features/secrets-manager/gcp-workload-identity.mdx
  • docs/edge/ar/enterprise/features/secrets-manager/gcp.mdx
  • docs/edge/ar/enterprise/features/secrets-manager/overview.mdx
  • docs/edge/ar/enterprise/features/secrets-manager/usage.mdx
  • docs/edge/ar/enterprise/features/secrets-manager/verify-rotation.mdx
  • docs/edge/ar/enterprise/features/tools-and-integrations.mdx
  • docs/edge/ar/enterprise/features/traces.mdx
  • docs/edge/ar/enterprise/features/webhook-streaming.mdx
  • docs/edge/ar/enterprise/guides/automation-triggers.mdx
  • docs/edge/ar/enterprise/guides/azure-openai-setup.mdx
  • docs/edge/ar/enterprise/guides/build-crew.mdx
  • docs/edge/ar/enterprise/guides/capture_telemetry_logs.mdx
  • docs/edge/ar/enterprise/guides/custom-mcp-server.mdx
  • docs/edge/ar/enterprise/guides/deploy-to-amp.mdx
  • docs/edge/ar/enterprise/guides/enable-crew-studio.mdx
  • docs/edge/ar/enterprise/guides/gmail-trigger.mdx
  • docs/edge/ar/enterprise/guides/google-calendar-trigger.mdx
  • docs/edge/ar/enterprise/guides/google-drive-trigger.mdx
  • docs/edge/ar/enterprise/guides/hubspot-trigger.mdx
  • docs/edge/ar/enterprise/guides/human-in-the-loop.mdx
  • docs/edge/ar/enterprise/guides/kickoff-crew.mdx
  • docs/edge/ar/enterprise/guides/microsoft-teams-trigger.mdx
  • docs/edge/ar/enterprise/guides/monorepo-deployments.mdx
  • docs/edge/ar/enterprise/guides/onedrive-trigger.mdx
  • docs/edge/ar/enterprise/guides/outlook-trigger.mdx
  • docs/edge/ar/enterprise/guides/prepare-for-deployment.mdx
  • docs/edge/ar/enterprise/guides/private-package-registry.mdx
  • docs/edge/ar/enterprise/guides/react-component-export.mdx
  • docs/edge/ar/enterprise/guides/salesforce-trigger.mdx
  • docs/edge/ar/enterprise/guides/slack-trigger.mdx
  • docs/edge/ar/enterprise/guides/team-management.mdx
  • docs/edge/ar/enterprise/guides/tool-repository.mdx
  • docs/edge/ar/enterprise/guides/training-crews.mdx
  • docs/edge/ar/enterprise/guides/update-crew.mdx
  • docs/edge/ar/enterprise/guides/webhook-automation.mdx
  • docs/edge/ar/enterprise/guides/zapier-trigger.mdx
  • docs/edge/ar/enterprise/integrations/asana.mdx
  • docs/edge/ar/enterprise/integrations/box.mdx
  • docs/edge/ar/enterprise/integrations/clickup.mdx
  • docs/edge/ar/enterprise/integrations/databricks.mdx
  • docs/edge/ar/enterprise/integrations/github.mdx
  • docs/edge/ar/enterprise/integrations/gmail.mdx
  • docs/edge/ar/enterprise/integrations/google_calendar.mdx
  • docs/edge/ar/enterprise/integrations/google_contacts.mdx
  • docs/edge/ar/enterprise/integrations/google_docs.mdx
  • docs/edge/ar/enterprise/integrations/google_drive.mdx
  • docs/edge/ar/enterprise/integrations/google_sheets.mdx
  • docs/edge/ar/enterprise/integrations/google_slides.mdx
  • docs/edge/ar/enterprise/integrations/hubspot.mdx
  • docs/edge/ar/enterprise/integrations/jira.mdx
  • docs/edge/ar/enterprise/integrations/linear.mdx
  • docs/edge/ar/enterprise/integrations/microsoft_excel.mdx
  • docs/edge/ar/enterprise/integrations/microsoft_onedrive.mdx
  • docs/edge/ar/enterprise/integrations/microsoft_outlook.mdx
  • docs/edge/ar/enterprise/integrations/microsoft_sharepoint.mdx
  • docs/edge/ar/enterprise/integrations/microsoft_teams.mdx
  • docs/edge/ar/enterprise/integrations/microsoft_word.mdx
  • docs/edge/ar/enterprise/integrations/notion.mdx
  • docs/edge/ar/enterprise/integrations/salesforce.mdx
  • docs/edge/ar/enterprise/integrations/shopify.mdx
  • docs/edge/ar/enterprise/integrations/slack.mdx
  • docs/edge/ar/enterprise/integrations/snowflake.mdx
  • docs/edge/ar/enterprise/integrations/stripe.mdx
  • docs/edge/ar/enterprise/integrations/zendesk.mdx
  • docs/edge/ar/enterprise/introduction.mdx
  • docs/edge/ar/enterprise/resources/frequently-asked-questions.mdx
  • docs/edge/ar/examples/cookbooks.mdx
  • docs/edge/ar/examples/example.mdx
  • docs/edge/ar/guides/advanced/customizing-prompts.mdx
  • docs/edge/ar/guides/advanced/fingerprinting.mdx
  • docs/edge/ar/guides/agents/crafting-effective-agents.mdx
  • docs/edge/ar/guides/coding-tools/agents-md.mdx
  • docs/edge/ar/guides/coding-tools/build-with-ai.mdx
  • docs/edge/ar/guides/concepts/evaluating-use-cases.mdx
  • docs/edge/ar/guides/crews/first-crew.mdx
  • docs/edge/ar/guides/flows/conversational-flows.mdx
  • docs/edge/ar/guides/flows/first-flow.mdx
  • docs/edge/ar/guides/flows/inputs-id-deprecation.mdx
  • docs/edge/ar/guides/flows/mastering-flow-state.mdx
  • docs/edge/ar/guides/migration/migrating-from-langgraph.mdx
  • docs/edge/ar/guides/migration/upgrading-crewai.mdx
  • docs/edge/ar/guides/tools/publish-custom-tools.mdx
  • docs/edge/ar/index.mdx
  • docs/edge/ar/installation.mdx
  • docs/edge/ar/introduction.mdx
  • docs/edge/ar/learn/a2a-agent-delegation.mdx
  • docs/edge/ar/learn/before-and-after-kickoff-hooks.mdx
  • docs/edge/ar/learn/bring-your-own-agent.mdx
  • docs/edge/ar/learn/coding-agents.mdx
  • docs/edge/ar/learn/conditional-tasks.mdx
  • docs/edge/ar/learn/create-custom-tools.mdx
  • docs/edge/ar/learn/custom-llm.mdx
  • docs/edge/ar/learn/custom-manager-agent.mdx
  • docs/edge/ar/learn/customizing-agents.mdx
  • docs/edge/ar/learn/dalle-image-generation.mdx
  • docs/edge/ar/learn/execution-hooks.mdx
  • docs/edge/ar/learn/force-tool-output-as-result.mdx
  • docs/edge/ar/learn/hierarchical-process.mdx
  • docs/edge/ar/learn/human-feedback-in-flows.mdx
  • docs/edge/ar/learn/human-in-the-loop.mdx
  • docs/edge/ar/learn/human-input-on-execution.mdx
  • docs/edge/ar/learn/kickoff-async.mdx
  • docs/edge/ar/learn/kickoff-for-each.mdx
  • docs/edge/ar/learn/litellm-removal-guide.mdx
  • docs/edge/ar/learn/llm-connections.mdx
  • docs/edge/ar/learn/llm-hooks.mdx
  • docs/edge/ar/learn/llm-selection-guide.mdx
  • docs/edge/ar/learn/multimodal-agents.mdx
  • docs/edge/ar/learn/overview.mdx
  • docs/edge/ar/learn/replay-tasks-from-latest-crew-kickoff.mdx
  • docs/edge/ar/learn/sequential-process.mdx
  • docs/edge/ar/learn/streaming-crew-execution.mdx
  • docs/edge/ar/learn/streaming-flow-execution.mdx
  • docs/edge/ar/learn/tool-hooks.mdx
  • docs/edge/ar/learn/using-annotations.mdx
  • docs/edge/ar/mcp/dsl-integration.mdx
  • docs/edge/ar/mcp/multiple-servers.mdx
  • docs/edge/ar/mcp/overview.mdx
  • docs/edge/ar/mcp/security.mdx
  • docs/edge/ar/mcp/sse.mdx
  • docs/edge/ar/mcp/stdio.mdx
  • docs/edge/ar/mcp/streamable-http.mdx
  • docs/edge/ar/observability/arize-phoenix.mdx
  • docs/edge/ar/observability/braintrust.mdx
  • docs/edge/ar/observability/datadog.mdx
  • docs/edge/ar/observability/galileo.mdx
  • docs/edge/ar/observability/langdb.mdx
  • docs/edge/ar/observability/langfuse.mdx
  • docs/edge/ar/observability/langtrace.mdx
  • docs/edge/ar/observability/maxim.mdx
  • docs/edge/ar/observability/mlflow.mdx
  • docs/edge/ar/observability/neatlogs.mdx
  • docs/edge/ar/observability/openlit.mdx
  • docs/edge/ar/observability/opik.mdx
  • docs/edge/ar/observability/overview.mdx
  • docs/edge/ar/observability/patronus-evaluation.mdx
  • docs/edge/ar/observability/portkey.mdx
  • docs/edge/ar/observability/tracing.mdx
  • docs/edge/ar/observability/truefoundry.mdx
  • docs/edge/ar/observability/weave.mdx
  • docs/edge/ar/quickstart.mdx
  • docs/edge/ar/skills.mdx
  • docs/edge/ar/snippets/snippet-intro.mdx
  • docs/edge/ar/telemetry.mdx
  • docs/edge/ar/tools/ai-ml/aimindtool.mdx
  • docs/edge/ar/tools/ai-ml/codeinterpretertool.mdx
  • docs/edge/ar/tools/ai-ml/dalletool.mdx
  • docs/edge/ar/tools/ai-ml/daytona.mdx
  • docs/edge/ar/tools/ai-ml/langchaintool.mdx
  • docs/edge/ar/tools/ai-ml/llamaindextool.mdx
  • docs/edge/ar/tools/ai-ml/overview.mdx
  • docs/edge/ar/tools/ai-ml/ragtool.mdx
  • docs/edge/ar/tools/ai-ml/visiontool.mdx
  • docs/edge/ar/tools/automation/apifyactorstool.mdx
  • docs/edge/ar/tools/automation/composiotool.mdx
  • docs/edge/ar/tools/automation/multiontool.mdx
  • docs/edge/ar/tools/automation/overview.mdx
  • docs/edge/ar/tools/automation/zapieractionstool.mdx
  • docs/edge/ar/tools/cloud-storage/bedrockkbretriever.mdx
  • docs/edge/ar/tools/cloud-storage/overview.mdx
  • docs/edge/ar/tools/cloud-storage/s3readertool.mdx
  • docs/edge/ar/tools/cloud-storage/s3writertool.mdx
  • docs/edge/ar/tools/database-data/mongodbvectorsearchtool.mdx
  • docs/edge/ar/tools/database-data/mysqltool.mdx
  • docs/edge/ar/tools/database-data/nl2sqltool.mdx
  • docs/edge/ar/tools/database-data/overview.mdx
  • docs/edge/ar/tools/database-data/pgsearchtool.mdx
  • docs/edge/ar/tools/database-data/qdrantvectorsearchtool.mdx
  • docs/edge/ar/tools/database-data/singlestoresearchtool.mdx
  • docs/edge/ar/tools/database-data/snowflakesearchtool.mdx
  • docs/edge/ar/tools/database-data/weaviatevectorsearchtool.mdx
  • docs/edge/ar/tools/file-document/csvsearchtool.mdx
  • docs/edge/ar/tools/file-document/directoryreadtool.mdx
  • docs/edge/ar/tools/file-document/directorysearchtool.mdx
  • docs/edge/ar/tools/file-document/docxsearchtool.mdx
  • docs/edge/ar/tools/file-document/filereadtool.mdx
  • docs/edge/ar/tools/file-document/filewritetool.mdx
  • docs/edge/ar/tools/file-document/jsonsearchtool.mdx
  • docs/edge/ar/tools/file-document/mdxsearchtool.mdx
  • docs/edge/ar/tools/file-document/ocrtool.mdx
  • docs/edge/ar/tools/file-document/overview.mdx
  • docs/edge/ar/tools/file-document/pdf-text-writing-tool.mdx
  • docs/edge/ar/tools/file-document/pdfsearchtool.mdx
  • docs/edge/ar/tools/file-document/txtsearchtool.mdx
  • docs/edge/ar/tools/file-document/xmlsearchtool.mdx
  • docs/edge/ar/tools/integration/bedrockinvokeagenttool.mdx
  • docs/edge/ar/tools/integration/crewaiautomationtool.mdx
  • docs/edge/ar/tools/integration/mergeagenthandlertool.mdx
  • docs/edge/ar/tools/integration/overview.mdx
  • docs/edge/ar/tools/overview.mdx
  • docs/edge/ar/tools/search-research/arxivpapertool.mdx
  • docs/edge/ar/tools/search-research/bravesearchtool.mdx
  • docs/edge/ar/tools/search-research/codedocssearchtool.mdx
  • docs/edge/ar/tools/search-research/databricks-query-tool.mdx
  • docs/edge/ar/tools/search-research/exasearchtool.mdx
  • docs/edge/ar/tools/search-research/githubsearchtool.mdx
  • docs/edge/ar/tools/search-research/linkupsearchtool.mdx
  • docs/edge/ar/tools/search-research/overview.mdx
  • docs/edge/ar/tools/search-research/serpapi-googlesearchtool.mdx
  • docs/edge/ar/tools/search-research/serpapi-googleshoppingtool.mdx
  • docs/edge/ar/tools/search-research/serperdevtool.mdx
  • docs/edge/ar/tools/search-research/tavilyextractortool.mdx
  • docs/edge/ar/tools/search-research/tavilyresearchtool.mdx
  • docs/edge/ar/tools/search-research/tavilysearchtool.mdx
  • docs/edge/ar/tools/search-research/websitesearchtool.mdx
  • docs/edge/ar/tools/search-research/youtubechannelsearchtool.mdx
  • docs/edge/ar/tools/search-research/youtubevideosearchtool.mdx
  • docs/edge/ar/tools/tool-integrations/overview.mdx
  • docs/edge/ar/tools/web-scraping/brightdata-tools.mdx
  • docs/edge/ar/tools/web-scraping/browserbaseloadtool.mdx
  • docs/edge/ar/tools/web-scraping/firecrawlcrawlwebsitetool.mdx
  • docs/edge/ar/tools/web-scraping/firecrawlscrapewebsitetool.mdx
  • docs/edge/ar/tools/web-scraping/firecrawlsearchtool.mdx
  • docs/edge/ar/tools/web-scraping/hyperbrowserloadtool.mdx
  • docs/edge/ar/tools/web-scraping/overview.mdx
  • docs/edge/ar/tools/web-scraping/oxylabsscraperstool.mdx
  • docs/edge/ar/tools/web-scraping/scrapeelementfromwebsitetool.mdx
  • docs/edge/ar/tools/web-scraping/scrapegraphscrapetool.mdx
  • docs/edge/ar/tools/web-scraping/scrapewebsitetool.mdx
  • docs/edge/ar/tools/web-scraping/scrapflyscrapetool.mdx
  • docs/edge/ar/tools/web-scraping/seleniumscrapingtool.mdx
  • docs/edge/ar/tools/web-scraping/serperscrapewebsitetool.mdx
  • docs/edge/ar/tools/web-scraping/spidertool.mdx
  • docs/edge/ar/tools/web-scraping/stagehandtool.mdx
  • docs/edge/en/api-reference/inputs.mdx
  • docs/edge/en/api-reference/introduction.mdx
  • docs/edge/en/api-reference/kickoff.mdx
  • docs/edge/en/api-reference/resume.mdx
  • docs/edge/en/api-reference/status.mdx
  • docs/edge/en/changelog.mdx
  • docs/edge/en/concepts/agent-capabilities.mdx
  • docs/edge/en/concepts/agents.mdx
  • docs/edge/en/concepts/checkpointing.mdx
  • docs/edge/en/concepts/cli.mdx
  • docs/edge/en/concepts/collaboration.mdx
  • docs/edge/en/concepts/crews.mdx
  • docs/edge/en/concepts/event-listener.mdx
  • docs/edge/en/concepts/files.mdx
  • docs/edge/en/concepts/flows.mdx
  • docs/edge/en/concepts/knowledge.mdx
  • docs/edge/en/concepts/llms.mdx
  • docs/edge/en/concepts/memory.mdx
  • docs/edge/en/concepts/planning.mdx
  • docs/edge/en/concepts/processes.mdx
  • docs/edge/en/concepts/production-architecture.mdx
  • docs/edge/en/concepts/reasoning.mdx
  • docs/edge/en/concepts/skills.mdx
  • docs/edge/en/concepts/tasks.mdx
  • docs/edge/en/concepts/testing.mdx
  • docs/edge/en/concepts/tools.mdx
  • docs/edge/en/concepts/training.mdx
  • docs/edge/en/enterprise/features/a2a.mdx
  • docs/edge/en/enterprise/features/agent-control-plane/monitoring.mdx
  • docs/edge/en/enterprise/features/agent-control-plane/overview.mdx
  • docs/edge/en/enterprise/features/agent-control-plane/rules.mdx

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch luzk/docs-versioning-snapshots

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit 93dafe2. Configure here.

Comment thread .github/workflows/docs-snapshots.yml Resolved
@mintlify

mintlify Bot commented Jun 17, 2026 •

Copy link
Copy Markdown

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated (UTC)
crewai 🟢 Ready View Preview Jun 17, 2026, 2:34 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

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>

@lorenzejay Lorenze Jay (lorenzejay) left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

BOOM

@lucasgomide
Lucas Gomide (lucasgomide) merged commit a237eba into main Jun 17, 2026
59 checks passed
@lucasgomide
Lucas Gomide (lucasgomide) deleted the luzk/docs-versioning-snapshots branch June 17, 2026 15:57
Simran Sachdeva (dotslashsimran) added a commit to dotslashsimran/crewAI that referenced this pull request Aug 6, 2026
crewAI adopted directory-based docs versioning with an Edge channel
(crewAIInc#6202) while this PR was open, moving the live docs tree from
docs/en/ to docs/edge/en/. That commit relocated whatever was still
at docs/en/observability/neatlogs.mdx on main at the time, which was
the pre-PR version of this page, none of this PR's improvements had
landed yet.

This carries the PR's actual current state (updated copy, demo
videos, and refreshed screenshots) onto the new docs/edge/en/ path so
it lands on the live docs tree instead of a frozen version snapshot.

No content changes beyond the path move, this is the same page
already reviewed by CodeRabbit and GitHub Copilot on this PR.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants