copilotkit 4.21.0 → 4.22.0

package/onboarding/prompts/framework/custom-ag-ui.md

@@ -0,0 +1,98 @@
+# Connect an existing AG-UI agent
+
+This route is for an agent that the project already has, that speaks AG-UI, and that is
+none of the listed frameworks. For example, an `AbstractAgent` subclass that the project
+wrote, or a service that streams AG-UI events through AG-UI middleware.
+
+Do not port the agent to a listed framework. Do not rewrite its tools, model, or prompts.
+Preserve its model setup and the credential variable names that the repository already
+uses. This route has no default vendor.
+
+The research findings must prove that the agent speaks AG-UI. Either of these is proof:
+
+- a class that extends `AbstractAgent` from `@ag-ui/client` and implements `run`,
+- an endpoint that the project serves and that streams AG-UI events.
+
+A package that names AG-UI is not proof. If the findings prove neither, run the
+unsupported route below.
+
+## Documentation
+
+- https://docs.copilotkit.ai/backend/copilot-runtime.md
+- https://docs.copilotkit.ai/backend/ag-ui.md
+- https://docs.copilotkit.ai/quickstart.md
+- https://docs.copilotkit.ai/inspector.md
+- https://docs.copilotkit.ai/agent-app-context.md
+- https://docs.copilotkit.ai/generative-ui/tool-based.md
+
+These pages use the root documentation scope. Do not add a framework path segment to
+their URLs. Use the tool-based generative UI page for this route.
+
+## Connect the agent
+
+Register the agent in the `agents` map of the Copilot Runtime from
+`@copilotkit/runtime/v2`. The key in that map is the agent id that the frontend asks for.
+
+- Register an `AbstractAgent` subclass that runs in the runtime process directly. Pass an
+  instance of the project's own class.
+- Connect an agent that runs as its own service with `HttpAgent` from `@ag-ui/client`. Its
+  `url` is the service's own AG-UI endpoint, not the runtime's `/api/copilotkit` path.
+
+Do not use `selfManagedAgents` or `agents__unsafe_dev_only`. Those provider options send
+requests past the runtime, so the Intelligence features that this run adds never reach
+the agent.
+
+## Match the AG-UI client version
+
+`@copilotkit/runtime` depends on one exact `@ag-ui/client` version. Read that version
+from the `package.json` of the installed `@copilotkit/runtime`. The npm `latest` tag of
+`@ag-ui/client` can be a different version.
+
+An `AbstractAgent` subclass built on another version is a different class to TypeScript.
+`AbstractAgent` has private members, so the `agents` map rejects the subclass with
+`Types have separate declarations of a private property`. Import `HttpAgent` from the
+same version for the same reason.
+
+If the project's `@ag-ui/client` version is not the runtime's version, name both versions
+in the plan. The agent depends on its own version, so ask the developer before you change
+it.
+
+## Keep the agent working on a clone
+
+The runtime clones the registered agent for every request. `AbstractAgent.clone()`
+copies only the fields that `AbstractAgent` itself declares. A subclass that sets its
+own fields in its constructor, such as a model client or a configuration object, loses
+them on the clone. Its `run` then fails on the first request. `HttpAgent` copies its own
+fields, so this applies only to a subclass.
+
+Read the subclass before you plan. If `run` reads a field that the subclass sets, and
+the subclass does not override `clone()`, the plan adds an override. The override calls
+`super.clone()` and copies those fields. This is the only change that this route makes to
+the agent's code. Name it in the plan.
+
+## Project data
+
+The agent receives `useAgentContext` entries on the AG-UI run input, in its `context`
+field. No page documents how a custom agent gives them to its model, because that is the
+agent's own code. If the requested work passes project data to the agent, and the
+agent's code does not already read `context`, run the unsupported route below. Otherwise,
+record the gap and continue.
+
+A2UI is not on this path. If the developer asks for it, say first that no page documents
+A2UI for a custom agent.
+
+## Record the selection
+
+The Copilot Runtime that this route adds runs on Node. The agent keeps running the way
+the project runs it now.
+
+Record the selected framework `custom-ag-ui` and the agent id. Record how the agent
+connects: in the runtime process, or through `HttpAgent` and its URL. Record the
+credential variable names that the agent already uses, the `clone()` finding, and these
+URLs.
+
+If the pages support the selection, run
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read frontend/plan`.
+
+If the documentation does not support the selection, run
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/framework/deep-agents.md

@@ -33,7 +33,7 @@ Record the selected framework, language, vendor, model, required credential vari
 names, these URLs, and each documentation gap.
 
 If the pages support the selection, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read frontend/plan`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read frontend/plan`.
 
 If the documentation does not support the selection, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read unsupported/no-validated-path`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/framework/google-adk.md

