## What
Two unrelated cleanups:
### 1. Move internal-only skills out of the public repo
Three staff-only skills lived under `.claude/skills/` and
`.agents/skills/`, so `npx skills add CopilotKit/CopilotKit` swept them
into end-user installs. This PR deletes them here; they now live in the
internal-skills plugin (**CopilotKit/internal-skills#108**):
- `copilotkit-demo-parity`
- `git-hooks`
- `showcase-demo-debugging`
### 2. Recommend a cleaner skills install command
The **Build with agents** guide now recommends:
```bash
npx skills add CopilotKit/CopilotKit/skills -y
```
- `/skills` subpath installs only the published skills under `skills/`
(the repo root also picks up internal skills).
- `-y` skips the interactive prompts.
A Callout documents the interactive variant and `-g` for a global
install.
On consecutive interrupts, pressing Enter for the second turn (turn-2) while
the resumed run from turn-1 was still in flight routed the keystroke to the
STOP action, aborting the in-flight resume instead of sending the new message.
The fix gates the Enter handler on `canSend` so a pending/running state no
longer maps Enter to STOP, and `onSubmitInput` now awaits the in-flight run's
completion before dispatching the queued message — the message is sent after
the current run finishes rather than aborting it.
Also hardens the queuing and attachment tests to cover the consecutive-
interrupt path and the send-after-run-completes behavior.
Same dead-v1-labels bug as the batch-1 starters: labels.title/initial are
ignored by the v2 CopilotSidebar, so the header rendered the default
'CopilotKit Chat' and the starter smoke's text=Popup Assistant wait timed
out (crewai-crews @interaction). Map to the v2 keys (modalHeaderTitle /
welcomeMessageText) in the two v2-migrated starters that were missed in the
earlier pass.
Verified with the exact CI compose for crewai-crews: 4 passed, exit 0.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
These three starters were migrated to the v2 API surface (23af69041c, already
on main) but never got the matching @copilotkit version bump or provider
config, so their starter smoke is red ON MAIN today (main's latest run is red
for 9 starters) — not a regression from this PR. Healing them here to green
the required check:
- bump @copilotkit/react-core + runtime to 1.59.1 (the v2 pages don't work
against the 1.55.2 pair — same failure mastra had pre-bump; runs 404/hang)
- add useSingleEndpoint={false} to the CopilotKit provider, matching every
batch-1 example: without it the v2 client's endpoint-detection probe GETs
the bare /api/copilotkit, which 404s on the multi-route endpoint and trips
the smoke's zero-console-errors assertion
Verified with the exact CI command (docker compose -f docker-compose.test.yml
up --exit-code-from tests) for llamaindex: 4 passed, exit 0.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
the per-service promote loop ran under `set -euo pipefail`, so the first failing
service aborted the whole `all` fleet promote; extracted to promote-fleet.sh
which attempts every service, accumulates succeeded/failed sets, exits non-zero
only after attempting all, and exports succeeded_csv. verify-prod now runs
`if: !cancelled()` and scopes --services to the succeeded set; the staging
precondition is advisory (promote runs even when it reports red — bin/railway
enforces staging-green per-service); notify success keys on PROMOTE && PROD.
Adds a shell-script-tests CI job (bats + shellcheck) and input-validation
hardening (fail-loud on empty/all-empty CSV, RAILWAY_BIN check, whitespace trim).
`from __future__ import annotations` turned the set_steps tool's
`context_variables: ContextVariables` param into an unresolved ForwardRef at
AG2 tool-schema-generation time, raising PydanticUserError on import and failing
the showcase-ag2 staging healthcheck since 2026-05-31. Removing it matches the
working sibling agents. Adds a regression test that statically asserts the
future-import stays absent (version-independent) plus a live import check.
Addresses the blocking review on #5151:
1. Starter smoke 'Popup Assistant' timeouts (adk, agno, mastra,
ms-agent-framework-python/dotnet): the pages passed the dead v1 label keys
(labels.title / labels.initial), which v2 CopilotSidebar ignores — the
header rendered the default 'CopilotKit Chat' so the smoke's
text=Popup Assistant wait timed out. Map to the v2 CopilotChatLabels keys:
title -> modalHeaderTitle, initial -> welcomeMessageText. Verified live:
SSR now renders 'Popup Assistant'.
2. llamaindex TypeError (reading 'proverbs'): the page still used the v1
useAgent API ({ state, setState } = useAgent({ name, initialState })) —
v2 returns { agent }, so state was undefined at render. Migrate to the v2
pattern (agent.state with a guarded default + agent.setState + one-time
seed effect), and fix its dead v1 label keys too. Verified: next build
prerenders all pages cleanly.
3. parity-check drift: ran _parity/sync.ts --all — syncs example-layout
(mobile-header fix), layout.tsx, docker-route-override.ts to the
north-star, and bumps @copilotkit/* to 1.59.1 in langgraph-fastapi and
strands-python. parity verify: 0 errors across all instances.
(next-env.d.ts is gitignored repo-wide; verify warns-and-skips it in a
clean checkout, so it is intentionally not committed.)
4. Trailing-whitespace diff-check failure (showcase google-adk agent): already
resolved by the merge of main (the file matches main; diff --check clean).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Resolves 5 conflicts from main's e793257650 (v2 frontend tool parameters
array -> Zod) overlapping the threads-wired examples:
- adk/mastra/ms-agent-framework-{dotnet,python} page.tsx: keep the branch
versions — they already use Zod parameters and add the threads drawer
wiring + the reviewed v2 restructure on top of what main converted.
- adk/package.json: union — keep the branch's threads-drawer deps +
@copilotkit 1.59.1 bump, and take main's zod dependency (which our adk
page imports but the branch never declared — main's line fixes that gap).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Previously only the top-level /build-with-agents and built-in-agent pages
rendered the Skills section (via <BuildWithAgents />). Every framework
integration page used the MCP-only <CodingAgents /> snippet (or, for
langgraph, <MCPSetup /> directly), so Skills — the recommended path — was
hidden there.
Point the shared coding-agents.mdx snippet at <BuildWithAgents /> so all
pages that reference CodingAgents now render Skills + MCP, and switch the
langgraph page from <MCPSetup /> to <BuildWithAgents />. The snippet inliner
recurses with cycle protection, so no duplication is needed.
## Summary
Two body links on the **Self-Hosting Intelligence** page
(`/<framework>/premium/self-hosting`, rendered from the shared snippet
`docs/snippets/shared/premium/self-hosting.mdx`) were broken in
production:
- **"How the Intelligence Platform Works"** (Prerequisites + Next steps)
linked `/learn/intelligence-platform`. The `NavigationLink` rewriter
(`docs/components/react/subdocs-menu.tsx`) makes absolute links
section-relative, so under each framework it became
`/<framework>/learn/intelligence-platform` → **404**. The page is served
at `/premium/intelligence-platform` in every section (verified live
across built-in-agent, langgraph, mastra, crewai, agno, and root).
Changed both occurrences to `/premium/intelligence-platform`, matching
the sibling premium links (`/premium/overview`).
- **"chart releases" (GHCR)** used the repo-scoped package URL for the
private `CopilotKit/Intelligence` repo → **404** for public readers.
Switched to the public org-scoped package URL
`github.com/orgs/CopilotKit/packages/container/package/charts%2Fintelligence`
(200). The `oci://ghcr.io/...` pull itself was already fine — only the
web link was broken.
The other two body links (`/premium/overview`, `/threads`) and all
in-page anchors were already valid.
## Why this shipped broken
`scripts/check-broken-links.js` only scans `content/docs` and
`components` — it never looks at `snippets/`, so links in shared
snippets are completely unvalidated. Extending the checker to cover
`snippets/` (and to model the section-relative rewriting) would catch
this class of bug. Not included here to keep this PR focused — happy to
follow up.
## Test plan
- [x] `/built-in-agent/premium/intelligence-platform` returns 200
(verified across built-in-agent, langgraph, mastra, crewai, agno, and
root prefixes)
- [x] Org-scoped GHCR package URL returns 200
- [x] Pre-commit hooks pass (`test-and-check-packages`, `commitlint`)
- [ ] Confirm on docs preview deploy that both links resolve from the
rendered page
The shared self-hosting snippet renders under every framework section
(built-in-agent, langgraph, ...), and the NavigationLink rewriter makes
absolute links section-relative.
- "Intelligence Platform Works" linked /learn/intelligence-platform,
which became /<framework>/learn/intelligence-platform (404). The page
is served at /premium/intelligence-platform in every section.
- The GHCR chart-releases link used the repo-scoped URL for the private
Intelligence repo (404 for public readers); switched to the public
org-scoped package URL.
Addresses review feedback on the Build with agents page:
- Add a top-three skills table (copilotkit-setup / -develop / -integrations)
and call out that copilotkit-contribute is for working on CopilotKit
itself, not building with it, so the skills directory's build-vs-contribute
split is clear from the docs page.
- Clarify where to run `npx skills add`: from the project root, where any
coding agent (Claude Code, Codex, Cursor, Gemini CLI) discovers the skills
automatically — answering 'in your agent environment'.
- Demote the MCP per-tool section headers (Cursor, Claude Web, Claude Code,
...) from H2 to H3 so they nest under 'MCP Docs Server' in the on-this-page
TOC instead of sitting as flat siblings; demote the 'Other' subsections to
H4 accordingly.
The static/quality format job runs in check mode on push and was failing
on main: `ruff format --check .` flagged 5 unformatted Python files under
examples/showcases/a2ui-pdf-analyst/agent (main.py, src/dynamic_agent.py,
src/fixed_agent.py, src/multimodal_middleware.py, src/pdf_tools.py). The
oxfmt JS/TS check already passes, so this is ruff-only drift. Applied
`ruff format` (pinned 0.15.13, matching CI); diff is formatting-only.
The langgraph-js agent `dev` script ran `npx @langchain/langgraph-cli@1.2.1`,
which resolves its own isolated dependency tree. That tree pulled a 1.2.x
`@langchain/langgraph` to satisfy the `@langchain/langgraph-api` peer
dependency, but the API hard-imports `STREAM_EVENTS_V3_MODES` from
`@langchain/langgraph/web` — a symbol only present in langgraph 1.3.0+ —
crashing the agent at startup with a SyntaxError.
Install `@langchain/langgraph-cli@1.2.4` as a devDependency and invoke the
local `langgraphjs` binary so the `@langchain/langgraph` peer resolves from
the agent's own pinned 1.3.0, which exports the symbol. Verified the agent
boots cleanly (graph registered, API on :8123, no SyntaxError).
The v1→v2 migration left tool `parameters` in the old v1 array shape
(`[{ name, type, description, required }]`), which does not satisfy the
v2 `FrontendTool.parameters?: StandardSchemaV1` contract. This produced a
`Property '"~standard"' is missing` TypeScript error, failing the
Next.js build for starters whose Docker smoke build typechecks (mastra,
ms-agent-framework-python, adk).
Convert each tool's parameters to a `z.object({...})` schema so typed
`args`/handler arguments resolve correctly. Add `zod` as a dependency to
the two starters (adk, a2a-middleware) that lacked it.
Affected starters: adk, agno, llamaindex, mastra, pydantic-ai,
ms-agent-framework-dotnet, ms-agent-framework-python, a2a-middleware.
The starter smoke-test Slack alert had no indication of where it came
from, which is ambiguous when the same workflow runs across multiple
repos (e.g. the public CopilotKit/CopilotKit repo vs the internal
testybara fork). Prepend a `[ci:<owner/repo>]` tag derived from
github.repository so triage is unambiguous about the source. These CI
alerts test example source and carry no staging/production dimension,
so [ci] is the meaningful source axis. Existing message format is
otherwise preserved.
Prefix every harness-dispatched alert with a `[staging]`/`[production]`/
`[unknown]` source-env tag so operators triaging a red probe know which
deploy environment is affected. The label is derived in the orchestrator
from SHOWCASE_ENV ?? RAILWAY_ENVIRONMENT_NAME ?? "unknown" and applied at
the single renderer chokepoint (covering per-key, cron, and on-error
dispatch) plus the aggregation flush path that bypasses the renderer, via
a shared sourceEnvPrefix helper so the two paths never drift. A missing
env var surfaces as a visible [unknown] rather than a silent un-prefixed
alert.
- STAGING-OUTAGE regressions: degraded alarm fires (not silent) when the
set empties from a relaunch storm; self-heal re-inits a fresh set once the
kernel relaxes; a waiter queued during the dead window is served by
self-heal; a transient relaunch EAGAIN is retried and the entry survives
(no eviction, no alarm).
- Bounded serveNextWaiter transient re-drive + FIX#7 dead-vs-alive gate
propagation to the serve path.
- orchestrator: degraded/recovered signal wiring covered.
- BUG3 (orphan-by-recycle waiter drain) adapted to the crash-recovery
acquire path: an acquire whose in-flight open is orphaned re-enqueues as a
waiter; with cap=1 the freed slot goes to the other waiter, so the orphaned
acquire settles via its own (now bounded) timeout. The invariant it
verifies (freed capacity immediately serves the queued waiter) is unchanged.
Lift the soft nproc limit to the hard ceiling (`ulimit -u $(ulimit -Hu)`)
before exec'ing the orchestrator so the legitimate 40-context chromium
workload (several hundred OS threads at steady state) has ample thread
headroom instead of running near the default ~1024 soft ceiling, where
`chromium.launch()` tripped `pthread_create: Resource temporarily
unavailable`. `exec` keeps node as PID 1 for correct signal handling; the
`|| true` fallback keeps boot resilient when the runtime forbids raising
the soft limit (the cgroup pids limit then remains the dominant control).
Make the long-lived chromium pool survive a pthread/PID-ceiling
(`pthread_create: Resource temporarily unavailable`, errno 11) thread-
exhaustion storm instead of draining to an empty, permanently-wedged set.
- Crash-recovery relaunch backpressure: a transient EAGAIN on relaunch is
retried with bounded linear backoff before the entry is evicted, so a
thread-exhaustion window that relaxes within seconds recovers in place
rather than splicing the entry out of the set.
- Self-heal + degraded/recovered alarm: when the set empties mid-life the
pool fires an `onDegraded` red alarm (previously only emitted on init()
failure — mid-life death was silent) and kicks a background self-heal
loop that relaunches a fresh set the moment a launch succeeds, firing
`onRecovered`. No manual redeploy required.
- Bounded serveNextWaiter transient re-drive: a persistently-transient
newContext() on a still-connected browser no longer hot-loops the event
loop; it self-reschedules up to a ceiling then leaves the waiter queued
for a later release/recovery handoff (mirrors acquire()'s retry-once
semantics).
- Accounting hardening: generation-token guard on in-flight opens across a
recycle, clamped servedContexts rollback on orphan-close, deferred-recycle
re-check on non-release teardown paths, and waiter-drain on orphan-by-
recycle rollback so freed capacity is served immediately.
- orchestrator wires the pool's onDegraded/onRecovered hooks to the shared
`system:browser-pool-degraded` red/green capacity-loss signal.
Fixes the 2026-06-03 staging incident: the browser pool died from thread
exhaustion, the relaunch storm emptied the set, and the harness wedged with
no alarm -> 626 D0-red cells until a manual redeploy.
Removes the three internal-only skills (copilotkit-demo-parity, git-hooks,
showcase-demo-debugging) from .claude/skills/ and .agents/skills/. These are
staff-only and now live in the internal-skills plugin. Removing them at the
source means root skill discovery no longer sweeps internal skills into a
user's install.
## Problem
The top-level `docs/` app is retired, but nothing in the repo said so,
and contributors (and agents) kept editing it. Two parallel docs trees
plus a one-directional legacy sync script made it ambiguous where
documentation should be authored:
- `docs/content/docs/` — the old Fumadocs app, no longer publishing
- `showcase/shell-docs/src/content/docs/` — the live source for
docs.copilotkit.ai
Two instruction surfaces actively pointed the wrong way: `CLAUDE.md`
said nothing about docs at all, and `.claude/docs/hooks.md` told
contributors to "add a docs page under `/docs`" (the retired location).
## Change
Establish one canonical rule and reduce the other surfaces to pointers:
- **`.claude/docs/documentation.md`** (new) — source of truth.
CopilotKit docs are authored in `showcase/shell-docs/src/content/`
(`docs/`, `reference/`, `snippets/`, `framework-overviews/`); the
top-level `docs/` folder is retired; AG-UI protocol docs are authored
upstream in `ag-ui-protocol/ag-ui` (publishing to docs.ag-ui.com) and
mirrored into `content/ag-ui/`.
- **`CLAUDE.md`** — adds an Essentials hard-rule and a Reference link.
- **`docs/README.md`** — replaces boilerplate with a retired/STOP
banner; legacy README retained under a `<details>`.
- **`.claude/docs/hooks.md`** — fixes the stale `/docs` pointer and
clarifies that a hook's API reference page lives in
`reference/hooks/<hookName>.mdx`, where v2 reference navigation is
generated automatically from frontmatter (no `meta.json`); conceptual
guide pages under `docs/` still use `meta.json`.
- **`CONTRIBUTING.md`** — adds a two-domain documentation section for
human contributors.
## Notes
- Two docs domains: **CopilotKit docs** → shell-docs; **AG-UI protocol
docs** → upstream `ag-ui-protocol/ag-ui`, then synced into the in-repo
mirror.
- Instructions-only change; no enforcement hook or sync-process change.
- Markdown only; no package code touched.
Use `CopilotKit/CopilotKit/skills -y` instead of the repo root: root
discovery sweeps in the internal `showcase-demo-debugging` skill
(metadata.internal, lives in .claude/.agents, not skills/), so users got
12 skills incl. one internal. The /skills subpath yields exactly the 11
published skills. Drop -g so install defaults to project scope, letting each
project pin the skills version matching its CopilotKit dependencies.
The build-with-agents guide recommended a bare `npx skills add` that drops
human users into a multi-step interactive flow (skill multiselect, agent
selection, scope, install method, confirm). Recommend `-g -y` so all skills
install globally in one shot, with a Callout pointing to the flag-less command
for users who want to choose interactively.
The top-level docs/ app is retired but nothing said so, and two
instruction surfaces still pointed contributors there. Establish a
single canonical rule and reduce the other surfaces to pointers.
- Add .claude/docs/documentation.md as the source of truth: CopilotKit
docs are authored in showcase/shell-docs/src/content/; the top-level
docs/ folder is retired; AG-UI protocol docs are authored upstream in
ag-ui-protocol/ag-ui and mirrored here.
- CLAUDE.md: add an Essentials rule and a Reference link.
- docs/README.md: replace boilerplate with a retired/STOP banner.
- .claude/docs/hooks.md: fix the stale /docs pointer; document that a
hook's API reference page lives in reference/hooks/ and that v2
reference nav is generated from frontmatter (no meta.json).
- CONTRIBUTING.md: add a two-domain documentation section.
The .NET example's page.tsx pointed its Shared State and Generative UI doc
links at /pydantic-ai/ (copy-paste leftovers) instead of
/microsoft-agent-framework/. Also fix the threads-drawer CSS header comment
that still referenced 'mastra's CopilotSidebar'.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The no-license locked panel is a fixed-width (w-80 / 18-20rem) block. In the
single-column mobile grid it left a dead background strip beside it and pushed
the app content down. Hide it below 1024px (max-lg:hidden / .lockedPanel
display:none) — consistent with the real drawer + first-paint placeholder,
which also reserve no column on mobile. Content now gets the full width.
Applied across all 7 migrated examples.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
On the no-license locked threads panel:
- widen the panel slightly (w-72 -> w-80 / lockedPanel 18rem -> 20rem) and
add white-space: nowrap so `copilotkit add-intelligence` stays on one line
instead of wrapping mid-command
- add a 'with:' lead-in above the command box so it reads as a runnable command
rather than loose text
Applied across all 7 migrated examples (Card-based locked state in adk/agno/
langgraph-js/langgraph-python; themed .lockedPanel in mastra/ms-agent-*).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The disabled-state ThreadsPanelGate (shown when no Intelligence license is
present) rendered its locked card in a bare `w-72` container with no
background, so the threads column showed the page background (a black column in
dark-themed examples, white in light) instead of the drawer surface.
Give that container the drawer surface (bg + hairline right border) so the
locked card sits in a panel that matches the drawer, consistent with the
already-surfaced .lockedPanel examples (mastra, ms-agent-framework-*).
Affects adk, agno, langgraph-js, langgraph-python (the Card-based locked state).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The ThreadsPanelGate renders a first-paint placeholder while the client-only
drawer mounts. It was either a bare `w-72` div (no surface → a black/white
column flash in the page bg) or a fixed 18rem inline-styled div (correct color
but, on mobile where the mounted drawer floats, the reserved 18rem collapsed on
mount → content shifted left).
Replace both with a shared `.drawerPlaceholder` class that matches the open
drawer's footprint + surface (18rem, drawer bg, hairline border) on desktop and
`display: none` below 1024px (the mobile drawer floats, so reserve no column).
Result: no color flash and no content shift on load. Applied across all 7
migrated examples (themed vs raw surface tokens per example).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Port the langgraph-python mobile-header fix to langgraph-js (same shared
canvas/header demo). Below 1024px the threads drawer's floating launcher is
fixed top-left and collided with the top-left CopilotKit header:
- max-lg:pl-24 on the header so the logo clears the launcher pill
- max-lg:pt-2.5 + pb-0 (and drop the logo span's pb-1.5 on mobile) so the
logo is vertically centered with the launcher + the Chat/App toggle
- trim the collapsed launcher's icon buttons (2rem -> 1.75rem) + tighter
padding so the pill height lines up with the toggle
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
On phones/tablets (≤1024px) the threads drawer's floating launcher is fixed
at the top-left corner, and it collided with this example's top-left
CopilotKit header. Three small fixes so the header reads as one tidy row:
- max-lg:pl-24 on the header so the logo clears the launcher pill
- max-lg:pt-2.5 + pb-0 (and drop the logo span's pb-1.5 on mobile) so the
logo is vertically centered with the launcher + the Chat/App toggle
(was sitting ~7px low)
- trim the collapsed launcher's icon buttons (2rem -> 1.75rem) + tighter
padding so the pill height (~36px) lines up with the toggle instead of
towering over it
Local to langgraph-python (the only rollout example with a top-left header).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Below 1024px the in-flow threads column squeezed the demo content and the
(full-screen) CopilotSidebar chat into slivers. Raise the responsive
breakpoint from 900→1024 and make the panel a true off-canvas overlay:
- collapsed → a small floating launcher pill pinned top-left (z-1300),
above the full-screen mobile chat, so threads stay reachable
- open → a fixed full-height panel sliding in from the left (z-1300),
content + chat use the full width behind it
- default the drawer to collapsed when innerWidth ≤ 1024 on mount
Applied across all 7 integration examples' shared threads-drawer, each
adapted to its own theme tokens (themed examples use --threads-drawer-*,
raw examples use --card/--border for the launcher surface).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Austin Merrick