Three coupled bugs surfaced from the BIA-as-default cutover, all hitting
the A2UI snippet rendered on /built-in-agent/generative-ui/a2ui:
1. Framework-scoped link rewriter (docs-page-view) blindly prefixed
every root-relative MDX href with the active framework slug, so
`/a2a/generative-ui/declarative-a2ui` rendered as
`/built-in-agent/a2a/generative-ui/declarative-a2ui` (404). Now skip
the rewrite when the first URL segment matches a known framework
slug (registry integrations + docs-only a2a/agent-spec/deepagents)
or a reserved top-level route (/docs, /ag-ui, /reference, /api).
2. Snippet `shared/generative-ui/a2ui.mdx` "Learn More" block linked at
legacy paths (`/generative-ui/specs`, `/ag-ui-protocol`,
`/generative-ui/specs/*`) that the IA retired. Updated to canonical
destinations (`/concepts/generative-ui-overview`,
`/agentic-protocols/ag-ui`, `/generative-ui/<spec>`) so the
framework-prefix rewriter produces valid framework-scoped URLs.
3. S13 redirect (concepts/* -> framework root) was generated for every
legacy framework slug including those whose canonical slug didn't
change (mastra, ag2, agno, ...). The legacy docs never had
/<canonical-slug>/concepts/* pages so the rule never had legitimate
work for them — but shell-docs serves agnostic /concepts/* under
every framework's scope now, and the unconditional rule was 301'ing
those valid URLs to the framework root. Restricted to renamed
frameworks only.
Verified locally: every link rendered on /built-in-agent/generative-ui/a2ui
now resolves to 200; /<unchanged-slug-fw>/concepts/architecture still
serves; /langgraph/concepts/* still collapses to /langgraph-python.
shell-docs renders MDX server-side via MDXRemote, not Fumadocs's compile-
time MDX pipeline, so inline 'import { Boxes } from "lucide-react"' in an
.mdx body doesn't resolve at render time — Boxes ends up undefined and the
page errors with 'Expected component Boxes to be defined' on /cookbook.
Drop the import and the icon prop from the landing's <Card>. Existing
shell-docs pages (e.g. tutorials/ai-powered-textarea/*) use <Card> with no
icon, so this matches the local idiom. The Daytona recipe page is
unaffected because its icon is in frontmatter (icon: 'lucide/Boxes' — a
string, resolved by the page layout, not by MDX body).
OSS-222
Addresses PR review feedback (@tylerslaton): the docs/ folder is deprecated
in favor of showcase/shell-docs and will be removed soon. Move the entire
Cookbook contribution to shell-docs:
- showcase/shell-docs/src/content/docs/cookbook/ — landing + Daytona recipe
copied verbatim (Fumadocs frontmatter/components/dividers all match).
- showcase/shell-docs/src/content/docs/meta.json — new top-level
'---Cookbook---' divider with a '...cookbook' spread, slotted between
Platforms and Other.
- showcase/shell-docs/src/components/brand-nav.tsx — Cookbook tab added to
LEFT_LINKS (lucide ChefHat icon) and active-route detection extended so
/cookbook/* highlights it (peer to the existing Reference handling).
Reverts all earlier edits to docs/ from this PR (navbar, root meta, learn
meta, and the docs/content/docs/cookbook/ tree) so the deprecated folder is
left at zero-diff vs main.
OSS-222
Fumadocs's Tab component applies escapeValue() internally to the value
prop. Our DocsTab wrapper was also calling escapeValue() before passing
to FumadocsTab, causing multi-word tab values to be escaped twice.
For "JSON Configuration File" (3 words, 2 spaces):
1st escape (our wrapper): "json-configuration file" (1 space left)
2nd escape (Fumadocs Tab): "json-configuration-file" (fully hyphenated)
The trigger value uses only ONE escapeValue call:
escapeValue("JSON Configuration File") = "json-configuration file"
Trigger "json-configuration file" != content "json-configuration-file"
so Radix sets data-state="inactive" on the content panel, which is
then hidden by data-[state=inactive]:hidden.
Fix: remove escapeValue() from our Tab wrapper. The Tabs defaultValue
still needs pre-escaping because FumadocsTabs accepts it as-is (no
internal escape); only the individual Tab has internal escaping.
Single-word and two-word tabs (HTTP, Application Settings) were
unaffected because one escapeValue pass already produces a hyphen-only
string that is idempotent under a second pass. Same bug also affected
"stdio Transport (Local)" in the Windsurf section.
Three classes of legacy URLs were 404'ing because shell-docs (with BIA
as the soft-default framework) doesn't serve them at the root surface
the old docs did:
1. BIA-canonical pages — /server-tools, /mcp-servers, /model-selection,
/advanced-configuration, /agent-app-context live only under
/built-in-agent/ now. Internal sidebar clicks already framework-scope
via SidebarLink; external traffic (marketing, blog posts, bookmarks)
was 404'ing.
2. Moved root pages — /mcp-apps (moved to /generative-ui/),
/copilot-runtime, /custom-agent (moved to /backend/), /deep-agents
(renamed to /deepagents), /multi-agent-flows (LangGraph-only),
/custom-look-and-feel folder index, /generative-ui/specs/* (specs
subgroup retired), plus assorted misc (/what-is-copilotkit,
/getting-started/quickstart-chatbot, /telemetry, /migration-guides/*,
/reference/hooks/useCoAgent).
3. Legacy /integrations/<fw>/* prefix — R15/R17 already handled the
built-in-agent variant; this extends the same pattern to every other
framework, mirroring the existing /docs/integrations/* coverage.
All redirect destinations verified to return 200 against a local dev
build; existing tests still pass.
The @ag-ui/aws-strands TypeScript adapter ships alongside the Python
ag_ui_strands package but the docs only showed Python snippets. Add a
TypeScript tab next to every Python snippet (Python default, `persist`
on the tab group so a reader's choice sticks across pages) covering:
- quickstart: project init, install, agent file, run command
- frontend-tools: @tool stub + createStrandsApp server
- shared-state (read + write): StrandsAgentConfig.stateContextBuilder
- generative-ui tool-rendering: backend tool definition
- generative-ui state-rendering: ToolBehavior.stateFromArgs
Also applied to the parallel showcase/shell-docs tree. Non-code pages
(deploy-agentcore, copilot-runtime, inspector, etc.) remain untouched
since they either re-export shared snippets or have no framework code.
## Summary
- Bundle Inter Medium/Bold locally for shell-docs OG image rendering and
pass them to ImageResponse.
- Localize the OG background and CopilotKit logo as data URIs so the
route avoids render-time remote image fetches.
- Add route tests for valid image construction, unknown slug 404
propagation, render failure 500 behavior, and framework-scoped slug
resolution.
## Verification
- pnpm test in showcase/shell-docs (36 passed)
- pnpm lint in showcase/shell-docs (exits 0; existing warnings only)
- Local dev-server curl: /og/quickstart/og.png returned 200 image/png,
valid 1200 x 630 PNG
- Local dev-server curl: /og/does-not-exist/og.png returned 404
- Commit hook ran test-and-check-packages successfully
## Notes
- showcase/shell-docs is not present in the Nx project graph, so there
was no direct shell-docs Nx target to run.
- pnpm typecheck / pnpm build for standalone shell-docs currently fail
on pre-existing src/lib/rehype-code-meta.ts missing shiki types.
## Summary
- Unify authored and generated shell-docs navigation so the sidebar
keeps the same structure across framework modes.
- Restore setup-content bundling from integration-owned docs and wire
shell-docs to consume the generated bundle at runtime.
- Audit and fix the LangGraph TypeScript and Google ADK code regions so
the generated snippets are more useful and accurate.
- Tighten docs/build routing and workflow triggers so shell-docs
rebuilds when the relevant integration docs inputs change.
## Testing
- Shell-docs unit tests passed.
- Shell-docs typecheck passed.
- Shell-docs lint passed with existing repository warnings only.
- Setup-content bundle generation passed.
- Python integration files compiled successfully.
- Workflow YAML parsed successfully.
## Summary
- Restore the missing NewLookAndFeelPreview component for shell-docs
troubleshooting migration pages.
- Wire the MDX registry to render the real preview instead of an empty
shim.
## Verification
- npm --prefix showcase/shell-docs run typecheck
- npm --prefix showcase/shell-docs run lint (warnings only,
pre-existing)
- Browser verified
http://localhost:3003/built-in-agent/troubleshooting/migrate-to-1.8.2:
preview launcher renders and opens populated panel
- git commit pre-commit hooks passed: check-binaries, lint-fix,
test-and-check-packages
## Notes
- @copilotkit/showcase-scripts:verify-shell-docs:fast runs but fails on
existing broad shell-docs dead-link/import/content backlog unrelated to
PDX-203.
- Production next build hung locally after content generation with no
diagnostics; verified the affected route via dev server instead.
## Summary
- Disabled Fumadocs search in `showcase/shell-docs` so Cmd/Ctrl+K no
longer opens the built-in dialog.
- Centralized the custom search modal behind a single app-level
provider/event bridge so desktop and mobile triggers share one instance.
- Kept the custom search button and hotkey behavior intact, including
Escape to close.
## Testing
- `npm run typecheck` in `showcase/shell-docs` passed.
- `npm run lint` in `showcase/shell-docs` passed with pre-existing
warnings only.
- Verified locally in the in-app browser that Cmd+K opens one custom
search modal, Escape closes it, and no Fumadocs search dialog appears.
Root page was duplicating the snippet content inline. Switch it to
<BuildWithAgents /> so snippets/shared/guides/build-with-agents.mdx
is the one source — root page and built-in-agent both render from it.
built-in-agent uses docs_mode: 'authored' so it loads the per-framework
integrations/built-in-agent/build-with-agents.mdx directly, bypassing
the root page entirely. Other frameworks (generated mode) fall through
to the root page and already show the skills section.
Fix: extract the full page body into a shared snippet
snippets/shared/guides/build-with-agents.mdx
register it as <BuildWithAgents /> in SNIPPET_MAP + mdx-registry, and
switch built-in-agent's page to <BuildWithAgents />. Root page keeps
its inline content (for crawlability). The snippet is the source used
by authored-mode frameworks; root is the source for generated-mode and
crawlers — same pattern as MCPSetup / coding-agents.
The table was incomplete (6 skills listed, 12 actually install) and has
no CI check to keep it in sync. Replace with a one-line prose summary
and a link to the canonical skills/ directory on GitHub, which is always
accurate.
- Rewrites the root build-with-agents page to document Skills + MCP Docs Server
- Skills section: intro, npx skills add command, skills table, starter prompt
- Removes hideTOC so the new TOC (Skills / MCP Docs Server) renders
- Updates icon to BrainCircuit and description to keyword-rich copy
- Renames mcp-server-setup snippet heading: ## Overview → ## MCP Docs Server
so both sections compose cleanly on the root page without a double Overview
Closes out the last AC on OSS-133: npx skills add flow documented with
table of skills, starter prompt, and page structure matching Mastra reference.
## Summary
Ports the changes from PR #4927 to the live shell-docs app. PR #4927
renamed \`coding-agents\` → \`build-with-agents\` in the legacy
\`docs/\` tree, but \`showcase/shell-docs\` has its own independent
content directory that was never updated.
## Changes
- **11 file renames:** \`coding-agents.mdx\` → \`build-with-agents.mdx\`
(root + 10 integrations: ag2, agno, aws-strands, built-in-agent,
crewai-flows, langgraph, llamaindex, mastra, microsoft-agent-framework,
pydantic-ai)
- **Frontmatter titles:** \`"Coding Agents"\` → \`"Build with agents"\`
in all 11 files
- **Root \`build-with-agents.mdx\`:** replaced 291 lines of hardcoded
content with \`<MCPSetup />\` shared snippet (content had drifted from
the canonical snippet)
- **9 integration \`meta.json\` files:** \`"coding-agents"\` →
\`"build-with-agents"\` in sidebar nav
- **Root \`meta.json\`:** rename entry + add React Native under new
\`---Platforms---\` section (mirrors PR #4927's second commit)
- **\`seo-redirects.ts\`:**
- Update S4 (\`vibe-coding-mcp\`) and S15 (\`mcp\`) subpath destinations
to \`build-with-agents\`
- Add S16: \`coding-agents\` → \`build-with-agents\` subpath rename for
all 13 legacy framework slugs
- Add \`CODING_AGENTS_RENAMES\`: root \`/coding-agents\` + all canonical
framework \`/*/coding-agents\` → \`/*/build-with-agents\` (exact 301s)
- Fix stale destinations in F20, R12, R18, R19
- **\`docs-render.tsx\`:** update \`SUBPATH_TO_COMPONENT\` key
\`"coding-agents"\` → \`"build-with-agents"\` so pages at the new slug
still resolve the shared MCP snippet
## Test plan
- [x] \`/coding-agents\` 301-redirects to \`/build-with-agents\`
- [x] \`/langgraph-python/coding-agents\` 301-redirects to
\`/langgraph-python/build-with-agents\`
- [x] \`/mcp\` and \`/vibe-coding-mcp\` redirect to
\`/build-with-agents\`
- [x] Sidebar shows "Build with agents" entry in each integration
- [x] React Native appears under Platforms section in root sidebar
- [x] All 11 \`build-with-agents\` pages render content correctly (MCP
setup snippet loads)
- [x] Root \`/build-with-agents\` shows correct MCP setup content
main added its own CANONICAL_FRAMEWORKS const after this branch was cut.
CI tests the merge commit, so the duplicate declaration caused a build
error. Replace with an inline derivation from FRAMEWORKS so the variable
is self-contained and never conflicts with whatever main defines.
The root /build-with-agents page had 290 lines of inline content that had
drifted from the canonical mcp-server-setup.mdx snippet: wrong MCP endpoint
paths (/mcp vs /sse), and missing Tadata attribution Callout that every
per-framework build-with-agents page renders.
Replace with <MCPSetup /> to use the same shared snippet as the langgraph
integration page, ensuring the root page and all framework pages render
identical, authoritative content from a single source of truth.
S16 in SUBPATH_RENAMES already generates /<fw>/coding-agents → /<fw>/build-with-agents
for all 13 legacy frameworks including unchanged-slug ones (agno, ag2, pydantic-ai,
llamaindex, mastra, agent-spec, a2a). Including them in CANONICAL_FRAMEWORKS created
7 duplicate source entries in the redirect table, corrupting PostHog decommission
attribution (the CA×<fw> IDs would never get traffic).
Restrict CANONICAL_FRAMEWORKS to frameworks whose canonical slug differs from their
legacy slug (langgraph-python, google-adk, crewai-crews, ms-agent-dotnet, strands,
built-in-agent) — these are the ones S16 can't cover since S16 sources use legacy slugs.
CANONICAL_FRAMEWORKS was referenced in CODING_AGENTS_RENAMES but never
defined, causing a TypeScript error. Derive it from FRAMEWORKS.map(canonicalSlug)
so all 13 canonical slugs (langgraph-python, google-adk, strands, etc.) get
/coding-agents → /build-with-agents redirects.
PR #4927 landed this rename in the legacy `docs/` tree, but `showcase/shell-docs`
has its own content directory that was never updated.
Changes:
- Rename 11 `coding-agents.mdx` → `build-with-agents.mdx` (root + 10 integrations)
- Update frontmatter title "Coding Agents" → "Build with agents" in all 11 files
- Update `"coding-agents"` → `"build-with-agents"` in 9 integration meta.json nav files
- Update root meta.json: rename entry + add React Native under new ---Platforms--- section
- seo-redirects.ts: update S4/S15 subpath destinations; add S16 (coding-agents→build-with-agents)
subpath rename for all legacy framework slugs; add CODING_AGENTS_RENAMES for root + all
canonical framework slugs; fix stale destinations in F20, R12, R18, R19
- docs-render.tsx: update SUBPATH_TO_COMPONENT key "coding-agents" → "build-with-agents"
6 prebuilt-components pages were missing their PrebuiltComponents import,
causing the inlineSnippets regex to skip them and drop the framework prop
(iframe URLs defaulted to langgraph). 8 HITL pages had copy-pasted code
examples using the deprecated v1 parameters array format instead of Zod
schemas. Added a component-imports validation check to verify-shell-docs.ts
to catch missing snippet imports going forward.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
.reference-content p { margin-bottom: 1rem } is unlayered CSS and
always beats the layered prose-no-margin utility from fumadocs-ui,
causing visible extra space at the bottom of info callout boxes.
Mirror prose-no-margin's intent at (0,2,1) specificity in globals.css
so the first/last-child margin resets actually apply.
Also bump NODE_OPTIONS in the lefthook test-and-check-packages hook
to 8 GB — @copilotkit/core:build bundles many deps inline with
rolldown and exhausts the default 4 GB V8 heap, causing a native
binding crash on every pre-commit run.
Tyler Slaton