@@ -30,7 +30,7 @@ Record the selected framework, vendor, model, required credential variable names
 these URLs.
 
 If the pages support the selection, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read frontend/plan`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read frontend/plan`.
 
 If the documentation does not support the selection, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read unsupported/no-validated-path`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/framework/langgraph-fastapi.md

@@ -25,7 +25,7 @@ Record the selected framework, vendor, model, required credential variable names
 these URLs.
 
 If the pages support the selection, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read frontend/plan`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read frontend/plan`.
 
 If the documentation does not support the selection, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read unsupported/no-validated-path`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/framework/langgraph-python.md

@@ -19,7 +19,7 @@ Record the selected framework, vendor, model, required credential variable names
 these URLs.
 
 If the pages support the selection, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read frontend/plan`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read frontend/plan`.
 
 If the documentation does not support the selection, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read unsupported/no-validated-path`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/framework/langgraph-typescript.md

@@ -19,7 +19,7 @@ Record the selected framework, vendor, model, required credential variable names
 these URLs.
 
 If the pages support the selection, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read frontend/plan`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read frontend/plan`.
 
 If the documentation does not support the selection, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read unsupported/no-validated-path`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/framework/llamaindex.md

@@ -34,7 +34,7 @@ Record the selected framework, vendor, model, required credential variable names
 URLs, the documented dependencies and adapter, and both documentation limits.
 
 If the pages support the selection, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read frontend/plan`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read frontend/plan`.
 
 If the documentation does not support the selection, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read unsupported/no-validated-path`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/framework/mastra.md

@@ -47,7 +47,7 @@ Record the selected framework, vendor, model, required credential variable names
 these URLs.
 
 If the pages support the selection, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read frontend/plan`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read frontend/plan`.
 
 If the documentation does not support the selection, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read unsupported/no-validated-path`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/framework/ms-agent-dotnet.md

@@ -15,7 +15,7 @@ Run `dotnet --version` before you change the project. If it fails, no .NET SDK i
 shell's PATH. Do not change the project, and do not install the SDK yourself. Tell the
 developer to install the .NET SDK from https://dotnet.microsoft.com/download. Say that the
 coding agent's shell cannot see a new install until the developer restarts the coding
-agent. Give them `npx --prefer-offline --yes copilotkit@4.21.0 onboard start --run <onboarding_run_id>`
+agent. Give them `npx --prefer-offline --yes copilotkit@4.22.0 onboard start --run <onboarding_run_id>`
 to resume the run after the restart. Then end your turn and wait for the developer.
 
 ## Documentation
@@ -41,7 +41,7 @@ Record the selected framework, provider, model, required credential variable nam
 these URLs.
 
 If the pages support the selection, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read frontend/plan`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read frontend/plan`.
 
 If the documentation does not support the selection, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read unsupported/no-validated-path`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/framework/ms-agent-harness-dotnet.md

@@ -9,7 +9,7 @@ you change the project. If it fails, no .NET SDK is on this shell's PATH. Do not
 the project, and do not install the SDK yourself. Tell the developer to install the .NET
 SDK from https://dotnet.microsoft.com/download. Say that the coding agent's shell cannot
 see a new install until the developer restarts the coding agent. Give them
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard start --run <onboarding_run_id>` to resume the run
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard start --run <onboarding_run_id>` to resume the run
 after the restart. Then end your turn and wait for the developer.
 
 ## Documentation
@@ -49,7 +49,7 @@ Record the selected framework, provider, model, required credential variable nam
 URLs, and the quickstart gap.
 
 If the pages support the selection, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read frontend/plan`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read frontend/plan`.
 
 If the documentation does not support the selection, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read unsupported/no-validated-path`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/framework/ms-agent-python.md

