Tyler Slaton
5cae8d4937
## Problem Claude Agent SDK docs could render malformed or missing extracted snippets across the generated Python and TypeScript integration docs. The generative UI pages had stale duplicate regions and generic setup leakage, while the custom look-and-feel reasoning and slots pages referenced demo cells or regions that did not exist for every Claude integration. ## Why The docs pipeline treated accidental duplicate region names across files as intentional multi-file regions, and several authored docs pages drifted from the actual generated showcase demo IDs/regions. That left some pages visually correct at a glance but broken when users opened specific extracted code snippets. ## Fix - Move the shared `bar-chart-renderer` regions to the complete `useComponent` call and delete stale duplicate snippet files. - Add an explicit duplicate-region guard and verifier coverage for accidental cross-file region collisions. - Add line-emphasis support for extracted `<Snippet>` blocks and setup `<DemoCode>` output. - Scope generative UI feature pages away from generic `agent-setup` boilerplate. - Repair the shared reasoning-messages docs to use the generated `reasoning-default` and `reasoning-custom` demo cells. - Add the missing Claude Python chat-slots teaching snippet regions and keep both Claude slot snippets self-contained. - Broad-audit both Claude integration docs locally, then targeted-audit the repaired reasoning/slots pages in light and dark mode.
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/.