Mark
0c10d8c882
Mechanical repairs found while auditing the pydantic-ai docs. Each was verified against the tree; nothing here is a content rewrite. - Delete `quickstart/pydantic-ai.mdx` + its `meta.json`. `seo-redirects.ts` already routes `/pydantic-ai/quickstart/pydantic-ai` -> `/pydantic-ai/quickstart` (rule F6), and adk got the same treatment (F7). pydantic-ai was the only framework still carrying a `quickstart/` subdirectory alongside the canonical `quickstart.mdx`. - `human-in-the-loop/agent.mdx`: link to the canonical quickstart directly instead of the redirected legacy path, and point the starter link at `examples/integrations/pydantic-ai` — `examples/coagents-starter-pydantic-ai` does not exist. - `docs-links.json`: `subagents.shell_docs_path` was `/multi-agent/subagents`, which has no page. The real page is `/multi-agent-flows`, which the entry's own `og_docs_url` already pointed at. - `headless-simple/chat.tsx`: the console tag said `langgraph-python` inside the pydantic-ai package. This sits in an `@region` block, so it is pulled into docs as a snippet. 11 other integrations carry the same copy-paste; they are left for the fleet sweep. - `examples/showcases/pydantic-ai-todos/README.md`: `uv run src/main.py` -> `uv run main.py` (there is no `src/main.py` in that tree), and the stated Python floor now matches `agent/pyproject.toml` (`>=3.13`). - `examples/canvas/pydantic-ai/README.md`: Python 3.8+ was unrunnable — `agent/agent.py` uses PEP 604 unions. Aligned to the sibling tree that pins the same `pydantic-ai-slim==2.22.0`.
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/<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/.