@@ -30,7 +30,7 @@ Record the selected framework, vendor, model, required credential variable names
 these URLs.
 
 If the pages support the selection, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read frontend/plan`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read frontend/plan`.
 
 If the documentation does not support the selection, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read unsupported/no-validated-path`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/framework/pydantic-ai.md

@@ -43,7 +43,7 @@ Record the selected framework, vendor, model, required credential variable names
 URLs, and the two-step context route.
 
 If the pages support the selection, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read frontend/plan`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read frontend/plan`.
 
 If the documentation does not support the selection, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read unsupported/no-validated-path`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/framework/strands-python.md

@@ -29,7 +29,7 @@ Record the selected framework, vendor, model, required credential variable names
 URLs, and the context documentation gap.
 
 If the pages support the selection, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read frontend/plan`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read frontend/plan`.
 
 If the documentation does not support the selection, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read unsupported/no-validated-path`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/framework/strands-typescript.md

@@ -30,7 +30,7 @@ Record the selected framework, vendor, model, required credential variable names
 URLs, and the context documentation gap.
 
 If the pages support the selection, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read frontend/plan`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read frontend/plan`.
 
 If the documentation does not support the selection, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read unsupported/no-validated-path`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/frontend/angular.md

@@ -5,7 +5,7 @@ Preserve an existing Angular frontend. Use the selected page for a new frontend.
 Use the starter shortcut only if all these facts are true: the target directory holds no
 project, its name is a valid `init` project name, and the selected framework is ADK.
 If all three facts are true, record Angular as the selected frontend. Then run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read starter/clone` before you fetch documentation.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read starter/clone` before you fetch documentation.
 
 ## Documentation
 
@@ -35,26 +35,15 @@ thread as the tool's result.
 `@copilotkit/angular` publishes on a `0.x` line of its own. Every other `@copilotkit/*`
 package publishes on the `1.x` line. Never move either onto the other's line.
 
-The two lines are released separately, so a published `@copilotkit/angular` declares a
-`@copilotkit/core` chosen when that Angular release was cut, not when this run happens.
-Read that declaration before you plan any dependency change:
+A published `@copilotkit/angular` declares the `@copilotkit/core` chosen when that Angular
+release was cut. `onboard upgrade-plan` reads that declaration from the registry. When it
+excludes the version the floor requires, the command answers `blocked` and names both
+versions. Installing both gives two copies of `@copilotkit/core`, and the threads drawer
+then throws in the browser while every command-line check passes.
 
-```text
-npm view @copilotkit/angular@latest dependencies
-```
-
-If the `@copilotkit/core` it declares cannot be satisfied by the version the floor
-requires, the two published packages do not fit together. Installing both resolves two
-copies of `@copilotkit/core`, the Angular package's calls land on the copy that does not
-export what they need, and the threads drawer and the Inspector threads view throw in the
-browser while every command-line check passes.
-
-That is a version-line mismatch. Report it naming both versions -- the `@copilotkit/core`
-the Angular package declares, and the one the floor requires -- and take the unsupported
+That is a version-line mismatch. Report it naming both versions, and take the unsupported
 route at the end of this page. Do not add an `overrides`, `resolutions`, or
-`pnpm.overrides` block to force them together. That is a repair the developer did not
-approve, it silently pins their whole tree, and it hides a mismatch between two packages
-CopilotKit publishes rather than reporting it.
+`pnpm.overrides` block to force them together.
 
 ## Node
 
@@ -63,7 +52,7 @@ you create or build an Angular project. If the installed version is lower, selec
 supported version first and use it for every later command in this project.
 
 If the pages support the selection, record Angular and these URLs. Then run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read credentials/finalize-plan`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read credentials/finalize-plan`.
 
 If the documentation does not support the selection, or the two version lines do not fit
