## Summary
- Rename 3 confusingly-named probe driver files to reflect what they
actually do:
- `smoke` → `liveness` (HTTP liveness check, not a smoke test)
- `e2e-smoke` → `e2e-chat-tools` (Playwright chat + tool-rendering test)
- `e2e-demos` → `e2e-readiness` (Playwright structural check across all
demos)
- Reorder cell drilldown popup: D6 Parity → D5 Deep → E2E → Health →
Smoke (highest depth first)
Kind strings, PB dimension keys, and YAML configs are intentionally
unchanged — this is a file/export rename only with no data migration.
## Test plan
- [x] All 1343 showcase/ops tests pass
- [x] All imports verified via grep — zero stale references
- [x] YAML→driver mapping verified (loader uses kind strings, not file
paths)
- [x] 7-agent CR converged Round 1 with 0 findings
The previous commit (993746111) bundled image fixes with a structural
nav change that wasn't asked for. The ask was simply "rename the page
to Overview so there is no duplicated item in the nav" — a frontmatter
title change, nothing more.
Reverting just the structural pieces:
- agentic-protocols/overview.mdx → index.mdx (back to original filename)
- agentic-protocols/meta.json: pages list back to ["index", ...]
- top-level meta.json: drop "---Agentic Protocols---" section header so
agentic-protocols stays as a subgroup under Get Started
- next.config.ts: drop the new /agentic-protocols → /overview redirect;
restore /concepts/agentic-protocols and /learn/agentic-protocols
redirect targets to /agentic-protocols (not /overview)
The page's frontmatter title stays "Overview" — that part of 993746111
was the actual ask and it solves the duplicate-label problem on its own.
Image fixes from 993746111 are kept.
## Replaced 11 LFS-pointer-stub images with real binaries
The repo stores several diagram PNGs in Git LFS and the local clone
didn't have them resolved (git-lfs not installed). They were 131-byte
text-pointer files on disk, so every page that referenced them
showed a broken-image icon. Affected images:
- any-agentic-backend-{light,dark}.png (used on /agentic-protocols
overview, /agentic-protocols/a2a, /agentic-protocols/mcp)
- agui-ecosystem-{light,dark}.png (/agentic-protocols/ag-ui)
- mcp-and-a2a-through-agui-{light,dark}.png (overview)
- gen-ui-specs-{light,dark}.png (/concepts/generative-ui-overview)
- ai-protocol-stack.png, ag-ui-overview-with-partners-dark.png,
a2ui-composer.png (referenced from various promoted pages)
- generative-ui/{chat,chat-plus,chatless}-surface.png (the surfaces
section in /concepts/generative-ui-overview — these were missing
from public/images entirely after the gen-UI merge; copied from
upstream first, then replaced with the real binaries from the live
docs site since upstream's copies are also LFS stubs)
Source: production docs site at docs.copilotkit.ai/images/* (HTTP 200
on every file). Pulled via curl, sizes range 128KB–714KB — real
binaries, not pointers.
## Agentic Protocols promoted to its own section
Per design call: "Agentic Protocols" is now a top-level section
between Get Started and Build Chat UIs (was wedged into Get Started
as a spread group, which produced an awkward duplicate label —
"Agentic Protocols" group label with an "Agentic Protocols" page
entry inside it).
Changes:
- `agentic-protocols/index.mdx` renamed to `overview.mdx` so the
nav slug is `/agentic-protocols/overview` (was the ugly
`/agentic-protocols/index` because buildNavTree pushed `"index"`
through as a literal slug).
- The page's frontmatter title is now "Overview" (was "Agentic
Protocols", which duplicated the section header in the nav).
- `agentic-protocols/meta.json` lists `["overview", "ag-ui", "mcp",
"a2a"]`.
- Top-level `meta.json` adds `---Agentic Protocols---` section header
before the spread, dropping the wedged `...agentic-protocols` from
inside Get Started.
- `next.config.ts` adds `/agentic-protocols → /agentic-protocols/overview`
redirect (the bare path used to resolve via `index.mdx`; now needs
to land on the renamed overview page). The earlier `/learn/...`
and `/concepts/...` redirects for the same target updated to point
at `/overview` directly.
## Sidebar reads cleanly now
GET STARTED
Quickstart, Coding Agents, Concepts (3-page subgroup)
AGENTIC PROTOCOLS
Overview, AG-UI, MCP, A2A
BUILD CHAT UIS
...
The first Accordion body wrapped two paragraphs of prose in a manual
`<p>...</p>` tag. MDX auto-wraps each blank-line-separated paragraph
in its own `<p>`, so the rendered output became `<p><p>...</p><p>...</p></p>`
— invalid HTML and a hydration error in the browser.
Removed the outer `<p>` wrapper; the prose now relies on MDX's
default paragraph wrapping. Also fixed a typo in the same block
("a server the suits your needs" → "a server that suits your needs").
Inherited from the upstream `learn/connect-mcp-servers.mdx` source.
Verified zero nested-`<p>` occurrences across all 13 of the
moved/promoted pages on this branch.
Tightens the Concepts subgroup (which had ballooned to 10 entries
after the /learn/ consolidation) and gives the protocol pages and
Enterprise-flavoured explanation pages the homes they actually
belong in.
## Structural changes
**New `Agentic Protocols` section under Get Started.** The four
protocol-related pages move from `/concepts/*` into a dedicated
`/agentic-protocols/` folder so they live as a coherent section
rather than as four siblings inside Concepts. Titles drop the
`(Agents<->X)` parenthetical — folder + section context already
disambiguates.
/concepts/agentic-protocols → /agentic-protocols (now the section overview)
/concepts/ag-ui-protocol → /agentic-protocols/ag-ui
/concepts/mcp-servers → /agentic-protocols/mcp
/concepts/a2a-protocol → /agentic-protocols/a2a
`agentic-protocols/meta.json` lists the four pages with the section
overview as `index`. Top-level `meta.json` adds `...agentic-protocols`
under Get Started.
**Intelligence Platform + Threads explanation pages move to
Enterprise.** Both pages document Premium-only architecture
(threads + the platform that hosts them); they belong next to the
how-to and self-hosting pages, not in framework-agnostic Concepts.
/concepts/intelligence-platform → /premium/intelligence-platform
/concepts/threads → /premium/threads-explained
(renamed to disambiguate from
the existing how-to /threads)
`premium/meta.json` reordered so the explanation pages sit between
the overview and the how-to pages.
**Generative UI Overview merged.** The old
`concepts/generative-ui-overview.mdx` (long, with surfaces /
attributes / patterns / ecosystem mapping sections, but using
inconsistent terminology — "Static" vs "Controlled") and
`concepts/three-types-of-gen-ui.mdx` (concise, sharp prose, canonical
"Controlled / Declarative / Open-Ended" terminology that matches the
Build Generative UI nav section names) overlapped substantially.
Merged into a single `concepts/generative-ui-overview.mdx` with:
- Tight intro from three-types
- Application Surfaces section (chat / chat+ / chatless) from overview
— unique value, not duplicated elsewhere
- Three types section using three-types' prose + terminology, with
the tradeoff bullets borrowed from overview's PatternCard component
- Ecosystem Mapping table from overview, retitled with the unified
terminology
- "AG-UI / CopilotKit are gen-UI agnostic" closer with the dual
light/dark image
- "Where to go next" pointers for downstream guides
three-types-of-gen-ui deleted; redirect catches any inbound link.
## `<Image>` registry fix (load-bearing)
The MDX `<Image>` component was registered to destructure only `src`
and `alt`, silently dropping `className`. Every page that ships dual
light/dark variants (`block dark:hidden` / `hidden dark:block`)
rendered both versions stacked — the user-visible "duplicate image"
on agentic-protocols (and the same shape on ag-ui, a2a, mcp, the
gen-UI overview).
Updated the registry component to forward `className`, `width`, and
`height`. The dark/light Tailwind toggling now works as authored.
## Concepts post-restructure
After the moves, the Concepts subgroup is back to a focused set:
architecture
generative-ui-overview
oss-vs-enterprise
These are the framework-agnostic 5-minute primers under Get Started.
Everything that was specifically about a protocol, the Intelligence
Platform, or threads has a more accurate home.
## Redirects
Per-path rules in `next.config.ts` for every URL that was live
between the /learn/ consolidation pass and this restructure:
/concepts/agentic-protocols → /agentic-protocols
/concepts/ag-ui-protocol → /agentic-protocols/ag-ui
/concepts/mcp-servers → /agentic-protocols/mcp
/concepts/a2a-protocol → /agentic-protocols/a2a
/concepts/intelligence-platform → /premium/intelligence-platform
/concepts/threads → /premium/threads-explained
/concepts/three-types-of-gen-ui → /concepts/generative-ui-overview
The earlier /learn/ rules also rewritten to point straight at the
new canonical homes (avoiding 308→308 chains).
## Inbound link rewrites
All cross-page links in the moved pages, plus the architecture
concept page, oss-vs-enterprise concept page, threads how-to,
premium/self-hosting, useCapabilities reference, and the snippets
that referenced the old `/concepts/*` paths. Verified zero remaining
references to the old URLs (except the irrelevant external
`learn.microsoft.com` URLs in MS Agent Framework integration pages).
## Smoke tested
All 9 new canonical URLs return 200. All 10 sampled redirects
(7 /concepts/* + 3 /learn/*) hit the right destination in one hop.
The upstream `/learn/*` tree was largely a Diátaxis explanation-tier
parallel to the rest of the docs, and after the IA restructure shipped
the Concepts subgroup under Get Started in PR #4329, /learn/* read as
visible duplication: two "Threads" entries, two "Architecture"
entries, two "AG-UI" pages, etc. The earlier Notion plan kept the
split and proposed a nav-label fix; this PR reverses that call and
folds the explanation pages into Concepts where they belong.
## What moved
**Promoted to /concepts/** (7 files):
- learn/threads.mdx → concepts/threads.mdx
- learn/intelligence-platform.mdx → concepts/intelligence-platform.mdx
- learn/agentic-protocols.mdx → concepts/agentic-protocols.mdx
- learn/ag-ui-protocol.mdx → concepts/ag-ui-protocol.mdx
- learn/a2a-protocol.mdx → concepts/a2a-protocol.mdx
- learn/connect-mcp-servers.mdx → concepts/mcp-servers.mdx (renamed)
- learn/generative-ui/index.mdx → concepts/generative-ui-overview.mdx
The new Concepts subgroup is a 10-page cluster covering architecture,
the Intelligence Platform, the three gen-UI types + a deep overview,
the four agentic protocols (AG-UI, MCP, A2A, plus the meta page), and
threads + OSS-vs-Enterprise. Ordered by topic flow rather than
alphabetically.
**Moved to natural homes**:
- learn/tutorials/multi-conversation-chat.mdx → tutorials/multi-conversation-chat.mdx
- learn/generative-ui/specs/open-json-ui.mdx → generative-ui/open-json-ui.mdx (added under "Declarative" in the gen-UI nav alongside A2UI)
**Promoted to top-level /whats-new/**: 7 files. New top-level
nav section between Tutorials and Migrate. Release-cadence content
doesn't belong inside Concepts; promoting it gives it room to grow as
a real changelog.
**Deleted** (5 files, all stubs or duplicates):
- learn/index.mdx (the Learn landing — its card grid pointed at the
pages above, all of which now live elsewhere)
- learn/architecture.mdx (15L stub: just a heading + the same
ImageZoom that already lives in /concepts/architecture)
- learn/generative-ui/specs/{index, a2ui, mcp-apps}.mdx (7-line
component-stubs already covered by their canonical
/generative-ui/* pages)
- learn/generative-ui/{meta.json, specs/meta.json} + learn/meta.json
(now-empty meta scaffolding)
## Nav updates
- concepts/meta.json grows to 10 pages, ordered by topic cluster
- tutorials/meta.json adds multi-conversation-chat
- generative-ui/meta.json adds open-json-ui under "Declarative"
- whats-new/meta.json gets a clean "What's New" title (was a dated
"Updates - Jan 22, 2025") + the full file list in reverse-chrono
- top-level meta.json gets a new "What's New" section between
Tutorials and Migrate
## Redirects
15 redirect rules in next.config.ts cover every /learn/* path that
existed (literal pages + the /learn/whats-new/:path* and
/learn/generative-ui/specs/* sets). Plus a generic /learn → /concepts/architecture
catch-all so the old root URL doesn't 404.
## Inbound link rewrites
22 inbound /learn/* references rewritten across the docs tree
(snippets, threads.mdx, premium/self-hosting.mdx, useCapabilities,
useThreads, the existing Concepts pages that linked to /learn/*, and
internal cross-links inside the moved files themselves). Verified zero
remaining /learn/ references except the unrelated `learn.microsoft.com`
external URLs in the MS Agent Framework integration pages.
## Smoke tested
All 12 new canonical URLs return 200. All 8 sampled /learn/* legacy
URLs 308-redirect to the correct canonical home (/concepts/*, /tutorials/*,
/generative-ui/*, /whats-new/*).
Closes PDX-69.
Two follow-ups from the tutorial walkthrough.
**Standalone Card link styling.** Cards used outside a `<Cards>`
wrapper (the GitHub source link on tutorial overviews; the lone Next
card on step-1 before this commit) still showed prose-style
underlines. Reason: the escape-hatch CSS rule
`.reference-content .not-prose a { text-decoration: none }` is a
*descendant* selector — it requires `not-prose` to live on a parent
of the <a>. Standalone Cards have nothing above them carrying that
class, so the rule never fired. Cards inside `<Cards>` were fine
because the wrapper has `not-prose`.
Fixed by adding inline `style={{ textDecoration: "none", color:
"inherit" }}` to the linked Card. Inline styles win on specificity
in every shape, regardless of whether `not-prose` is present on a
parent. The class-based `not-prose` + `no-underline` stay too —
they're harmless and serve as documentation of intent.
**Previous on step-1.** Earlier "steps 2-end need Previous" was read
too literally; step-1 of both tutorials wasn't getting a Previous
link back to overview. Added Previous + Next pairs (in `<Cards>`
2-column grid) on step-1 of both tutorials, matching the layout used
on step-2 / step-3 / step-4.
The full chain now:
overview → Next only
step-1 → Prev (Overview) + Next
step-2 / 3 / 4 → Prev + Next
next-steps → Prev only
MDX wraps loose paragraphs in <p>. The hand-written `<p>` I'd used
for the time/difficulty meta line ended up inside another <p> wrapper
generated by MDX, producing `<p><p>...</p></p>` — invalid HTML and a
hydration error in the dev console.
Switching to a `<div>` keeps the same inline-styled muted-text
appearance without triggering the autoclose-then-reopen behaviour
that React/HTML enforces around block-vs-inline `<p>` rules.
Verified the rendered HTML for /tutorials/ai-todo-app/overview no
longer contains a `<p><p>` sequence.
The MDX article body has class `.reference-content`, which carries
this global rule:
.reference-content a {
color: var(--accent);
text-decoration: underline;
}
That selector wins specificity-wise against Tailwind's `.no-underline`
class on the wrapping `<a>`, so the previous Card styling fix didn't
actually visibly remove the underline — the markup said
`no-underline` but the rendered link still had it.
The site has an escape-hatch rule:
.reference-content .not-prose a {
text-decoration: none;
color: inherit;
}
Add `not-prose` to the wrapping Cards container and to the linked
Card itself. The Card's own `hover:border-[var(--accent)]` +
`group-hover:text-[var(--accent)]` classes now control link
appearance entirely.
Verified the rendered anchor on /tutorials/ai-todo-app/step-2-setup-copilotkit
has both `not-prose` and `no-underline` on the wrapping <a>.
The earlier `unselected/` cleanup pass categorized
`unselected/generative-ui/your-components/interrupt-based.mdx` as
D-promote (unique content, needs new home at root). On closer
inspection the file is byte-identical to
`integrations/langgraph/human-in-the-loop/interrupt-flow.mdx` (modulo
title), and references LangGraph's `interrupt()` API + LangChain
interrupt docs throughout — it's LangGraph-specific, not a
framework-agnostic generative-UI feature.
Mastra has its own different interrupt-flow.mdx (264L vs 403L). Other
frameworks (ag2, agno, adk, llamaindex, etc.) don't have an interrupt
flow at all because their agent runtimes don't expose the concept.
Putting it at root would mislead users on other frameworks into
expecting an API that doesn't exist for them.
Reversing the promotion:
- Delete `generative-ui/your-components/interrupt-based.mdx` from the
root tree
- Drop `interrupt-based` from `generative-ui/your-components/meta.json`
- Repoint the `/unselected/.../interrupt-based` redirect to
`/human-in-the-loop` (the framework-agnostic HITL page) instead of
the now-deleted root location
LangGraph's interrupt page stays reachable at
`/langgraph-python/human-in-the-loop/interrupt-flow` (sidebar entry
"Interrupts" under the LangGraph framework block). Mastra's stays at
`/mastra/human-in-the-loop/interrupt-flow`. The `unselected/` copy was
just a redundant fork that was never visible in nav anyway.
Updates the verified-audit framing recorded in PDX-49 — the "13
unique promotions" count drops to 12 (the tutorials), and a new
D-delete entry replaces the interrupt-based promotion.
Three issues from the tutorial polish smoke test.
**1. Card links no longer show prose underlines, hover matches the
rest of the site.** The MDX `<Card>` component was rendering as a
`<Link>` wrapping a styled `<div>`, so prose CSS added a default
underline to the link text and the hover state was a faint
`bg-elevated` swap. Aligns with the docs-landing pointer-card pattern:
`no-underline`, accent border + soft shadow on hover, title color
flips to accent via `group-hover`. Non-linked Cards keep their
neutral surface.
**2. Tutorial overview meta strip simplified.** Replaced the heavier
`<Callout type="info">` (rendered with the "Info" icon + label) with
a small muted inline line: "⏱ 5 minutes · Easy". The Callout was
overweight for two pieces of frontmatter-style metadata.
**3. Previous buttons added to step-2 through next-steps** on both
tutorials. Each step now has a Prev + Next pair (in a `<Cards>`
2-column grid); the terminal `next-steps` page has Prev only. Pattern:
step-1: Next only
step-2..4: Prev + Next side by side
next-steps: Prev only
**4. Dev meta cache invalidation.** Caught while testing the earlier
interrupt-based nav fix: `metaCache` and `titleCache` in
`lib/docs-render.tsx` are process-scoped, so meta.json edits in dev
required a server restart to show up. Skip both caches when
`NODE_ENV=development` so authors get immediate feedback. Build / prod
behaviour unchanged (content is frozen at deploy time, so caching
the entire process lifetime is still right there).
Verified `/your-components/interrupt-based` now appears in the
sidebar without a restart, all 8 step Prev/Next routes return 200.
Three small fixes that surfaced when smoke-testing the
unselected/ → /tutorials/ promotion.
**Tutorial overviews** styled to match the rest of the site:
- Time/difficulty meta is now a `<Callout type="info">` (was a bare
`<div>` block with raw `**bold**` markdown that rendered as plain
prose).
- GitHub source link is a styled `<Card>` (was a hand-rolled
`<button class="bg-neutral-800 ...">` wrapped in `<Link>`, which
didn't match site Card patterns and rendered the icon as a
keyboard glyph since react-icons isn't in the MDX registry).
- Demo iframe is wrapped in `<Frame>` (was a hand-rolled chrome bar
with `bg-neutral-800` header div that didn't match site styling).
- Redundant `<h1>` "AI Todo List Copilot Tutorial" / "AI-Powered
Textarea Tutorial" headings removed — page title comes from
frontmatter + meta already.
- Fixed `<YouTubeVideo>` props: `videoId` → `id`, dropped
`defaultPlaybackRate` (neither matched the registry component's
shape; videos rendered nothing before).
**Next-step buttons** added to every step page until the final one.
Each step ends with a `<Card title="Next: ..." href="..."
description="..." />` so the reader can click straight through:
- ai-todo-app: overview → step-1 → step-2 → step-3 → step-4 → next-steps
- ai-powered-textarea: overview → step-1 → step-2 → step-3 → step-4 → next-steps
The terminal `next-steps` page has no Next card (per "until the final
one" — it's the wrap-up).
**Dangling import tails removed** from both tutorials' step-2 files —
historical sync-stripper artifact (orphaned `TailoredContent,
TailoredContentOption, } from "..."` block with the opening `import {`
missing).
**interrupt-based nav fix:** `generative-ui/your-components/meta.json`
was missing `interrupt-based` in its `pages` array, so the file
existed on disk but never appeared in the sidebar.
Verified all 13 tutorial / Next-button URLs return 200 in dev.
Three unique-content moves from `unselected/`:
- 12 tutorial files in two series (`ai-todo-app/*`, `ai-powered-textarea/*`)
→ `/tutorials/*` with a new `---Tutorials---` section in the top-level
nav, slotted before Migrate.
- `generative-ui/your-components/interrupt-based.mdx` (403L) →
`generative-ui/your-components/interrupt-based.mdx` alongside the
existing `display-only.mdx` and `interactive.mdx` peer pages.
Inline `/unselected/tutorials/*` link references (only in the two
`next-steps.mdx` files) rewritten to `/tutorials/*`.
Fixes a stale meta entry: `tutorials/ai-todo-app/meta.json` referenced
`step-4-copilot-actions` but the actual file was renamed to
`step-4-frontend-tools.mdx` at some point. Aligned the meta to the
real filename.
Outer `tutorials/meta.json` title bumped from `"tutorials"` to
`"Tutorials"` so the matching `---Tutorials---` section header
triggers the existing nav-render dedup (suppresses the redundant
inner group label).
Verified: `/tutorials/ai-todo-app/overview`, `/tutorials/ai-powered-textarea/overview`,
`/built-in-agent/tutorials/ai-todo-app/overview`, and
`/generative-ui/your-components/interrupt-based` all 200 in dev.
Nine files where the root version was either a one-line component stub
(`<Inspector />`, `<HeadlessUI />`, `<Observability />`, `<Overview />`)
or used v1 API patterns (`<CopilotKit>` / `@copilotkit/react-core`)
that the unselected/ tree had already updated to v2 patterns
(`<CopilotKitProvider>` / `@copilotkit/react-core/v2`). Promoting the
richer content over the root stubs / v1 versions:
- inspector.mdx (root: 11L stub → 79L of real content)
- premium/headless-ui.mdx (root: 7L stub → 290L)
- premium/observability.mdx (root: 7L stub → 259L)
- premium/overview.mdx (root: 7L stub → 84L)
- generative-ui/your-components/interactive.mdx (root: 21L IntegrationGrid placeholder → 78L with snippet_cell)
- troubleshooting/common-issues.mdx (v1 imports → v2; tighter prose)
- troubleshooting/error-debugging.mdx (v1 imports → v2; "& Observability" added to title; programmatic onError section retained)
- backend/ag-ui.mdx (v1 → v2 imports)
- backend/copilot-runtime.mdx (v1 → v2 imports)
The unselected/ versions weren't a side-tree of duplicate content —
they were the v2-aware refresh that hadn't propagated to root yet.
First commit of the `unselected/` editorial cleanup tracked under
PDX-49. Cat A deletes (root canonical), Cat B deletes (BIA canonical),
D-promote moves (interrupt-based + 12 tutorials), Cat D-delete
(agent-app-context), redirect rules, and inbound link rewrites still
to come.
Per-framework region pass on llamaindex. 16 (framework x cell) targets
advanced from B (regions missing) to A (ready). Same patterns as mastra
(#4326), smalls batch 1 (#4361), ms-agent batch 2 (#4363), and google-adk
(#4369).
Frontend regions (in-place markers):
- agentic-chat: provider-setup, configure-suggestions
- prebuilt-popup: popup-basic-setup
- prebuilt-sidebar: sidebar-basic-setup, sidebar-configuration
- frontend-tools: frontend-tool-registration + handler
- chat-customization-css: theme-css-import (page.tsx) + css-variables (theme.css)
- chat-slots: register-welcome-slot (lifted prop into named variable)
- tool-rendering: render-weather-tool
- tool-rendering-default-catchall: default-catchall-zero-config
- tool-rendering-custom-catchall: use-default-render-tool-wildcard
- headless-simple: use-agent-simple, message-list-simple
- readonly-state-agent-context: context-provider-sketch, use-agent-context-call
- open-gen-ui: minimal-runtime-flag (route.ts)
- open-gen-ui-advanced: advanced-runtime-config (same span as minimal)
- shared-state-read-write: notes-card-render, preferences-card-render
(multi-file), use-agent-read, use-agent-write
- subagents: delegation-log-frontend
Sibling teaching files (mirror mastra/google-adk pattern):
- agentic-chat/chat-component.snippet.tsx (production Chat carries QA
hooks - useFrontendTool, useRenderTool, useAgentContext - that aren't
relevant to the prebuilt-chat docs page)
- tool-rendering/render-flight-tool.snippet.tsx (covers both
render-flight-tool and catchall-renderer; production demo only
registers a weather renderer)
Backend regions (Python files):
- tool-rendering: weather-tool-backend on src/agents/agent.py
(manifest highlight extended to include this shared-agent file)
- a2ui-fixed-schema: backend-schema-json-load + backend-render-operations
on src/agents/a2ui_fixed.py - wraps llamaindex's idiom (raw a2ui_operations
dict ops returned from a backend tool) rather than langgraph-python's
a2ui.render(...) helper
Manifest highlight added: tool-rendering picked up src/agents/agent.py so
the backend region is bundled with the cell. All other backend files were
already in highlight.
Deferred (documented divergence; will pick up via PDX-68 auto-config or
when showcase team aligns):
- chat-slots disclaimer + assistant-message slots - production demo only
registers welcome; the other slots aren't implemented.
- declarative-gen-ui::runtime-inject-tool - cross-cutting (PDX-70).
- headless-complete (5 regions: custom-bubbles, manual-activity-message-
rendering, manual-tool-call-rendering, page-send-message, use-rendered-
messages-hook) - llamaindex's headless-complete is structurally simpler
than the canonical pattern (single MessageList component, no separate
bubble components, no useRenderedMessages hook). The regions don't fit
cleanly. Defer until showcase team expands the demo or PDX-68 ships.
- shared-state-streaming - llamaindex demo is a TODO stub (page.tsx
contains 'TODO: Implement State Streaming demo'); skip until the demo
is implemented.
Add `// @region[...]` markers (or sibling .snippet.tsx files where the
production demo doesn't exercise the region the docs teach) to bring
pydantic-ai to feature parity with langgraph-python's region coverage,
so shell-docs renders real teaching code instead of "Missing snippet"
boxes.
Cells advanced (in-place markers): agentic-chat, chat-customization-css,
chat-slots, frontend-tools, headless-simple, open-gen-ui,
open-gen-ui-advanced, prebuilt-popup, prebuilt-sidebar,
readonly-state-agent-context, shared-state-read-write, subagents,
tool-rendering-custom-catchall, tool-rendering-default-catchall,
a2ui-fixed-schema.
Cell with sibling file: tool-rendering — production page.tsx renders
only get_weather and uses an `{ args, ... }` render shape; added
render-flight-tool.snippet.tsx (mirroring mastra's pattern) for the
render-weather-tool / render-flight-tool / catchall-renderer regions
in the docs-canonical `{ parameters, ... }` shape, and an in-place
weather-tool-backend marker on the Python tool.
Deferred: declarative-gen-ui::runtime-inject-tool (cross-cutting,
tracked as PDX-70).
Brings claude-sdk-python to feature parity with langgraph-python on the
shell-docs snippet audit. 10 (framework x cell) targets advanced from B
(missing regions) to A (ready), following the patterns established in
#4326 (mastra), #4361 (smalls batch 1), #4363 (ms-agent), and #4369
(google-adk).
Frontend regions (in-place markers):
- agentic-chat: configure-suggestions, provider-setup
- frontend-tools: frontend-tool-handler, frontend-tool-registration
- headless-complete: page-send-message
- open-gen-ui: minimal-provider-setup
- open-gen-ui-advanced: sandbox-function-registration (multi-file:
page.tsx + sandbox-functions.ts)
- readonly-state-agent-context: context-provider-sketch,
use-agent-context-call
- tool-rendering: render-weather-tool
- tool-rendering-custom-catchall: use-default-render-tool-wildcard
- tool-rendering-default-catchall: default-catchall-zero-config
Runtime regions (route.ts, in-place):
- open-gen-ui: minimal-runtime-flag
- open-gen-ui-advanced: advanced-runtime-config
(both names share one block — server config is identical)
Backend regions (Python, in-place):
- subagents: subagent-setup wraps SUB_AGENT_PROMPTS plus _invoke_sub_agent;
supervisor-delegation-tools wraps _delegation_tool_schema plus
SUPERVISOR_TOOLS — captures the Claude Agent SDK idiom (Anthropic tool
schemas plus a manual run loop) rather than langgraph-python's
@tool/create_agent shape.
Sibling teaching files (production demo carries QA hooks irrelevant to
the docs page):
- agentic-chat/chat-component.snippet.tsx — minimal Chat for the
prebuilt-chat docs page
- tool-rendering/render-flight-tool.snippet.tsx — flight + catchall
renderer patterns; production demo only registers a weather renderer
- tool-rendering/weather_tool.snippet.py — single-tool teaching example
for the Anthropic tool-schema idiom; production agent.py declares
get_weather inside a shared TOOLS list with dispatch via _execute_tool
Markers are comment-only and stripped from rendered output, so the
runtime demos are byte-for-byte unchanged. No manifest edits.
Two additional sibling files in the same docs-only pattern as
chat-component.snippet.tsx and render-flight-tool.snippet.tsx, picking
up cells that were deferred in the previous commit because the
production demo doesn't use the slots/customizations the docs teach.
- chat-slots/disclaimer-and-assistant-message.snippet.tsx — wraps
register-disclaimer-slot and register-assistant-message-slot regions.
google-adk's production chat-slots only registers the welcome slot;
these regions now have a real teaching example without changing the
runtime demo.
- agentic-chat-reasoning/reasoning-block-render.snippet.tsx — wraps
reasoning-block-render. The production demo uses default reasoning
rendering and the ReasoningBlock component file exists but isn't
wired into the messageView slot. This file imports ReasoningBlock and
teaches the slot wiring pattern, leaving page.tsx untouched.
Both files follow the established convention: not imported, not
rendered, picked up by the bundler via @region markers, captioned via
the docs <Snippet title="…">. Two more cells (chat-slots,
agentic-chat-reasoning) flip from B to A — google-adk now at 20 cells
fully tagged.
Remaining deferred (engineering / cross-cutting only):
- gen-ui-tool-based (generate_haiku vs pie-chart shape mismatch)
- declarative-gen-ui::runtime-inject-tool (cross-cutting; PDX-70)
- headless-complete (5 regions; production demo simpler than canonical)
from __future__ import annotations turns all type annotations into
lazy string forward references. When autogen's ConversableAgent
registers @tool()-decorated functions, it calls Pydantic TypeAdapter
on parameter types. TypeAdapter cannot resolve
ForwardRef('ContextVariables') and raises PydanticUserError.
The fix removes the import from shared_state_read_write.py and
subagents.py. Neither file uses PEP 585/604 syntax that would
require it — they already use typing.List and typing.Literal.
Rename 8 probe driver/probe files to names that describe what they
actually test rather than using legacy naming:
- drivers/smoke.ts -> drivers/liveness.ts
- drivers/e2e-smoke.ts -> drivers/e2e-chat-tools.ts
- drivers/e2e-demos.ts -> drivers/e2e-readiness.ts
- probes/smoke.ts -> probes/liveness.ts
Updates all exports, imports, and comment references across
orchestrator, discovery, alerts, rule-loader, YAML configs, and
README. Kind strings, PB dimension keys, and log keys are
intentionally preserved.
The v2 createCopilotRuntimeHandler returns 404 for malformed POSTs to
the base path, while the v1 API returns 400. The smoke probe treats
404 as "route not wired" and marks agent:built-in-agent red. Wrap the
POST handler to convert 404→400 so the probe reads it as proof-of-life.
## Summary
- Adds `seedEntryLastRun` to the Scheduler interface for one-time boot
hydration of lastRun fields from PocketBase history
- Adds `hydrateProbeLastRuns` to the orchestrator, wired into boot()
before scheduler.start() -- queries the most recent completed run per
probe and seeds the scheduler state
- Race guard: seedEntryLastRun only writes if no real cron tick has
already completed (lastRunFinishedAt === null)
- Resilience: Promise.allSettled ensures one PB failure does not block
other probes; the function never throws
- NaN guard on Date.parse results prevents malformed PB dates from
crashing the /api/probes route
- Hydration warn log includes probeId so operators can identify which
probe PB fetch failed
## Why
After service restarts, the dashboard showed "never run" for all probes
until their first cron tick because scheduler EntrySlot fields are
in-memory only. This hydrates from PocketBase probe_runs history on boot
so probes immediately show their last known run state.
## Test plan
- 4 unit tests for seedEntryLastRun (populates fields, no-op unknown id,
null summary, race guard)
- 4 unit tests for hydrateProbeLastRuns (seeds completed runs, skips
non-probe entries, tolerates PB failures, skips incomplete runs)
- 2 tests for NaN guard and probeId in warn log
- 1 integration test verifying seeded lastRun surfaces through
GET /api/probes
- All 121 existing tests pass
## Summary
- Replace `[[...slug]]/route.ts` catch-all with flat `route.ts`
(matching every other integration)
- The CopilotKit runtime's internal Hono router handles sub-path
dispatch; the catch-all was unnecessary and caused the bare
`/api/copilotkit` POST to return 404
## Why
The smoke probe POSTs `{}` to `/api/copilotkit/` — the catch-all catches
it but passes an empty slug to the CopilotKit runtime, which returns
`{"error":"Not found"}` (404). This blocks `agent:built-in-agent` at red
and the depth ladder at D2. Flat route.ts is the proven pattern across
all 17 other integrations.
## Test plan
- [ ] CI green
- [ ] After deploy: `curl -X POST
https://showcase-built-in-agent-production.up.railway.app/api/copilotkit`
returns non-404
- [ ] Probe tick shows `agent:built-in-agent` green
🤖 Generated with [Claude Code](https://claude.com/claude-code)
## Summary
- Delete `test_smoke-starter-deployed.yml` workflow (runs every 6h,
would flood Slack with 17 red alerts once starter Railway services are
torn down)
- Remove `starter:` blocks from all 17 integration manifest.yaml files
(stale `demo_url` pointing to `showcase-starter-*` Railway services)
- Clean stale starter references from CI workflow comments
- Remove `"starter"` from dashboard's `manifestation` type union and
dead starter-handling code in cell-matrix
- Fix useLiveStatus test to match INITIAL_CAP=2000 (pre-existing from
#4362)
## Why
PR #4351 merged packages/starters into a unified integrations/
directory, eliminating starters as separate deployable units. The 17
`showcase-starter-*` Railway services are being deprovisioned. These
references must be cleaned up BEFORE teardown to prevent false alerts
and stale data propagation.
## Test plan
- [ ] Dashboard tests pass (15/15 useLiveStatus, depth-utils,
cell-matrix)
- [ ] No `showcase-starter-` URLs remain in generated data files
- [ ] No `starter:` blocks remain in manifest.yaml files
- [ ] CI green
The [[...slug]] catch-all route handles sub-paths but the CopilotKit
runtime returns 404 for an empty slug (bare /api/copilotkit POST).
Every other integration uses a flat route.ts — the runtime's internal
Hono router handles sub-path dispatch. Move the handler to route.ts
and delete the catch-all so the bare path returns non-404.
## Summary
- Add `/api/copilotkit/route.ts` re-exporting from the `[[...slug]]`
catch-all so the bare path returns non-404
- Add `/api/smoke/route.ts` matching the standard contract all other
integrations follow
## Why
The smoke probe POSTs to `/api/copilotkit` (bare path) and interprets
404 as "route not wired", marking `agent:built-in-agent` red. This
blocks the depth ladder at D2, so all dashboard cells show D0 despite
e2e probes passing 35/35.
## Test plan
- [ ] CI green (build proves the routes compile)
- [ ] After deploy, verify `curl -X POST
https://showcase-built-in-agent-production.up.railway.app/api/copilotkit`
returns non-404
- [ ] Verify `curl
https://showcase-built-in-agent-production.up.railway.app/api/smoke`
returns 200
- [ ] Next probe tick shows `agent:built-in-agent` green, depth ladder
unblocked
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Malformed PocketBase date strings would produce NaN timestamps that
crash GET /api/probes via RangeError in toISOString(). Add
Number.isFinite guard. Also include probeId in Promise.allSettled
rejection log so operators can identify which probe's PB fetch failed.
The catch-all [[...slug]] route doesn't handle the bare /api/copilotkit
path, returning 404. The smoke probe interprets 404 as "route not wired"
and marks agent:built-in-agent red, blocking the depth ladder at D2.
## Summary
Promotes Built-in Agent to the default integration so fresh visitors
land on working code instead of a forced framework picker. Bundles the
chrome cleanup that falls out of the soft-default — sidebar rename,
redundant nav affordances removed, legacy URL scheme retired.
`unselected/` editorial cleanup is split out as a follow-up PR
([PDX-49](https://linear.app/copilotkit/issue/PDX-49)) since it's 47
file operations + 2 editorial merge calls and benefits from independent
review.
## What changes
### Built-in Agent as the soft-default
`FrameworkProvider` gains `effectiveFramework`, which falls through URL
→ `storedFramework` → `DEFAULT_FRAMEWORK ("built-in-agent")`. Snippet
renderers, sidebar links, and "Continue with X" affordances read this;
the original `framework` field stays URL-strict for the few call sites
that genuinely need to know "is the URL scoped?"
Behavioural impact:
- Fresh visitor on `/` sees "Continue with Built-in Agent" + the docs
landing's pointer cards (no forced picker)
- Fresh visitor on `/threads`, `/frontend-tools`, etc. → `RouterPivot`
redirects to `/built-in-agent/<feature>` on mount
- Returning visitor with a stored framework still gets their pick
honoured; the soft-default only kicks in when both URL and stored are
null
- Sidebar quickstart entry no longer needs `hideWhenUnscoped` —
`effectiveFramework` is always set
### Sidebar chrome cleanup
- **Built-in Agent → "CopilotKit"** in the sidebar selector. The framing
in the sidebar is "you're reading CopilotKit's docs," not "you've picked
the BIA backend." Other surfaces (DocsLandingNext, IntegrationGrid, page
bodies) keep the registry name where the framing is about choosing a
backend.
- **CopilotKit pinned to the top** of the dropdown, outside the
"Popular" category bucket. It's the default; reads more naturally as the
always-there starting point than as one of several Popular options.
- **Built-in Agent dropped from the "Switch backend" picker** on `/`.
Showing "switch to BIA" inside a "Switch backend" affordance is a no-op
tile when BIA is already the soft-default.
- **"← All docs" link removed** from the framework-scoped sidebar (3
call sites). Vestige of the pre-IA-restructure world where `/` was a
distinct picker view; with `/` and `/<framework>` rendering the same
docs-landing shell now, the link just changed the URL with no visible
effect.
- **Framework-name link removed** from the sidebar (4 call sites). The
selector pill above already names the active framework; the breadcrumb
at the top of the body covers "go to root"; the CopilotKit logo in the
top header is the canonical "go home." Drops `sidebarTitle` / `backLink`
props from `DocsPageView`.
- **"Reset to default (Built-in Agent)" dropdown row removed.** With
CopilotKit pinned at the top of the dropdown, picking it does the same
thing end-to-end (`effectiveFramework` becomes BIA either way).
### Legacy `/integrations/<framework>/<slug>` URLs retired
`UnscopedDocsPage`'s `integrationMatch` branch is gone. Any
`/integrations/...` URL now 404s. The `integrations/<framework>/`
content tree on disk stays — it's still loaded by the framework router's
per-framework override fallback (e.g. `/built-in-agent/quickstart`
serves `integrations/built-in-agent/quickstart.mdx`). Only the URL
scheme is retired.
`search-modal.tsx` integration and demo result links now point at the
shell host's integrations explorer (`${SHELL_HOST}/integrations/...`)
instead of the now-404 shell-docs paths.
### `RouterPivot` simplified
With `effectiveFramework` always resolving, the no-framework branch in
`RouterPivot` is unreachable. Stripped to a pure redirect component;
legacy picker grid (~140 lines) deleted. `FrameworkGuardedContent` now
always returns null (the body is hidden during the brief redirect tick).
`UnscopedDocsPage` drops the props that fed RouterPivot's old picker
(`frameworksWithCell`, `previewUrl`, `featureName`,
`featureDescription`).
## Test plan
- [ ] `/` (no localStorage) renders "Continue with Built-in Agent" + the
picker grid below; sidebar selector reads "CopilotKit"
- [ ] `/<framework>` (e.g. `/langgraph-python`) renders "Continue with
LangGraph (Python)"; sidebar selector reads "LangGraph (Python)"
- [ ] `/threads` redirects to `/built-in-agent/threads`;
`/frontend-tools` → `/built-in-agent/frontend-tools`
- [ ] Sidebar dropdown: CopilotKit pinned at top above the Popular
category header; checkmark on the active framework; no "Reset to
default" row
- [ ] No "← All docs" or framework-name header anywhere in the sidebar
- [ ] After picking LangGraph from the dropdown → "Continue with
LangGraph (Python)" everywhere; closing tab and reopening `/` keeps
LangGraph picked
- [ ] Picking CopilotKit from the dropdown returns to BIA
- [ ] `/integrations/built-in-agent/quickstart` returns 404 (legacy URL
retired)
- [ ] `/built-in-agent/quickstart` renders the BIA quickstart MDX
(canonical short form unchanged)
- [ ] Cmd-K → search "LangGraph" → integration result links to
`${SHELL_HOST}/integrations/langgraph-python`
- [ ] No regressions on existing framework-scoped feature pages
(`/<framework>/<feature>`)
## Closes
- PDX-46 — BIA-as-default UX decision (soft-default chosen and shipped)
## Follow-ups (not in this PR)
- PDX-49 — `unselected/` editorial cleanup. 47 file operations: 17
deletes redirecting to root, 8 deletes redirecting to
`/built-in-agent/*`, 7 promotions over root stubs, 13 promotions for
unique content (interrupt-based + 12 tutorials), 1 delete
(agent-app-context). Plus content-merge calls for
`troubleshooting/{common-issues,error-debugging}.mdx`. Verified diff
audit produced; will ship as a follow-up branch.
- New ticket TBD — merge `/learn/*` content into the Concepts subgroup.
The upstream learn pages are largely duplicative with the new Concepts
primer pages; consolidation pass needed.
- BIA showcase package + `deployed: true` flip. PR #4321 (Alem) is the
showcase package; once it lands, flipping `deployed: true` is a one-line
registry change.
The ADK source pin moved 1.55.2 → 1.56.4, so the corresponding
[FAIL] line in showcase validate-pins now reads "Dojo=1.56.4".
Same FAIL count (129), different hash. Updates the baseline so
CI accepts the new (still-failing-but-known) state.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Jordan Ritter