## Summary
External QA flagged that Deep Agents and Agent Spec are documented in
shell-docs but neither has shipped as a showcase integration. Both have
orphaned MDX in the dead `src/content/docs/integrations/*/` tree (which
the framework router doesn't serve), and the live
`/whats-new/langgraph-deep-agents` page had a CTA pointing at
`/langgraph/deep-agents` which 404s.
This PR backports both as **live placeholder pages, hidden from sidebar
navigation and framework pickers**, ready to be revealed in nav when the
showcase integrations are built. It also re-points the broken CTA at the
new canonical URL and adds legacy URL redirects.
Supersedes PR #4832 (which only removed the CTA).
## What changed
### New live placeholder pages
- `/deepagents` — full Deep Agents documentation, content adapted from
the upstream `integrations/langgraph/deep-agents.mdx` (the
self-referential "promoted to top-level integration" Callout removed
since this *is* the destination now)
- `/agent-spec` — Agent Spec landing
- `/agent-spec/quickstart`
- `/agent-spec/langgraph`
- `/agent-spec/wayflow`
- `/agent-spec/human-in-the-loop`
All six new MDX files are at
`showcase/shell-docs/src/content/docs/{deepagents,agent-spec}/`.
### Hiding mechanism
The framework router (`[framework]/[[...slug]]/page.tsx`) falls through
to `UnscopedDocsPage` when `getIntegration(slug)` returns `undefined`.
Neither `deepagents` nor `agent-spec` is in `registry.json` (since
neither has showcase integration code), so they automatically take this
fall-through path and `loadDoc()` resolves the MDX. No registry entries
needed.
- Sidebar nav: pages are not listed in any `meta.json`, so
`buildNavTree()` (which iterates `meta.json` `pages` arrays) silently
omits them
- Framework picker / `<IntegrationGrid>`: pulls from `registry.json`,
which only contains integrations with manifests under
`showcase/integrations/`. Neither placeholder is in the registry —
neither surfaces in pickers
- Existing `<IntegrationGrid exclude={["agent-spec", ...]}>` calls
remain no-ops (the grid renders a static link, not a registry-driven
list) — no behavior change
### CTA fix
`whats-new/langgraph-deep-agents.mdx` CTA now points at `/deepagents`
(was: `/langgraph/deep-agents`, 404).
### Redirect entries
Two new `LEGACY_CHAINS_EXACT` rules in `src/lib/seo-redirects.ts`:
- `L12`: `/langgraph/deep-agents → /deepagents`
- `L13`: `/langgraph-python/deep-agents → /deepagents`
Together these catch the legacy-slug upstream URL (`/langgraph/...`) and
the post-slug-rename path that the existing rename system would
otherwise produce (`/langgraph-python/...`). Both land on the canonical
placeholder.
No new redirects are needed for Agent Spec — `agent-spec` is already in
the `FRAMEWORKS` array, and the subpath-rename redirects it generates
now resolve to live placeholder pages rather than 404s.
## Future evolution
When the Deep Agents or Agent Spec showcase integration ships:
1. Add a manifest at `showcase/integrations/{integration}/manifest.yaml`
(or wherever new integrations register)
2. The registry regenerates, the framework picker surfaces the
integration, sidebar nav surfaces its pages
3. The placeholder content can be replaced with real demo-linked content
and the redirects remain valid
## Files changed
- `showcase/shell-docs/src/content/docs/deepagents/index.mdx` (new, 370
lines)
- `showcase/shell-docs/src/content/docs/agent-spec/index.mdx` (new, 54
lines)
- `showcase/shell-docs/src/content/docs/agent-spec/quickstart.mdx` (new,
509 lines)
- `showcase/shell-docs/src/content/docs/agent-spec/langgraph.mdx` (new,
114 lines)
- `showcase/shell-docs/src/content/docs/agent-spec/wayflow.mdx` (new,
114 lines)
-
`showcase/shell-docs/src/content/docs/agent-spec/human-in-the-loop.mdx`
(new, 119 lines)
-
`showcase/shell-docs/src/content/docs/whats-new/langgraph-deep-agents.mdx`
(1 line — CTA repoint)
- `showcase/shell-docs/src/lib/seo-redirects.ts` (15 lines — two new
redirect entries)
## Test plan
- [ ] `/deepagents` renders the Deep Agents documentation
- [ ] `/agent-spec`, `/agent-spec/quickstart`, `/agent-spec/langgraph`,
`/agent-spec/wayflow`, `/agent-spec/human-in-the-loop` all render
- [ ] Neither page appears in the sidebar nav on any framework
- [ ] Neither integration appears in the framework picker or in
`<IntegrationGrid>` listings
- [ ] `/whats-new/langgraph-deep-agents` CTA points at `/deepagents` and
lands on the placeholder
- [ ] `/langgraph/deep-agents` 301s to `/deepagents`
- [ ] `/langgraph-python/deep-agents` 301s to `/deepagents`
## Hook bypass
Pre-commit `test-and-check-packages` fails on a pre-existing
`@copilotkit/web-inspector` telemetry test on main (jsdom not installed
in fresh worktrees). Commits used
`LEFTHOOK_EXCLUDE=test-and-check-packages` to bypass only that one hook;
lint-fix, commitlint, sync-lockfile, and check-binaries all ran and
passed.
The DocsLayout sidebar uses `position: fixed` with hardcoded `top: 76px / 96px`
overrides at md/xl. When the rotating banner is visible, body-flow `Banners` +
`BrandNav` shift down (banner ~54px + BrandNav 68/88px), but the fixed sidebar
stays pinned — so the "LangGraph (Python)" framework picker overlaps the
BrandNav row.
Wrap both top overrides in `calc(... + var(--fd-banner-height, 0px))` so the
sidebar slides down by the banner's height when shown and snaps back when
dismissed. `Banners` already writes that variable on `<html>` (54px / 0px),
and `MobileTopNav` uses the same pattern.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The whats-new/langgraph-deep-agents CTA pointed at /langgraph/deep-agents,
which 404s. With the placeholder now live at /deepagents, re-point the
CTA there and add LEGACY_CHAINS_EXACT entries so old upstream URLs
(/langgraph/deep-agents and /langgraph-python/deep-agents) redirect to
the canonical /deepagents placeholder.
Supersedes the standalone CTA-removal PR #4832; this commit consolidates
that fix into the backport PR so a single PR covers all Deep Agents
URL wiring.
Adds upstream Deep Agents (/deepagents) and Agent Spec (/agent-spec/*)
docs as live placeholder pages in shell-docs. The pages are reachable
by URL but absent from the sidebar nav and framework pickers — when the
showcase integrations are wired in (PDX-167 follow-ups), the docs are
already in place and just need to be revealed in nav.
Hiding mechanism: the new MDX files live at top-level slugs under
src/content/docs/ but are NOT listed in the root meta.json `pages`
array. buildNavTree() in docs-render.tsx uses meta.json as the source
of truth when present, so unlisted files are silently absent from the
sidebar. The framework picker is also unaffected — registry.json is
generated from showcase/integrations/*/manifest.yaml (neither
integration exists yet), so the picker has no entry for them.
URLs:
- /deepagents — promoted from langgraph/deep-agents
- /agent-spec, /agent-spec/quickstart, /agent-spec/langgraph,
/agent-spec/wayflow, /agent-spec/human-in-the-loop
Content is copied from the dead src/content/docs/integrations/ tree
(already adapted to shell-docs conventions) with the self-referential
"Deep Agents has been promoted" callout removed from the new
/deepagents landing page. agent-spec/index.mdx is a new plain-markdown
adaptation of the upstream FrameworkOverview-driven page (the upstream
component is a no-op stub in shell-docs).
Verification: existing <IntegrationGrid exclude={[...,"agent-spec",...]}>
calls remain no-ops since IntegrationGrid renders a static link rather
than iterating the registry. seo-redirects.ts already lists agent-spec
in its FRAMEWORKS set; the generated S-class subpath renames continue
to target slugs that exist in this backport (/agent-spec/prebuilt-
components, /agent-spec/programmatic-control, etc. — same shape as
the rest of the registered frameworks).
Refs PDX-167
Two surgical pickups from the closed auto-sync PR #4805, applied directly
to shell-docs (the post-cutover canonical authoring location).
1. telemetry/index.mdx — collapse three opt-out paragraphs into a single
tighter sentence, and add the Inspector dev-console to the scope of
what COPILOTKIT_TELEMETRY_DISABLED covers.
2. snippets/use-agent.mdx — three independent improvements:
- `agent.id` → `agent.agentId` (current v2 API field name).
- New Callout pointing out that useAgent({ agentId }) is required
when not using CopilotKit Cloud's public access/license key.
- subscribe() useEffect cleanup gets `[agent]` in the deps array
(exhaustive-deps; prevents stale subscriber after the agent
reference changes).
Skipped from #4805: `@copilotkit/shared/v2` → `@copilotkit/shared` rewrite
in the same file. The `/v2` subpath was deliberately restored as the V2
canonical-form import — leaving it alone here.
Note: committed with --no-verify because the pre-commit hook runs
`pnpm run test` which still fails 22 tests in web-inspector telemetry
(window.localStorage.clear in vitest/jsdom env) after the recent revert
of the polyfill fix. Pre-existing on origin/main; unrelated to this
docs-only change.
The Fumadocs UI adoption PR (#4898) removed highlight.js + rehype-highlight
from package.json and replaced the bespoke nav rendering with Fumadocs's
DocsLayout + page-tree bridge, but four stale call sites survived the
sweep and broke the Docker build of showcase-shell-docs on main:
- agentcore-command-tabs.tsx still imported the now-uninstalled
highlight.js to syntax-highlight inline bash. Rebuilt the body on
Fumadocs's DynamicCodeBlock so the AgentCore command tabs share Shiki
+ the native copy-button chrome with every other code block.
- [[...slug]]/page.tsx still defined nodeKey + OverviewNavItem, which
reach for the removed SidebarLink. The functions are unreachable —
DocsOverview renders the sidebar via ShellDocsLayout(tree=pageTree) —
so they were deleted outright instead of patched.
- docs-page-view.tsx had the same dead renderNavItem helper; deleted.
- brand-nav.tsx referenced ExternalLinkIcon without importing it.
Verified with `next build` of showcase/shell-docs locally: all 30 static
pages generate cleanly and no Webpack/TS errors remain.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Rebuild the shell-docs chrome on top of Fumadocs UI primitives and ship the
visual polish pass that replaces the legacy custom chrome.
- Fumadocs adoption: route every docs page (home, framework-scoped, ag-ui)
through a shared ShellDocsLayout that wraps DocsLayout / DocsPage with
the project's nav slot, sidebar config, scroll preserver, and content
wrapper. Swap custom tabs/code-block components for Fumadocs's Tabs,
CodeBlock, Pre, CodeBlockTabs, DynamicCodeBlock — Snippet and DemoSource
now share the same chrome as authored fenced blocks.
- Syntax highlighting: replace rehype-highlight + hand-rolled hljs CSS
with Fumadocs's Shiki-based rehypeCode in all three MDX renderers and
in mdx-registry-loader. A tiny `transformerMeta` Shiki transformer
surfaces fence title= / language as data-attrs so MdxCodeBlock can
render the file-path figcaption + floating copy button.
- Sidebar: floats on all four viewport edges (rounded-2xl, 0.75rem inset,
light-gray border), framework picker pill is rounded-xl with symmetric
padding above/below, sticky picker bg matches the panel surface.
Section headers render in normal caps (no more uppercase shouting), with
scroll position preserved across navigations via SidebarScrollPreserver.
- Navbar: bg flips to `--bg`, full-width inset matches the sidebar,
search trigger drops its border and the entire right-wing pill is the
click target.
- Code chrome: figure surface forced to plain white in light and the
matching dark in dark, shadow stripped, figcaption divider uses
`--border` (was `currentColor` from `text-fd-muted-foreground`). Scoped
the `.reference-content code` chip-bg rule to `:not(pre)` so block
code bodies no longer pick up the gray inline-chip background.
- Content area: 49px (3.0625rem) of left/right padding so the article
column has visible breathing room from both the floating sidebar and
the viewport edge.
- IA: meta.json restructure for /docs (Build Generative UI section,
controlled/declarative/open-ended folders, A2UI lifted to its own
folder with an index page, Migrate moved under Other), Concepts content
rewrite, snippet/region cleanups.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
## Summary
Four small rendering-pipeline fixes from a post-cutover QA pass that
diagnosed copy-malformation reports on specific code blocks. Single PR
because the fixes are each tiny and form a coherent "render/copy parity"
group.
## Fixes
### 1. `MdxCodeBlock` now dedents fence-in-JSX bodies
**Problem**: When a `python` / `tsx` etc. fence sits inside JSX (e.g.
`<Tab><Step>...</Step></Tab>`), MDX preserves the JSX nesting's leading
whitespace on every body line. `extractText` recovers it faithfully, but
the copy payload comes out with 16-24 leading spaces per line — user
pastes invalid Python with top-level statements indented.
**Fix**: Added a private `dedent()` helper in
`src/components/mdx-code-block.tsx` that measures min leading-whitespace
across non-blank lines and strips it. Both the visible `<pre>` body and
the `<CopyButton>` payload use the dedented text, so rendered == copied.
Column-0 fences (the common case) keep full syntax highlighting
unchanged; JSX-nested fences fall back to plain `<code>` after dedent.
Fixes the reports against AG-UI middleware, A2A middleware section 3,
MS-Py Quickstart `main.py` and `route.ts`.
### 2. Framework route renders post-features content with parity
**Problem**: PR #4830 wired `rehypeCodeMeta` + `pre: MdxCodeBlock` into
`docs-page-view.tsx` and the AG-UI route, but the `FrameworkRootPage`
(line 451 of `[framework]/[[...slug]]/page.tsx`) renders its
after-features MDX with bare `rehypeHighlight` and no `pre` override. So
features-page MDX on framework-scoped routes loses the file-path
caption, copy button on bare fences, and dedent behavior.
**Fix**: Imported `MdxCodeBlock` + `rehypeCodeMeta` into that route and
added them to the `MDXRemote` config — symmetric with
`docs-page-view.tsx`.
### 3. `display-only.mdx` fence closers fixed
**Problem**: Lines 30 and 53 closed `tsx` fences with **four** backticks
instead of three. CommonMark requires matching counts — fences never
closed, copy payload grabbed subsequent JSX tags + adjacent prose.
**Fix**: Two single-character edits, fences now balance.
Note: this specific bug was also caught by @Abubakar-01 in #4862 —
including it here so the closing of #4862 doesn't leave the bug behind.
### 4. Deduplicate `<Callout>` on `tool-rendering.mdx`
**Problem**: Identical `<Callout type="info">` blocks at lines 17-19 and
23-25 (verified byte-identical). Copy-paste artifact making the page
look messy and probably contributing to the QA verdict of "Missing
imports, Unclear how to integrate".
**Fix**: Removed the duplicate at lines 23-25; kept the first occurrence
(before `<InlineDemo>` — natural callout-then-demo order). The other 2
`<Callout>` matches in the file are different blocks (free-course,
name-must-match).
## Files changed
```
src/app/[framework]/[[...slug]]/page.tsx | 21 ++++++++-
src/components/mdx-code-block.tsx | 51 +++++++++++++++++++++-
src/content/docs/generative-ui/tool-rendering.mdx | 4 --
src/content/docs/generative-ui/your-components/display-only.mdx | 4 +-
4 files changed, 70 insertions(+), 10 deletions(-)
```
## Test plan
- [ ] Visit `/{framework}/agentic-protocols/a2a` — copy the middleware
code block in section 3, paste into an editor: should be column-0 valid
TypeScript (no leading 4-sp indent)
- [ ] Visit
`/{framework}/integrations/microsoft-agent-framework/quickstart` — copy
`main.py`, paste: valid Python with no 24-sp leak
- [ ] Visit
`/{framework}/integrations/microsoft-agent-framework/quickstart` — copy
`route.ts`, paste: clean
- [ ] Visit `/{framework}/agentic-protocols/ag-ui-middleware` — copy
button + file path caption present (parity with unscoped route)
- [ ] Visit `/generative-ui/your-components/display-only` — Tabs render
correctly, copy works on both `page.tsx` and `chart.tsx` tabs
- [ ] Visit `/generative-ui/tool-rendering` — single Callout at the top,
not duplicated around the InlineDemo
- [ ] No regression on column-0 fences (e.g. `/auth`, `/react-native`):
syntax highlighting still works, copy/caption unchanged
- [ ] Bundler clean: `npx tsx showcase/scripts/bundle-demo-content.ts`
(697 demos)
- [ ] Typecheck: `npx tsc --noEmit` in `showcase/shell-docs/` (was clean
against current main)
## Verification done
- Typecheck: pass
- Bundler: pass (697 demos, no MDX errors)
- Sample dedent input/output on a 24-sp body: column-0 output as
expected
## Hook bypass
Pre-commit `test-and-check-packages` and `commitlint` bypassed via
`LEFTHOOK_EXCLUDE` (pre-existing web-inspector test failure on main +
commitlint binary not installed in worktrees). Lint-fix, lockfile-sync,
check-binaries all ran and passed.
Section 3 "Configure the A2A middleware" had a literal ... ellipsis where
the imports should go, and the code block ended at runtime definition
with no POST handler — pasted code would not compile. Add the imports
the block actually uses (HttpAgent, A2AMiddlewareAgent, CopilotRuntime,
ExperimentalEmptyAdapter, copilotRuntimeNextJSAppRouterEndpoint,
NextRequest) and the canonical Next.js App Router POST handler that
hands requests to the runtime. Pattern matches the ms-agent-framework
quickstart route.ts.
Consolidates four QA findings from the post-cutover rendering pipeline:
- MdxCodeBlock now dedents fence-in-JSX bodies before passing the copy
payload to <CopyButton>. Fences nested inside <Tab>/<Step>/<Tabs> were
reaching the clipboard with 16-24 leading spaces per line (invalid
Python / TS on paste). The visible <pre> body is dedented in lockstep
so rendering matches what's copied.
- Wires rehypeCodeMeta + pre: MdxCodeBlock into the framework-root
after-features MDX renderer, achieving parity with docs-page-view.tsx.
Previously bare rehypeHighlight left these blocks without copy
buttons or file-path captions.
- Closes the two fences in display-only.mdx with three backticks instead
of four, so the fences actually terminate and copy doesn't grab
adjacent JSX/prose.
- Removes a copy-paste-duplicated <Callout> on tool-rendering.mdx
(kept the first occurrence, dropped the post-InlineDemo duplicate).
The // @endregion[reasoning-block-render] comment was indented inside the
Chat function body, causing the rendered docs snippet to omit the final
closing brace — a visible syntax error. Moves the marker to after the }
in all 16 agentic-chat-reasoning/page.tsx files.
Also wraps the custom-reasoning snippet in reasoning.mdx in a two-tab
block so the ReasoningBlock import in page.tsx links directly to the
reasoning-block.tsx component definition in the adjacent tab.
## Summary
Restores per-framework introduction pages at `/<canonical-slug>` for the
13 third-party integrations. Pages render via a single
`<FrameworkOverview>` component driven by per-framework TypeScript data
records, with per-variant link rewriting and an MDX escape hatch for the
three frameworks that need post-features content.
PostHog shows these intros (under their legacy slugs on the previous
docs surface) drew ~56K external visits over 90 days — 1.3–2× the
traffic of their corresponding quickstarts in 13 of 14 cases, with ~8.3K
organic-search landings. Shipping shell-docs without them would have
left meaningful SEO and acquisition surface dark.
## What's included
- Data-driven `<FrameworkOverview>` component ported from legacy docs/,
with plain `<button>` + Tailwind CTAs (no shadcn / CVA / clsx /
radix-slot dragged into shell-docs).
- 13 per-framework data records under `src/data/frameworks/`
(langgraph-python, google-adk, ms-agent-dotnet, a2a, strands,
pydantic-ai, mastra, agno, ag2, agent-spec, crewai-crews, deepagents,
llamaindex), aliased to cover variant slugs (langgraph-typescript,
langgraph-fastapi, ms-agent-python).
- Three `after-features.mdx` escape hatches (ms-agent-dotnet, ag2,
agent-spec) for content that doesn't fit the structured CTA shape.
- Three-tier resolution in `app/[framework]/[[...slug]]/page.tsx`: data
record → MDX index → 404. Also recognizes docs-only integrations (a2a,
agent-spec, deepagents) that have docs content but no demo package in
`showcase/integrations/`.
- `"index"` slug rewrite in `buildNavTree` +
`buildFrameworkOverridesNav` so meta.json `"index"` entries resolve to
`/<framework>` rather than `/<framework>/index`.
- `mergeFrameworkNav` hoists the Introduction to position 0 of the
sidebar, above the global root nav — not buried in the per-framework
section.
- Per-variant link rewriting inside `<FrameworkOverview>`: when
langgraph-typescript renders the shared langgraph data record,
Quickstart / Learn more / Live demo / feature-viewer URLs all route
within `langgraph-typescript`, not the python primary.
- `built-in-agent` is the default framework and the docs root `/` is its
overview, so `/built-in-agent` 308s to `/` and no separate Introduction
sidebar entry is rendered for it.
- `next.config.ts` allows `cdn.copilotkit.ai` in `images.remotePatterns`
for banner videos, architecture diagrams, and the CopilotKit logo.
- `Blocks` lucide icon stub added to the MDX component registry —
referenced by both built-in-agent's index.mdx and the shared
`premium/headless-ui.mdx` snippet.
## Test plan
- [ ] `/langgraph-python`, `/google-adk`, `/ms-agent-dotnet`, `/a2a`,
`/strands`, `/pydantic-ai`, `/mastra`, `/agno`, `/ag2`, `/agent-spec`,
`/crewai-crews`, `/deepagents`, `/llamaindex` render the
FrameworkOverview with correct hero copy, video, supported features,
architecture asset, live demos, and CTA.
- [ ] `/langgraph-typescript`, `/langgraph-fastapi`, `/ms-agent-python`
render the aliased intro and every CTA stays on the variant's slug
(Quickstart → `/langgraph-typescript/quickstart`, not
`/langgraph-python/quickstart`).
- [ ] `/built-in-agent` returns 308 to `/`.
- [ ] Legacy slug redirects still work: `/langgraph`, `/adk`,
`/aws-strands`, `/microsoft-agent-framework`, `/crewai-flows` all 301 to
their canonical slugs.
- [ ] Sidebar on every framework page shows "Introduction" at position
0, above the global root nav sections.
- [ ] `pnpm run build` in `showcase/shell-docs` succeeds.
The four pages all had the same shape problem: prose followed by
<IntegrationGrid>, which hides on framework-scoped routes via
useFramework() -> null. On /<framework>/<slug> URLs the picker
disappears and the page truncates to a content-less heading.
Add InlineDemo + Snippet + FeatureIntegrations blocks above the picker
so framework-scoped routes still render demo content:
- interactive.mdx: cell gen-ui-interrupt, regions
frontend-useinterrupt-render and backend-interrupt-tool.
- state-rendering.mdx: cell shared-state-streaming, regions
frontend-use-coagent-state and state-streaming-middleware.
- display.mdx: cell gen-ui-tool-based, region bar-chart-renderer.
Drop the hardcoded '## Choose your Integration' heading
(IntegrationGrid renders its own '<h2>Choose your AI backend</h2>').
- your-components/display-only.mdx: same fix as display.mdx.
Mirrors the wiring pattern in frontend-tools.mdx and the slot-2 fix
for shared-state.mdx.
Mirror the frontend-tools.mdx shape so /shared-state and framework-scoped
routes like /google-adk/shared-state render meaningful code examples
instead of ending with a content-less 'Get started by choosing your AI
backend' heading (the IntegrationGrid hides itself once a framework is
selected).
- Preserve the existing 'What is shared state?' and 'When should I use
this?' prose, ImageZoom, and OpsPlatformCTA verbatim.
- Add Reading / Writing / UI render sections driven by Snippet regions
from the shared-state-read-write demo (use-agent-read, use-agent-write,
notes-card-render).
- Add a Streaming overview pointing at the shared-state-streaming demo's
state-streaming-middleware region, with a link to the existing
/shared-state/streaming sub-page for the full walkthrough.
- Add a Read-only context section linking to the existing
/shared-state/agent-readonly orphan sub-page.
- Swap the trailing hardcoded heading for FeatureIntegrations +
IntegrationGrid so unscoped and scoped routes both terminate cleanly.
Two existing MDX pages reference lucide-react's <Blocks /> inside
<Card icon={...}> attributes — built-in-agent/index.mdx and the shared
snippet premium/headless-ui.mdx — but the docs MDX component registry
didn't stub it alongside Sparkles, Wrench, Server, Plug, ArrowLeftRight,
Cpu, BookA, and Cog. Both pages rendered fine pre-cutover (the BIA
intro was hidden behind a hardcoded splash and the shared snippet was
unused), so the gap is only visible now that the framework-root route
exercises both surfaces.
Two related next.config tweaks for the framework intro pages:
1. images.remotePatterns allows cdn.copilotkit.ai so next/image stops
throwing 'hostname not configured' for banner videos, architecture
diagrams, and the CopilotKit color logo embedded in every
FrameworkOverview data record.
2. 308 redirect /built-in-agent → / since built-in-agent is the
default framework and the docs root is its overview. Without the
redirect, /built-in-agent rendered a separate intro and the
sidebar carried a redundant Introduction link.
Adds "index" as the first page in 13 integration meta.json files (all
except built-in-agent) so the framework intro page appears at the top
of the left sidebar. Pairs with buildNavTree's "index"-slug rewrite
which resolves "index" to the bare /<framework> URL, and with
mergeFrameworkNav's hoist which places this entry above the global
root nav.
For the 12 integrations whose Getting Started section had only the
intro under it, the now-empty section header is dropped. For
deepagents (Getting Started also has quickstart) the section header
stays after Introduction.
built-in-agent and deepagents previously had no meta.json (sidebar
fell through to filesystem order); a new meta.json is added for each.
built-in-agent's omits "index" because /built-in-agent redirects to
the docs root rather than rendering a separate intro.
Replaces the hardcoded FrameworkLandingPage splash with a three-tier
resolution at /<framework>:
1. frameworkOverviews[slug] exists → render <FrameworkOverview> with
the data record (plus an optional after-features.mdx slot for the
three frameworks that need one).
2. integrations/<folder>/index.mdx exists → render through loadDoc /
DocsPageView.
3. otherwise notFound().
Recognizes docs-only integrations (a2a, agent-spec, deepagents) that
have docs content but no showcase/integrations/<slug>/ demo package —
previously the registry check sent them to UnscopedDocsPage and they
404'd at /<slug>.
Adds an "index" slug rewrite in buildNavTree and
buildFrameworkOverridesNav so meta.json "index" entries resolve to
the bare /<framework> URL rather than /<framework>/index.
Hoists the framework's Introduction (slug "") to position 0 of the
merged sidebar so users see it above the global root nav rather than
buried inside the per-framework section. RenderNav and sidebar-link
pass an empty slugPath through for active-state matching at the root.
One TS record per integration (canonical slug): name, icon key, hero
copy, banner video, three supported-feature cards, architecture asset,
live-demo iframes, optional structured CTA. The aggregator
src/data/frameworks/index.ts exports the slug-keyed map consumed by
the framework-root route.
Three frameworks (ms-agent-dotnet, ag2, agent-spec) have post-features
content that doesn't fit the structured cta field (Resources links, a
Callout, an Agent Spec how-to body). Each ships a sibling
after-features.mdx loaded into the FrameworkOverview's afterFeatures
slot when hasAfterFeaturesMdx is true.
LangGraph variants (langgraph-typescript, langgraph-fastapi) and
ms-agent-python alias the same record as their primary variant —
their content folders are shared and the legacy docs never
differentiated variants at the intro-page level. The component's link
rewriter keeps every CTA on the variant's own URL.
built-in-agent is excluded — it's the default framework and the docs
root '/' IS its overview page.
Ports the FrameworkOverview marketing layout from legacy docs/ with
data-driven icon resolution via a customIcons registry. The original
shadcn Button (CVA / clsx / tailwind-merge / @radix-ui/react-slot) is
deliberately not ported — its only consumer here is six marketing CTAs
and a demo toggle, all of which use plain <button> + inlined Tailwind
matching the existing copy-button.tsx convention. This keeps shell-docs
out of the workspace lockfile and avoids the latent gray-matter /
js-yaml-v4 override that fires under workspace pnpm but not under
prod's npm install in the Dockerfile.
The component accepts a currentFramework prop and rewrites any
embedded slug in the data record's links (guideLink, featuresLink,
per-feature documentationLink / demoLink, tutorialLink) to that slug
— so when langgraph-typescript or langgraph-fastapi alias the
langgraph-python record, every CTA still routes within the user's
selected variant. Covers internal paths ("/<slug>/...") and
feature-viewer URLs ("feature-viewer.copilotkit.ai/<slug>/...").
Adds A2AIcon and AgentSpecMarkIcon as new icon components; extends the
existing framework-icons module with a DeepAgentsIcon and a customIcons
barrel typed by IconKey.
Type contracts for the data-driven framework intro pages. Optional
fields cover observed variance across the 13 in-scope integrations:
a2a omits bannerVideo, crewai-flows uses architectureVideo instead of
architectureImage, llamaindex's only feature lacks a videoUrl.
Neither app had a favicon configured locally, so the browser tab
showed the generic globe icon. Drop the canonical copilotkit.ai
favicon (3-image .ico, 16×16 + 32×32) into each app's app/ directory
so Next.js auto-serves it via its file-system convention. Same asset
on both surfaces.
## Label
"Talk to Our Engineers" → "Talk to an Engineer" everywhere it appears
(button text, aria-labels, mobile drawer entry, source comment).
## Desktop pill (≥1100px)
- Gradient fill (indigo-500/90 → purple-500/90 at rest, full at hover)
- Soft shadow lift on hover
- Shimmer animation: a translucent white stripe slides across via an
::after pseudo-element on hover (overflow-hidden + after:translate-x
transition over 700ms). Replaces the earlier scale-on-hover.
- Breakpoint lowered from 1400px → 1100px so the pill is visible at
most laptop widths where there's plenty of room
## Compact calendar icon (md → 1099px)
- New second button rendered alongside the pill, visible only when
the rest of the right cluster is icon-only (768–1099px)
- Same gradient + shimmer treatment in a 36×36 rounded-full button
- Inline calendar SVG (matches the Lucide calendar shape)
## Free Developer Access — shell-docs parity with docs/
- Added as a text link in shell-docs' LEFT_LINKS (mirrors the existing
docs/ pattern); cloud icon on the right cluster now hands off to it
at ≥1100px
- Visibility transitions on both surfaces realigned to 1100px so the
cloud↔text and calendar↔pill flips happen at the same boundary
- whitespace-nowrap on LEFT_LINKS label spans so long labels like
"Free Developer Access" don't wrap when the nav gets tight
## Mobile drawer
- docs/: add a Talk-to-Engineer button at the top of MobileSidebar
(was missing entirely). Tracks `talk_to_us_clicked` with
location: docs_navbar_mobile.
- shell-docs: move the existing Talk-to-Engineer button to the top of
the drawer column so it's the first thing readers see.
The right-rail TOC scraped headings from raw MDX source, so framework-
gated pages like /auth surfaced every per-framework variant's H2/H3
simultaneously even though only one variant's body rendered. Four
duplicate Frontend/Backend pairs appeared on the auth page TOC.
Add filterFrameworkScopedBlocks() in lib/toc.ts that mirrors the
runtime evaluation in components/when-framework-has.tsx: keep
<WhenFrameworkHas flag=X equals=Y> only when integration[X] === Y,
keep absent blocks only when the flag is null/missing, and strip
everything when no framework is resolved. docs-page-view.tsx applies
this filter to the MDX source before extractHeadings(), so the TOC
lists exactly the headings that actually render.
Flat-only — matches the runtime component, which is also single-level.
The Quickstart QA report flagged code blocks reading as black-on-black
in dark mode. Cause: `globals.css` imported `github-dark-dimmed.css`
gated on `prefers-color-scheme: dark`, but shell-docs's theme toggle
flips a `.dark` class on <html> independent of OS preference. A user
on a light OS who clicked the dark toggle ended up with the dark
chrome (page bg, code-block bg via CSS vars) but the LIGHT hljs token
colors — the symptom the report described.
Drop the media-query @import and inline the github-dark-dimmed token
colors below, scoped to `.dark`. Source: highlight.js's own
github-dark-dimmed stylesheet. Also force `.hljs { background: transparent }`
so the upstream `#fff` background no longer punches white rectangles
through our themed `var(--bg-surface)` surfaces.
Adds `.reference-content .mdx-code-block` styling so the new `pre`
override's figure chrome wins over the global `.reference-content pre`
border/shadow/padding rule and doesn't double-up.
Plugs the new `pre` override and rehype plugin into the two places shell-docs
renders MDX:
- `DocsPageView` (the shared component behind /docs/* and /<framework>/*)
- `app/ag-ui/[[...slug]]/page.tsx` (AG-UI catch-all)
The components map now sets `pre: MdxCodeBlock`, and `rehypeCodeMeta` is
appended after `rehypeHighlight` in `options.mdxOptions.rehypePlugins`.
Order is load-bearing — the meta plugin reads the `language-<name>`
className that highlight pushes onto the `<code>` element.
QA on the Quickstart pages flagged that triple-fenced code blocks (the
ones authored as plain ```python or ```bash in MDX) had no copy button
and no filename caption, even when the fence carried a `title=` meta.
<Snippet> and <DemoSource> already had both, but the rehype-highlight
pipeline that handles raw fences dropped the metastring on the floor
and produced a bare <pre><code>.
This adds a small rehype plugin (`rehypeCodeMeta`) that runs after
rehype-highlight and copies the fence's `title="..."` and resolved
language onto the parent <pre> as data-attrs, and an `MdxCodeBlock`
client component used as the `pre` override in both MDX renderers
(`DocsPageView` and the AG-UI catch-all page). The wrapper reuses the
existing `<CopyButton>` so visual treatment matches <Snippet> exactly.
Skips the test-and-check-packages pre-commit hook because the
@copilotkit/web-inspector telemetry suite fails on main with a jsdom
`window.localStorage.clear is not a function` baseline error
unrelated to this change.
Replace each affected stub in `mdx-registry.tsx` with the new
`stubWithPartial(name)` helper so a self-closing `<Inspector />`,
`<CopilotCloudConfigureCopilotKit />`, `<SelfHostingCopilotRuntimeCreateEndpoint />`,
etc. on a live MDX page renders the corresponding partial under
`src/content/snippets/` instead of an empty `<div>`.
The STUB_PARTIAL_MAP table colocates the stub-name → partial-path
mapping with the registry that consumes it. Entries cover both the
keys already present in `docs-render.tsx#SNIPPET_MAP` (so the
fallback works for prop-bearing invocations the regex can't match)
and the keys that were never in SNIPPET_MAP at all
(CopilotCloudConfigureCopilotKit*, SelfHostingCopilotRuntime*,
several Snippet-suffixed aliases).
EcosystemTable receives a real `data` prop on
`concepts/generative-ui-overview.mdx` and has no partial, so it is
replaced with a functional component that renders a 4-column table
of approach/examples/strengths/weaknesses from `props.data`.
The unused legacy `stub()` helper is removed; `stubWithPartial`
subsumes its prop-discard warning behavior.
Stub components in mdx-registry.tsx historically rendered as
`<div>{children}</div>`, which collapsed to an empty div for the
common `<Inspector />`, `<GenerativeUISpecsOverview />`,
`<CopilotCloudConfigureCopilotKit />`, etc. invocations on live MDX
pages — those self-closing references pass no children, so the
rendered page was empty under its heading.
The existing snippet-inlining pipeline in `docs-render.tsx` already
handles a subset of these via the SNIPPET_MAP regex, but only when
the JSX has no props (the regex matches `<Component />` and
`<Component components={...} />` and nothing else). Stubs invoked
with other props (e.g. `<EcosystemTable data={...} />`) or stubs
not listed in SNIPPET_MAP fall through to the registry.
This change introduces a new `mdx-registry-loader.tsx` that resolves
a partial by relative path under `src/content/snippets/`, runs the
same `inlineSnippets` + `convertTablesInJSX` preprocessing the page
renderer uses, and renders the partial via MDXRemote with the full
docsComponents map so nested JSX (Callouts, Tabs, etc.) inside the
partial composes correctly.
A new `stubWithPartial(name)` helper wires the relevant stub
components to that loader via STUB_PARTIAL_MAP. When children are
present the helper preserves the legacy passthrough; when children
are absent it renders the partial.
EcosystemTable has no partial — it takes a `data` prop on the only
page that uses it — so the stub is replaced with a real functional
component that renders the 4-column table from `props.data`.
Note: committed with --no-verify because the pre-commit hook runs
the full monorepo test suite, which has a pre-existing failure in
@copilotkit/web-inspector telemetry tests (window.localStorage.clear
is not a function) unrelated to this change and outside the
shell-docs scope this branch is allowed to touch.
Every integration quickstart in docs/ and showcase/shell-docs/ now opens with
a "Create a free account" step that points the reader at the Enterprise
Intelligence Platform before the framework path. Existing top-of-page
<OpsPlatformCTA> blocks on the six integrations that already had one are
left in place.
- New <SignupLink surface="docs_<int>_quickstart_step1">…</SignupLink> MDX
component in both apps. It mirrors OpsPlatformCTA's URL+UTM contract
(https://dashboard.operations.copilotkit.ai/ with the canonical docs
UTMs, picked up from NEXT_PUBLIC_INTELLIGENCE_SIGNUP_URL when set) and
fires the same PostHog event the other CTAs use:
posthog.capture("try_for_free_clicked", { location: surface }).
- Registered as an MDX global in:
docs/app/integrations/[[...slug]]/page.tsx
docs/app/(home)/[[...slug]]/page.tsx
showcase/shell-docs/src/lib/mdx-registry.tsx
- All 28 integration quickstart .mdx files now lead with a Step that uses
this component as an inline link inside a single sentence of prose —
no CTA card inside <Steps>.
The <TailoredContent> "Choose your starting point" / "How do you want to
get started?" selector is now wrapped in its own <Step> so it advances
the counter, and the inner CLI/manual paths render as steps 3, 4, 5, …
instead of 2, 3, 4, …. Applies to all 20 quickstarts that use the
picker.
- Indigo→purple gradient text on the Step 1 heading on both surfaces
(`.fd-steps > .fd-step:first-child h3` on docs/,
`.docs-steps > div:first-child h3` on shell-docs). Direct-child
combinator scopes it to the outer first Step so inner first-children
inside TailoredContentOption don't pick it up. Bump weight to 700
and font-size to 1.375rem on docs/ to compensate for the
background-clip:text rendering path (grayscale AA, no solid fill)
which makes glyphs look lighter/smaller than the adjacent solid
600/20px headings.
- Tone down the selected TailoredContent option card on both surfaces
to a near-grayscale wash (from-slate-50 → to-indigo-50/30) and
shorten the card itself (smaller padding, smaller icon, smaller
title; extra left padding for breathing room) so the picker takes
less vertical space and doesn't compete with the Step 1 gradient
heading. Indigo ring still does the "selected" signal.
- Bump the tablist's bottom margin in shell-docs (my-2 → mt-2 mb-6)
so the gap between the picker and the first inner Step matches the
1.5rem gap that every other consecutive-Step transition uses.
- Black SignupLink color in Step 1 on shell-docs so the link doesn't
clash with the gradient heading above it.
- Shell-docs: reset margin-top on the first heading inside any Step so
the badge and heading align, and nudge the badge top from -0.125rem
to 0.1875rem so its vertical center matches the heading line center.
Moved the badge's appearance (background/border/color/font-weight)
out of inline style and into globals.css so :first-child overrides
can win without fighting inline-style specificity.
⚠️ **Docs sync — MANUAL REVIEW REQUIRED**
This PR was auto-opened because the docs-sync script detected
showcase-local modifications overlapping with upstream changes.
The script attempted a best-effort 3-way merge:
- Where `git merge-file` produced a clean merge, the merged content was
written.
- Where `git merge-file` produced conflict markers, **upstream content
was written as-is** and showcase-local modifications were overridden.
**Manual review required.**
### Source
- Upstream ref:
[`3552bdd48`](https://github.com/CopilotKit/CopilotKit/commit/3552bdd48)
- Workflow run:
https://github.com/CopilotKit/CopilotKit/actions/runs/25689341730
**Review before merging.** Auto-merge is intentionally disabled for
`needs-review` PRs — confirm the upstream-wins sections preserve any
intentional showcase-local divergence you want to keep, then merge
manually.
---
### Update 2026-05-13 — corrective commit on top
A second commit `8e1d969e` was added by Sam on top of the bot's original
`ad4ea35c` to revert specific changes that conflicted with deliberate
shell-docs decisions (e.g. resurrected deleted landing pages,
`/quickstart` shim revert, EIP brand regression, `react-core/v2` →
`react-core` import-path regression).
**Several of the corrective-revert decisions are being re-evaluated** to
confirm we're not throwing away legitimate content updates
(specifically: `premium/self-hosting.mdx` page collapse to `<SelfHosting
/>`, `shared-state.mdx` line removals, `generative-ui/a2ui.mdx` line
removals, `threads.mdx` `<ThreadsEarlyAccess>` wrapper). The corrective
commit may be adjusted before merge based on that re-evaluation.
The bot's original commit is preserved as the first commit on this
branch. To restore the bot's full original proposal, revert `8e1d969e`.
Re-evaluation of the surgical revert (8e1d969ec) found 4 files where the
upstream sync was the right move and my drop was over-conservative:
1. docs/premium/self-hosting.mdx — collapse 559-line inline content into
<SelfHosting /> shell. Component IS registered (SNIPPET_MAP at
docs-render.tsx:464) and renders the shared snippet, which is
structurally identical (same 23 sections, brand-corrected). The page
was duplicating content the snippet already provides.
2. docs/threads.mdx + snippets/shared/threads/threads.mdx — take bot's
versions (drop the <ThreadsEarlyAccess> wrapper; Threads has been
promoted out of early access upstream) but fix
/reference/v2/hooks/useThreads → /reference/hooks/useThreads
(canonical reference path is src/content/reference/, no /v2/ segment).
3. docs/shared-state.mdx — take bot's IntegrationGrid landing-page form.
The pattern was Tyler's deliberate IA refactor in cc8c94589
(refactor(docs): optimize structure, content and navigability,
2026-02-23) — turning content pages into framework-picker landings —
which shell-docs missed at fork time. Extended exclude list to
["agno", "agent-spec", "spring-ai", "langroid"] since those four
frameworks have no shared-state page; without the addition spring-ai
and langroid would render as broken framework cards.
Not taken (separate decision): docs/generative-ui/a2ui.mdx — bot also
turns this into an IntegrationGrid landing, but 13 of 14 frameworks have
NO a2ui page. Adopting the landing pattern now would produce ~13 broken
cards. Stays as content-rich 108-line orientation page until the
framework-scoped a2ui content exists.
## Summary
Phase 4 validation surfaced 13 broken redirects under the
`/unselected/*` tree. They were dropping users (and SEO equity from
indexed legacy URLs) at the framework-agnostic root pages (e.g.
`/prebuilt-components`) instead of the BIA-scoped equivalents (e.g.
`/built-in-agent/prebuilt-components`).
## Root cause
`next.config.ts` `redirects()` runs at the Next.js routing layer,
**before** middleware. So any rule it matches preempts the
`seo-redirects.ts` catalog. The existing `/unselected/*` catch-all in
`next.config.ts` stripped the prefix (`/unselected/foo` → `/foo`),
regardless of what the seo-redirects catalog specified for BIA-scoped
destinations.
## Changes
`showcase/shell-docs/next.config.ts`:
- `/unselected` (root): destination `/built-in-agent` (was `/`)
- `/unselected/:path*` catch-all: destination `/built-in-agent/:path*`
(was `/:path*`)
- Added 14 explicit slug-rename entries above the catch-all, mirroring
`SUBPATH_RENAMES` in `seo-redirects.ts` (S1–S15, minus S13 which is
handled implicitly):
- `agentic-chat-ui` → `prebuilt-components`
- `use-agent-hook` → `programmatic-control`
- `frontend-actions` → `frontend-tools`
- `vibe-coding-mcp` → `coding-agents`
- `generative-ui/{agentic,render-only}` →
`generative-ui/your-components/display-only`
- `generative-ui/{backend-tools,tool-based}` →
`generative-ui/tool-rendering`
- `generative-ui/frontend-tools` → `frontend-tools`
-
`custom-look-and-feel/{bring-your-own-components,customize-built-in-ui-components,markdown-rendering}`
→ `custom-look-and-feel/slots`
- `guide` → `guides`
- `mcp` → `coding-agents`
The pre-existing per-path entries for
`/unselected/{quickstart,server-tools,mcp-servers,...}` are unchanged —
they already routed correctly to `/built-in-agent/*`. Same for the
`unselected/ag-ui` → `/backend/ag-ui` and `unselected/copilot-runtime` →
`/backend/copilot-runtime` special cases.
## What's NOT changed (intentionally)
- `/unselected/agent-app-context` → `/` kept as-is. The comment in
next.config notes "agent-app-context was concept-per-framework only; no
canonical root home." Genuine product call, not a redirect bug.
- `/copilot-suggestions` → `/` and other non-`/unselected/*`
catalog/next.config conflicts left alone. Those reflect deliberate
product decisions ("orphaned broken stub") that the catalog hasn't
caught up with — separate cleanup.
## Test plan
- [ ] Build succeeds
- [ ] After deploy, re-run Phase 4 redirect catalog probe —
`unselected/*` failures should drop from 13 to 0
- [ ] Manual spot-check: `curl -sIL
https://docs.showcase.copilotkit.ai/unselected/agentic-chat-ui` → final
URL `/built-in-agent/prebuilt-components`, status 200
- [ ] Manual spot-check: `curl -sIL
https://docs.showcase.copilotkit.ai/unselected/some-random-path` →
`/built-in-agent/some-random-path` (catch-all path)
The next.config redirects() block runs at Next.js routing time (before
middleware), so it preempts the seo-redirects.ts catalog rules. The
existing catch-all dropped users at the framework-agnostic root tree
(/agentic-chat-ui, /frontend-tools, etc.) instead of the BIA-scoped
equivalent (/built-in-agent/...), diffusing SEO equity from legacy
/unselected/ URLs.
Changes:
- /unselected (root): destination /built-in-agent (was /)
- /unselected/:path* catch-all: destination /built-in-agent/:path* (was /:path*)
- Add 14 explicit slug-rename entries above the catch-all, mirroring
SUBPATH_RENAMES in seo-redirects.ts (S1-S15 minus S13).
Verified against Phase 4 redirect probe — closes 13 of 22 unselected/
failures.
## Summary
Client-side telemetry on `docs.showcase.copilotkit.ai` was silent. The
shell-docs Dockerfile and `showcase_build.yml` workflow never plumbed
the `NEXT_PUBLIC_*` analytics keys through to `next build`, so the
client JS chunks shipped with empty strings (verified by grepping the
live bundle: `let l = i(95704).env.NEXT_PUBLIC_POSTHOG_KEY` — a runtime
lookup with no inlined value).
Railway runtime env doesn't reach the Docker build phase, so server-side
reads (middleware `POSTHOG_KEY`, server-component canonical URLs) worked
but client-side reads (posthog-js init, RB2B, Scarf, Reo, GA) silently
no-op'd in the browser.
## Changes
- **`showcase/shell-docs/Dockerfile`** — declare `ARG` + `ENV` for
`NEXT_PUBLIC_POSTHOG_KEY`, `NEXT_PUBLIC_RB2B_ID`,
`NEXT_PUBLIC_SCARF_PIXEL_ID`, `NEXT_PUBLIC_REO_KEY`,
`NEXT_PUBLIC_GOOGLE_ANALYTICS_TRACKING_ID` in the builder stage so they
reach `next build`.
- **`.github/workflows/showcase_build.yml`** — add
`build_args_analytics: "yes"` flag to the shell-docs matrix entry;
extend the `Prepare build args` step to emit the five `NEXT_PUBLIC_*`
`--build-arg`s when the flag is set, sourcing values from repo secrets.
Mirrors the existing shell-dashboard pattern (`build_args_pb_url` /
`build_args_shell_url` / `build_args_ops_url`).
## Secrets
Existing repo secret reused: `POSTHOG_PROJECT_KEY`.
New repo secrets required (configured separately in repo settings before
this lands):
- `RB2B_ID`
- `SCARF_PIXEL_ID`
- `REO_PROJECT_KEY`
- `GOOGLE_ANALYTICS_TRACKING_ID`
## Out of scope (intentionally)
- `NEXT_PUBLIC_BASE_URL` is already correctly working via Railway
runtime env (canonical links render with `https://docs.copilotkit.ai`) —
left alone.
- Server-side `POSTHOG_KEY` (no `NEXT_PUBLIC_` prefix) stays on Railway
runtime env; middleware reads it at Edge Runtime.
## Test plan
- [ ] Next build of shell-docs succeeds with new ARGs in scope
- [ ] After deploy, search the live bundle on
`docs.showcase.copilotkit.ai` for the literal `phc_` prefix — must be
present (not `process.env.NEXT_PUBLIC_POSTHOG_KEY` runtime lookup)
- [ ] PostHog Live Events shows `$pageview` (client) and `$autocapture`
arriving from staging
- [ ] RB2B / Scarf / Reo / GA dashboards show events from staging
- [ ] Server-side `seo_redirect` + `docs_pageview` continue firing (no
regression)
The previous commit used `NEXT_PUBLIC_RB2B_ID` based on a stale entry
in the cutover plan doc, but `app/layout.tsx:86` reads
`NEXT_PUBLIC_REB2B_KEY`. Without this fix the build-arg would be
piped under the wrong name and the REB2B Script tag would still not
render.
Client-side telemetry on docs.showcase.copilotkit.ai was silent: the
shell-docs Dockerfile and Showcase Build & Push workflow never plumbed
NEXT_PUBLIC_POSTHOG_KEY / RB2B_ID / SCARF_PIXEL_ID / REO_KEY /
GOOGLE_ANALYTICS_TRACKING_ID through to `next build`. Railway runtime
env doesn't reach the Docker build phase, so the client JS chunks
shipped with empty strings — posthog-js.init etc. silently no-op'd in
the browser.
Mirrors the shell-dashboard pattern: matrix flag triggers the args
block; values come from repo secrets (POSTHOG_PROJECT_KEY already
existed; RB2B_ID, SCARF_PIXEL_ID, REO_PROJECT_KEY,
GOOGLE_ANALYTICS_TRACKING_ID added separately in repo settings).
Server-side telemetry (middleware seo_redirect, docs_pageview) was
unaffected — it reads POSTHOG_KEY at Edge Runtime, which Railway
runtime env satisfies.
## Summary
PR #4691 introduced `import { createPortal } from "react-dom"` in
`src/components/search-trigger.tsx` but did not add `@types/react-dom`
to `showcase/shell-docs/package.json`'s devDependencies. The Railway
production build fails:
```
./src/components/search-trigger.tsx:4:30
Type error: Could not find a declaration file for module 'react-dom'.
'/app/shell-docs/node_modules/react-dom/index.js' implicitly has an 'any' type.
```
Local dev was unaffected because the type was being satisfied via
hoisting from a root `node_modules`. The Docker builder installs each
package's deps in isolation, so the type resolution failed.
## Fix
Add `@types/react-dom: ^19.0.0` to shell-docs devDependencies (matches
the existing `@types/react: ^19.0.0` constraint and resolves to the same
major version as the runtime `react-dom: ^19.0.0`).
## Test plan
- [ ] Railway production build succeeds
- [ ] `npx tsc --noEmit` from `showcase/shell-docs/` returns no
`react-dom` errors
- [ ] No regression in local dev
PR #4691 introduced createPortal from react-dom in search-trigger.tsx
but the shell-docs package was missing @types/react-dom, breaking the
Railway production build with:
Type error: Could not find a declaration file for module 'react-dom'
Hoisting masks this in local dev, but the Docker builder installs
each package's deps in isolation.
Sam Julien