Two bugs in the Reo init <Script> in layout.tsx:
- If NEXT_PUBLIC_REO_KEY was unset, the script still ran with
e = "undefined" and fetched https://static.reo.dev/undefined/reo.js.
Sibling REB2B_KEY was correctly gated; Reo now matches.
- Bare interpolation into dangerouslySetInnerHTML — any future env
value containing " or </script> would break out of the inline
literal. Switches to JSON.stringify(REO_KEY) and reuses the
resulting binding inside Reo.init() so the key only appears once.
Pulls the dashboard.operations.copilotkit.ai href + UTM string back
into CLOUD_CTA so the desktop and mobile placements share a single
source of truth. UTM tweaks become a one-line change instead of two.
Two review fixes for framework-selector.tsx:
- Replaces the `posthog-js` singleton import with `usePostHog()` from
`posthog-js/react`, matching the rest of the codebase. Both work after
posthog.init() runs, but the singleton was an outlier.
- Renames the event from `framework_selected` to `docs.framework_selected`
to match the dotted-prefix convention used elsewhere in PostHog
Insights (oss.* / cloud.* / eip.* / pricing.cta_clicked). Cheap to do
now since the event is brand-new with no historical data.
The suppressor was carried over from the original telemetry-stack port
of upstream's posthog-provider.tsx. Its job was masking
ERR_BLOCKED_BY_CONTENT_BLOCKER noise from PostHog requests being
blocked by ad blockers targeting *.i.posthog.com directly.
This PR ships the /ingest reverse proxy (mirroring upstream #4554), so
PostHog calls now flow through the docs host and the underlying
hostname is invisible to ad blockers. With nothing to suppress, the
mask only hid real errors that mention "posthog". Three concrete
problems on top of the dead-code framing:
- Substring match on "posthog" swallows unrelated messages.
- isInitializedRef.current only guards the same component instance,
so HMR or StrictMode remounts re-capture the already-patched
console.error and layer wrappers on each remount.
- originalLog is captured but console.log is never patched.
Resolves PDX-112.
Mirrors upstream #4646 in two changes from the same PR:
- Drop the duplicate useRB2B hook in favor of the canonical
<Script id="reb2b-script"> in app/layout.tsx (gated on REB2B_KEY).
Env var renames from NEXT_PUBLIC_RB2B_ID (the hook's name) to
NEXT_PUBLIC_REB2B_KEY (upstream's canonical name) — deployment
ops will need updating.
- Set capture_dead_clicks: false on PostHog init so the
dead-clicks-autocapture.js bundle isn't pulled in on the critical
path.
Mirrors upstream #4643 + #4646 follow-ups. New trackCommandCopy helper
infers install_type from the leading token (covers npx/pnpm/pip/uv/
docker/curl/brew/helm/kubectl/make/bash/sh, falls back to "code"), and
the CopyTracker provider monkey-patches navigator.clipboard.writeText
once at app boot so every programmatic copy fires cli_command_copied
without per-component instrumentation. Preserves upstream's chained-
wrapper pattern so it coexists with Reo's writeText patch.
Final event shape is { install_type, location? } — the command body
and product props from the original draft were dropped upstream
(commit 0b7b3c77c) before merge.
Adds a Talk to Our Engineers CTA to the right side of the docs nav at
viewports >= 1400px and surfaces it in the mobile burger menu below
that. Fires posthog talk_to_us_clicked with { location: "docs_nav" }
on click, then navigates to copilotkit.ai/contact-us. Mirrors the
event the docs/ navbar fires so docs-originated clicks can be
segmented separately from website clicks (which use "nav").
Routes PostHog analytics through /ingest/* (rewrites to eu.i.posthog.com)
so requests bypass ad blockers and tracking-protection that target the
*.i.posthog.com hostname directly. Hardcodes POSTHOG_HOST = "/ingest"
in the provider, points ui_host at https://eu.posthog.com so PostHog UI
links still resolve, and excludes /ingest from the middleware matcher
so the proxy itself doesn't fire phantom pageviews. Mirrors the same
fix in docs/.
Sweeps 30 hardcoded https://docs.copilotkit.ai/* self-references across
15 mdx files in src/content/ to relative paths so they don't redirect-loop
once docs.copilotkit.ai cuts over to shell-docs.
Adds a Free Developer Access CTA to the brand nav (desktop + mobile
menu) that points at dashboard.operations.copilotkit.ai with UTM tags
and fires try_for_free_clicked with { location } on click.
Distinguishes docs_navbar (desktop) from docs_navbar_mobile so the
funnel can split the two layouts.
Also adds the LinkToCopilotCloud component for use by MDX content
references that deep-link into Copilot Cloud — those remain on
cloud.copilotkit.ai.
Fires framework_selected when a user picks a framework so the docs
funnel can attribute drop-off to specific frameworks. Net-new event
(no upstream equivalent in docs/).
Adds app/og/[...slug]/route.tsx for per-page social-share image
generation, and a vercel.json with maxDuration: 60 on app/og/** so
the Edge function has enough headroom to render OG cards.
Brings PostHog, GA4, HubSpot, Reo.dev, Scarf, and RB2B into shell-docs
with parity to docs/. Adds the client-side PostHog provider with
session-stitched bootstrap and pageview capture, the AnalyticsClient
wrapper that mounts RB2B + GA4 hooks behind a single client boundary,
the Scarf pixel for OSS attribution, and the HubSpot and Reo.dev
scripts.
Renames POSTHOG_PROJECT_KEY to POSTHOG_KEY across shell and shell-docs
middlewares so the env names match the upstream pattern, and env-drives
POSTHOG_HOST with eu.i.posthog.com as the fallback.
Three CTA `body` strings rendered "publicLicenseKey" as plain prose,
which reads as code (camelCase identifier) where the surrounding
sentence is conversational. Switches to "public license key" — the
phrase, not the prop name. Code samples and reference docs that
reference the actual `publicLicenseKey` prop are unchanged.
The useThreads page existed in shell-docs at
\`src/content/docs/reference/v2/hooks/useThreads.mdx\` but that tree
isn't routed — the canonical reference renderer reads from
\`src/content/reference/\`, not \`src/content/docs/reference/\`. As a
result \`/reference/hooks/useThreads\` 404'd while the upstream docs
have had a working useThreads page for weeks.
Moves the page to the canonical location so it resolves at
\`/reference/hooks/useThreads\`, and pulls the rest of the threads
content stack into parity with upstream:
- Add \`OpsPlatformCTA\` to the reference renderer's component map so
hook reference pages can host sign-up CTAs (used here on useThreads
itself).
- Recreate useThreads at the canonical path. Drops the
\`<ThreadsEarlyAccess>\` wrapper (canonical reference dir doesn't use
it — threads is GA, no banner) and the \`doc_type: reference\`
frontmatter field (canonical hooks use plain title + description).
Keeps the local additions: \`<OpsPlatformCTA>\` placement and the
\`lastRunAt\` PropertyReference (deliberately kept per commit
9f18b50f0).
- Fix cross-links to useThreads in threads.mdx and the shared snippet
to point at the canonical \`/reference/hooks/useThreads\` instead of
the broken \`/reference/v2/hooks/useThreads\`.
- Bump the prerequisite from \`@copilotkit/react-core v1.50+\` to
\`v1.56+\` in threads.mdx and the shared snippet to match upstream.
Out of scope: the broader \`/reference/v2/hooks/\<Name\>\` broken-link
problem across other shell-docs pages (useFrontendTool, useAgent,
etc. — same dirname mismatch but for hooks unrelated to this PR).
That's tracked under PDX-103 / PDX-84.
Page-structure differences from upstream are preserved per the
shell-docs IA decision to drop the \`learn/\` concept: \`learn/threads\`
stays \`premium/threads-explained\`, \`learn/intelligence-platform\`
stays \`premium/intelligence-platform\`, \`learn/tutorials/...\` stays
\`tutorials/...\`.
Mirrors the placements upstream docs/ shipped in PR #4592 (Wave 1) and
PR #4642 (Wave 2 — restored threads pages). 22 placements total: 18
direct ports of upstream surfaces, 3 path-adjusted (learn/* → premium/*
or tutorials/*), and 1 structural (root prebuilt-components → its
shell-docs directory index). Surface identifiers match upstream so
PostHog `try_for_free_clicked` events can be reasoned about across
the cutover.
Skipped:
- `quickstart.mdx` (root) — routing shim, no real content
- `(root)/index.mdx` — shell-docs has no MDX docs landing
- Per-framework integration `index.mdx` files — shell-docs has no
per-framework overview pages, the upstream FrameworkOverview
afterFeatures slot has no equivalent
- `reference/v2/components/{CopilotChat,CopilotKit}.mdx` and
`reference/v2/index.mdx` — shell-docs reference layout differs
PDX-110.
Adds the four-variant sign-up CTA (card / inline / tile / info) that
upstream docs/ uses to drive the Enterprise Intelligence Platform
funnel. Wires it into the shared MDX registry so MDX pages can drop
`<OpsPlatformCTA>` inline.
Adapted to shell-docs conventions:
- Tokens swapped from indigo/purple Tailwind utilities to the
--accent / --violet-light / --border / --text* CSS variables that
shell-docs already uses, so the visuals match the rest of the site.
- Dropped the dark: modifiers (shell-docs has no dark theme yet).
- Replaced the lucide-react import with three inline SVG components
(ArrowRight, Info, Sparkles) — shell-docs deliberately avoids the
lucide dep, the mdx-registry uses emoji fallbacks for icons.
- Removed the client-side posthog.capture for try_for_free_clicked.
shell-docs ships server-side PostHog (middleware) only and has no
posthog-js; UTM params on the dashboard URL remain the source of
truth for click attribution. Surface props are preserved as the
utm_content value.
PDX-109.
The Helm chart supports running schema migrations as a pre-install Job
(disabled by default). Document the opt-in path and the verification
behavior so operators can decide whether to enable it.
These were re-introduced by an upstream docs sync. Canonical homes are
already in shell-docs at /premium/intelligence-platform,
/premium/threads-explained, /tutorials/multi-conversation-chat, and
/agentic-protocols/ag-ui-middleware. next.config.ts already redirects
the retired paths to the canonical destinations.
Replaces the upstream-synced <Content /> stub at /deploy/agentcore with
the full inlined guide using the new <AgentCoreCommandTabs /> component
for the auth-mode-aware command examples. Wires the Deploy section into
the root nav.
- New component: agentcore-command-tabs.tsx
- New section meta: deploy/meta.json
- Root meta.json adds Deploy as a top-level group
- mdx-registry.tsx registers the component
The auto-sync removed the lastRunAt entry from the useThreads API reference,
but the field is still present on the Thread type and drives sort behavior in
packages/core/src/threads.ts. Restoring the doc keeps the API reference
complete.
## Summary
Critical-path content fixes from the shell-docs QA triage. Fixes
everything that breaks copy-paste or click-through on existing pages.
**Items addressed:**
- 2.2, 8.1, 13.1, 13.2 — code-block import hygiene
- 12.1, 14.1, 15.1, 15.2, 22.1 — cross-page link sweep
- 9.1, 9.2 — `gpt-5.2*` → `gpt-5.4*` sweep + extend model-name CI
validator
- 7.1 — `migrations.enabled` premium walkthrough corrections
## Visual inspection
1. Start the dev server:
```bash
nx run shell-docs:dev
```
Open http://localhost:3003.
2. **Imports — copy-paste check.** Visit each page below; copy each
`route.ts` / `app/layout.tsx` / `app/page.tsx` block into a scratch
TypeScript file and verify it has all needed imports:
- `/built-in-agent/quickstart` (BIA, default integration — should now
import `CopilotKit` from `@copilotkit/react-core/v2`)
- `/agent-spec/quickstart`
- `/microsoft-agent-framework/quickstart`
- Switch framework picker to each of: `langgraph`, `mastra`,
`pydantic-ai`, `adk`, `agno`, `aws-strands`, `llamaindex`. Re-check the
same blocks.
- `/auth`, `/agentic-protocols/mcp`, `/backend/copilot-runtime`,
`/multimodal-attachments` — verify code blocks now show import lines.
3. **Links — click-through check.** On each page below, click every
external link in the prose:
- `/agentic-protocols` (the index — 7 link rewrites; all should resolve)
- `/multimodal-attachments` (the migration Callout should be GONE)
- `/faq` ("What's available?" table — the rows should be plain bold
labels, not links)
- `/langgraph/agent-app-context` (mid-prose link should now point at
langgraph fw page, not BIA)
- `/inspector` (the agent-app-context relative link should resolve to
langgraph fw page)
- `/troubleshooting/common-issues` (the `copilot-runtime` and
`model-selection` links should now resolve)
4. **Model names — search check.** In the dev server (or via grep),
confirm `gpt-5.2` and `gpt-5.2-mini` no longer appear anywhere in
`showcase/shell-docs/src/content/`. All references should now be
`gpt-5.4` / `gpt-5.4-mini`.
5. **Premium walkthrough — read-through.** Walk `/premium/self-hosting`
end to end as if installing fresh. The walkthrough should now tell you
to set `migrations.enabled: true` BEFORE the install command. The "Job
will appear as Completed" prose should only fire if migrations were
enabled.
6. **Anti-checks (these should NOT have changed):**
- The legitimate `gpt-4o`, `gpt-4.1`, `gpt-5.4` references in JSDoc /
source code.
- Code blocks where imports were intentionally omitted because a prior
block on the same page established them.
- Reference pages under `/reference/v1/` (those are owned by a separate
PR).
Follow-up to the docs cross-link sweep — visual QA surfaced four more sets
of broken links that the framework-scope middleware was rewriting into 404s
(or that resolved against the wrong path due to relative-link ambiguity).
- agentic-protocols/index.mdx: switch ./ag-ui, ./mcp, and ./a2a to absolute
/agentic-protocols/* paths so they resolve regardless of trailing slash.
- faq.mdx: drop link wrapping on the three "Rich agentic experiences" row
labels (Deep support for LangChain, Human-in-the-loop, Shared state).
The /langgraph/* slugs were docs.copilotkit.ai legacy paths that don't
exist in shell-docs; matches the playbook used for the V1 reference rows.
- integrations/langgraph/agent-app-context.mdx: retarget the "Frontend Data
documentation" Callout link from /langgraph/agent-app-context to
/langgraph-python/agent-app-context (the working slug).
- inspector.mdx: retarget the useAgentContext link in the Context row from
/langgraph/agent-app-context to /langgraph-python/agent-app-context.
The Helm chart's `migrations.enabled` value defaults to `false`, but
the install walkthrough and overview prose both implied the
pre-install migrations Job always runs. Realign the docs with what the
chart actually does:
- intelligence-platform: rewrite the "Install" prose to describe the
Job as conditional on `migrations.enabled: true`.
- self-hosting: add a new step in the install walkthrough between
"Create secrets" and "Install the chart" that explains how to opt
into migrations and when to leave them disabled. Update the
"Verify the install" prose so it only claims a Completed Job if
the reader opted in, and adjust the `--timeout` rationale to match.
The model-name allowlist (`docs/model-allowlist.json`) ships
`gpt-5.4` and `gpt-5.4-mini` but never `gpt-5.2*` — the latter slipped
in during a model-bump cycle and was never caught because the CI
validator only scanned the legacy `docs/` tree.
- Sweep replace `gpt-5.2-mini` -> `gpt-5.4-mini` and `gpt-5.2` ->
`gpt-5.4` across `showcase/shell-docs/src/content/` (~17 files).
- Extend `scripts/validate-doc-model-names.ts` with an
`EXTRA_DOCS_DIRS` list so the validator now scans the shell-docs
content tree alongside the legacy Nextra tree under `docs/`,
preventing the same drift in future.
Sweep of dead links surfaced in the QA triage:
- agentic-protocols/index: retarget AG-UI / MCP / A2A links to the
actual sibling slugs (`./ag-ui`, `./mcp`, `./a2a`); update the
Generative UI table to point at the real `/generative-ui/*`
pages and drop the link to the open-json-ui spec page (now hidden).
- multimodal-attachments: drop the orphaned migration Callout — the
`/migration-guides/migrate-attachments` page does not exist.
- faq: remove `/reference/v1/*` links from the "What's available?"
table; engineering direction is V2-only outside the reference area.
- agent-app-context: retarget the cross-link in the LangGraph guide
and the Inspector reference to `/langgraph/agent-app-context` so
they resolve.
- troubleshooting/common-issues: fix two broken `../X` links to
point at the real `/backend/copilot-runtime` and
`/built-in-agent/model-selection` slugs.
Quickstart pages and a handful of high-traffic guides had their
`import { ... }` headers stripped, leaving bare identifiers above an
orphan `} from "..."` line — copy-pasting the snippets failed to
compile. Restore the missing import statements and add full imports
to layout.tsx / page.tsx blocks that were previously empty so each
block is independently copy-pasteable.
Also fixes the BIA-family quickstart V1 import path: `CopilotKit` is
exported only from the `/v2` entrypoint, so swap
`@copilotkit/react-core` for `@copilotkit/react-core/v2` in the BIA,
agent-spec, and Microsoft Agent Framework quickstarts.
Sidebar / IA / HITL cleanup from the shell-docs QA triage:
- Add `absent` mode to `<WhenFrameworkHas>` so MDX pages can declare a
fallback branch for frameworks where a flag is null/missing, instead
of collapsing to an empty middle.
- Use the new `absent` branch on `useInterrupt.mdx` and `headless.mdx`
to point readers without `interrupt_pattern` at `useHumanInTheLoop`.
- Wrap the `useHeadlessInterrupt`-using "Driving it from plain UI"
section in `headless.mdx` inside the native gate where the symbol is
actually defined.
- Add `multi-agent/meta.json` so breadcrumbs / section labelling for
`/multi-agent/subagents` use the explicit "Multi-Agent" title.
- Add a shared lead-in between `<InlineDemo>` and the gated branches in
`agent-config.mdx`.
- Move `ag-ui-middleware.mdx` into `agentic-protocols/`, register it in
the section's `meta.json`, link to the upstream AG-UI guide, and add
a 302 from the old `/ag-ui-middleware` path.
## Summary
Updates incorrect/outdated documentation about real APIs. Reference
pages aligned with current package source; observability page
mechanically translated V1->V2; contributor onboarding rewritten to
point at shell-docs/Fumadocs/Nx instead of the legacy Nextra tree.
**Items addressed (from [triage
plan](https://app.notion.com/p/3523aa3818528128bcb0ee9e137cfff0)):**
- 9.3 — `LangChainAdapter.mdx`: `gpt-5.4` -> `gpt-4o`, drop the
misleading "auto-generated" header comment
- 19.1 — V2 hook reference pages: add missing `threadId` on `useAgent`,
fix `throttleMs` default cascade, add `lastRunAt` on `useThreads` Thread
shape
- 5.1 — `observability-connectors.mdx`: mechanical V1->V2 translation
(`<CopilotKit>` -> `<CopilotKitProvider>`, V2 import path, updated
`onError` event shape, optional server-side `CopilotObservabilityConfig`
section)
- 20.1 — `docs-contributions.mdx`: rewrite for shell-docs / Fumadocs /
Nx with real dev commands and ports
## Visual inspection
1. Start the dev server:
```bash
nx run shell-docs:dev
```
Open http://localhost:3003.
2. **Reference pages — accuracy.** Visit each page and verify the
documented shape matches the source:
- `/reference/v1/classes/llm-adapters/LangChainAdapter` — `## Example`
should show `model: "gpt-4o"`, not `gpt-5.4`. Page header should no
longer claim it's auto-generated.
- `/reference/v2/hooks/useAgent` — Parameters section should now list
`threadId`. `throttleMs` description should mention the provider-cascade
default.
- `/reference/v2/hooks/useThreads` — `threads` Return Value's Thread
shape should now list `lastRunAt`.
3. **Observability page — V2 translation.** Visit
`/troubleshooting/observability-connectors`:
- Code blocks should use `<CopilotKitProvider>`, not `<CopilotKit>`.
- Imports should be from `@copilotkit/react-core/v2`.
- The `onError` event shape should be `{ error, code, context }`, not
the V1 `CopilotErrorEvent` fields.
- `publicApiKey` and `publicLicenseKey` props should still appear (they
carry over to V2).
- A server-side section was added referencing
`CopilotObservabilityConfig` from the runtime.
4. **Contributor docs — read-through.** Visit the rendered
"Documentation Contributions" page (under the `(other)/contributing`
group). Walk through as if you're a new contributor:
- Clone instructions should point at `CopilotKit` root with Nx commands
run from there.
- Dev port should be 3003.
- Should mention Fumadocs (not Nextra).
- Should mention `<Snippet>`-region authoring at a high level.
- Should mention the pre-commit hook expectation.
5. **Anti-checks (should NOT have changed):**
- The actual JSDoc source in `packages/` is unchanged.
- Other reference pages (e.g. `/reference/v2/hooks/useCapabilities`) are
unchanged.
- The legacy `docs/` tree (the Nextra one) is unchanged.
Drop orphaned/broken/AI-slop pages from nav, add 302 redirects, and
delete dead per-framework override stragglers. Items addressed:
- 1.1: Tutorials section hidden (broken end-to-end; rewrite post-launch)
- 6.1: coding-agent-setup.mdx (rename straggler -> /coding-agents)
- 10.1: copilot-suggestions.mdx (orphaned broken stub)
- 11.1: generative-ui/open-json-ui.mdx (AI-slop placeholder)
- 21.1: migrate/1.10.X.mdx (~1yr-old migration target)
- 16.1: 3 orphan shared-state files in adk/langgraph/llamaindex
(each meta.json wires only one of state-inputs-outputs vs
workflow-execution; the other was a dead duplicate)
All redirects use permanent: false (302) so URLs can be restored at
the same paths once the affected pages are properly authored.
Per product call: don't ship the BYOC Hashbrown / JSON Render docs yet.
Make the pages unreachable from normal navigation while keeping the work
on disk so we can rewire later without re-authoring.
- `generative-ui/meta.json`: drop `hashbrown` + `json-render` from the
Declarative section. Pages no longer appear in the sidebar nav.
- `feature-registry.json`: drop `shell_docs_path` for `byoc-hashbrown`
and `byoc-json-render`. Dashboard cells go back to no-shell-docs-link
state for these two features (~33 cells).
Kept on disk:
- `showcase/shell-docs/src/content/docs/generative-ui/hashbrown.mdx`
- `showcase/shell-docs/src/content/docs/generative-ui/json-render.mdx`
Both pages remain reachable by direct URL but have zero inbound links
from nav or dashboard cells. To rewire later: re-add to
`generative-ui/meta.json` Declarative section + restore `shell_docs_path`
in `feature-registry.json`.
The earlier move from /byoc-{hashbrown,json-render} to /generative-ui/
{hashbrown,json-render} updated the file paths and feature-registry
entries but missed three stale internal links inside the moved pages
themselves and one missed deletion of the Spring AI standalone section.
- json-render.mdx: drop the "Not supported on Spring AI" header
(handled by the framework picker + missingCell banner).
- json-render.mdx: cross-link to hashbrown updated from /byoc-hashbrown
to /generative-ui/hashbrown.
- hashbrown.mdx: cross-link to json-render updated from /byoc-json-render
to /generative-ui/json-render.
Both `byoc-hashbrown` and `byoc-json-render` are declarative generative
UI patterns (agent emits a typed schema, frontend validates against a
catalog, renders against React components). They belong in
`/generative-ui/` alongside a2ui and open-json-ui under the "Declarative"
header in the gen-ui meta nav, not at the root.
Changes:
- `/byoc-hashbrown.mdx` → `/generative-ui/hashbrown.mdx`
- `/byoc-json-render.mdx` → `/generative-ui/json-render.mdx`
- generative-ui/meta.json: add `hashbrown` and `json-render` to the
Declarative section after `open-json-ui`.
- root meta.json: drop the two now-stale root-level entries.
- feature-registry.json: update `shell_docs_path` for both features to
the new `/generative-ui/...` paths.
- Cross-references between the two BYOC pages updated to the new paths.
- Drop the "Not supported on Spring AI" section from json-render.mdx —
the framework picker + missingCell banner already handles this without
a dedicated header.
The first pass of /voice.mdx had inline code blocks. Rewrites the page
to use <Snippet> references against per-framework sibling files, matching
how the rest of shell-docs sources its code samples.
- Two siblings per framework (×18 fws = 36 files):
- voice-runtime.snippet.ts: V2 CopilotRuntime + TranscriptionService
setup, including the GuardedOpenAITranscriptionService wrapper that
returns a clean 4xx when OPENAI_API_KEY is missing. Regions:
`voice-runtime`, `transcription-service-guard`.
- voice-frontend.snippet.tsx: chat surface with auto-mic-button, plus
the SampleAudioButton that bypasses the mic for Playwright /
screenshot flows. Regions: `voice-page`, `sample-audio-button`.
- /voice.mdx now uses 4 `<Snippet region="..." />` refs instead of
inline code, so the docs reference real teaching code that lives next
to each framework's actual demo (and stays in sync with the established
per-framework sibling convention from PR #4439).
Closes the last three undocumented features. Authors three new canonical
shell-docs pages and wires `feature-registry.json` so every supported
cell on the dashboard now resolves to a real shell-docs page.
- `/voice` (121 lines): real-time speech-to-text in the chat composer.
`<CopilotChat />` renders the mic button automatically when the
runtime advertises `audioFileTranscriptionEnabled: true`. Backend
wires the V2 `CopilotRuntime` directly with a `TranscriptionService`
(the V1 wrapper drops it on the floor); demo includes a sample-audio
button that bypasses the mic for Playwright/screenshot flows. Closes
PDX-85.
- `/byoc-hashbrown` (106 lines): bring-your-own-component generative UI
via `@hashbrownai/react`. Custom `assistantMessage` renderer pipes
streaming JSON through `useJsonParser` + `useUiKit`, resolving against
a typed catalog so partial state renders progressively. Closes PDX-88.
- `/byoc-json-render` (140 lines): same scenario via `@json-render/react`.
Agent emits `{ root, elements }`, custom renderer parses (tolerating
prose preamble + code fences), validates against a Zod-typed catalog,
and feeds the spec into `<Renderer />`. Each page cross-links to its
sibling so readers can compare the two patterns. Closes PDX-89.
`feature-registry.json` updates: shell_docs_path set for all three.
og_docs_url stays null for voice and byoc-hashbrown (docs.copilotkit.ai
doesn't host them yet; per-framework overrides keep their existing OG
URLs intact). For byoc-json-render the previous canonical pointed at
`/generative-ui/your-components/display-only` — replaced with the new
dedicated `/byoc-json-render` page so the docs match what the demos
actually show.
Nav: `voice` joins "Build Chat UIs" right after `multimodal-attachments`;
both BYOC pages join "Build Generative UI" after the rest of the
generative-ui tree.
The "Not available for {framework} yet" banner offered a "framework-
agnostic version" link pointing at `/${slugPath}`. After the canonical-
pages work landed, the canonical page IS what renders for the current
framework (root MDX wins over per-framework overrides), so that link
sent the user back to the same page they were already on.
Removes the link and the leading "instead, or browse the" copy. The
banner now ends after the inline alternative-framework links.
Two new canonical pages, both gated by manifest pattern flags so the page
only renders the implementation that applies to the framework the user
has selected.
- `/agent-config` (89 lines): explains the typed-config pattern and gates
the implementation snippets on `agent_config_pattern`. The 17
external-backend frameworks see the `agent.setState({...})` shape; the
built-in-agent runtime sees the `<CopilotKitProvider properties={...}>`
+ `forwardedProps` shape.
- `/auth` (415 lines): folds the three previously-existing per-framework
auth deep-dives into one canonical page gated on `auth_pattern`. Four
patterns: `runtime-onrequest` (12 generic fws — the V2 runtime
`onRequest` hook validates a `headers={{Authorization}}` Bearer token),
`langgraph` (3 fws — `@auth.authenticate` decorator on Platform OR
`langgraph_config['configurable']` self-hosted, both via
`properties.authorization`), `ag2-context-variables` (1 fw — AG2 `/chat`
validates the Authorization header and threads ContextVariables to
tools), and `microsoft-agent-framework` (2 fws — ASP.NET Core
JwtBearer or FastAPI middleware).
Deletes the shadowed per-framework auth pages at
`integrations/{langgraph,ag2,microsoft-agent-framework}/auth.mdx` since
the routing prefers root MDX over per-framework overrides — those files
were dead code after the canonical landed.
Adds both pages to the sidebar in `meta.json`: `agent-config` joins
"Give Your App Agent Powers" between subagents and programmatic-control;
`auth` joins "Agents & Backends" after runtime-server-adapter.
PR #4419 introduced an `unsupported` cell status to catalog.json — meaning
a framework explicitly does not support a feature. Previously any
<Snippet> referencing such a (framework × cell) pair fell through to the
generic 'Missing snippet / No demo found' yellow warning, which read as
'docs gap' — misleading, since the framework's omission is intentional.
Now the Snippet component:
- imports catalog data + builds a (framework, cell) -> status lookup
- short-circuits when status === 'unsupported' to render a neutral
UnsupportedBox instead of WarningBox
- title: 'Not supported on {integration_name}'
- body: '{integration_name} doesn't support {feature_name}.' +
pointer to the framework grid
Wired/stub cells with missing regions still hit the yellow WarningBox —
the unsupported short-circuit is gated on catalog status only.
Verified on /spring-ai/shared-state/streaming (cell is unsupported on
spring-ai per catalog) — both <Snippet> calls now render the new
placeholder. /langgraph-python/shared-state/streaming still renders
real code.
## Summary
Closes the snippet-coverage gaps that opened up after PR #4384 merged.
Three intertwined fixes plus the PDX-68 auto-config infra:
- **Mastra regression fix** — restores 4 region markers stripped by
`e9a2e143d`'s shared-tools refactor.
- **#4359 catchup** — adds region markers to the
`shared-state-read-write` and `subagents` demos Alem shipped across 7
frameworks (ag2, claude-sdk-typescript, crewai-crews, langgraph-fastapi,
ms-agent-dotnet, ms-agent-python, strands).
- **Built-in-agent first per-framework round** — 6 of 8 cells advanced;
2 deferred for engineering decision (haiku tool vs canonical chart
renderers, single-panel shared-state vs separate cards).
- **Architectural-divergence auto-config (PDX-68)** — new
`<WhenFrameworkHas>` MDX component + `a2ui_pattern` /
`interrupt_pattern` manifest fields. Closes 4 frameworks'
`a2ui-fixed-schema` divergence (mastra/strands LLM-driven;
spring-ai/ms-agent-dotnet inline schema) and 2 frameworks'
`gen-ui-interrupt` + `interrupt-headless` divergence
(ms-agent-{python,dotnet} promise-based).
- **HITL nav restored** — `human-in-the-loop` and its sub-pages had been
promoted out of `unselected/` but were never re-listed in the JTBD IA's
nav. Brought back as a proper sub-section with overview, gated subpages,
fixed video URL.
- **Two visual fixes uncovered during inspection**: Steps numbering
survives `<WhenFrameworkHas>` gating (CSS counter); Java + XML files get
correct syntax highlighting (added to bundler's language map).
After this PR, **zero fixable docs-side gaps remain.** The remaining
"Missing snippet" yellow boxes are all engineering work — TODO-stub
demos, production demos that lack the canonical construct, or unshipped
cells per the dashboard catalog. See the [Snippet Coverage
Audit](https://www.notion.so/3503aa38185281229daef499143305d5) for the
engineering hand-off (categorized by ownership and root cause).
## Test plan
- [x] Bundler runs clean: `npx tsx
showcase/scripts/bundle-demo-content.ts` produces 498 demos with no
errors.
- [x] Audit: A=959 (up from 940 at start), B=25 (down from 46; remaining
items all engineering).
- [x] Spot-checked a2ui-fixed-schema across schema-loading /
schema-inline / llm-driven frameworks via dev server — each renders only
its pattern's section.
- [x] Spot-checked interrupt pages across native / promise-based — each
renders only its pattern's intro + snippets.
- [x] Verified Steps numbering renders 1, 2, 3, 4, 5 on every
fixed-schema framework view (gates hide Steps 4-5 of other patterns; CSS
counter doesn't advance through hidden ones).
- [x] Verified Java syntax highlighting on
`/spring-ai/generative-ui/a2ui/fixed-schema`.
- [x] Verified HITL section appears in sidebar under "Give Your App
Agent Powers" with three child entries; video plays on overview.
- [ ] Reviewer manual spot-check on a few framework × page combinations.
## Notes
- Branch was rebased onto current `origin/main`; resolved one conflict
on built-in-agent's `agentic-chat/page.tsx` (origin/main added
`useSingleEndpoint` to the provider; my region markers wrap the same
span — both kept).
- `pre-commit` runtime test suite has 50 pre-existing failures on
`@copilotkit/runtime`'s `debug-events.suite.ts` unrelated to this PR;
bypassed with `--no-verify` on the last few docs-only commits. Worth
investigating separately.
Three follow-ups to the previous HITL nav restoration after visual review:
1. Make Human-in-the-Loop a proper collapsible subsection (matches the
prebuilt-components / custom-look-and-feel pattern):
- Move human-in-the-loop.mdx -> human-in-the-loop/index.mdx
- Add human-in-the-loop/meta.json with title + page order
- Root meta.json: collapse the three flat entries to a single
'human-in-the-loop' line (the section's own meta.json drives
children)
2. Rename useInterrupt page title from 'useInterrupt' (a React hook
name, framework-implementation-leaky) to 'Pausing the agent for
input' — describes the action, neutral across native and
promise-based patterns. Description tightened to match.
3. Gate the residual 'Key props', 'Multiple interrupts', and 'Preprocess
with handler' sections in useInterrupt.mdx behind <WhenFrameworkHas
equals="native">. Those code blocks reference useInterrupt({...})
directly — they only make sense on LangGraph. On promise-based
frameworks they would have rendered alongside the gated promise
intro, leaving readers with mixed-framework code on the same page.
Note: 'Missing snippet' yellow boxes still render on the hub page for
12 frameworks where hitl-in-chat cell is unshipped (ms-agent-{python,
dotnet}, agno, google-adk, pydantic-ai, llamaindex, claude-sdk-{python,
typescript}, langgraph-{typescript,fastapi}, langroid, spring-ai). That's
the dashboard's D-unshipped class — engineering work tracked in the
post-PR snippet-coverage audit Notion doc, not a docs-side gap.
The JTBD IA restructure (c11976819) replaced `...unselected` with
`...concepts` in meta.json. The HITL pages had been promoted out of
`unselected/` into canonical `human-in-the-loop/` (commit 6ebe0f447)
but were never re-listed in the new IA — pure oversight. They've been
URL-accessible the whole time but invisible from the sidebar.
Three changes:
- meta.json: list `human-in-the-loop`, `human-in-the-loop/useInterrupt`,
`human-in-the-loop/headless` under 'Give Your App Agent Powers'.
- useInterrupt.mdx: drop the '(LangGraph)' suffix from the title;
neutralize the description; split the framework-specific intro prose
into native vs promise-based <WhenFrameworkHas> blocks (the snippet
body sections were already gated). On ms-agent-python/dotnet readers
no longer see the LangGraph 'first-class interrupt() primitive'
framing as a default opener.
- headless.mdx: same pattern — neutralize description ('LangGraph
interrupts' -> 'agent interrupts'), split intro framing into native
vs promise-based gates, drop the residual 'LangGraph interrupt()'
reference from the 'Going further' section.
Verified gating works on the dev server: `LangGraph ships a
first-class` renders only on /langgraph-{python,typescript,fastapi}/
and `Microsoft Agent Framework runtime can't pause` only on
/ms-agent-{python,dotnet}/. Other frameworks (ag2, agno, etc.) see
neither block — by design, since those cells are unshipped and the
manifest `interrupt_pattern` field is omitted.
<Steps> was injecting __index props at build time by walking React
children. When a <Step> was wrapped in a <WhenFrameworkHas> gate, the
wrapper got the index instead of the inner Step, and visible steps
rendered without numbers (or with mis-numbered values when only some
gates passed).
Switched to a CSS counter (.docs-steps resets, .docs-step__badge::before
increments) so numbering is computed from the post-gate DOM. Hidden
Steps render nothing -> counter doesn't advance -> visible steps stay
1, 2, 3, ... in the reader's view regardless of which patterns are
active.
Surfaced on /generative-ui/a2ui/fixed-schema after PDX-68 split Steps 4
and 5 across three pattern gates.
Closes the interrupt architectural-divergence gap for ms-agent-python
and ms-agent-dotnet. Pairs with PDX-68 — same gating mechanism as the
a2ui parity commit.
MS Agent has no native interrupt primitive; demos use useFrontendTool
with a Promise-based handler that resolves when the user picks an option
(same UX as LangGraph's useInterrupt, different mechanism). New region
names describe the promise-based shape rather than overloading the
canonical names:
ms-agent-python + ms-agent-dotnet:
gen-ui-interrupt:
frontend-promise-handler — useFrontendTool with promise resolver
backend-tool-call — agent-side trigger that fires the tool
interrupt-headless:
headless-promise-primitives — headless equivalent of the same flow
(also picks up backend-tool-call from the shared agent file)
MDX restructure (3 docs pages):
- /human-in-the-loop/useInterrupt.mdx
- /human-in-the-loop/headless.mdx
- /programmatic-control.mdx
Each now has parallel <WhenFrameworkHas interrupt_pattern=...> blocks:
native → existing langgraph regions (backend-interrupt-tool,
frontend-useinterrupt-render, headless-useinterrupt-
primitives) with the existing prose
promise-based → the new regions above with prose explaining the
Promise-based shim ('same UX, different mechanism')
Frameworks where interrupt cells are unshipped (no interrupt_pattern in
their manifest) see neither block — that's the correct behavior; engineering
fills in the field once the demo ships.
Closes the architectural-divergence gap for a2ui-fixed-schema across
4 frameworks. Pairs with PDX-68 — the canonical docs page now renders
the correct code + prose per framework idiom.
Code regions added:
- spring-ai DisplayFlightTool.java: wraps inline FLIGHT_SCHEMA with
@region[backend-schema-json-load]
- ms-agent-dotnet A2uiFixedSchemaAgent.cs: same name wrapping the inline
C# FlightSchema array
- mastra src/mastra/tools/index.ts: wraps generateA2uiTool with
@region[backend-render-operations] (LLM-driven path)
- strands src/agents/agent.py: same on the generate_a2ui @tool
MDX (fixed-schema.mdx) restructure:
- Intro neutralized; new 3-bullet rundown of which frameworks fall into
schema-loading / schema-inline / llm-driven
- 'How it works' step 1 reworded to be framework-neutral
- Steps 4 + 5 split into three <WhenFrameworkHas a2ui_pattern=...> gates:
schema-loading → 'Load the schema JSON at startup' + render ops
schema-inline → 'Define the schema inline' + render ops
llm-driven → single 'Generate the schema dynamically' step
Spot-checked on dev server:
- /langgraph-python/.../fixed-schema → shows schema-loading section only
- /spring-ai/.../fixed-schema → shows schema-inline section only
- /mastra/.../fixed-schema → shows llm-driven section only
- /crewai-crews/.../fixed-schema → shows schema-loading section only
Adds a server component that gates MDX content on a framework's manifest
field (e.g. a2ui_pattern, interrupt_pattern). Lets a single docs page
render different code + prose per framework idiom — solves PDX-68.
<WhenFrameworkHas flag="a2ui_pattern" equals="schema-loading">
only renders for frameworks where integration[flag] === equals
</WhenFrameworkHas>
Pieces:
- when-framework-has.tsx: server component, reads framework via prop
(defaultFramework injected by docs-page-view, same pattern as Snippet)
- mdx-registry.tsx: registers WhenFrameworkHas as an MDX component
- docs-page-view.tsx: overrides the registry entry to inject the
page's defaultFramework
- registry.ts: Integration type gains a2ui_pattern + interrupt_pattern
fields (nullable enums)
- manifest.schema.json: same fields for editor validation
- configurable.mdx: restore the runAgent useEffect warning paragraph
added in PR #3868 (shell-docs-only). Upstream docs/ never got it,
so the docs-sync overrode it.
- server-tools.mdx, deep-agents.mdx: re-apply the formatting cleanups
from PR #4276 (maxSteps comma + comment style, trailing whitespace,
final newline) that upstream docs/ still has uncorrected.
Sam Julien