Sam Julien
3ae761a966
## Summary - remove the retired top-level `docs/` Next app and the disabled docs-sync workflow/script - add `docs -> showcase/shell-docs` as a top-level symlink for `cd docs` muscle memory without restoring the old docs tree - move the docs model allowlist into `showcase/shell-docs/` and retarget docs validation/doctest extraction to shell-docs content - update docs/agent guidance and CI path filters so `docs/` is treated as an alias, not an active separate docs surface - tighten the pre-commit package check so non-package docs/tooling changes do not fan out into the full package matrix ## Validation - `pnpm exec tsx scripts/validate-doc-model-names.ts` - `pnpm exec tsx scripts/doc-tests/extract.ts` - `pnpm exec vitest run scripts/__tests__/validate-doc-model-names.test.ts scripts/doc-tests/__tests__/extract.test.ts showcase/harness/src/cli/eval/scope.test.ts` - `pnpm exec oxlint showcase/harness/src/cli/eval/scope.test.ts scripts/doc-tests/extract.ts` - `git diff --cached --check` before follow-up commit - `test "$(readlink docs)" = "showcase/shell-docs"` - `test -f docs/package.json` - `pnpm exec oxfmt --check .claude/docs/documentation.md .claude/docs/hooks.md AGENTS.md CLAUDE.md CONTRIBUTING.md showcase/shell-docs/README.md` - commit hooks passed ## Notes - historical docs remain recoverable from `archive/docs-save-do-not-prune` and `archive/docs-retired-2026-06-17` - I intentionally left Vercel/project teardown out of this PR; this is repo cleanup only
Shell Docs
showcase/shell-docs is the Next.js app that builds and serves
docs.copilotkit.ai. Author CopilotKit product documentation here, not in the retired
top-level docs/ app.
Run Locally
Shell-docs is a standalone npm-based app. You do not need a root install just to run the docs app locally.
cd showcase/scripts
npm install
cd ../shell-docs
npm install
npm run dev
The local dev server runs on port 3003.
http://localhost:3003
The shell-docs npm lifecycle generates registry, demo-content, setup-content, and search
data before dev, build, and typecheck.
Validate Changes
Run these from showcase/shell-docs:
npm run build
npm run typecheck
npm run test
For repo-level CI parity, prefer Nx when a shell-docs target is available in the current checkout and root dependencies are installed. For normal shell-docs local development, the npm commands above are the canonical path.
Authoring Recipes
Showcase-Driven Framework Docs
Showcase-driven frameworks use docs_mode: generated. The docs are assembled from showcase
registry/generated data, demos, source regions, shared/root MDX, snippets, and sparse
framework overrides.
To update showcase-driven docs:
- Edit the showcase source of truth: manifests, demos, feature coverage, source regions, or registry inputs.
- Edit shared/root MDX only when the change applies across generated frameworks.
- Add sparse framework overrides only for real framework-specific differences.
- Do not hand-edit generated files under
src/data/frameworks/. - Validate routes, sidebar state, search results, snippets, and framework switching.
Authored Framework Docs
Authored frameworks use docs_mode: authored. The framework owns an MDX tree under
src/content/docs/integrations/<docsFolder>/ with a meta.json sidebar.
To update authored docs:
- Check
getDocsFolder()insrc/lib/registry.ts; the URL slug and folder name may differ. - Edit the MDX page under
src/content/docs/integrations/<docsFolder>/. - Update that folder's
meta.jsonwhen adding, removing, or moving pages. - Reuse shared snippets from
src/content/snippets/when content should stay consistent across frameworks. - Validate the framework route, sidebar, search result, and any shared snippet render.
Reference Docs
Edit API reference pages under src/content/reference/.
The v2 reference does not use meta.json; navigation is generated by walking the tree and
reading each page's title and description frontmatter. Only the legacy reference/v1/
tree uses meta.json.
Snippets
Reusable snippets live under src/content/snippets/. Snippets may be rendered by root docs,
authored framework pages, and showcase-driven framework pages, so keep them general unless
the path is intentionally framework-specific.
Frontend Applicability
Frontend routes use page-level applicability metadata, independent from where the content is authored. A page can be authored MDX, showcase-generated content, mirrored protocol docs, or reference content and still be universal across frontends.
Use the frontend field in page frontmatter or meta.json when a root doc should appear in
non-React frontend docs:
universal— render the same page under/frontends/<frontend>/....frontend-variant— render only when a matching page exists undersrc/content/docs/frontends/<frontend>/....hide— omit the page from frontend-scoped docs.
Do not use "showcase-driven" as a proxy for frontend availability. Showcase derivation is an authoring/source detail; frontend applicability controls routing and sidebar inclusion.
AG-UI Mirrored Docs
AG-UI protocol docs are authored upstream in ag-ui-protocol/ag-ui. The
src/content/ag-ui/ tree is a downstream mirror rendered on the CopilotKit docs host.
Change AG-UI docs upstream first, then sync the mirror back into shell-docs.
Top-Level Docs Symlink
The repository's top-level docs/ path is a symlink to showcase/shell-docs/ for
contributor muscle memory. It is not a separate docs app. Do not recreate the old
docs/content/docs/ tree; author CopilotKit docs in showcase/shell-docs/src/content/.