-together, run `npx --prefer-offline --yes copilotkit@4.21.0 onboard read unsupported/no-validated-path`.
+together, run `npx --prefer-offline --yes copilotkit@4.22.0 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/frontend/nextjs.md

@@ -15,7 +15,7 @@ These TypeScript options have starters: Claude Agent SDK TypeScript, LangGraph T
 Mastra, and Strands Agents TypeScript. The .NET option is Microsoft Agent Framework .NET.
 
 If all shortcut conditions are true, record Next.js as the selected frontend. Then run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read starter/clone` before you fetch documentation.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read starter/clone` before you fetch documentation.
 
 ## Documentation
 
@@ -40,7 +40,7 @@ developer's work.
 - Do not claim, revert, or delete these files. Name them in the report as Next.js output.
 
 If the page supports the selection, record Next.js and this URL. Then run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read credentials/finalize-plan`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read credentials/finalize-plan`.
 
 If the documentation does not support the selection, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read unsupported/no-validated-path`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/frontend/plan.md

@@ -37,15 +37,15 @@ CopilotKit web apps. Then recommend the one the developer names, and say what ea
 
 Use exactly one matching internal route:
 
-1. React SPA: `npx --prefer-offline --yes copilotkit@4.21.0 onboard read frontend/react-spa`
-2. Next.js: `npx --prefer-offline --yes copilotkit@4.21.0 onboard read frontend/nextjs`
-3. Angular: `npx --prefer-offline --yes copilotkit@4.21.0 onboard read frontend/angular`
-4. Vue 3: `npx --prefer-offline --yes copilotkit@4.21.0 onboard read frontend/vue`
-5. React Native: `npx --prefer-offline --yes copilotkit@4.21.0 onboard read frontend/react-native`
-6. Slack or Microsoft Teams: `npx --prefer-offline --yes copilotkit@4.21.0 onboard read feature/channels/start`
+1. React SPA: `npx --prefer-offline --yes copilotkit@4.22.0 onboard read frontend/react-spa`
+2. Next.js: `npx --prefer-offline --yes copilotkit@4.22.0 onboard read frontend/nextjs`
+3. Angular: `npx --prefer-offline --yes copilotkit@4.22.0 onboard read frontend/angular`
+4. Vue 3: `npx --prefer-offline --yes copilotkit@4.22.0 onboard read frontend/vue`
+5. React Native: `npx --prefer-offline --yes copilotkit@4.22.0 onboard read frontend/react-native`
+6. Slack or Microsoft Teams: `npx --prefer-offline --yes copilotkit@4.22.0 onboard read feature/channels/start`
 
 If they chose Slack or Microsoft Teams, tell that node which one they chose so it
 does not ask again.
 
 If no listed frontend fits, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read unsupported/no-validated-path`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/frontend/react-native.md

@@ -18,7 +18,7 @@ documents `useRenderTool`, which is React Native's own hook for drawing a tool t
 already has. That is a different job and needs a tool in the agent.
 
 If the pages support the selection, record React Native and these URLs. Then run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read credentials/finalize-plan`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read credentials/finalize-plan`.
 
 If the documentation does not support the selection, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read unsupported/no-validated-path`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/frontend/react-spa.md

@@ -14,7 +14,7 @@ not move the agent into it.
 - https://docs.copilotkit.ai/react-spa.md
 
 If the page supports the selection, record React SPA and this URL. Then run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read credentials/finalize-plan`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read credentials/finalize-plan`.
 
 If the documentation does not support the selection, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read unsupported/no-validated-path`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/frontend/vue.md

@@ -19,7 +19,7 @@ page above. Vue has its own `useComponent`, which is not the React package. Take
 that reference page rather than from a Vue generative-UI guide, which is not published.
 
 If the pages support the selection, record Vue 3 and these URLs. Then run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read credentials/finalize-plan`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read credentials/finalize-plan`.
 
 If the documentation does not support the selection, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read unsupported/no-validated-path`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/implementation/build-and-validate.md

