## Problem
The discontinued AG-UI protocol mirror remained published on
docs.copilotkit.ai. Its sitemap advertised pages owned by the separate
AG-UI repository, including eight routes that returned 500.
## Why
The protocol documentation is maintained at docs.ag-ui.com. Keeping an
unsynchronized duplicate on the CopilotKit host created broken
user-facing URLs and misleading search results.
## Fix
Remove the vendored `/ag-ui/*` content, renderer, sitemap/search/LLM
enumeration, and mirror-specific tests. Retain CopilotKit's own AG-UI
integration documentation under `/backend/ag-ui` and
`/agentic-protocols/ag-ui`.
Validation: `npm run typecheck`; focused Vitest suite (39 tests).
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* AG-UI protocol documentation has been removed from the documentation
site.
* AG-UI documentation updates are now directed to the upstream protocol
project.
* Related guides, SDK references, drafts, roadmap, integrations, and
contribution pages are no longer available here.
* **Search & Navigation**
* AG-UI pages no longer appear in search indexes, sitemap listings, or
LLM-generated documentation content.
* Documentation routing now resolves supported content areas without the
former AG-UI route.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
The prompt a developer copies from the Inspector, the docs hero and the feature
cards opened with two sentences of instruction to the coding agent: identify
yourself with a slug, and pass it as a flag. It is the one piece of text a human
reads, decides on and pastes, and most of it was addressed to something else.
Help me get started with CopilotKit. Run this command and follow the
instructions:
npx --yes copilotkit@latest onboard start --run <run-id>
Identification moves into the prompt graph, which is the surface that talks to
the agent for the rest of the run: `onboard identify --coding-agent <slug>` is
run by `authenticate/start` (Intelligence OSS-1157). The CLI still accepts
`--coding-agent` on `start`, so this wording and the old wording both work and
neither repository has to land first.
The feature prompts keep their standing permission for the CLI session check.
That sentence is the developer granting something by copying the text, and the
graph cannot grant it to itself, so only the identification half is cut.
Kept byte-identical across the Inspector template, the docs constant, and
Intelligence's own `createCodingAgentOnboardingPrompt`.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
## Problem
The documentation does not clearly establish the Google ADK agent-side
path for `useAgentContext`. The hook reference points generically to
integration guides, while the existing ADK setup uses
`state["copilotkit"]["context"]`, which is not where the adapter stores
the AG-UI request context.
## Why
Reproduced using the actual adapter and ADK Runner with an instruction
provider and a deterministic local model. Given
`RunAgentInput.context=[{description: "Incident records", value:
"[{\"id\":\"INC-1041\"}]"}]` and empty request state:
```text
state["copilotkit"]["context"]: []
state[CONTEXT_STATE_KEY] (_ag_ui_context):
[{"description": "Incident records", "value": "[{\"id\":\"INC-1041\"}]"}]
```
## Fix
Document the public `CONTEXT_STATE_KEY` export in the hook reference and
link directly to the ADK context guide. Replace that guide's setup with
a standalone instruction-provider example using the correct state key.
Preserve the Gemini final-text termination safeguard with a fully
defined callback in the same example. Explain the string values, parsing
structured values, callback/tool access, and the distinction between
exposing frontend tools and including context in model instructions.
Validation: regenerated the setup-content bundle through Nx, extracted
and executed its Python example, and drove the documented instruction
provider through the real adapter/Runner. It delivered `INC-1041` into
the model request's system instruction and completed with text events
and `RUN_FINISHED`. This is a deterministic integration reproduction,
not a live Gemini/browser test. `git diff --check` passes.
Targeted shell-docs checks: **26 passed across 3 files**
(`setup-content`, `setup-concept`, and `frontend-tools-setup-coverage`),
run through Nx after generating the normal docs prerequisites.
The context example also passes nine copied-code callback checks
(registration, final text, partial/thinking output, tool calls, and
private-context compatibility). The bundled context-to-model execution
check and 26 targeted docs tests pass after this correction.
## Problem
A Next.js app in `web/` cannot read an Intelligence key stored in a
shared repository-root `.env` without explicit environment loading. The
runtime connection guide reads `process.env.CPK_INTELLIGENCE_API_KEY`
without explaining this layout.
## Why
Next.js loads app-local env files. A sibling agent's root env-file
configuration does not load that file for the Next.js process.
TypeScript's non-null assertion does not supply the key.
## Fix
Document an explicit `node --env-file=../.env` Next.js startup command,
the app-local alternative, and hosted server environment settings. One
docs file; no runtime path guessing or secret handling change.
Validation with a synthetic key and Next.js's actual `@next/env` loader:
loading the nested app directory leaves the root key undefined. Starting
the same check with `node --env-file=../.env` exposes the key to that
loader. MDX compilation and git whitespace checks pass. Full docs build
and hosted Intelligence connection were not run; no real credentials
were used.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Added guidance for configuring environment variables in Next.js
applications located in subdirectories.
* Documented how to explicitly load shared root `.env` files, including
a Node.js 20.6+ command example.
* Clarified app-local and hosted deployment environment configuration.
* Explained that the environment key must be loaded before initializing
the intelligence integration.
* Noted that TypeScript’s non-null assertion does not load or validate
environment variables.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Problem
A completed tool card can still show placeholder details when its
renderer reads output fields from the tool inputs.
## Why
`useRenderTool` keeps `parameters` (inputs) separate from `result` (the
completed output string). Completion does not replace inputs with
output, and declaring a field in the parameters schema does not populate
it from the result. The guide showed a working example but did not
explain this distinction.
## Fix
Add one explanation beside the existing per-tool example, including the
exact completed-placeholder symptom and how to read JSON output. No API
or runtime changes.
Reproduction against the real `useRenderTool` registration and
`useRenderToolCall` resolver (only surrounding context mocked), using
identical input and result messages:
```html
<article>
<p data-testid="before">complete: Placeholder detail</p>
<p data-testid="after">complete: Sunny, 22 C</p>
</article>
```
The first card reads an absent input field; the second parses `result`.
A temporary Nx reproduction target ran the existing resolver tests plus
this case: **9 tests passed**. The temporary harness is not shipped in
this docs-only PR. MDX parsing and `git diff --check` passed. Full docs
build not run.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **Documentation**
- Clarified how tool inputs and completed outputs are represented when
using tool rendering.
- Added guidance for parsing JSON results and distinguishing input
parameters from output data.
- Documented how to diagnose placeholder data that appears after tool
execution completes.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Problem
The LangGraph TypeScript app-context example reads
`state.copilotKit.context`, but the SDK schema and CopilotKit runtime
adapter supply lowercase `copilotkit`.
## Why
The TypeScript spelling differs from the actual state field. Following
the example throws before it can consume frontend context.
## Fix
Correct the expression and explain the lowercase state key. One docs
file; no runtime behavior change.
Validation: sent a synthetic colleague through the real CopilotKit
LangGraph adapter's state merge and a compiled LangGraph node using the
expression extracted from this page. Before: `TypeError: Cannot read
properties of undefined (reading 'context')`. After: the node reads
colleague `Ada`. MDX syntax compilation passes after stripping snippet
imports, as the docs loader does. Git whitespace and commit hooks pass.
No hosted browser/model call was needed for this deterministic
reproduction; full docs build was not run.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **Documentation**
- Clarified that the CopilotKit state key is lowercase `copilotkit` in
Python and TypeScript integrations.
- Updated the TypeScript example to access context using the correct
lowercase state key.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Problem
An onboarding run using CLI 4.9.1 installed unversioned Zod alongside
`@copilotkit/sdk-js` 1.71.0 and hit npm `ERESOLVE`.
## Why
The SDK's declared Zod peer range accepts only v3. Unversioned installs
select v4. The LangGraph quickstart, also served at
`/langgraph-typescript/quickstart.md`, does not explain this constraint.
## Fix
Add a version-scoped installation note with `npm install
@copilotkit/sdk-js@1.71.0 zod@3`, equivalent package-manager guidance,
and a note for existing Zod 4 applications. This avoids expanding SDK
compatibility in a documentation fix.
Reproduction in a clean temporary directory using published packages:
```text
npm install --package-lock-only --ignore-scripts --no-audit --no-fund @copilotkit/sdk-js@1.71.0 zod@4
ERESOLVE: Found zod@4.6.1; SDK requires ^3.23.3 || ^3.24.0 || ^3.25.0
npm install --package-lock-only --ignore-scripts --no-audit --no-fund @copilotkit/sdk-js@1.71.0 zod@3
up to date in 2s (exit 0)
```
LangGraph quickstart MDX compilation and `git diff --check` pass. Full
docs build not run. No SDK runtime behavior changes or claims of Zod 4
support.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Added a prerequisite note for TypeScript users integrating LangGraph
agents.
* Clarified the required Zod version when installing the CopilotKit SDK.
* Added guidance to avoid bypassing dependency conflicts with
force-install options.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Problem
The app can show a runtime error when the browser loads before
`/api/copilotkit/info` is ready. Reloading after startup clears it.
## Why
A listening SPA server does not prove the separate runtime has
registered its routes and agents. The SPA guide told readers to start
both processes and open the browser without a readiness check.
## Fix
Check `/api/copilotkit/info` for a successful response containing the
configured agent before opening the SPA. Explain how this also applies
when a dev script launches both processes, and how to recover if the
browser was already opened.
This is a surgical startup-guide fix. It does not add or change core
reconnect behavior.
Reproduced against production `CopilotKitCore` with a real localhost
HTTP server. The endpoint starts with 404, then returns valid runtime
info:
```text
Failed to load runtime info (.../api/copilotkit/info): Runtime info request failed with status 404
BEFORE: /info is now HTTP 200, but the already-mounted client remains error.
AFTER: checking /info before mounting connects on the first load.
```
A temporary Nx test asserted the early client's error, successful HTTP
readiness, continued error during the observed 300 ms interval, and a
connected client when created after readiness: **1 test passed**. No
fetch mocks, credentials, or model calls; this verifies the core
connection sequence, not a full browser/Mastra onboarding run. The
temporary harness is not shipped in this docs-only PR.
Validation: localhost reproduction passed, edited MDX parsed, and `git
diff --check` passed. Full docs build not run.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **Documentation**
- Updated the React SPA quickstart with a runtime readiness check before
opening the app.
- Added guidance to wait for the runtime’s `default` agent to appear in
the response.
- Clarified that a running Vite server does not guarantee runtime
readiness.
- Added recovery guidance to reload the app if its initial runtime
connection fails.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Problem
An onboarding run reported a type error from passing `agent` to the v2
`CopilotKitProvider` when connecting a React SPA to LangGraph.
## Why
The integration quickstart shows the legacy `CopilotKit
agent="sample_agent"` API, while the SPA guide introduces
`CopilotKitProvider`. The SPA guide only demonstrates the default agent
and sends readers back to integration guides for external agents,
leaving this mapping unstated.
The report's precise claim that the SPA page itself passes `agent` could
not be reproduced: both its current source and live Markdown omit that
prop. The type error itself is reproducible against published 1.71.0
declarations.
## Fix
Add one named-agent example with `agentId="sample_agent"`, matching the
runtime registration, and explain when to omit it. No provider behavior
changes.
Validation using published `@copilotkit/react-core@1.71.0` declarations:
```text
const props: CopilotKitProviderProps = { children: null, runtimeUrl: 'http://localhost:8200/api/copilotkit', agent: 'sample_agent' };
TS2561: 'agent' does not exist in type 'CopilotKitProviderProps'. Did you mean 'agentId'?
```
Changing only `agent` to `agentId` passes `tsc --noEmit --skipLibCheck
--module esnext --moduleResolution bundler`. The React SPA MDX compiles
and `git diff --check` passes. Full docs build not run.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **Documentation**
- Added guidance for configuring `CopilotKitProvider` with a named
`agentId`.
- Included a `sample_agent` configuration example.
- Clarified that `agentId` is the supported provider property.
- Documented that the legacy `agent` property is invalid.
- Explained that `agentId` should be omitted when using the `default`
agent.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
`useAgent({ agentId, runtimeAgentId, threadId })` — a private proxied agent
pinned to one thread — shipped in v1.64.2 (27827adee2, type-enforced by
acdd9a9ef5) and has never been documented. `runtimeAgentId` appeared in no
docs page, and none of the 122 object-form `useAgent({...})` call sites in the
content tree passed a `threadId`.
The only writeup lived in the bundled react-core skill, which #7029 deleted.
That skill also had it wrong — it showed `useAgent({ agentId, threadId })`,
which is a compile error, and attributed per-thread isolation to `clone()`
rather than to `registerProxiedAgent`. deepshekhardas had corrected exactly
that in #6636, against the file #7029 removed; the prose here follows his
correction.
Adds to `reference/hooks/useAgent`:
- a "Two valid shapes" section, since the type admits nothing between binding
to a shared agent and binding a private one to a thread, and the reason
partial combinations are rejected (a runtime agent is a singleton, so a
per-hook threadId written onto it lets two hooks sharing an `agentId`
clobber each other's thread)
- `runtimeAgentId`, `threadId` and `throttleMs` property entries; all three
were absent, and the `agentId` entry now notes that in the thread-scoped
shape it is a *local* id that must not already be taken
Adds to the Headless Threads guide a "Driving one agent per thread" section,
because that is where someone building a multi-thread UI looks, and it was the
discovery path the reporter of #6125 was missing.
Refs #6125, #6636
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
## What
Replaces nine packaged knowledge skills with two entry points.
| | |
| --- | --- |
| `copilotkit` | The `copilotkit-docs` MCP server: four search tools and
two explore tools, which corpus answers which question, and the
instruction not to answer from memory. |
| `copilotkit-cli` | The CLI, led by `copilotkit verify --json`. |
**Deleted:** `copilotkit-setup`, `copilotkit-develop`,
`copilotkit-integrations`, `copilotkit-debug`, `copilotkit-upgrade`,
`copilotkit-agui`, `copilotkit-contribute`, `copilotkit-self-update`,
and the three package-generated skills (`react-core`, `runtime`,
`a2ui-renderer`).
Net: **-28,851 / +335 lines.**
**Kept, and out of scope here:** `setup-slack-channel`,
`channels-setup`, `copilotkit-channels`, `inspector-docs`,
`inspector-workbench`, `intelligence-docs`. The first three are
procedures rather than knowledge; the last three are internal
maintenance, not part of the public product. Their disposition is a
separate call.
## Why
The packaged skills had become a second copy of the documentation, and a
copy goes stale silently.
- `runtime` and `react-core` were roughly 60% transcribed API surface.
Of the remaining "Common Mistakes" prose, most already existed on a docs
page.
- Four claims in the deleted skills contradicted the source they cited.
One of them reached a shipped PR (#7005) before it was caught, and had
to be corrected in `14231a6169` — the skill asserted that server tools
cannot render UI because the browser never sees a tool-call start event,
which `packages/runtime/src/agent/index.ts:1519,1584` contradicts.
- `copilotkit-debug` was 1,289 lines of hand-written triage. Since
#1180, `copilotkit verify` covers version skew, CORS, and transcription
directly, which is most of what those lines described.
- Nothing in telemetry or in the issue tracker suggests the
per-lifecycle split was load-bearing for anyone.
The gotchas worth keeping were moved onto docs pages first, in #6993,
#6997 and #7021's predecessors, so this PR removes rather than discards.
## Also in this PR
- `skills` dropped from the `files` field of `@copilotkit/react-core`,
`@copilotkit/runtime` and `@copilotkit/a2ui-renderer`, so the tarballs
stop carrying a copy.
- `RESERVED_LIFECYCLE_SLUGS` in `scripts/sync-plugin-skills.ts` goes
from 14 entries to 8.
- `.claude-plugin/plugin.json` and `marketplace.json` descriptions no
longer advertise the deleted lifecycle.
- `/build-with-agents` (56,393 distinct viewers in 90 days) named three
deleted skills in a table and told the reader to "Use the
copilotkit-setup skill to get started". Rewritten for the two-skill
model.
- `README.md` and the two stale cross-references in
`copilotkit-channels/SKILL.md` updated.
- One dead `skills/copilotkit-setup/SKILL.md` entry removed from
`ALIAS_ALLOWLIST` in `scripts/validate-intelligence-env-names.ts`.
`scripts/__tests__/public-skill-drift.test.ts` guarded specific wording
inside files that no longer exist. It is now a link guard instead: every
`docs.copilotkit.ai` path a packaged skill names has to resolve to a
page in this repo, and the two entry points have to stay free of a
transcribed API surface (asserted as: no `sources.md` other than the
channels skill's).
## Supersedes
Closed in favour of this one, with a comment on each: #7017 (the CLI
skill, whose content seeded `copilotkit-cli`), #7021, #7023.
## Needs a decision from someone else
- **#5689** (@onsclom) is a skill-lift eval for `copilotkit-setup`,
which this PR deletes. No file overlap, so it will not conflict, but the
eval target is gone. Austin's call whether to retarget it at
`copilotkit` or drop it.
- **#6636** (community, for #6125) fixes
`packages/react-core/skills/react-core/references/agent-access.md`, the
one file it touches, which this PR deletes. Needs a reply to the author
explaining why, not a silent close.
- **Install-command drift, unresolved.** `README.md` and
`showcase/.../cli/cli.mdx` say `npx copilotkit@latest skills install`;
`/build-with-agents` says `npx skills add CopilotKit/CopilotKit/skills
-y`. Both commands work. Picking one retires a shipped CLI command,
which belongs in the Intelligence repo, so this PR leaves both in place
and changes only the prose around them.
## Testing
The worktree has no `node_modules`, so `lefthook` could not resolve
`tsx`, `oxlint` or `nx` and the commit used `--no-verify`. Every gate
the hook would have run was run by hand against the repo's own binaries,
and the pre-commit failure output was the "command not found" line in
each case, not a gate verdict.
`pnpm check:plugin-skills` — the mirror gate, which also enforces orphan
deletion:
```
$ tsx scripts/sync-plugin-skills.ts --check
plugin skill mirror in sync
```
`pnpm check:intelligence-env-names`:
```
$ tsx scripts/validate-intelligence-env-names.ts
Intelligence env var names and hosts are canonical.
```
Both script suites:
```
$ vitest run scripts/__tests__/public-skill-drift.test.ts scripts/__tests__/sync-plugin-skills.test.ts
Test Files 2 passed (2)
Tests 16 passed (16)
```
**Mutation-checked the new link guard**, so it is not passing for the
wrong reason. Appending `See
[nope](https://docs.copilotkit.ai/this-page-does-not-exist).` to
`skills/copilotkit/SKILL.md`:
```
⎯⎯⎯⎯⎯⎯⎯ Failed Tests 1 ⎯⎯⎯⎯⎯⎯⎯
+ "skills/copilotkit/SKILL.md: /this-page-does-not-exist",
Test Files 1 failed (1)
Tests 1 failed | 3 passed (4)
```
Restored, back to 4 passed. The guard already caught one real mistake of
mine while I was writing the skill: I had linked `/custom-look-and-feel`
from the nav list without checking, and the page is
`/custom-look-and-feel/css`.
`oxfmt` on the four changed TypeScript files: no changes. Both plugin
manifests re-parsed as JSON after editing.
MDX: `build-with-agents.mdx` changes are prose, one table body and one
fence body. Its JSX tag inventory is byte-identical to `origin/main`:
```
$ diff <(git show origin/main:$f | grep -o '</\?[A-Z][A-Za-z]*' | sort | uniq -c) \
<(grep -o '</\?[A-Z][A-Za-z]*' $f | sort | uniq -c) && echo IDENTICAL
IDENTICAL
```
`https://docs.copilotkit.ai/build-with-agents` returns 200, so the new
README link resolves.
Not run: the showcase docs build, which needs the per-entry
`node_modules` symlinks and the pretest generators this worktree does
not have. CI covers it.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **New Features**
- Added `copilotkit` skill for searching current documentation and
source.
- Added `copilotkit-cli` skill for project verification, onboarding,
authentication, scaffolding, and CLI commands.
- Added guidance to use `copilotkit verify` to validate project wiring.
- **Documentation**
- Updated marketplace, plugin, README, and agent-building guidance for
the new skills.
- Updated channel guidance to reference CLI-based setup.
- **Removals**
- Removed legacy setup, development, integration, debugging, upgrade,
contribution, and self-update skills.
- Package distributions no longer include bundled skill documentation.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## What does this PR do?
Points the Inspector's seven per-feature "Copy setup prompt" buttons at
the CLI's seven `--intent` feature routes, and retires the prose that
duplicated them.
Intelligence#994 shipped `onboard start --intent <slug>` and seven
feature routes. Nothing emitted the flag, so the only way to reach a
route was to type it by hand — and the Inspector had already solved the
same problem its own way, with a per-feature template of its own. Two
implementations of feature onboarding for the same seven outcomes, and
the routes had no caller at all.
**What changed**
* Home's feature buttons emit `onboard start --run <id> --coding-agent
<slug> --intent <slug>`.
* `homeFeatureImplementationPrompt` is gone. Its body — inspect first,
read the guide, make a plan, implement the smallest change, prove it
works — is what the route already carries, with per-phase check-ins, a
`feature/stop` route for a missing prerequisite, prompts pinned to a CLI
version through `onboarding-graph.lock.json`, and intent-tagged
telemetry on every step. A copied paragraph carries none of that and
drifts the moment the API moves, which had already happened once to
Learning.
* One table, `FEATURE_ONBOARDING_INTENT`, maps each tile to one intent.
`Record<HomeServiceId, OnboardingIntent>` makes a new tile without an
intent a type error, and a test holds the two sets equal in both
directions.
* The two docs feature prompts follow: the Learning and Rich Threads
guides name an intent instead of repeating setup prose. They pass no
`--run` id, because these strings are static and `llm-text` inlines them
into cached raw Markdown, where one minted id would be shared by every
reader. The CLI mints its own when the flag is absent.
**Two naming decisions, both recorded in code**
The two id sets stay separate. A `HomeServiceId` names a tile and the
pane behind it, so `websocket` and `audio` are right for it; an intent
names work to be done, so `add-realtime-sync` and `add-voice` are right
for that. One table maps between them rather than forcing one string to
be both.
`memory` maps to `add-learning`, and that is now a fact rather than a
guess. `learningOn` is `learningSnapshot?.configuration.state ===
"configured"` — a configured Learning *container*, which is exactly what
`feature/learning/start.md` sets up through `getLearningContainerId`.
The tile id `memory` and the `memories` menu key are older names for
that same pane.
**The generic prompts stay generic**
The Inspector's install prompt, the docs CTA, and the Intelligence web
app keep pointing at the generic route. All three are entry points for a
developer with no CopilotKit app yet, and every feature route requires
one: it inspects for an app first and reads `feature/stop` when it is
missing. The reasoning is written into `onboarding-prompt.ts` so the
next person does not have to rederive it.
## The release blocker is cleared
`copilotkit@4.9.50` published on 2026-09-10 and is now `latest`. Its
tarball carries all seven `intentRoots` and all seven `prompts/feature/`
directories, built from Intelligence `1e703c3c`.
The exact string this PR's buttons copy was run against the real
package:
```
$ npx --yes copilotkit@latest onboard start --run abc123def456 \
--coding-agent claude-code --intent add-a2ui
onboarding_run_id: abc123def456
onboarding_graph_tree: 249d0337...
# Add A2UI to the existing CopilotKit app
```
All seven intents exit 0 against the published package. An unknown
intent is refused with `ONBOARDING_INTENT_NOT_FOUND` and a list of the
seven valid slugs, so a future drift between the table in this PR and
the CLI's map fails on the first command rather than onboarding the
wrong feature.
The release pinned the same CopilotKit template commit as 4.9.47
(`380ad122`), so the only delta between the two CLI versions is
Intelligence-side.
## The shell-docs half was ungated, so this adds a job
No CI job ran the `showcase/shell-docs` vitest suite, and none of the
prompt files were in `test_integration-docs.yml`'s paths filter. The
assertions in that half were verified on a developer's machine and
nowhere else, which is the same gap the retired prose had.
`feature-prompt-intents` now runs the five prompt test files on any
change to them, scoped to those files because the whole suite is not
green on main. Verified by running the job's exact command locally: 5
files, 17 tests, all passing.
## Related PRs and Issues
- Closes OSS-1150
- Follow-up: OSS-1151
- Callers for CopilotKit/Intelligence#994
## Validation
Run in a worktree off `origin/main`, with pre-existing failures
confirmed by running the same specs against unmodified `origin/main` in
the same worktree.
* `web-inspector` — `tsc --noEmit` clean; `tsdown` build clean; `vitest
run` 662 passed, 35 failed. All 35 are `threads-states.spec.ts` dying in
`setupSettledState` on `Cannot assign to read only property 'mock'`,
which reproduces identically on `origin/main` (35 failed | 1 passed of
36, before and after). The one assertion this PR changes in that file is
therefore not exercised locally; the same button is covered by
`launcher-hud.spec.ts`, which passes.
* `web-inspector` — `tsc --project dev/tsconfig.json` reports 2 errors
in `dev/*-state-lab-server.ts`, both `Uint8Array` vs `BodyInit`; same 2
on `origin/main`.
* `shell-docs` — `tsc --noEmit` clean; `vitest run` 875 passed, 6 failed
in `brand-nav`, `angular-docs-content`, `llm-text` (mastra) and
`ms-agent-python-stable-api`; the same 6 fail on `origin/main`.
* `oxfmt --check` and `oxlint` clean on every file in the diff. The
three files oxfmt still flags are two generated JSON bundles and
`page-tree-bridge.ts`, none of them touched here.
## Checklist
- [x] I have read the Contribution Guide
- [x] If the PR changes or adds functionality, I have updated the
relevant documentation
- [x] "Allow edits by maintainers" is checked
🤖 Generated with [Claude Code](https://claude.com/claude-code)
The packaged skills had grown into a second copy of the documentation.
`runtime` and `react-core` were roughly 60% transcribed API surface, and
most of their remaining "Common Mistakes" prose already existed on a docs
page. A cached copy of an API goes stale silently: four claims in the
deleted skills contradicted the source they cited, and one of them reached
a shipped PR before it was caught.
Replace them with two skills that look the answer up instead of restating
it:
- `copilotkit` — the four search tools and two explore tools of the
bundled `copilotkit-docs` MCP server, which corpus answers which
question, and the instruction not to answer from memory.
- `copilotkit-cli` — the CLI, led by `copilotkit verify --json`. Since
#1180 `verify` covers version skew, CORS, and transcription, which is
what most of the old `copilotkit-debug` skill described by hand.
Deleted: copilotkit-setup, copilotkit-develop, copilotkit-integrations,
copilotkit-debug, copilotkit-upgrade, copilotkit-agui, copilotkit-contribute,
copilotkit-self-update, and the three package-generated skills (react-core,
runtime, a2ui-renderer).
The `skills` directory is dropped from the `files` field of the three
packages that shipped one, so the tarballs no longer carry a copy.
`public-skill-drift.test.ts` guarded wording in files that no longer exist.
It is now a link guard: every `docs.copilotkit.ai` path named by a packaged
skill has to resolve to a page in this repo, and the two entry points have
to stay free of a transcribed API surface.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Completes the docs side of the runtime-skill consolidation. With #7005
and this, **every hazard the skill carries has a documented home**, so
the deletion can proceed without losing anything.
Three callouts — because most of these 15 turned out to be documented
already.
## Added
| Hazard | Home |
| --- | --- |
| A `BuiltInAgent` refuses a second concurrent run on itself |
`backend/copilot-runtime.mdx` § Agents |
| Don't call `.abort()` on a factory's `abortController` |
`backend/custom-agent.mdx` |
| What to pass when wiring an external agent, and which URL it takes |
`backend/copilot-runtime.mdx` § Agents |
The concurrent-run one is the most valuable. `Agent is already running.
Call abortRun() first or create a new instance.` — and every example
constructs the instance at module scope, so on a server serving more
than one person, the *second* concurrent request is the one that fails.
Nothing in the docs said so.
## Already covered, so nothing written
`maxSteps` and the tool-call loop. The `"provider:model"` rule —
`model-selection.mdx` states it *and* that `"provider/model"` also
works, which matches `index.ts:178` normalising `/` to `:`.
`forwardSystemMessages` defaulting to `false`. TanStack AI not surfacing
reasoning events. State tools and `config.tools` being the factory's
job, covered by both the Simple-versus-Factory table and the converter
reference.
Four of the six wiring hazards **cite a docs page as their own source**,
and each still holds: `getLocalAgents` returning a record is in the
Mastra guide, and the `/run` and `/agui` suffixes are in the LlamaIndex
and Agno guides.
## Not carried over
The skill flags defaulting to Simple Mode as a **HIGH** mistake and
calls Factory Mode with TanStack AI "the preferred default". Source
expresses no preference between the two — `isFactoryConfig` is a type
guard and nothing more, and the word "prefer" does not appear. The
skill's own evidence is an example file plus a maintainer conversation.
The docs say to stick with simple mode until you need more, which
nothing contradicts.
That is the **fourth** skill claim in this effort that source did not
support, after the deprecated-handler pair, the edge-runtime adapters,
and server-tool rendering. It was also the skill's headline
recommendation for this entire surface.
Also skipped: a hazard about passing a URL to `A2AAgent`. The documented
path is `A2AMiddlewareAgent`, so writing it would introduce an API the
docs deliberately leave out.
## Method note
Two hazards looked uncovered to a keyword search and were not.
`model-selection.mdx` states the model-string rule in quotes (``
`"provider:model"` ``), which my grep for `openai/` missed entirely; I
only found it by reading the file. Every "covered" verdict above came
from reading the page, and every "added" claim was verified against
source — `index.ts:997` for the concurrent-run message, `:746-748` for
the `abortController` JSDoc.
## Testing
Both changed files parse as MDX (`remark-parse` + `remark-mdx`):
```
OK docs/backend/copilot-runtime.mdx
OK docs/backend/custom-agent.mdx
```
## What this unblocks
The runtime skill's 27 files can now be deleted. Remaining prerequisites
for that are no longer about content:
- `packages/runtime/package.json` `"files": ["dist", "skills"]` needs
deciding
- Both copies must go together (`packages/runtime/skills/` and
`skills/runtime/`), which `check:plugin-skills` enforces
- One hazard stays unresolved by design: whether a thrown error in a
server tool kills the run. `/server-tools` says throw, the skill says it
kills the run, and nothing in the repo pins it. Worth a live test before
the deletion, so the answer isn't lost with the skill.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **Documentation**
- Added guidance for connecting external agents, including accepted
agent types and endpoint configuration.
- Documented concurrent-run limitations and recommended handling for
per-request agents or serialized turns.
- Clarified cancellation practices for custom agents to ensure proper
teardown.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
First half of consolidating the packaged `runtime` skill onto the docs.
Cleanup of the skill itself follows in a second PR, once every hazard
has a documented home.
## Why
The skill is 4,509 lines: **61% cached API surface** the docs already
supply, and **38% Common Mistakes** they do not. Caching the first half
is why the skill rots — its predecessors prescribed two dead hostnames
up to v1.62.2. This moves the second half in, as inline `<Callout
type="warn">`, which the docs already use 70-plus times.
## What landed
Twelve callouts across five pages, covering **17 of the skill's 51
hazards**.
| Page | Added |
| --- | --- |
| `/server-tools` | 5 callouts — it had **no warnings at all** |
| `backend/runtime-endpoints` | `basePath` throws at mount; keep runtime
imports on `/v2` |
| `voice` | `/transcribe` 503 with no service; the wire contract for
direct calls; return-a-string and let-provider-errors-through |
| `backend/agent-runner` | Don't pass a `runner` on an Intelligence
runtime |
| `intelligence/connect-your-runtime` | `identifyUser` is required by
the options type |
The `identifyUser` one corrects a misleading comment. The page said
omitting it means "every visitor shares one history", implying it is
optional with a downside. The options type is a discriminated union: it
is required whenever the runtime serves a web surface, and the only
exception is a Channels-only runtime passing a non-empty `channels`
array.
## What needed nothing
**Sixteen hazards were already covered — several better than the
skill.** `backend/agent-runner` documents eviction semantics,
`onConcurrentRun`, and the process-global limits clobber, none of which
the skill mentions. The lifecycle-hooks table already states "Throw
`Response` to short-circuit". `connect-your-runtime` maps wsUrl symptoms
to causes in a table.
The whole `middleware` group came out moot: the docs teach `hooks` and
never teach `beforeRequestMiddleware`, so hazards about the legacy API
have nothing to attach to.
## Two skill claims I did not carry over, because they are wrong
- The skill flags `createCopilotExpressHandler` /
`createCopilotHonoHandler` as **CRITICAL to avoid in new code**. The
source says the opposite:
```
/** @deprecated Use `createCopilotExpressHandler` instead. */
export { createCopilotExpressHandler as createCopilotEndpointExpress };
```
It is `createCopilotEndpoint*` that is deprecated, in favour of exactly
the two handlers the skill condemns. The docs use them 12 times as the
primary path and are correct. Following the skill here would have
degraded working documentation.
- The skill warns against framework adapters on Workers / Bun / Deno.
`runtime-server-adapter.mdx` carries dedicated sections for all three,
plus Elysia. The skill's claim conflates "Express needs Node" with
"adapters don't work on edge runtimes".
An `A2AAgent`/`A2AClient` hazard was also skipped: the docs teach
`A2AMiddlewareAgent`, and writing the hazard would introduce an API the
docs deliberately don't document.
## Deliberately unresolved
The skill says a thrown error inside a server tool's `execute` kills the
run. `/server-tools` tells readers to throw, and the model will see the
error. `execute` is handed to the underlying SDK rather than called by
CopilotKit, no test in the repo pins the behaviour, and I could not
settle it statically — so **neither claim was written**. The
serialization half, which I did verify, is in the callout; the throw
half is untouched.
## Still outstanding
Two hazard groups: `wiring-external-agents` (6) and `built-in-agent`
(9). Both want their own pass rather than a rushed one. Two things found
while scoping them:
- `built-in-agent.mdx` at the docs root is a **12-line placeholder**
with a `TODO` comment, while 1,450 lines of real content sit under
`integrations/built-in-agent/`. Its nine hazards have no root page to
land on.
- "Simple Mode" / "Factory Mode" appears in only **2 files**, and most
of those nine hazards are about that distinction.
The runtime-skill deletion should not start until these two groups land,
so the cleanup PR can cite where every hazard went.
## Testing
Every changed file parses as MDX (`remark-parse` + `remark-mdx`):
```
OK docs/backend/agent-runner.mdx
OK docs/backend/runtime-endpoints.mdx
OK docs/integrations/built-in-agent/server-tools.mdx
OK docs/intelligence/connect-your-runtime.mdx
OK docs/voice.mdx
```
Every claim written was verified against the tree at this commit —
`express.ts:205` for the `basePath` throw, `agent/index.ts:1699-1703`
for the serialization fallback, `runtime.ts:253-266` for the
`identifyUser` union, `handle-transcribe.ts` for the 503 and the
field-name and `mimeType` rules. Placement was chosen after reading each
page in full; an earlier pass of this work misjudged coverage twice by
reading headings instead of prose, and once by reading a stale checkout.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **Documentation**
- Clarified runner selection rules for Intelligence and self-hosted
runtimes.
- Documented required `basePath` configuration and endpoint-specific
errors.
- Added guidance on server-tool limitations, validation, naming
conflicts, serialization, and factory-created agents.
- Clarified Intelligence client requirements, including API key and
runtime user identification.
- Documented voice transcription setup, request formats, configuration
errors, and custom backend requirements.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Resolution has four steps, not three: explicit `agentId`, the chat
configuration's `agentId`, the provider-level `CopilotKitAgentIdContext`
value, then `DEFAULT_AGENT_ID`. See use-agent.tsx:206-208.
Also note that the provisional agent is returned in the runtime error
state too, not only while connecting.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Completes the docs side of the runtime-skill consolidation, so the skill can
be deleted without losing anything. Three callouts, because most of these 15
hazards turned out to be documented already.
Added:
- A `BuiltInAgent` refuses a second concurrent run on itself
(`Agent is already running. Call abortRun() first or create a new
instance.`). The examples construct the instance at module scope, so on a
server serving more than one person the second concurrent request is the one
that fails. Nothing in the docs said so.
- Do not call `.abort()` on the `abortController` handed to a factory — the
source's own JSDoc says so, and the docs showed the field without the
warning.
- What to pass when wiring an external agent, and which URL it takes: an
`AbstractAgent` wrapper rather than the framework's SDK client, and the
framework's own server rather than `/api/copilotkit`.
Already covered, so nothing written: `maxSteps` and the tool-call loop; the
`"provider:model"` rule, which `model-selection.mdx` states along with
`"provider/model"` also working; `forwardSystemMessages` defaulting to false;
TanStack AI not surfacing reasoning events; state tools and `config.tools`
being the factory's job, which the Simple-versus-Factory table and the
converter reference both cover. Four of the six wiring hazards cite a docs
page as their own source, and each still holds — `getLocalAgents` returning a
record, and the `/run` and `/agui` suffixes, are in the Mastra, LlamaIndex and
Agno guides.
Not carried over: the skill flags defaulting to Simple Mode as a HIGH mistake
and calls Factory Mode with TanStack AI "the preferred default". The source
expresses no preference between the two — it is a type guard and nothing more
— and its own evidence is an example file plus a maintainer conversation. The
docs say to stick with simple mode until you need more, which nothing
contradicts. That is the fourth skill claim in this effort that source did not
support.
Also skipped: a hazard about passing a URL to `A2AAgent`. The documented path
is `A2AMiddlewareAgent`, so writing it would introduce an API the docs
deliberately leave out.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The React Native `useAgent` reference page still described the pre-1.64.2
hook: parameters listed only `agentId` and `updates`, and the signature
returned `{ agent: AbstractAgent }` with no `isReady`.
React Native re-exports react-core's `useAgent` verbatim from
`@copilotkit/react-core/v2/headless`, so the page was documenting props the
hook no longer has alone. Add `threadId`, `runtimeAgentId` and `throttleMs`,
add the `isReady` return value, note the headless entry point, and describe
the two valid option shapes. Mirrors the React page changes in #6388 so the
two stay consistent.
Reported for the React page in #6125.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Self-review of the previous commit against source.
The first callout on `/server-tools` was wrong. It said a server tool's call
never reaches the browser, so nothing can render it. Both `TOOL_CALL_START`
emissions are driven by the model's stream parts, `tool-input-start` and
`tool-call`, with no filtering on whether the tool has a server-side
`execute` — so the call does stream, and a render-only `useRenderTool`
registration can give it UI while `execute` stays on the server. The claim
came from the packaged runtime skill, whose source for it was a dev-docs note
rather than code, and I carried it over without checking. Rewritten around the
distinction that actually holds: `execute` runs on the server and cannot touch
the page.
Three smaller corrections:
- The AG-UI state tools are injected whenever the Built-in Agent makes the
model call itself, not, as written, when it is given a `tools` array.
- The unserializable-result placeholder names the tool call id when no tool
name is available, so the callout no longer quotes a fixed string.
- The Express and single-route handlers throw different `basePath` messages;
the callout quoted only the Express one while claiming both.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
First half of consolidating the packaged `runtime` skill onto the docs. The
skill's 4,509 lines are 61% cached API surface, which the docs already supply,
and 38% Common Mistakes, which they do not. This moves that 38% in as inline
`<Callout type="warn">`, the convention the docs already use 70-plus times.
Twelve callouts across five pages, covering 17 of the skill's 51 hazards:
- `/server-tools` had no warnings at all. Added five: server tools cannot
render UI, `parameters` needs a Standard Schema validator rather than JSON
Schema, the two reserved AG-UI tool names, server tools winning name
collisions with frontend tools, results having to serialize, and a factory
ignoring the `tools` array.
- `runtime-endpoints`: `basePath` throwing at mount, and keeping every runtime
import on `/v2`.
- `voice`: `/transcribe` answering 503 with no service configured, the wire
contract for calling it directly, and the return-a-string plus
let-provider-errors-through rules for a custom service.
- `agent-runner`: not passing a `runner` on an Intelligence runtime.
- `intelligence/connect-your-runtime`: `identifyUser` is required by the
options type, not merely advisable. The page's comment implied omitting it
only degraded per-user history.
Sixteen hazards needed nothing, because the docs already covered them, in
several cases better than the skill: the runner page documents eviction
semantics, `onConcurrentRun` and the process-global limits clobber; the
lifecycle-hooks table already says to throw a `Response` to short-circuit;
`connect-your-runtime` maps wsUrl symptoms to causes.
Two skill claims turned out to be wrong and were not carried over. The skill
flags `createCopilotExpressHandler` and `createCopilotHonoHandler` as CRITICAL
to avoid in new code, but the source deprecates `createCopilotEndpoint*` in
favour of exactly those two, so the docs were right and the skill would have
degraded them. The skill also warns against framework adapters on
Workers/Bun/Deno, where the docs carry dedicated sections for all three.
Deliberately left: the skill says a thrown error in a server tool kills the
run, while `/server-tools` tells readers to throw. Nothing in the repo pins
which is true, so neither claim was written.
Still outstanding: the `wiring-external-agents` and `built-in-agent` hazard
groups. The `built-in-agent` root page is a 12-line placeholder, and
Simple-versus-Factory Mode — where most of its nine hazards live — appears in
only two files.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The three docs expansion tests pinned the hand-written prose that OSS-1150
retired. They now assert the command that reaches the route instead, and
keep the structural check that the prompt tag is expanded.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The seven `--intent` feature routes shipped with no caller. Every copyable
prompt still ran `onboard start --run … --coding-agent …`, so the only way
to reach a route was to type the flag by hand, and the Inspector solved the
same problem again with its own per-feature prose.
Home's feature buttons now emit `onboard start … --intent <slug>` and carry
no feature-specific instruction. The route owns the guide links, the plan,
the per-phase check-ins, the refusal when a prerequisite is missing, and the
proof step. One table maps each tile to one intent, and a test holds the two
sets equal in both directions.
The two docs feature prompts follow: Learning and Rich Threads name an
intent instead of repeating setup prose that had already drifted from the
shipped API once. The generic prompts on docs and the Intelligence web app
stay generic, because every feature route requires an app that those
readers do not have yet.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
## Problem
Inspector message shortcuts do not consistently follow Inspector
visibility.
## Why
The shortcuts should respect local development restrictions and
visibility settings.
## Fix
- Add a wrench shortcut with a hover menu and a hide-until-reload
action.
- Add `CopilotChat.inspectorTools`, with provider settings taking
precedence.
- Keep shortcuts in sync with Inspector visibility and restrict
Inspector to local development.
Includes tests and API documentation.
## Summary
The same onboarding prompt supports greenfield projects, brownfield
applications or agent backends, and existing CopilotKit OSS projects
connecting to Intelligence. The index states these starting points
explicitly and explains where to run the prompt.
Replace the exhaustive default `/llms.txt` expansion with a curated
index that exposes the canonical onboarding prompt, then routes readers
to their existing agent framework. The prompt is imported from the same
template used by the docs copy button, with instructions to create a
fresh run ID per onboarding session. Research-only readers are directed
to the documentation links.
Every visible external framework in the docs registry receives an
overview and quickstart link in a dedicated section. This includes the
LangGraph variants, Google ADK, Claude Agent SDK, Strands, Microsoft
Agent Framework, and other published integrations; hidden integrations
remain excluded.
The following section covers chat, generative UI, human-in-the-loop
workflows, Rich Threads, Automatic Learning, Intelligence, Channels, and
thread imports. Built-in Agent quickstart, model selection, and server
tools are explicitly labeled. Readers are directed to framework-specific
implementation guides instead of assuming root instructions apply to
every backend. `/llms-full.txt` remains available for exhaustive
retrieval.
Channels has two prominent canonical entries, with descriptions covering
native messages, approvals, and managed connection availability.
Repeated framework-specific channel guides remain in the full index.
Regression coverage now requires Slack and Teams entry points instead of
excluding every channel route.
## Validation
- Focused index tests cover the shared onboarding prompt, deterministic
output, every visible framework's canonical overview and quickstart,
hidden exclusions, ordering, and duplicates.
- Explicit TypeScript check passed after adding the onboarding prompt.
- Changed-file formatting and diff checks passed.
- Both canonical Slack and Teams documentation URLs returned HTTP 200.
- The initial implementation passed typecheck, lint, production build,
and commit hooks.
## Existing verification failures
The broader Nx `verify-shell-docs:fast` check reported existing unknown
snippet regions, internal dead links, and essential-content findings.
The unchanged Mastra LLM rendering test also expects a `createTool`
import absent from an existing generated snippet. These failures are
recorded separately from the passing index contract tests.
Linear: PDX-332
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **New Features**
- Updated `/llms.txt` with a curated documentation index covering key
capabilities, interfaces, agent workflows, persistence, and supported
channels.
- Added dynamically generated entries for supported external agent
frameworks and integration quickstarts.
- Added onboarding instructions for connecting CopilotKit with a coding
agent.
- Clarified built-in agent documentation labels.
- Linked to `/llms-full.txt` for the complete documentation inventory.
- **Bug Fixes**
- Improved index consistency through validated ordering, uniqueness, and
visibility checks.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
The documented Codex command connects `mcp-remote` to the server root,
which returns 404 for both HTTP and SSE. Use the working `/mcp` endpoint
with Codex's native Streamable HTTP support. Correct the same root-URL
error in the shared HTTP/stdio examples, and add `-y` to the remaining
npx bridge commands.
The guide now explains how to replace the old configuration and verify
an actual search, since `codex mcp list` only verifies registration.
Validation:
- Reproduced the old command failing with `Cannot POST /` and SSE 404.
- Live `/mcp` initialization and tool discovery succeeded.
- Codex CLI 0.153.4 successfully called `search-docs` and `explore-docs`
against `/mcp` (only those read tools preapproved for the noninteractive
smoke test).
- Docs content generation and 47 tests passed across docs-render, .NET
guidance, frontend-tool coverage, and setup-concept suites.
- Updated MDX compiles and every JSON example parses; commit hooks
passed.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Updated MCP setup examples with the correct endpoint URL.
* Added automatic confirmation to relevant npx commands.
* Revised Codex instructions to use Streamable HTTP MCP servers
directly.
* Updated Codex configuration examples to use URL-based server entries.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Mike Ryan