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.
## Summary
Three changes to `src/lib/docs-render.tsx` that together eliminate the
`[docs-render] snippet missing for component X` log noise on prod AND
fix a hard SSR error on `/quickstart` caused by a missing
`ComponentExamples` registration.
## Changes
**1. Suppress warnings for components the MDX imports** (existing scope
of this PR).
`inlineSnippets()` runs after `stripLeadingImports()` removes the MDX's
`import` lines, so the regex can't tell a `<PascalCase />` reference
apart from a real React component imported into the file. Every imported
component triggered a false-positive `snippet missing` warning. The page
still rendered correctly via `docsComponents`; only the log was wrong.
Capture imports before stripping, then short-circuit the warning when
the regex hits one of those names.
**2. Add `ComponentExamples` to `SNIPPET_MAP`** (new).
`copilot-ui.mdx` imports `ComponentExamples` from
`@/snippets/component-examples.mdx` and renders it. When
`copilot-ui.mdx` is recursively inlined into a parent MDX (e.g. via
`<CopilotUI />`), the import line is stripped and the inliner finds no
`SNIPPET_MAP` entry for `ComponentExamples`. The bare JSX survives the
inliner and `next-mdx-remote` throws `Expected component
ComponentExamples to be defined` at SSR. The error is caught in a
partial-render error boundary so the page returns 200, but a chunk of
content is missing from the rendered output.
Add `ComponentExamples: "component-examples.mdx"` to `SNIPPET_MAP` so
the recursive inliner resolves it the same way it resolves `CopilotUI`.
One line, fixes both the SSR error and the cosmetic warning.
(Note: the `gatherImportedComponentNames` shortcut from change 1 doesn't
help here because it captures imports from the OUTER MDX, not from
recursively-inlined snippet bodies. That deeper structural limitation
can be addressed later; the `SNIPPET_MAP` entry resolves the immediate
failure.)
**3. Skip icon-prefix bare references** (new).
Lucide `Square*` icons (`SquareTerminal`, `SquareChartGantt`) and
`react-icons` `Fa*` / `Si*` / `Pi*` families are bare-referenced in many
MDX files — no explicit import, resolved at render time via the
registry's emoji stubs in `docsComponents`. The existing
`endsWith("Icon")` filter doesn't catch these PascalCase +
library-prefix shapes. Add a regex check next to it:
`/^(Fa|Si|Pi|Square)[A-Z]/`.
## Components covered after changes 1-3
The import-aware filter catches every `import { X } from "..."`
reference (current set: AgentCoreCommandTabs, CodePanel, CodeShowcase,
Frame, IframeSwitcher, ImageAndCode, LinkToCopilotCloud,
NewLookAndFeelPreview, StartProviders).
The icon-prefix filter catches `FaArrowUp`, `FaWrench`,
`SquareTerminal`, `SquareChartGantt`, and future icon-library additions
matching the prefix shape.
`ComponentExamples` is registered in `SNIPPET_MAP` so the inliner
resolves it instead of warning.
Remaining bare references that don't match any of the above (e.g.
`CloudCopilotKit`) still warn — these are runtime React components
registered in `docsComponents` but not imported in the MDX. The right
cleanup for those is to add explicit `import { CloudCopilotKit } from
"..."` lines in the MDX, which the import-aware filter then catches
automatically. Out of scope for this PR.
## Adjacent observation (not fixed)
While diagnosing change 2, found that the underlying
`new-look-and-feel.tsx` component file referenced by
`troubleshooting/migrate-to-1.8.2.mdx` doesn't exist on disk. The MDX
registry stubs the name with `<div>{children}</div>`, so the preview
area in that page renders empty. This PR doesn't address the
empty-preview behavior; the snippet-missing log noise is purely
cosmetic.
## Test plan
- [x] Diff is additive only; runtime render path unchanged.
- [ ] Local: build shell-docs, hit `/built-in-agent/quickstart` +
`/crewai-crews/quickstart` + `/built-in-agent/agentic-protocols/mcp` +
`/built-in-agent/shared-state/predictive-state-updates` +
`/built-in-agent/troubleshooting/migrate-to-1.8.2`. Confirm zero
`[docs-render] snippet missing` and zero `Expected component
ComponentExamples to be defined` warnings in the dev server log.
- [ ] Local: confirm the ComponentExamples Tabs block actually renders
on `/crewai-crews/quickstart` (was silently missing pre-fix).
- [ ] Post-deploy: re-check Railway logs for the warning + error class
over a sample of page loads.
Two follow-on fixes to the same docs-render snippet pipeline.
1. ComponentExamples SSR error. The shared copilot-ui.mdx snippet
imports ComponentExamples from @/snippets/component-examples.mdx
and renders it. When copilot-ui.mdx is recursively inlined into a
parent MDX (e.g. crewai-flows/quickstart.mdx via <CopilotUI />),
stripLeadingImports removes the import line, then the regex hits
<ComponentExamples /> with no matching SNIPPET_MAP entry. The
inliner leaves the bare JSX in the output and at MDX render time
next-mdx-remote throws "Expected component ComponentExamples to be
defined". Add the snippet to SNIPPET_MAP so the recursive inliner
resolves it the same way it resolves CopilotUI.
The gatherImportedComponentNames shortcut from the same PR only
captures imports in the OUTER MDX, not in recursively inlined
snippet bodies — a deeper structural limitation worth fixing later
but not load-bearing here. The SNIPPET_MAP entry resolves both the
SSR error AND the false-positive warning in one line.
2. Icon-library bare references logging spurious warnings. Lucide
Square-prefixed icons (SquareTerminal, SquareChartGantt) and
react-icons fa / si / pi families appear bare in many MDX files —
no import, resolved at render time via the registry's emoji stubs.
The existing endsWith("Icon") filter doesn't catch these. Add a
PascalCase-prefix check next to it.
Strictly additive; runtime render path unchanged.
The Built-in Agent sidebar still rendered the deprecated tutorials section
("Tutorial: AI Todo App", "Tutorial: AI Textarea" with step pages) even
after PR #4987 added 301 redirects for /{fw}/tutorials/:path* paths.
The redirects fired on click, but the entries should never have appeared.
Root cause: integrations/built-in-agent/meta.json declared a
"---Tutorials---" section header followed by a "...tutorials" spread.
BIA runs in docs_mode "authored" which routes through buildFrameworkOnlyNav;
that path preserves section headers and recurses through spreads. The
spread descended into integrations/built-in-agent/tutorials/ and
enumerated the AI Todo App and AI Textarea subfolders into the sidebar.
Other frameworks were already safe: buildFrameworkOverridesNav (used by
generated-mode frameworks like langgraph, mastra, google-adk) explicitly
strips section nodes from per-framework override nav.
Fix: remove the "---Tutorials---" section header and "...tutorials"
spread from BIA's parent meta.json. Nothing now references the
tutorials folder from BIA's nav, so the spread handler never recurses
into it and the entries disappear. Two-line minimal change.
Tutorial source MDX under content/docs/integrations/built-in-agent/tutorials/
stays in place (PDX-100 owns the rewrite). The redirect catalog in
lib/seo-redirects.ts is untouched.
Refs PDX-205.
inlineSnippets() runs after stripLeadingImports() removes the MDX's
import lines, so its regex scan can't tell whether a `<Component />`
reference is a snippet lookup or a real React component rendered via
the docsComponents registry. Every imported component triggered a
false-positive "[docs-render] snippet missing for component X"
warning.
Capture the set of imported component names BEFORE stripping, then
short-circuit the warning when the regex hits one of those names.
Catches NewLookAndFeelPreview, AgentCoreCommandTabs, CodePanel,
CodeShowcase, Frame, IframeSwitcher, ImageAndCode, LinkToCopilotCloud,
and StartProviders (the full current set imported into snippet MDX
files under src/content/snippets/), plus any future additions
automatically.
The runtime render path is unchanged: the docsComponents registry
in mdx-registry.tsx still resolves these names at render time.
## Summary
Three independent regressions surfaced during Phase 6 post-cutover
validation against the live docs.copilotkit.ai. Bundled together since
they all live under `showcase/shell-docs/` and were verified together
end-to-end.
### 1. Soft-404 returning HTTP 200 with not-found UI body
Unknown URLs returned `HTTP 200` with the Next.js "404: This page could
not be found" body. Internal Next 404 markers
(`NEXT_HTTP_ERROR_FALLBACK`, `<meta name="robots" content="noindex">`)
were present in the body but the wire status stayed 200. Google treats
this as low-quality content and demotes the entire site.
Root cause: `<Suspense fallback={null}>` in `app/layout.tsx` committed
the response stream at status 200 before page-level `notFound()` could
flip it.
Fix:
- Removed the layout Suspense wrapper (both PostHogProvider and
FrameworkProvider are `"use client"` with no suspending APIs, so the
boundary was incidental from the original telemetry port).
- Added an explicit `src/app/not-found.tsx` rendering a branded 404
page.
- Marked the three catch-all routes `dynamic = "force-dynamic"` so
unknown slugs always re-evaluate at request time. Reference route stays
SSG (its slugs come from `referenceStaticParams`).
Verified: `/this-clearly-does-not-exist` returns `HTTP 404`. Real pages
return 200.
### 2. Per-page metadata + OG / Twitter cards
All four `generateMetadata` functions returned only
`alternates.canonical`. Every page inherited the layout's generic `<meta
name="description">` and emitted zero `og:*` / `twitter:*` tags. Every
social share unfurled bare.
Fix: routes now build full `Metadata` via a shared
`src/lib/seo-metadata.ts` helper that reads MDX frontmatter for title
and description and emits openGraph + Twitter card with absolute URLs.
Bonus fix in `app/og/[...slug]/route.tsx`: the OG image route fetched
Inter TTFs from `fonts.gstatic.com` on every request. Any failure
(Railway egress, font URL drift) tripped the catch block, which 307'd to
a 25-byte broken CDN fallback. Dropped the runtime font fetch (Satori's
default sans-serif renders cleanly), broadened slug resolution to also
try `integrations/<folder>/<slug>` paths, and replaced the
broken-fallback redirect with a real 500 + log.
Verified locally: full og/twitter meta set on every page;
`/og/built-in-agent/quickstart/og.png` and
`/og/langgraph-python/quickstart/og.png` both return 1200x630 PNGs with
branded backgrounds.
### 3. Pydantic-ai shared-state pages 500
`/pydantic-ai/shared-state/in-app-agent-read` and
`/pydantic-ai/shared-state/in-app-agent-write` returned deterministic
HTTP 500. Same paths on all other frameworks returned 200. A full
sitemap crawl (2451 URLs) found these as the only 5xx on the entire
site.
Root cause: both MDX files at
`src/content/docs/integrations/pydantic-ai/shared-state/in-app-agent-{read,write}.mdx`
were truncated/malformed during the v1→v2 content port — `read.mdx`
ended mid-Python-fence with unclosed `<Step>` / `<Steps>`; `write.mdx`
had a Python code fence containing JS/TSX. Pure MDX parse failure during
SSR.
Fix: restored both files from the canonical legacy source under
`docs/content/docs/integrations/pydantic-ai/shared-state/`, stripped
leading `import` blocks per the convention used by other pydantic-ai
pages (components resolve via `docsComponents` in
`src/lib/mdx-registry.tsx`).
Verified locally: both URLs go 500 → 200.
### 4. `/reference/v1/:path*` redirect dropped its suffix
Catalog rule P10 redirected `/reference/v1/hooks/useCopilotChat` to a
generic `/reference/v2` index instead of
`/reference/v2/hooks/useCopilotChat`. Users following v1 docs links from
product code messages landed on the wrong page.
Fix: one-line change in `seo-redirects.ts`: destination `/reference/v2`
→ `/reference/v2/:path*`. Audited all other catalog rules with `:path*`
source and bare destination — remaining cases (`concepts/*` collapse,
tutorials deprecation wildcards) are documented intentional
wildcard-to-single-page rules, not drift.
## Test plan
- [x] `npm run typecheck`, `npm run lint`, `npm test` (32 tests pass),
`npm run build` all green in `showcase/shell-docs/`.
- [x] Local prod-mode walkthrough on all four fix surfaces:
- `/built-in-agent/quickstart` → 200 + full og/twitter meta + per-page
description + branded OG PNG.
- `/langgraph-python/voice` → 200, live demo iframe renders.
- `/built-in-agent/garbage-page-xyz` → 404 (real status, branded 404
page).
- `/pydantic-ai/shared-state/in-app-agent-read` → 200.
- `/reference/v1/hooks/useCopilotChat` → 301 →
`/reference/v2/hooks/useCopilotChat` → 200.
- [ ] Post-deploy: re-curl a sample of soft-404 URLs against prod and
confirm wire status is `404`, not `200`.
- [ ] Post-deploy: validate a docs URL share in Slack / X to confirm OG
card renders with title + description + image.
Five post-cutover follow-ups bundled together because all surfaced in
the same spot-check pass on `/integration/<page>` routes.
## 1. Tag `page-send-message` region (`4680eb9c1`)
`/langgraph-python/programmatic-control` and
`/google-adk/programmatic-control` rendered a yellow "Missing snippet"
callout because `<Snippet region="page-send-message" />` had no matching
`// @region[page-send-message]` / `// @endregion[page-send-message]`
pair in the resolved `headless-complete` cell. Peer integrations
(mastra, ag2, strands, pydantic-ai, llamaindex, langgraph-fastapi,
crewai-crews, …) already had the tags; only north-star and its ADK
mirror were missing them. The region wraps the connect / send / stop
block in `chat/chat.tsx`.
## 2. Suppress HubSpot-rewritten href hydration mismatch on nav-bar
(`2c0791930`)
HubSpot's analytics tag (loaded from `js-na2.hs-analytics.net`) rewrites
the Intelligence CTA's outbound `href` client-side to append `__hstc` /
`__hssc` / `__hsfp` cross-domain tracking params. Server-rendered HTML
keeps the bare URL, post-hydration DOM has the rewritten URL, React's
hydration diff fires.
Add `suppressHydrationWarning` to the two anchor elements that point at
`INTELLIGENCE_CTA_HREF` (desktop BrandNav `LEFT_LINKS` entry,
MobileTopNav Lightbulb icon).
## 3. Register `UseAgentSnippet` (`f809b9b8b`, expanded by `773631cbd`)
`inlineSnippets()` in `docs-render.tsx` maintains its own `SNIPPET_MAP`
separate from `mdx-registry.tsx`'s `STUB_PARTIAL_MAP`. The two
registries drifted. `UseAgentSnippet` was the most-hit miss, but Railway
logs surfaced 14 more: `InstallSDKSnippet`, `InstallPythonSDK`,
`RunAndConnect` (+ `Snippet` alias), `CopilotUI`, `LandingCodeShowcase`,
the four `CopilotCloudConfigure*` / `SelfHostingCopilotRuntime*` keys,
plus `MigrateTo` / `MigrateToV` / `ToolRenderer` aliases. All added.
## 4. Make `inlineSnippets()` code-fence-aware + add Icon-suffix
heuristic (`773631cbd`)
After the registry fix, the remaining `[docs-render] snippet missing`
log entries split into two false-positive classes:
- **Code-fence false positives.** The regex matched `<Component />`
references inside ` ```tsx ``` ` example blocks — e.g. `<CopilotChat />`
/ `<CopilotSidebar />` shown as runtime usage, `<WeatherCard />` /
`<YourApp />` as placeholders. A new `isInsideCodeFence(content,
offset)` helper tracks fenced blocks (matching any indentation — MDX
inside `<Step>` is routinely 8-space-indented) and inline-code spans.
Replaces the ad-hoc `CopilotChat`-only allowlist from commit 3.
- **JSX-prop runtime components.** `icon={<PaintbrushIcon />}` etc. are
real React components from `mdx-registry.tsx::docsComponents`, not
snippets. Add an `Icon`-suffix heuristic: lucide icons used as JSX props
are silenced.
## 5. Suppress HubSpot hydration mismatch on `<OpsPlatformCTA>` +
`<SignupLink>` (`10b4960a3`)
Same HubSpot rewrite hits every dashboard.operations.copilotkit.ai
outbound link. Add `suppressHydrationWarning` to all four `<a>` tags in
`OpsPlatformCTA` (`info` / `inline` / `tile` / `card` variants) and the
single `<a>` in `SignupLink`. Observed live as a hydration error on
`/<framework>/prebuilt-components`, `/<framework>/headless`, and any
page that embeds an Intelligence-platform CTA.
## Verification
- `grep -n "@region\[page-send-message\]"
showcase/integrations/{langgraph-python,google-adk}/src/app/demos/headless-complete/chat/chat.tsx`:
both files have start (line 38) + end (line 114) markers; `diff` between
them is empty post-change.
- `npx tsx showcase/scripts/bundle-demo-content.ts`: regenerated
`demo-content.json` exposes `regions["page-send-message"]` for both
`langgraph-python::headless-complete` and
`google-adk::headless-complete` (1878 bytes, `chat/chat.tsx` lines
38-112).
- Playwright sweep across `/programmatic-control`,
`/runtime-server-adapter`, `/frontend-tools`,
`/generative-ui/tool-rendering`, `/prebuilt-components`,
`/deploy/agentcore`, `/auth` on `google-adk` and `mastra`: 0 console
errors, 0 warnings, 0 "Missing snippet" callouts in rendered DOM, both
desktop (1440px) and mobile (390px) viewports.
## Test plan
- [ ] Pull, build shell-docs, smoke
`/langgraph-python/programmatic-control` and
`/google-adk/programmatic-control`: yellow "Missing snippet" callout is
gone.
- [ ] Same pages on a mobile viewport: no hydration warning in the
console.
- [ ] `/<framework>/prebuilt-components` and any page with an inline
`<OpsPlatformCTA>`: no hydration warning.
- [ ] Peer integration pages (e.g. `/mastra/programmatic-control`,
`/<framework>/deploy/agentcore`, `/<framework>/frontend-tools`):
snippets still render, no `[docs-render] snippet missing` warnings.
- [ ] Redeploy shell-docs.
## Out of scope
- Underlying prose-vs-code parity gap on the headless-complete cell
(north-star uses `agent.abortRun()` and skips `connectAgent`) is tracked
separately.
- Unifying `docs-render.tsx::SNIPPET_MAP` and
`mdx-registry.tsx::STUB_PARTIAL_MAP` into a single source of truth (so
future entries can't drift) is the right architectural follow-up. Filed
separately.
- Environmental jsdom × vitest interaction blocking
`packages/web-inspector/src/lib/__tests__/telemetry.test.ts` (which
forced `--no-verify` on these commits) is tracked separately.
Three post-cutover SEO/social gaps surfaced once docs.copilotkit.ai
pointed at shell-docs:
- `generateMetadata` in the four catch-all routes returned only the
canonical link, so every page inherited the layout's generic title
and description and zero og/twitter tags shipped. Every share unfurled
bare. Routes now build full Metadata via a shared helper
(`src/lib/seo-metadata.ts`) that reads MDX frontmatter for title and
description and emits openGraph + twitter card with absolute URLs.
- The `/og/<slug>` route fetched Inter TTFs from fonts.gstatic.com on
every request. Any failure tripped the catch block, which 307'd to a
broken CDN fallback. Removed the runtime font fetch and let Satori
fall back to its built-in sans-serif; also broadened the slug
resolution to try the framework-scoped `integrations/<folder>/<slug>`
path so OG images render for framework variants too. Catch block now
surfaces real failures as 500 instead of redirecting to a broken PNG.
- Unknown URLs returned HTTP 200 with a not-found UI body (soft-404).
Root cause was a `<Suspense fallback={null}>` wrapper in the root
layout that committed the response stream before page-level
`notFound()` could set the 404 status. Removed the Suspense, added an
explicit `src/app/not-found.tsx`, and marked the catch-all routes
`force-dynamic` so unknown slugs always re-evaluate at request time.
Verified locally: `/this-clearly-does-not-exist` returns HTTP 404,
`/built-in-agent/quickstart` returns HTTP 200 with full meta tags.
The cutover to `docs_mode: authored` for pydantic-ai exposed two MDX
files that had been ported in a truncated state during the v1->v2
content migration:
integrations/pydantic-ai/shared-state/in-app-agent-read.mdx
integrations/pydantic-ai/shared-state/in-app-agent-write.mdx
`in-app-agent-read.mdx` ended mid-python-fence at
`if __name__ == "__main__":` with no closing ```, no closing `</Step>`,
no closing `</Steps>`. `in-app-agent-write.mdx` had a python code block
that switched to TSX content mid-fence (Python `if __name__` followed
by JS `// ...` and a TSX function inside a `python` block), which the
MDX/Shiki pipeline then tried to parse as Python.
Both produced SSR 500s in production (Railway edge: text/plain
"Internal Server Error") at:
/pydantic-ai/shared-state/in-app-agent-read
/pydantic-ai/shared-state/in-app-agent-write
These were the only two 5xx URLs in the full 2451-URL sitemap crawl.
Every other framework variant of the same paths (langgraph-python,
mastra, built-in-agent, google-adk, etc.) returned 200, confirming the
crash was content-specific to pydantic-ai.
Restore the full content from the canonical legacy source at
`docs/content/docs/integrations/pydantic-ai/shared-state/` (which was
intact, 178+188 lines), with the leading `import` block stripped to
match the convention used by the other ported pydantic-ai pages
(`predictive-state-updates.mdx` etc.) where `RunAndConnect`,
`IframeSwitcher`, and friends are resolved via `docsComponents` in
`src/lib/mdx-registry.tsx` rather than per-file imports.
Verified locally with `next dev`:
/pydantic-ai/shared-state/in-app-agent-read 500 -> 200
/pydantic-ai/shared-state/in-app-agent-write 500 -> 200
The P10 catalog rule was stripping the suffix when redirecting legacy
v1 reference URLs, sending /reference/v1/hooks/useCopilotChat to the
generic /reference/v2 index instead of /reference/v2/hooks/useCopilotChat.
Affects user-facing console messages in packages/react-core that ship
/reference/v1/hooks/useCopilotChatHeadless_c links and bounced users to
the index page instead of the specific hook reference.
Middleware substitutes :path* in destinations (verified against the
coagents rule), so adding :path* to the destination is enough to fix it.
OpsPlatformCTA and SignupLink both link out to
dashboard.operations.copilotkit.ai, which HubSpot's analytics tag
rewrites client-side to attach `__hstc` / `__hssc` / `__hsfp`
cross-domain tracking params. Same root cause as the prior nav-bar
Intelligence CTA fix — server-rendered href has the bare URL,
post-hydration DOM has the rewritten URL, React flags a hydration
mismatch on every page that surfaces the inline / tile / card CTA
(observed live on /<framework>/prebuilt-components and
/<framework>/headless among others).
Add `suppressHydrationWarning` to all four <a> tags in
OpsPlatformCTA (card / inline / tile / link-inside-card) and the
single <a> in SignupLink. Scoped to those anchors so genuine
mismatches elsewhere still surface.
Railway logs surfaced 15+ distinct `[docs-render] snippet missing for
component …` warnings post-cutover. Root causes split three ways:
1. Registry drift. `docs-render.tsx::SNIPPET_MAP` had drifted from
`mdx-registry.tsx::STUB_PARTIAL_MAP` — InstallSDKSnippet,
InstallPythonSDK, RunAndConnect (+ Snippet alias), CopilotUI,
LandingCodeShowcase, the four CopilotCloudConfigure* /
SelfHostingCopilotRuntime* keys, plus MigrateTo / MigrateToV /
ToolRenderer aliases were all missing. Add them.
2. Code-fence false positives. The inliner regex matched
`<Component />` references inside ```tsx``` example blocks (e.g.
`<CopilotChat />`, `<CopilotSidebar />` shown as runtime usage,
`<WeatherCard />` / `<YourApp />` placeholders). Make the regex
fence-aware via a new `isInsideCodeFence(content, offset)` helper
that tracks both fenced blocks (any indentation — MDX inside
`<Step>` is routinely 8-space-indented) and inline-code spans.
3. JSX-prop runtime components. `icon={<PaintbrushIcon />}` etc. are
registered in `mdx-registry.tsx::docsComponents` as real React
components, not snippets. Add an `Icon`-suffix heuristic: lucide
icons used as JSX props are silenced. CopilotChat / CopilotSidebar
in prose backticks are now silenced by (2) instead of the prior
ad-hoc allowlist, which is removed.
Verified clean across the previously-warning pages — /programmatic-control,
/runtime-server-adapter, /frontend-tools, /generative-ui/tool-rendering,
/prebuilt-components, /deploy/agentcore, /auth — all 0 docs-render
warnings post-change. Unified-registry refactor (single source of
truth) is the right next step but out of scope for this cutover-blocker
pass.
inlineSnippets() in docs-render.tsx maintains its own SNIPPET_MAP
separate from mdx-registry.tsx. The two registries drifted: mdx-registry
gained `UseAgentSnippet: "use-agent.mdx"` but docs-render didn't. As a
result every page that imports `<UseAgentSnippet />` (the shared
programmatic-control snippet, used by all integration overrides) logged
"[docs-render] snippet missing for component UseAgentSnippet" at SSR
time, and the snippet content was missing from non-MDX surfaces
(search-index, llms.txt, OG metadata).
Add the missing entry so the inliner can resolve it.
Separately, the inliner regex isn't code-fence-aware, so `<CopilotChat />`
usages inside example code blocks (slots.mdx, threads.mdx, etc.) were
also flagged as missing snippets even though CopilotChat is a runtime
React component, not a snippet. Add a small allowlist of known React
components so the regex short-circuits on those without warning. A
fence-aware regex is the right architectural fix but out of scope here.
Confirmed via Playwright: /mastra/programmatic-control console drops
from 3 [docs-render] warnings to 0 after the change.
Sam Julien