Sam Julien
a5b87eeb78
## Summary This PR updates thread import documentation and threads navigation across shell-docs, including a follow-up that makes the supported CLI-only import journey explicit. ## What changed - Adds thread import documentation: - Root generic guide at `/threads-import` for frameworks without a source-specific importer page. - Google ADK-specific guide at `/google-adk/threads-import`. - LangGraph-specific guide at `/langgraph-python/threads-import`, plus generated LangGraph framework routes through the framework resolver. - Authored framework wrappers so Mastra, AG2, Agno, Built-in Agent, CrewAI Flows, DeepAgents, LlamaIndex, Microsoft Agent Framework, and PydanticAI can surface the generic guide. - Updates the CLI and import journey: - Describes the CLI as supporting both cloud-hosted and self-hosted Enterprise Intelligence. - States up front that import runs from an app created with the CopilotKit CLI and Enterprise Intelligence enabled. - Clarifies that import uses the project already selected for the current directory. - Shows the source import commands before the optional `project select` explanation, while still directing users to change targets before running the dry run. - Removes the suggestion that `skills onboard` plus `project select` can add Enterprise Intelligence to an arbitrary existing app. - Keeps the CLI import section concise and links to the complete generic and source-specific guides. - Clarifies future thread continuity: - Threads Drawer uses the shared `CopilotChatConfigurationProvider`, so selecting a thread updates the active `threadId` without separate state wiring. - Headless Threads uses `useThreads`; the app stores the selected `thread.id` and passes it to the chat component as `threadId`. - ADK and LangGraph guides retain source-specific stable ID mapping guidance, including the LangGraph UUID caveat. - Removes source-guide links that rewrote to the current framework page and created circular navigation. - Adds and organizes Threads Drawer docs: - Extracts shared Threads Drawer content into a reusable snippet. - Adds root and authored-framework wrapper pages. - Moves Threads Drawer into a new expanded Threads nav grouping alongside Headless Threads and Import Thread History. - Renames and reorganizes threads docs: - Relabels the existing `Threads` guide as `Headless Threads`. - Removes the root prebuilt-components nav entry for Threads Drawer so generated frameworks do not show it in two places. - Updates root, authored, generated, and Built-in Agent nav metadata so the Threads grouping is consistent. - Updates nav tests to recognize pages nested inside authored-framework groups. ## Validation Run from `showcase/shell-docs`: - `npm run lint` passes with the existing repository warning set. - `npm run typecheck` passes. - `npm run test` passes: 32 files and 167 tests. - `npm run build` passes and generates 214 static pages; it reports the existing Turbopack NFT tracing warning. - Rendered and link-checked locally: - `/cli` - `/threads-import` - `/mastra/threads-import` - `/google-adk/threads-import` - `/langgraph-python/threads-import` - Root and framework-specific Threads Drawer and Headless Threads links ## Redirects No redirect URLs were added or required: - `Threads` was relabeled to `Headless Threads`, but the slug remains `/threads`. - `CopilotThreadsDrawer` was relabeled to `Threads Drawer`, but the URL remains `/prebuilt-components/copilot-threads-drawer` and framework equivalents. - Threads Drawer moved in navigation, but the route did not move. - `Import Thread History` is new at `/threads-import` and framework routes such as `/mastra/threads-import`, `/google-adk/threads-import`, and `/langgraph-python/threads-import`, so there is no prior URL to redirect. - The generated-framework routing change only selects framework-specific content for the new `threads-import` slug.
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/.