The byoc-hashbrown and byoc-json-render demos override the CopilotChat
assistantMessage slot with custom renderers, but the overrides were
missing the data-testid="copilot-assistant-message" attribute that the
e2e-deep conversation runner uses to detect settled assistant responses.
Without it, the runner's readMessageCount always returned 0 and the
byoc feature timed out at D5.
The langgraph-python gold-standard already had these attributes; this
aligns claude-sdk-typescript to match.
## Summary
- docs-only features (e.g. cli-start) exist purely for documentation
coverage tracking and have no route, depth probes, or health signals
- The catalog metadata was counting their 18 stub cells in the headline
wired/stub/unshipped/unsupported breakdown, inflating the total and
making the stats bar misleading
- Exclude docs-only cells from the headline counts; add a new
`docs_only` field to track them separately
**Before:** total_cells=720 wired=673 stub=18 unsupported=29
**After:** total_cells=702 wired=673 stub=0 unsupported=29 docs_only=18
## Test plan
- [x] `showcase/scripts` test suite: all 574 tests pass (including 13
catalog tests)
- [x] `showcase/shell-dashboard` test suite: same 3 pre-existing
failures, no regressions
- [x] TypeScript check clean (no new errors)
- [x] Invariant holds: wired + stub + unshipped + unsupported +
docs_only == cells.length
docs-only features (e.g. cli-start) exist purely for documentation
coverage tracking -- they have no route, no depth probes, and no
health signals. The catalog metadata was counting their 18 stub cells
in the headline wired/stub/unshipped/unsupported breakdown, inflating
the total and making the stats bar misleading.
Exclude docs-only cells from the headline counts. A new docs_only
field tracks the excluded count separately so the invariant
(wired + stub + unshipped + unsupported + docs_only == cells.length)
holds.
Before: total_cells=720 wired=673 stub=18 unsupported=29
After: total_cells=702 wired=673 stub=0 unsupported=29 docs_only=18
The llamaindex chat-slots demo only had the welcomeScreen slot,
missing the input.disclaimer and messageView.assistantMessage
overrides that langgraph-python (gold standard) provides. The D5
probe checks for data-testid="custom-assistant-message" after the
assistant responds, so the feature was stuck at D4.
Add CustomAssistantMessage and CustomDisclaimer components (matching
langgraph-python), wire them into CopilotChat props, update the e2e
spec to cover all three slots, and update manifest highlights.
Widen dialog from w-72 to w-[480px], extract key signal fields
(errorDesc, error, failureSummary, backendUrl) as readable key-value
pairs instead of buried JSON, make raw signal collapsible, remove
duplicate tooltip text that repeated badge color/status info.
Suppress RefDepthCell for docs-only features in the parity overlay,
showing '--' instead of a depth chip since docs-only features have no
probe coverage. Add depth distribution counts (D6..D1) to the
AdaptiveStatsBar when the depth overlay is active, giving operators
at-a-glance visibility into how many wired cells are at each depth.
Features with kind "docs-only" show only the docs row in the
dashboard -- no Dx badges, no status badges, no links or depth
layers. The row label is muted and tagged like "testing" rows.
- feature-registry.json: cli-start changed from primary to docs-only
- registry.ts: FeatureKind union extended with "docs-only"
- cell-pieces.tsx: CellStatus returns null for docs-only (hides all
badges)
- composed-cell.tsx: docs-only features render only DocsLayer, skip
links/depth/health
- feature-grid.tsx: docs-only rows use muted italic styling with a
"docs-only" tag
- Tests added for all three behavioral changes
## Summary
Adds a clickable "Run Evaluation" link in a bot comment on every PR. One
click triggers the showcase eval — no Checks tab navigation needed.
### How it works
1. `showcase_eval_check.yml` creates the Check Run AND posts a bot
comment with a signed link
2. The link points to
`eval-webhook-production.up.railway.app/trigger/eval?pr=N&check_run_id=M&sig=HMAC`
3. User clicks → webhook service verifies signature, dispatches eval
workflow, updates Check Run to in_progress, redirects user back to the
PR
4. Eval results appear in the Check Run (already implemented in #4517)
### Security
- Link is HMAC-signed using the webhook secret — can't be forged
- Signature covers `pr:check_run_id` — changing either invalidates the
link
- `EVAL_WEBHOOK_SECRET` added as repo secret for the signing step
### Changes
- `showcase/eval-webhook/src/server.ts` — new `GET /trigger/eval` route
with signature verification + redirect UX
- `.github/workflows/showcase_eval_check.yml` — posts bot comment with
signed link (updates on push, idempotent via HTML marker)
## Test plan
- [ ] Open a test PR → verify bot comment appears with "Run Evaluation"
link
- [ ] Click the link → verify redirect page shows, eval dispatches,
Check Run updates
- [ ] Tamper with the sig parameter → verify 403 response
deriveDepth() was computing D2 for not_supported_features because D1/D2
are integration-scoped. Add unsupported boolean to DepthResult, guard in
deriveDepth, update consumer components. 24/24 depth-utils tests pass.
Fix chat-slots agent name (dashes to underscores), prebuilt-popup
defaultOpen prop, auth demo defaults to unauthenticated state, and
add missing data-testid attributes to byoc renderers.
## Summary
Fixes 15 ag2 showcase files to bring all 29 ag2 features to D5-green
(verified locally with the D5 probe runner).
### Backend fixes
- **Starlette mount order**: `/open-gen-ui-advanced` must mount before
`/open-gen-ui` — Starlette resolves mounts via prefix matching in
registration order, so the shorter prefix was shadowing the longer one
- **`@tool` -> `@tool()` decorator**: bare `@tool` in
`agent_config_agent.py` silently fails to register the function as a
CopilotKit tool; needs the call form `@tool()`
- **headless-complete route wiring**: wired the headless-complete agent
into the `copilotkit-mcp-apps` runtime route so MCP Apps activity
messages render in the headless cell
- **Auth route cleanup**: removed stale `@ts-ignore`
- **Manifest update**: corrected headless-complete's route reference
from `copilotkit` to `copilotkit-mcp-apps`
### Demo page fixes
- **agent-config**: replaced broken `useAgent`/`setState` pattern with
CopilotKit `properties` prop (the correct way to pass config to AG2
ContextVariables)
- **multimodal**: rewrote the legacy-binary-shape converter to a content
flattener — AG2's AGUIStream validates message content as a plain string
and rejects content-part arrays with a 400
- **headless-complete**: changed `runtimeUrl` from `/api/copilotkit` to
`/api/copilotkit-mcp-apps`
- **byoc-hashbrown, byoc-json-render**: re-attached
`data-testid="copilot-assistant-message"` on custom slot overrides
(harness conversation runner needs this to count settled responses)
- **agentic-chat-reasoning, beautiful-chat**: added demo-level
`data-testid` wrappers
- **tool-rendering-reasoning-chain, voice**: fixed CopilotKit import
paths
### Railway rebuild note
Several demos (chat-slots, shared-state-*, subagents) were already
code-correct on `main` but showed D5 failures due to a stale Railway
image. A Railway rebuild (no code changes) will bring those green as
well.
## Test plan
- [ ] 29/29 ag2 features pass D5 probes locally (verified before PR)
- [ ] CI passes
- [ ] After merge + Railway rebuild, ag2 column should be fully D5-green
Rewrite the multimodal demo's message converter from a legacy-binary-shape
rewriter to a content flattener. AG2's AGUIStream validates message content
as a plain string and rejects arrays of content parts with a 400. The new
ContentFlattenerShim extracts text from multipart user messages before the
AG-UI run dispatches them to the AG2 backend.
Also adds defensive validation to sample-attachment-buttons: magic-byte
checks, LFS pointer detection, and actionable error messages.
- Fix Starlette mount order: /open-gen-ui-advanced before /open-gen-ui to
prevent prefix shadowing (open-gen-ui-advanced was unreachable)
- Fix @tool -> @tool() decorator in agent_config_agent.py (bare @tool
silently fails to register the function as a CopilotKit tool)
- Wire headless-complete agent into copilotkit-mcp-apps route so the
headless-complete demo can exercise MCP Apps rendering
- Update manifest to reference copilotkit-mcp-apps route for headless-complete
- Remove stale @ts-ignore in auth route
Add GET /trigger/eval route to eval-webhook with HMAC-signed URLs.
The showcase_eval_check.yml workflow now posts a bot comment with a
clickable "Run Evaluation" link. Clicking triggers the eval and
redirects back to the PR. The link is signed so it can't be forged.
## Summary
- Fix TOOL_CALL_RESULT events reusing parent assistant message ID across
StreamingToolAgent, SharedStateReadWriteController, and
SubagentsController —
React's deduplicateMessages() Map overwrote assistant messages with tool
messages when they shared the same ID
- Add `data-testid="copilot-assistant-message"` to BYOC hashbrown
renderer so
the D5 test harness can detect assistant messages
- Register AG-UI Jackson mixins via JacksonConfig postConfigurer,
normalize
array-format content via ContentNormalizingModule, remove ChatMemory
beans
that interfered with aimock fixture matching, inject Spring-managed
ObjectMapper into AgentConfigController
## Test plan
- [x] All 28/28 spring-ai D5 features pass locally (verified stable
across
multiple consecutive runs)
- [x] Docker build succeeds
- [x] No regressions — previously passing 22 features remain green
Root cause: TOOL_CALL_RESULT events reused the parent assistant
message ID, causing React deduplicateMessages() to overwrite
assistant messages with tool messages (Map keyed by ID). Fix uses
unique UUIDs for each tool result message across all three
controllers. Also adds data-testid to the BYOC hashbrown renderer
so the D5 harness can detect assistant messages, registers AG-UI
Jackson mixins via JacksonConfig postConfigurer, normalizes
array-format content via ContentNormalizingModule, removes ChatMemory
beans that interfered with aimock fixture matching, and injects
Spring-managed ObjectMapper into AgentConfigController.
Covers: failure triage (text-only vs tool features, probe text extraction,
message disappearing, chatMemory pollution), framework-specific gotchas
(LlamaIndex, Spring AI, Built-in Agent, MS Agent, AG2), and production
vs local parity checklist.
- Add buffer length check before timingSafeEqual to prevent RangeError
on missing/malformed X-Hub-Signature-256 headers
- Switch Dockerfile from pnpm to npm with package-lock.json (pnpm
lockfile lives at monorepo root, not in the package directory)
Add --ci flag to eval orchestrator that skips Docker lifecycle and
assumes services are already running. Add ci-native-eval.sh helper
that installs deps, starts next dev + agent servers natively, health-
waits, then runs showcase eval --ci. Fix on-demand E2E workflow with
langgraph-python support and agent-type detection.
Hono web server that receives check_run.requested_action webhooks from
GitHub, authenticates as the devops bot, updates the Check Run to
in_progress, and dispatches showcase_eval.yml via workflow_dispatch.
Includes GHCR build workflow and pnpm workspace registration.
The cell status row rendered RT (D4/e2e) and CV (D5) badges but was
missing the D2/API badge despite the legend already documenting it.
- Add `d2` field to `CellState` sourced from `agent:<slug>` rows
- Render API LiveBadge before RT in CellStatus (D2 < D4 ordering)
- Add API (Agent) to CellDrilldown DIMENSIONS array
- Fix stale FP/D6 references in tests left over from #4513
## 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).
## Summary
Sidebar / IA / HITL cleanup from the shell-docs QA triage. Adds fallback
callouts to HITL pages for non-native frameworks, fixes gate scoping
bugs, wires orphan pages into nav, adds missing `meta.json`.
**Items addressed:**
- 3.1 — `useInterrupt` and `headless` fallback callout for the 13
frameworks without `interrupt_pattern` (via new `absent` mode on
`<WhenFrameworkHas>`)
- 3.3 — `headless.mdx` `useHeadlessInterrupt` symbol scope fix (wrap
"Driving it from plain UI" inside the native gate)
- 3.5 — `multi-agent/meta.json` added so breadcrumbs use the explicit
"Multi-Agent" label
- 17.1 — `agent-config.mdx` shared lead-in between `<InlineDemo>` and
the gated branches
- 18.1 — `ag-ui-middleware.mdx` moved under `agentic-protocols/`,
registered in `meta.json`, links to upstream AG-UI guide, 302 from the
old `/ag-ui-middleware` path
## Visual inspection
1. Start the dev server:
```bash
nx run shell-docs:dev
```
Open http://localhost:3003.
2. **HITL fallback callout.** Switch the framework picker to each of:
`built-in-agent`, `mastra`, `crewai-crews`, `ag2`, `google-adk`,
`pydantic-ai`, `agno`, `claude-sdk-python`, `claude-sdk-typescript`,
`llamaindex`, `langroid`, `spring-ai`, `strands`. For each, navigate to:
- `/human-in-the-loop/useInterrupt`
- `/human-in-the-loop/headless`
The page should render a callout pointing readers at
`/human-in-the-loop` (`useHumanInTheLoop`), NOT collapse to an empty
middle.
3. **HITL native framework check (no regression).** Switch to
`langgraph-fastapi`, `langgraph-typescript`, `langgraph-python`,
`ms-agent-dotnet`, `ms-agent-python`. Same two pages should still render
their full native/promise-based content. Especially check
`/human-in-the-loop/headless` for proper `useHeadlessInterrupt` usage
now within its gate.
4. **Multi-agent sidebar.** With any framework selected, confirm
"Multi-Agent" appears in the sidebar with `subagents` as a sub-entry.
5. **agent-config lead-in.** Visit `/agent-config`. Verify there's a
smooth prose transition between the InlineDemo and the "How it works"
section.
6. **AG-UI middleware sidebar.** Confirm `ag-ui-middleware` appears in
the sidebar under the AG-UI / agentic-protocols section. Click through
and verify the page renders correctly. Verify the 302 from the old
`/ag-ui-middleware` URL works.
7. **Anti-checks (should NOT have changed):**
- Per-framework HITL nav for the 5 native fws unchanged in shape.
- Other sidebar sections unaffected.
- Existing `<WhenFrameworkHas>` gates on other pages still work.
Reorder legend items so depth-related explanations (D0-D4, L1-L4 Strip,
D4 RT, D5 CV, D6 FP) are grouped together on the left, followed by the
regression indicator, color chips, and status symbols.
The DepthChip (colored badge) correctly shows D4/D5/D6 depth numbers.
The descriptive text row below each cell's chip was also showing D4/D5/D6
instead of the human-readable RT (Round Trip) / CV (Conversation) /
FP (Feature Parity) labels. Fix the LiveBadge name props in CellStatus,
the DIMENSIONS labels in CellDrilldown, and all related tests.
Partially reverts #4506: chips display depth-layer numbers (D4, D5, D6)
instead of abbreviations (RT, CV, FP). The descriptive labels Round Trip,
Conversation, and Feature Parity now appear in parentheses in the cell
drilldown dimensions and as legend explanations, keeping the abbreviations
in prose only.
- cell-pieces: chip names D4/D5/D6 (were RT/CV/FP)
- cell-drilldown: dimension labels "D4 (Round Trip)" etc.
- adaptive-legend: chip refs use D4/D5/D6, descriptive text uses RT/CV/FP
- feature-grid tooltip: D4 per feature
- tests updated to match
Rename per-cell badge chip labels for clarity:
- E2E -> RT (Round Trip): single message, full-stack response verification
- D5 -> CV (Conversation): multi-turn scripted dialogue with tool calls
- D6 -> FP (Feature Parity): cross-framework behavioral consistency check
Reorganize the adaptive legend to group chip color indicators first,
followed by descriptive labels explaining what RT, CV, and FP mean.
Update cell-drilldown dimension labels to match the new naming.
Update all affected tests to use the new label strings.
## Summary
- Spring-ai StreamingToolAgent now classifies tool calls as frontend vs
backend, emitting TOOL_CALL events without TOOL_CALL_RESULT for frontend
tools so the CopilotKit runtime's processAgentResult handles them
- On HITL re-invocation (tool result sent back), sends full AG-UI
message history to aimock/LLM via convertMessages() for correct fixture
matching
- Fixes 3 HITL features: hitl-text-input, hitl-approve-deny, hitl-steps
(spring-ai now 6/11 D5 green, up from 3/11)
## Remaining 5 failures (pre-existing, not caused by this PR)
| Feature | Root cause |
|---------|-----------|
| tool-rendering | CopilotKit frontend re-render drops assistant
messages (count goes 1→0) |
| shared-state-read | SharedStateReadWriteController — separate
controller, not StreamingToolAgent |
| shared-state-write | Same as shared-state-read |
| subagents | SubagentsController — aimock returns "No fixture matched"
(404) |
| mcp-apps | Depends on external MCP server (excalidraw.com) unreachable
from Docker |
All 5 fail identically on baseline (main) without this PR's changes.
## Test plan
- [x] `showcase test spring-ai --d5` — 6 green, 5 red (same 5 red on
baseline)
- [x] Direct curl to Java backend confirms correct AG-UI event sequences
for all HITL flows
- [x] No regressions: agentic-chat, gen-ui-custom, gen-ui-headless still
pass
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.
## Summary
Hide and clean up stale shell-docs pages. Drops orphaned/broken/AI-slop
pages from nav, adds 302 redirects, deletes dead per-framework
overrides.
**Items addressed (from [triage
plan](https://app.notion.com/p/3523aa3818528128bcb0ee9e137cfff0)):**
- 1.1 — Tutorials (broken end-to-end; rewrite post-launch)
- 6.1 — `coding-agent-setup.mdx` (rename straggler)
- 10.1 — `copilot-suggestions.mdx` (orphaned broken stub)
- 11.1 — `generative-ui/open-json-ui.mdx` (AI-slop placeholder; rewrite
post-launch)
- 21.1 — `migrate/1.10.X.mdx` (~1-year-old migration target, no longer
supported)
- 3.4 — Legacy per-framework HITL overrides — see Concerns
- 16.1 — 3 orphan `state-inputs-outputs` / `workflow-execution` files in
adk/langgraph/llamaindex
All redirects are 302 (not 301) — we'll restore at the same URLs when
the affected pages are properly authored post-launch.
## Concerns
**3.4 (HITL overrides) intentionally NOT executed in this PR.** Audit
found that every per-framework HITL override carries substantive
framework-specific content beyond the canonical (e.g. `IframeSwitcher`
blocks pointing at fw-specific feature-viewer URLs, `CTACards` linking
to fw-specific sub-pages like
`/mastra/human-in-the-loop/interrupt-flow`,
`/crewai-flows/human-in-the-loop/flow`, etc.). Per the task's "be
conservative" guidance, none were deleted. If we want to land 3.4 the
right way, it likely needs a follow-up that either (a) merges the
fw-specific iframe demos into the canonical via per-fw branching, or (b)
explicitly designates these as legitimate per-fw overrides and accepts
them. Flagging for a separate decision.
## Visual inspection
1. Start the dev server:
```bash
nx run shell-docs:dev
```
Open http://localhost:3003.
2. **Sidebar disappearance.** Confirm the following are no longer in the
left sidebar:
- "Tutorials" section (entire dividing block + sub-pages)
- `Open-JSON-UI` under Generative UI > Declarative
- `Migrate to 1.10.X` under Migrate
- `Coding Agent Setup` and `Chat Suggestions` (these were already not in
nav — visual check just confirms nothing changed)
3. **Redirect check.** Visit these URLs directly; each should 302 to the
destination:
- `http://localhost:3003/tutorials/ai-todo-app/overview` → `/`
- `http://localhost:3003/tutorials/multi-conversation-chat` → `/`
- `http://localhost:3003/coding-agent-setup` → `/coding-agents`
- `http://localhost:3003/copilot-suggestions` → `/`
- `http://localhost:3003/generative-ui/open-json-ui` → `/generative-ui`
- `http://localhost:3003/migrate/1.10.X` → `/migrate`
4. **Shared-state per-fw check.** For adk, langgraph, llamaindex:
navigate to `/shared-state` (or the corresponding shared-state sidebar
entries). Confirm only the wired version (per `meta.json`) appears in
nav. The orphan URLs should 404 cleanly.
5. **Anti-checks (these should NOT have changed):**
- All other docs pages render normally.
- The canonical `human-in-the-loop` content (root) is unchanged.
- Existing redirect rules in `next.config.ts` still work.
Jordan Ritter