@@ -12,7 +12,7 @@ acted on. Send one short report before you stop. The friction command follows th
 setting the developer already chose, so it needs no separate question.
 
 ```text
-npx --prefer-offline --yes copilotkit@4.21.0 onboard friction --phase stop --category <slug> --message "<sentences>"
+npx --prefer-offline --yes copilotkit@4.22.0 onboard friction --phase stop --category <slug> --message "<sentences>"
 ```
 
 `--message` takes one or two sentences: the step you stopped at and what stopped it.
@@ -67,7 +67,7 @@ Approving the plan is the developer agreeing to every path it listed under
 app directory:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.21.0 onboard protect --authorize --path <path> --reason "<the plan's sentence>"
+npx --prefer-offline --yes copilotkit@4.22.0 onboard protect --authorize --path <path> --reason "<the plan's sentence>"
 ```
 
 Consent has to be on the record before the file moves, so a call made after the change is
@@ -99,7 +99,7 @@ No implementation step has run yet, so the change is theirs rather than this run
 consent over it by adding one flag:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.21.0 onboard protect --authorize --path <path> --reason "<the plan's sentence>" --with-prior-change
+npx --prefer-offline --yes copilotkit@4.22.0 onboard protect --authorize --path <path> --reason "<the plan's sentence>" --with-prior-change
 ```
 
 The flag records their change as drift beside the consent, so the closing report names both
@@ -119,7 +119,7 @@ audit below describes, rather than use this section.
 Run the audit from the target app directory:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.21.0 onboard audit
+npx --prefer-offline --yes copilotkit@4.22.0 onboard audit
 ```
 
 It compares every protected path with the digest the CLI captured for it. Its result starts
@@ -154,14 +154,14 @@ A path that no Files changed section names changed outside the run, and it is th
 developer's own file. Accept it by name:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.21.0 onboard protect --accept-external --path <path>
+npx --prefer-offline --yes copilotkit@4.22.0 onboard protect --accept-external --path <path>
 ```
 
 A changed env file is its own case. This run asked the developer to place a credential
 there, so it takes the credential route rather than this one:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.21.0 onboard protect --accept-credential --path <path>
+npx --prefer-offline --yes copilotkit@4.22.0 onboard protect --accept-credential --path <path>
 ```
 
 That route proves no recorded credential was lost, instead of taking the run's word that it
@@ -180,7 +180,7 @@ neither does a one-line fix. Never repair, reset, or revert it. Ask the develope
 the change, and record the answer they give:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.21.0 onboard protect --authorize --unplanned --path <path> --reason "<what the developer said>"
+npx --prefer-offline --yes copilotkit@4.22.0 onboard protect --authorize --unplanned --path <path> --reason "<what the developer said>"
 ```
 
 Use it only for an answer a developer actually gave. It records the consent as taken
@@ -215,7 +215,7 @@ directory. The developer approved the id before it was made, so this is the firs
 which it can be created:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.21.0 learning containers create --id <id> --name <name> --json
+npx --prefer-offline --yes copilotkit@4.22.0 learning containers create --id <id> --name <name> --json
 ```
 
 Pass the id the plan names. Take the name from the selected project's own display name, so
@@ -232,7 +232,7 @@ plan names no container, skip this section.
 ## Implement the plan
 
 Spawn one implementation subagent. Tell it to run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read subagent/implement-and-validate` first and follow
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read subagent/implement-and-validate` first and follow
 the prompt it returns. If that read fails because the subagent cannot use the shell, stop that
 subagent. Run the same command yourself, then spawn a fresh subagent with the returned prompt
 and the same handoff. Give it the plan, selected framework, frontend, model, exact target app
@@ -259,7 +259,7 @@ names the same way as above, against the Files changed section that subagent jus
 returned. Continue to proof only when that audit passes.
 
 Then run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read proof/round-trip`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read proof/round-trip`.
 
 ## Repair rules
 
@@ -285,9 +285,9 @@ the same command still fails after three repair attempts, a result starts with
 declined a file the plan does not name, or the run cannot ask them about it. A defect in a
 package this run installed is not a stack CopilotKit does not serve, a command this run cannot get to pass is not one either, and a blocked audit
 proved nothing about the stack. In those cases run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read stopped/run-failed`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read stopped/run-failed`.
 
 A plan with no path to follow takes the unsupported ending: the fix requires changing the
 developer's existing agent or frontend, or the documentation does not support the plan. In
 those cases run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read unsupported/no-validated-path`.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/proof/complete.md

