Bumps the bare `.reference-content pre` rule from 0.5rem to 0.875rem
border-radius and adds a `shadow-sm` drop shadow to match canonical
docs.copilotkit.ai chrome. Updates the `<Snippet>` figure wrapper from
`rounded-lg` to `rounded-xl` plus `shadow-sm` so MDX-mounted snippets
share the same visual treatment.
Folds in four low-coupling visual slots that all sit on the canonical
color tokens shipped earlier on this branch:
- Typography: page H1 to 40px / 500 / line-height 48px (was 32px / 700);
H2 to 600 weight with normal letter-spacing (was 700 / -0.015em); drop
the Spline Sans Mono Google Font and fall back to system mono, matching
what canonical docs.copilotkit.ai now ships.
- Callouts: rewrite the boxed admonition card to the canonical pattern —
white surface (`--bg-surface`) with shadow-md, full 1px border, a thin
inner left-strip in the type color at 50% opacity, and a lucide SVG
glyph instead of the round-badge letter. Brand violet for "info"
matches the synced accent.
- Tables: bump font to 14px (was 13px), switch from per-cell borders to
row-bottom-only borders, and pad to 10px / 12px per the canonical
data-table pattern.
- Content max-width: relax `max-w-3xl` (768px) to `max-w-[860px]` so long
prose lines aren't visibly cramped.
Legacy `--violet` and `--violet-light` tokens were left at the pre-sync
shell values (#5a3cd1, #ebe7fa) when the canonical accent moved to
#6d45f9 / #ede5ff. They're consumed by AG-UI section pages and
OpsPlatformCTA, both of which should track the brand violet.
Re-alias to the canonical accent values so the AG-UI pages and the CTA
match the rest of the docs visually.
Per visual styling audit slot 1: align shell-docs CSS custom properties
with the canonical docs.copilotkit.ai palette. Updates --accent to the
brand violet (#6d45f9) with derived --accent-light and --accent-dim,
shifts --bg to the canonical cool-gray (#dedee9), and introduces a new
--glass-background token (the previous --bg value) reserved for header
and sidebar glass-panel surfaces consumed by later slots.
## Summary
Three small pre-cutover cleanup fixes batched into one PR (consolidation
of the prior #4680, #4681, #4682 — same content, fewer review queues).
- `b3ec38720` — Add `<WhenFrameworkHas absent>` fallback to
`programmatic-control.mdx` for the 7 frameworks without
`interrupt_pattern` (ag2, agno, built-in-agent, crewai-crews,
google-adk, mastra, spring-ai), mirroring the canonical pattern from PR
#4496.
- `c080ca062` — Retarget `/migrate/1.10.X` redirect destination from
`/migrate` (which 404s) to `/migrate/v2`. `permanent: false` preserved.
- `e61e8c36d` — Add `mcp-server-setup.mdx` exclusion to docs sync
script. Shell-docs version is intentionally ahead of upstream (HTTP/SSE
Tabs + `mcp-remote` + Tadata callout); without exclusion the next sync
would clobber it.
Supersedes #4680, #4681, #4682.
## Test plan
- [ ] `nx run shell-docs:dev` and visit `/programmatic-control` while
switching the framework selector to non-native fws — verify fallback
callout renders and links to `/human-in-the-loop`.
- [ ] Visit `/migrate/1.10.X` — should redirect to `/migrate/v2` and
render the V2 migration page.
- [ ] Inspect `showcase/scripts/sync-docs-from-main.ts` PATH_EXCLUSIONS
for the `mcp-server-setup` regex.
The shell-docs Docker build fails because link-to-copilot-cloud.tsx
imports from lucide-react but the package was never added to
shell-docs/package.json. Adding it at ^0.469.0 to match sibling
showcase packages.
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.
Sam Julien