Clarify the wrapper's role (it forces noStore:false because unstable_noStore is
unavailable in middleware/Edge). Pure rename across shell, shell-docs, and
shell-dashboard: definitions, middleware call sites, and tests. No behavior
change.
Non-functional cleanup pass on the showcase deploy-pipeline integration
branch. All changes are scoped to comment rot, log severity for already-
demoted runtime-config fields, length-aware env-name coalescing (a
deliberately-empty primary no longer masks a populated alternate), and
test-quality tightening. No production behavior change beyond the
specific items below.
Changes by area:
- shell/shell-dashboard/shell-docs runtime-config.ts: factor the
`process.env[primary] ?? process.env[alt]` chain into a shared
length-aware `readEnvPair` helper. The prior `??` form treated
`PRIMARY=""` as set, masking a populated alternate; the helper now
treats empty-string as unset and falls through to the alternate.
- shell-docs runtime-config.ts: demote the two recoverable URL fields
(`intelligenceSignupUrl`, `posthogHost`) from console.info to
console.warn. The `FATAL-CONFIG:` Sentry-alert prefix is preserved
only on the true sentinels; the demoted fields now clear prod log-
aggregation thresholds without raising ops alerts.
- All three shells' runtime-config.ts: prefix log lines with the shell
name (e.g. `[shell-docs runtime-config]`) so the shared log stream
identifies which shell emitted the line.
- shell-docs runtime-config-serialize.ts: rewrite the U+2028 / U+2029
RegExp arguments using six-character ASCII backslash-u escape
sequences (was: literal codepoints in the string arg). The literal
codepoints are line terminators that a formatter or editor could
silently strip, breaking the security-critical XSS escape. The
ASCII form is robust to any such pass.
- shell-docs use-google-analytics.test.ts: de-tautologize the hook-
order test. It now asserts `usePathname(` and `useEffect(` both
exist in the source, so deleting all hooks would fail the test
rather than trivially satisfying the early-return path.
- shell-dashboard baseline-types.test.ts: update the partner-count
expectation from 25 to 26 -- the 26th entry (Cloudflare) is a
legitimate integration that landed independently; the test was
stale and had nothing to do with this branch.
- scripts/resolve-verify-matrix.ts: drop the `FIX 7 --` plan-
internal prefix from a comment; keep the explanation.
- shell-docs/.env.example: correct the `NEXT_PUBLIC_SHELL_URL`
fallback claim (sentinel, not canonical prod host) and document
the remaining 7 consumed env vars with their FATAL/warn/silent
semantics so the example matches runtime-config.ts.
Skipped:
- C-SENTINEL-DEDUP (`http://ops.invalid` shared constant across
shell-dashboard's next.config.ts and runtime-config.ts): both
files are at different module levels (root vs src/lib) and the
string appears once in each; extracting to a shared module would
widen the diff into a refactor for marginal benefit. Skipped per
the spec's "if it widens diff awkwardly, skip" guidance.
- C-SSRTEST: already exhaustively covered. Each of the three shells
has an SSR placeholder test that exercises every URL field via
`new URL()` parseability and (for shell-docs) the analytics-key
empty-string semantics. Treated as a no-op.
Validation: shell + shell-dashboard + shell-docs runtime-config /
serialize / GA tests green; bin/showcase Ruby suite green (87 runs);
showcase/scripts resolve-verify-matrix + aggregate-build-results +
lint-rule-no-public-env green (79 runs).
Six fixes addressing CR findings on the Option-B runtime URL-injection migration:
1. SSR_PLACEHOLDER must be parseable URL sentinels — `new URL("")` throws on
SSR causing 500s for any consumer that constructs URLs from runtime-config
fields. Use `.invalid`-TLD sentinels (RFC 2606) for URL fields; analytics
keys stay empty string. Add `suppressHydrationWarning` on consumers that
render the placeholder server-side and the real value post-hydration
(integration-grid, page-actions popover).
2. Hook-order: move `usePathname()`/`useEffect` ABOVE the early-return in
use-google-analytics. Gate the effect bodies on `GA_ID` instead so React
sees a stable hook order across renders.
3. `readUrl`/`readKey` accept either bare or `NEXT_PUBLIC_*`-prefixed env
names via a fallback chain — covers both server-only and inlined-public
variable conventions without forcing a rename across deploy targets.
4. Extract `serializeRuntimeConfig` to `lib/runtime-config-serialize.ts` so
the OWASP-escape behavior (XSS via </script>, U+2028/U+2029 line-terminator
injection) can be unit-tested without importing the layout into vitest.
5. Reclassify `intelligenceSignupUrl`/`posthogHost` from FATAL-CONFIG to
info-level in shell-docs — these are optional integrations, not hard
wiring failures, so absence should not poison the error stream.
6. Comment-rot cleanup: drop "Option B", B12, "the bug we are fixing", fix
"four substrings"→"three substrings" miscounts, and refresh shell-docs
.env.example to describe the runtime-injection contract instead of a
stale next.config throw claim.
V1: shell + shell-docs `next build` succeeds (no Edge-runtime crash on
`unstable_noStore`).
V2: `OPS_BASE_URL=` shell-dashboard `next build` no longer throws —
`next.config.ts` is now a phase-aware function that emits a sentinel
destination at build time and throws only at start (PHASE_PRODUCTION_BUILD
from next/constants).
Tests: shell-docs 72/72, shell 12/12, shell-dashboard runtime-config 16/16
(pre-existing baseline-partner-count failure unchanged).
getRuntimeConfig() in each shell's runtime-config.client.ts threw when
typeof window === 'undefined'. But Next.js App Router executes 'use
client' component bodies on the SERVER during initial SSR, so any client
component that called getRuntimeConfig() in its render body 500'd the
page. shell-dashboard already had the fix.
Mirror shell-dashboard's pattern: return a typed SSR_PLACEHOLDER (empty
strings for URL/key fields; {} for shell-dojo whose RuntimeConfig is
empty) when window is undefined. Keep the loud throw when window IS
present but window.__SHOWCASE_CONFIG__ is missing — that's a genuine
wiring bug and should not be masked.
Updated shell-docs and shell client tests: replace 'throws on server'
case with 'returns SSR sentinel placeholder' assertion matching each
shell's RuntimeConfig shape. shell-dojo has no client test so verified
via tsc only.
Migrate the remaining shell-docs consumers of NEXT_PUBLIC_* env vars
off of process.env reads and onto the runtime-config readers:
- lib/providers/posthog-provider.tsx (client): the PostHog key is
pulled inside PostHogProvider so the value reflects the current
deploy's NEXT_PUBLIC_POSTHOG_KEY; empty string disables analytics
via the existing truthiness gates around init/capture
- lib/providers/scarf-pixel.tsx (client): pixel id read at render
time; empty string returns null (existing no-op behavior preserved)
- lib/hooks/use-google-analytics.tsx (client): GA tracking id read
at hook invocation; empty string short-circuits via the existing
`if (!GA_ID) return` guard
- middleware.ts (Edge): POSTHOG_HOST is now resolved per-request via
getRuntimeConfigEdge() (the Edge wrapper skips unstable_noStore()
since next/cache is unavailable there and middleware always runs
per-request anyway). Server-side POSTHOG_KEY is unchanged — it's
not a NEXT_PUBLIC_* var.
Migrate every consumer of NEXT_PUBLIC_BASE_URL / NEXT_PUBLIC_SHELL_URL
/ NEXT_PUBLIC_INTELLIGENCE_SIGNUP_URL in the shell-docs tree off of
process.env reads and onto the runtime-config readers:
- lib/sitemap-helpers.ts (server): getBaseUrl() now delegates to
getRuntimeConfig().baseUrl
- components/search-modal.tsx (client): reads shellHost once per
render and threads it into normalizeHref() + the integration href
builder; normalizeHref is now parameterized rather than closing
over a module-scope SHELL_HOST
- components/integration-grid.tsx (client): reads shellHost after
the framework-scoped early return so we never touch the client
reader on no-op renders
- components/ai/page-actions.tsx (client): getClientBaseUrl()
delegates to getRuntimeConfig().baseUrl; the local inline copy is
retained so a "use client" file doesn't reach into the Node-only
sitemap-helpers module
- components/react/signup-link.tsx + ops-platform-cta.tsx (client):
buildHref() reads the signup URL lazily inside the function body
so the URL reflects the current deploy's env
Module-scope reads of process.env.NEXT_PUBLIC_* are eliminated from
all six files — every URL is now resolved at render time from the
runtime-config object the root layout injects.
Add inline <script> tag as the first child of <head> that populates
window.__SHOWCASE_CONFIG__ with values read from process.env at request
time via getRuntimeConfig(). This is the server side of the Option B
runtime-injection plumbing — every shell-docs client component will
read its URLs/analytics keys from this object instead of compiled-in
NEXT_PUBLIC_* values, so a single built artifact can serve staging
and prod by changing Railway env vars.
The serializer escapes < (XSS guard against </script> breakout) plus
U+2028 / U+2029 (legal in JSON, illegal in JS string literals when the
page is parsed as text/javascript) per OWASP guidance. The regex
sources are constructed via new RegExp(String.fromCharCode(...)) to
sidestep the TypeScript tokenizer treating the literal codepoints as
line terminators inside /regex/ literals.
Drop in NODE_ENV writes via Record<string,string> cast in the server
test — modern @types/node marks NODE_ENV read-only, and the runtime
reader only inspects the string value.
Adds the server (runtime-config.ts) and client
(runtime-config.client.ts) runtime config readers for shell-docs as
the foundation of Option B's per-request URL/key resolution. The
server module reads from process.env at request time (gated by
unstable_noStore so callers are not statically prerendered); a thin
getRuntimeConfigEdge wrapper skips the cache opt-out for middleware
(Edge runtime cannot import next/cache). The client module reads
window.__SHOWCASE_CONFIG__ which the root layout will inject in the
next commit.
Red-green: verified the test files fail without the modules
(module-not-found) and pass once the modules land — 10/10 green.
Part of plan-B (showcase per-env runtime URL injection).
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.
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.
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.
## 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.
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.
## 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.
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"
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.
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 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.
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.
The tutorials section is retired post-cutover. Step-2 MDX (both ai-todo-app
and ai-powered-textarea) currently 500s in the SSR layer, surfacing across
all active framework slugs and in ~38 sitemap entries. Add wildcard 301s
in the redirect catalog so framework-scoped tutorial URLs land on that
framework's quickstart, and unscoped variants land on the docs root.
Covers all 21 canonical framework slugs (generated, authored, hidden) plus
the unscoped /tutorials and /tutorials/* paths. Slotted before the P1×/P2×
per-framework catch-alls so the more specific tutorial rule wins.
Resolves merge conflict in `showcase/shell-docs/src/components/mobile-top-nav.tsx`:
- v16 of fumadocs moved `SidebarTrigger` from
`components/layout/sidebar` to `components/sidebar/base` (this PR's
upgrade). Keep the v16 path.
- `main` added Calendar / Lightbulb icons + `usePostHog` import for the
expanded mobile CTAs (Get-Intelligence-free + Talk-to-Engineer pill).
Keep those — they're referenced by the file body.
Combined resolution = main's import set with v16's import path for
SidebarTrigger. Other auto-merged files (brand-nav, snippet,
mdx-registry, etc.) merged cleanly; typecheck passes.
CR Round 3 surfaced two more real bucket-(a) findings.
(1) `app/layout.tsx` theme-init script — When a user explicitly picks
the "system" theme via the next-themes API, the persisted value in
`localStorage.theme` is the literal string `"system"`, not absent.
The previous inline script only fell back to `matchMedia(...)` when
the value was unset (`!t`); for a system-mode user on a dark-
preferring OS, the script would skip the matchMedia branch (because
`t === "system"` is truthy), then skip the `.dark` class application
(because `t !== "dark"`), and the page would paint in light before
next-themes resolves post-hydration. The light-flash this script
exists to prevent. Extend the fallback condition to `!t ||
t === "system"` so the matchMedia path also handles the explicit-
system case.
(2) `lib/llm-text.ts` Snippet file headers — `resolveSnippet`
hardcoded `// <filename>` as the in-fence header regardless of the
snippet's language. For Python regions this emits `//` (integer
division — invalid syntax), for YAML / Bash / TOML it emits the
wrong comment marker, for JSON it emits literal `//` (no comments
allowed in spec JSON). An LLM ingesting `/llms-full.txt` sees what
looks like real code from the file but with a broken first line.
Add a `fileHeaderComment(language, text)` helper that picks the
right comment shape:
- `#` for Python / Bash / YAML / TOML / Ruby / R / Dockerfile / etc.
- `/* ... */` for CSS / SCSS / Less
- `<!-- ... -->` for HTML / XML / Markdown / MDX
- `-- ` for SQL
- empty (drop the header) for JSON / JSONC
- `//` for C-family (TS / JS / Java / Go / Rust / C# / etc.) — the
previous behavior, preserved as the default.
Apply across all three snippet emission paths (region, file, file
+ lines). Pass the language through to the helper; when the helper
returns empty (JSON case), skip the header line entirely so the
fenced block contains only the code.
Call-site enumeration:
- theme-init inline script — no external callers; the next-themes
ThemeProvider reads/writes localStorage on its own schedule, our
script only seeds the `.dark` class pre-hydration. Behavior change
is strictly additive (one extra matchMedia call when t === "system").
- `fenceFor` — unchanged signature.
- `fileHeaderComment` (new) — used only within `resolveSnippet`. Three
call sites, all in the same function, all updated.
- `resolveSnippet` — three return paths updated; output shape change
is invisible to all current callers (`renderPageToLlmText`,
`inlineSnippets`) which treat the return value as opaque markdown.
`getAllLlmPages` was silently dropping framework root pages from
`/llms.txt`. `walkMdx` strips trailing `/index` from yielded slugs, so
`integrations/<folder>/index.mdx` arrived as `slug === ""` — and the
`if (!slug) continue` guard in section 2 then skipped it. Result: LLM
crawlers walking `/llms.txt` never saw `/langgraph-python`,
`/built-in-agent`, etc., so the framework landing pages were invisible
to the LLM index even though they're the canonical entry points.
Treat empty slug as the framework root and emit it as the bare
integration URL (mirroring how sections 3 and 4 already handle
reference/ag-ui index pages). The `loadSlug` falls back to
`integrations/<folder>/index` so `loadDoc()` can still resolve the
source.
Two silent `catch {}` blocks in the same file were dropping read /
parse errors with no diagnostic — `readMetaFromFile` would mask
malformed YAML (page appears bare in `/llms.txt` with no signal to the
author) and `readSource` would mask filesystem errors (the body gets
quietly dropped by the route handler's `if (!body) continue` guard).
Add `console.error` with a `[llm-text]` prefix in both, matching the
pattern `readTitle` in `docs-render.tsx` already uses.
`findExistingMdx` in `llms-mdx/[[...slug]]/route.ts` had a `void
CONTENT_DIR;` dead statement with a comment promising a `CONTENT_DIR`
fallback that didn't exist — the `import { CONTENT_DIR }` was only
kept alive by that no-op. Remove the dead statement, drop the unused
import, and log when the path-traversal guard rejects a candidate (the
previous silent `continue` meant a typo'd slug just 404'd with no log
to correlate the request).
`llms.txt/route.ts` had a comment claiming "no explicit revalidate
directive — Next defaults to dynamic" directly above
`export const revalidate = false`. The directive is intentional (cache
the slow filesystem walk indefinitely on the server; let the
per-response Cache-Control header drive CDN/client freshness) — update
both `llms.txt` and `llms-full.txt` comments to explain the two-cache
layering instead of contradicting it.
Call-site enumeration:
- `getAllLlmPages` — used by `/llms.txt`, `/llms-full.txt`, and
`/llms-mdx` route handlers. No caller depends on whether framework
roots are present; widening the result set is purely additive.
- `readMetaFromFile`, `readSource` — file-local helpers; only
`getAllLlmPages` / `renderPageToLlmText` call them. New `console.error`
is additive.
- `CONTENT_DIR` (removed import) — confirmed via grep that
`/llms-mdx/[[...slug]]/route.ts` no longer references the symbol;
`loadDoc` is still imported from the same module.
Tyler Slaton