@@ -24,7 +24,7 @@ friction commands follow the telemetry setting the developer already chose, so t
 separate question.
 
 ```text
-npx --prefer-offline --yes copilotkit@4.21.0 onboard friction --category <slug> --cost-seconds <seconds> --message "<sentences>"
+npx --prefer-offline --yes copilotkit@4.22.0 onboard friction --category <slug> --cost-seconds <seconds> --message "<sentences>"
 ```
 
 Put one or two sentences in `--message`. Pick one category from docs-missing, docs-wrong,
@@ -46,7 +46,7 @@ Pass the surface-check outcome the proof subagent returned, not the one you want
 web frontend, pass `--visual-check` and the URL the browser opened, unchanged:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.21.0 onboard complete --visual-check <outcome> \
+npx --prefer-offline --yes copilotkit@4.22.0 onboard complete --visual-check <outcome> \
   --frontend-url <the url you opened>
 ```
 
@@ -74,7 +74,7 @@ this graph opens.
 nothing drove the frontend:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.21.0 onboard complete --visual-check failed --blocked-by browser-control-unresponsive
+npx --prefer-offline --yes copilotkit@4.22.0 onboard complete --visual-check failed --blocked-by browser-control-unresponsive
 ```
 
 ## Write the handoff

package/onboarding/prompts/proof/oss-baseline.md

@@ -1,7 +1,7 @@
 # Prove the existing OSS baseline
 
 Do not prove the baseline yourself. Spawn one proof subagent. Tell it to run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read subagent/prove-oss-baseline` first and follow the
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read subagent/prove-oss-baseline` first and follow the
 prompt it returns. If that read fails because the subagent cannot use the shell, stop that
 subagent. Run the same command yourself, then spawn a fresh subagent with the returned prompt
 and the same handoff. Give it the repository findings and exact CLI package spec.
@@ -17,7 +17,7 @@ Wait for the subagent to finish.
 Record what that proof returned before you route on it:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.21.0 onboard proof --step oss-baseline --outcome <passed|failed|skipped> [--predicate <1-6>]
+npx --prefer-offline --yes copilotkit@4.22.0 onboard proof --step oss-baseline --outcome <passed|failed|skipped> [--predicate <1-6>]
 ```
 
 Report the gate whatever it returned. Use the list below. A proof that never ran is `skipped`, not failed. The command prints one line and sends
@@ -39,12 +39,12 @@ Do not change project files before this proof ends. Starting existing developmen
 processes and their ignored runtime files is allowed.
 
 If the subagent proves the `both-oss` predicate, keep its evidence with the plan and run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read conversion/plan`. That project already works.
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read conversion/plan`. That project already works.
 What it needs is the conversion, not a build.
 
 If the proof does not establish the baseline, record the starting state
 `both-copilotkit-unproved` and run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read credentials/plan`. This prompt is served
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read credentials/plan`. This prompt is served
 whenever a project looks like an OSS integration, so a baseline that did not prove is an
 ordinary starting state rather than a failure. Keep the failing predicate with the plan.
 
@@ -58,5 +58,5 @@ and the plan preserves it rather than repeating it.
 
 If it cannot identify the running process safely, exposes a secret, or finds a baseline
 failure that cannot be classified, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read stopped/run-failed`. None of those mean the
+`npx --prefer-offline --yes copilotkit@4.22.0 onboard read stopped/run-failed`. None of those mean the
 project is unsupported: they mean this run did not establish what it needed to.