copilotkit 4.21.0 → 4.23.0

package/onboarding/prompts/proof/round-trip.md

@@ -1,13 +1,18 @@
 # Prove the user journey
 
 Do not do the proof work yourself. Spawn one proof subagent. Tell it to run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read subagent/prove-round-trip` first and follow the
+`npx --prefer-offline --yes copilotkit@4.23.0 onboard read subagent/prove-round-trip` 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 selected framework, frontend, model, approved plan, selected
 documentation URLs, and validation evidence. Give it the documentation policy recorded during
 framework selection or conversion planning. On a conversion, also give it the frozen
-criterion. Give it the protected path list.
+criterion. Give it the protected path list. Give it the developer's answer on the Skills
+install and the Skills result the implementation returned.
+
+Give it the frontend files that publish the page context and register the tools, by path,
+from the Files changed sections the implementation returned. The subagent sends what those
+files send, and without their paths it searches the project and its dependencies for them.
 
 Give it the browser or device control you recorded in the preflight as well. The subagent
 drives the surface and cannot see your environment, so without that finding it spends the
@@ -17,7 +22,7 @@ A web run with no browser tool reports `skipped-no-browser-tool`. That outcome c
 run once the round trip is recorded as `passed`.
 
 A run that cloned a starter is the exception. Tell that subagent that this run cloned a
-starter, to finish after `verify --round-trip`, and to open no browser. The cloned code is what this repository's
+starter, to finish after `onboard proof-check`, and to open no browser. The cloned code is what this repository's
 starter smoke jobs already drive on every change, so opening a browser re-proves in the
 developer's run what those jobs prove before the starter ships, and it is the most
 expensive step in this setup. `verify --round-trip` reads the answer back off the thread,
@@ -35,7 +40,7 @@ pass the time.
 Record what that proof returned before you route on it:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.21.0 onboard proof --step round-trip --outcome <passed|failed|skipped>
+npx --prefer-offline --yes copilotkit@4.23.0 onboard proof --step round-trip --outcome <passed|failed|skipped>
 ```
 
 Report the gate whatever it returned. A proof that never ran is `skipped`, not failed. A
@@ -44,7 +49,7 @@ to record it as `skipped`. The command prints one line and sends nothing else. W
 record each attempt as it ends.
 
 For every protected-path audit in this prompt, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard audit` from the target app directory. If its result
+`npx --prefer-offline --yes copilotkit@4.23.0 onboard audit` from the target app directory. If its result
 starts with `Status: blocked`, report the printed reason and use the route-out rules below.
 A blocked audit proved nothing changed and is not a preservation failure. If a
 protected-path audit reports a changed path, decide it the way the implementation prompt
@@ -53,7 +58,7 @@ returns none, so a finding with no Files changed section to test against routes
 path one of those sections names is this run's own change and routes out too. Accept a
 path only when a section this run collected covers the step that wrote it and does not
 name it:
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard protect --accept-external --path <path>`. Then run
+`npx --prefer-offline --yes copilotkit@4.23.0 onboard protect --accept-external --path <path>`. Then run
 the audit again and name the path in the closing summary. Never repair, reset, or revert a
 protected path.
 
@@ -61,12 +66,12 @@ That holds for a repair cycle too. When the fix for a failing check lands on a p
 path, the path is still the developer's, however right the diagnosis is and however small
 the fix. Reading the file never settles who wrote it. Ask the developer to allow the
 change, and record their answer with
-`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.23.0 onboard protect --authorize --unplanned --path <path> --reason "<what the developer said>"`,
 or route out. Never repair it, and never send it to a repair worker.
 
 If the proof result starts with `Status: passed`, run the protected-path audit. Continue to
 `proof/complete` only if that audit passes. After the audit passes, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read proof/complete`. A performed surface outcome with
+`npx --prefer-offline --yes copilotkit@4.23.0 onboard read proof/complete`. A performed surface outcome with
 the full round trip is core success even if a continued-development tool fails. A skipped
 surface outcome still enters `proof/complete`. The CLI records `skipped-cloned-starter` and
 `skipped-no-browser-tool` after a passed round trip as complete, and `skipped-no-device` as
@@ -90,7 +95,7 @@ stop report instead of the application they now have.
 
 If the round trip fails, decide which kind of failure it is before you route. The proof
 subagent can repair only project-owned processes, ports, and request options, and it can
-make the credential write that its Step 4 names for `api_key_loadable_by_app`. A failure caused
+run the credential command that `verify:api_key_loadable_by_app` names. A failure caused
 by a source, configuration, dependency, or tracked-file change is a defect in the new work.
 
 Retry the proof subagent only for a project-owned process, port, request-option, or
@@ -140,8 +145,8 @@ way `implementation/build-and-validate` does: pause and ask the developer, add t
 the handoff if they allow it, and use the route-out rules below if they decline. For a
 protected file, record their answer with `--authorize --unplanned` and run the audit again
 first. Then spawn a fresh repair worker with this repair handoff, not the whole-plan
-implementation handoff: the plan, the proof evidence, the protected path list, and the
-authorized list from that audit.
+implementation handoff: the plan, the proof evidence, the protected path list, the
+authorized list from that audit, and the developer's answer on the Skills install.
 
 Run the protected-path audit again after validation passes. Continue only if its result
 starts with `Status: passed`.
@@ -161,7 +166,7 @@ proof cycles, use the route-out rules below.
 
 Route out only when the failure is not yours to fix, when the same proof still fails after
 three attempts, or when no evidence of the round trip can be produced. In those cases run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read stopped/run-failed`. The stack is supported:
+`npx --prefer-offline --yes copilotkit@4.23.0 onboard read stopped/run-failed`. The stack is supported:
 this run did not finish, which is a different ending and a different report. All three are
 about the round trip itself. A round trip that proved is not one of them, whatever failed
 after it.
@@ -172,7 +177,7 @@ friction command follows the telemetry setting the developer already chose, so i
 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.23.0 onboard friction --phase stop --category <slug> --message "<sentences>"
 ```
 
 `--message` takes one or two sentences: the step you stopped at and what stopped it.

package/onboarding/prompts/research/gather.md

@@ -1,8 +1,9 @@
 # Gather the evidence this run routes on
 
-Sign-in is settled. This phase inspects the project and proves what this environment can
-drive. Do not change application code here, and do not ask the developer a setup question
-yet: every read-only investigation finishes first.
+The developer can still be signing in. Keep reading the login process as
+`authenticate/start` says while this phase runs. This phase inspects the project and proves
+what this environment can drive. Do not change application code here, and do not ask the
+developer a setup question yet: every read-only investigation finishes first.
 
 ## How to wait for a subagent
 
@@ -44,7 +45,7 @@ Before you end your turn to wait for the developer where the prompt states no de
 report the pause:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.21.0 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.23.0 onboard checkpoint --phase awaiting-developer
 ```
 
 When the answer or the result arrives, continue from the step that paused. Do not read an
@@ -64,7 +65,7 @@ Both research subagents failing means this harness has no working subagent at al
 is worth recording once:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.21.0 onboard checkpoint --phase delegation-unavailable
+npx --prefer-offline --yes copilotkit@4.23.0 onboard checkpoint --phase delegation-unavailable
 ```
 
 Then say once, in your own words, that this environment has no working subagents, so you
@@ -77,7 +78,7 @@ Before you ask the developer any setup question, finish every read-only investig
 preflight check in this section.
 
 Prepare two research assignments. Give each research subagent one assignment. Tell it to run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read subagent/inspect-repository` first and follow the
+`npx --prefer-offline --yes copilotkit@4.23.0 onboard read subagent/inspect-repository` 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. Require only its assigned packet.
@@ -91,8 +92,8 @@ Start both research subagents in parallel:
 The research is under way. Continue to the surface-control preflight while it runs:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.21.0 onboard read research/preflight
+npx --prefer-offline --yes copilotkit@4.23.0 onboard read research/preflight
 ```
 
 If inspection stops onboarding, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read stopped/run-failed`.
+`npx --prefer-offline --yes copilotkit@4.23.0 onboard read stopped/run-failed`.

package/onboarding/prompts/research/merge.md

@@ -45,8 +45,11 @@ environment row. If either packet gives no match or more than one match, send ea
 worker a focused directory check. Continue only when both workers return the same one target
 app directory. Both results must start with `Status: passed`. Otherwise, use the stop route.
 
-When both research results are merged, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read research/route`.
+Read the next step only after `login --json` has emitted `type: completed`. If sign-in still
+waits on the developer, end your turn and wait for it: that is a pause.
+
+When both research results are merged and sign-in is done, run
+`npx --prefer-offline --yes copilotkit@4.23.0 onboard read research/route`.
 
 If inspection stops onboarding, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read stopped/run-failed`.
+`npx --prefer-offline --yes copilotkit@4.23.0 onboard read stopped/run-failed`.

package/onboarding/prompts/research/preflight.md

@@ -27,8 +27,8 @@ Where the device probe found no booted device, that is the whole finding.
 Then merge the research:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.21.0 onboard read research/merge
+npx --prefer-offline --yes copilotkit@4.23.0 onboard read research/merge
 ```
 
 If inspection stops onboarding, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read stopped/run-failed`.
+`npx --prefer-offline --yes copilotkit@4.23.0 onboard read stopped/run-failed`.

package/onboarding/prompts/research/route.md

@@ -9,7 +9,7 @@ sends the run down one path.
 Before you route on, run this from the target app directory:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.21.0 onboard protect
+npx --prefer-offline --yes copilotkit@4.23.0 onboard protect
 ```
 
 It reads the working tree itself, records every changed or untracked path with a digest,
@@ -31,28 +31,36 @@ route at the end of this prompt.
 
 ## Route a named Channel before the findings
 
-The prompt the developer copied names the docs page it came from. A Slack or Teams docs
-page names the surface this run is for. So does a developer who has already said Slack or
-Microsoft Teams. Either one settles the frontend.
+The prompt the developer copied names the docs page it came from. A CopilotKit docs page
+under `/channels`, `/slack`, or `/teams` names a Channel. So does a run that follows the
+`channels-setup` skill, which `copilotkit channels setup` installs in the project. The
+prompt that command prints names no page. So does a developer who asks for a Channel,
+Slack, or Microsoft Teams in their own words. Any one of these settles the frontend.
 
-Record that docs page and give it to every later node and subagent. The copied prompt is
-the only carrier of the surface the developer wants, and no flag states it.
+Record that page or request and give it to every later node and subagent. No flag states
+the surface the developer wants, so this record is its only carrier.
 
-On either, run this before you read the three findings below, and without asking the
-purpose question:
+On any one of them, run this before you read the three findings below, and without asking
+the purpose question:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.21.0 onboard read feature/channels/start
+npx --prefer-offline --yes copilotkit@4.23.0 onboard read feature/channels/start
 ```
 
-Name the provider to that node so it does not ask again. A Slack page names Slack. A Teams
-page names Teams.
+Name the provider to that node so it does not ask again. A `/slack` page names Slack. A
+`/teams` page names Teams. A request that names no provider leaves that question to the
+node.
 
 Take this route whatever the three findings prove. An agent, a frontend and a CopilotKit
 integration are a valid start for a Channel, not a reason to convert the application: the
 run keeps that code as it is and wires a managed Channel onto it. Do not send a Channel
 request to the conversion route.
 
+Nothing else names a Channel. A project with its own channels, bots, or coworkers does not
+ask for one. A repository the developer asked you to clone does not ask for one either.
+Without one of the requests above, read the findings below. `frontend/plan` offers Slack
+and Microsoft Teams when the project has no frontend.
+
 ## What the merged findings must contain
 
 If a repository file exists, each finding must cite it. For an empty project, the subagents
@@ -78,10 +86,10 @@ directory behind each answer. Read it as a proposal.
 - `unmatched` names the dependencies it did not place. Use them as evidence for what the
   project runs.
 
-Detection proposes and you dispose. Keep the documentation-gap exception exactly as it is:
-an agent framework outside this set that speaks AG-UI is still yours to recognize and
-route to best effort. Where your reading disagrees with the proposal, record your own
-answer and say that the two disagreed.
+Detection proposes and you dispose. An agent outside this set that already speaks AG-UI
+is still yours to recognize. The framework question has a route for it, so record in the
+findings that the agent speaks AG-UI and cite the file that proves it. Where your reading
+disagrees with the proposal, record your own answer and say that the two disagreed.
 
 ## Route on the merged findings
 
@@ -97,7 +105,7 @@ settle these three from your own reading of the project. Each one comes from the
 packets or it is not proved.
 
 If all three are proved, prove the live starting state before any project file changes. Run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read proof/oss-baseline`.
+`npx --prefer-offline --yes copilotkit@4.23.0 onboard read proof/oss-baseline`.
 
 Route there before you ask the developer anything else. The questions after this prompt
 select a framework and a frontend that the findings already name, so a developer who
@@ -110,7 +118,7 @@ developer nor the repository findings prove what the project is for, ask one gui
 question about the user outcome. This asks what the developer wants to build before you
 select a framework. Give two or three short examples. Record the answer and give it to
 each later subagent. Then run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read credentials/plan`.
+`npx --prefer-offline --yes copilotkit@4.23.0 onboard read credentials/plan`.
 
 Do not ask that question on the route above. A project carrying all three states its
 purpose in the application it already serves.
@@ -124,5 +132,5 @@ A purpose question here names a domain before that choice.
 Take the same read named above without asking.
 
 If authentication, inspection, or the baseline capture stops onboarding, run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read stopped/run-failed`. None of them says anything
+`npx --prefer-offline --yes copilotkit@4.23.0 onboard read stopped/run-failed`. None of them says anything
 about whether this project's stack is supported, which is not yet known at this point.

package/onboarding/prompts/starter/clone.md

@@ -55,7 +55,7 @@ the derived name.
 Only if the developer asks for an existing project, or asks to see the projects they have,
 read the choices:
 
-`npx --prefer-offline --yes copilotkit@4.21.0 project list --json`
+`npx --prefer-offline --yes copilotkit@4.23.0 project list --json`
 
 Then ask which one to use. Do not order the projects by creation time. If the developer
 already gave this answer, do not ask again. Do not read a secret value. Do not show or
@@ -78,18 +78,19 @@ way bills a project nobody chose.
 
 ## Clone the starter
 
-Run the command from the parent directory. Do not inspect another entry in the parent
-directory. Replace each placeholder with the recorded value. Do not run a placeholder as
-a shell argument. If the directory name holds a space, put it in double quotes.
+Run the command in one step, from any directory. `--dir` names the target, so the app
+lands there whatever directory the shell is in. Do not change directory before the command.
+Do not inspect another entry in the parent directory. Replace each placeholder with the
+recorded value. Do not run a placeholder as a shell argument. If the path holds a space,
+put it in double quotes.
 
-`npx --prefer-offline --yes copilotkit@4.21.0 init --name <directory-name> --framework <framework-id> --channel none --no-banner --no-key-prompt --create <name> --install`
+`npx --prefer-offline --yes copilotkit@4.23.0 init --dir <absolute-target-directory> --framework <framework-id> --channel none --no-banner --no-key-prompt --create <name> --install`
 
-`--name` is always the target directory name derived above, because `init` creates the
-app at `<parent>/<name>`. Any other value puts the app in a new folder beside the target,
-outside the directory this run is bound to. Pass the confirmed project name to `--create`
-only. If the developer names an existing project,
-use `--project <slug-or-id>` instead of `--create <name>`. If the developer asked to skip
-the dependency install, use
+`--dir` is always the absolute path of the target directory. `init` builds the app in that
+directory and gives the app the directory's name. Do not add `--name`: `init` refuses
+`--name` together with `--dir`. Pass the confirmed project name to `--create` only. If the
+developer names an existing project, use `--project <slug-or-id>` instead of
+`--create <name>`. If the developer asked to skip the dependency install, use
 `--no-install` instead of `--install`. Do not wait for an interactive prompt. Pass every
 answer as a flag. `--no-key-prompt` stops `init` from asking for a model key. The `init`
 output still names each missing key as `Set <VARIABLE> in .env`.
@@ -143,7 +144,7 @@ When you ask, name each variable and the file it goes in, and say that the run c
 when they reply or resume this session. Then report the pause and end your turn:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.21.0 onboard checkpoint --phase awaiting-model-credential
+npx --prefer-offline --yes copilotkit@4.23.0 onboard checkpoint --phase awaiting-model-credential
 ```
 
 This is a pause, not a stop. Do not send a stop report, and do not take a stop route.
@@ -154,10 +155,10 @@ call.
 
 If no credential is missing, report no pause and continue.
 
-Then run `npx --prefer-offline --yes copilotkit@4.21.0 onboard read proof/round-trip`.
+Then run `npx --prefer-offline --yes copilotkit@4.23.0 onboard read proof/round-trip`.
 
 If the command fails, report its exact error and do not claim that the starter is ready.
 Then run
-`npx --prefer-offline --yes copilotkit@4.21.0 onboard read stopped/run-failed`. The starter is one this
+`npx --prefer-offline --yes copilotkit@4.23.0 onboard read stopped/run-failed`. The starter is one this
 graph ships and the stack was chosen from its own supported list, so a command that
 returned an error is a run that broke, not a setup this release does not support.

package/onboarding/prompts/stopped/run-failed.md

@@ -41,7 +41,7 @@ put to them, stop here and send the report below.
 If they approve it, make that one fix and nothing else. Then come back into this run:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.21.0 onboard resume --message "<approval>"
+npx --prefer-offline --yes copilotkit@4.23.0 onboard resume --message "<approval>"
 ```
 
 Put the developer's approval in `--message`, in one or two sentences: the fix they
@@ -64,7 +64,7 @@ Send one short report. The friction command follows the telemetry setting the de
 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.23.0 onboard friction --phase stop --category <slug> --message "<sentences>"
 ```
 
 `--message` takes one or two sentences: the step you stopped at and what stopped

package/onboarding/prompts/subagent/create-plan.md

@@ -12,6 +12,13 @@ the documentation example differs from that purpose, the project wins.
 Read only inside the project directory. Answer an API question from the documentation
 URLs you were given, not from another checkout on this machine.
 
+The main coding agent also gives you the findings of the framework route, such as how the
+agent connects or whether a subclass needs a `clone()` override. Some of those rules, such
+as the `clone()` override, are on no documentation page. Use the findings of the framework
+route as they are. Do not confirm them again from the source of an installed package. Read
+the project's own code only to apply them, for example to find the fields that a `clone()`
+override copies.
+
 List the required credential variable names. Do not read or return credential values.
 Preserve each agent or frontend that already exists.
 
@@ -84,24 +91,32 @@ reference naming hosts that route nothing, and it requires the platform URLs the
 documentation calls optional. A run that reads that reference configures the runtime
 against a dead host, and the failure arrives as an empty-body 404 with no cause named.
 
-If any `@copilotkit/*` dependency is below 1.70.0, plan to upgrade every `@copilotkit/*`
-dependency to its latest published version. Packages that share a version line must end
-on the same version. Never force a package onto a version line it does not publish on.
-Resolve each latest version at run time rather than from a remembered version number.
-Where every `@copilotkit/*` dependency already meets that floor, plan no dependency
-change.
+Ask the CLI for the dependency upgrade, from the target directory:
 
-The floor is 1.70.0 because the runtime resolves managed Intelligence entitlement
-authority from that version. A runtime below it reports its license from a self-hosted
-token alone. A managed project holds no such token, so the threads drawer this conversion
-adds lists nothing even after every command-line check passes.
+```text
+npx --prefer-offline --yes copilotkit@4.23.0 onboard upgrade-plan --json
+```
 
-The upgrade moves more than the `@copilotkit/*` namespace. Intersect the dependencies the
-app declares directly with what the target `@copilotkit/*` versions require, and name in the
-plan every one whose declared range excludes the version the target needs, with the version
-it moves to. The `@ag-ui/*` packages are the CopilotKit protocol layer, on their own version
-line, so they are the ones this meets most often, but the rule is the intersection rather
-than that namespace.
+It reads the installed tree and the registry. Read `status`:
+
+- `none-needed`: every `@copilotkit/*` package already meets the 1.70.0 floor. Plan no
+  dependency change.
+- `upgrade`: plan `moves` as their own step, before the Intelligence runtime wiring. Each
+  move names the app, the declared range, and the exact version to declare. A
+  `required-by` move is a direct dependency the target CopilotKit version needs at a
+  version the app's range excludes. Plan to re-run the recorded baseline checks right
+  after the upgrade. The revert is `onboard upgrade-plan --revert`, which restores the
+  manifests and lockfiles the command snapshotted.
+- `blocked`: `blockedBy` names a package whose own declaration excludes the target.
+  Return `Status: blocked` and name `unsupported/no-validated-path` as the outcome.
+- `undetermined`: the CLI did not reach the registry. Return `Status: blocked` with the
+  `detail`.
+
+The floor is 1.70.0 because the runtime resolves managed Intelligence entitlement
+authority from that version. Below it, the Intelligence features stay dark with no error.
+An exact pin is usually deliberate, so each move is a step the developer approves, not a
+repair the run invents halfway through. Where the developer needs a pin held, return
+`Status: blocked` and name `unsupported/no-validated-path` as the outcome.
 
 A package the plan adds that a `@copilotkit/*` or `@ag-ui/*` package also depends on, such
 as `zod`, takes the version that tree resolves, not the latest published one. A peer range
@@ -110,29 +125,7 @@ does not settle it. `@copilotkit/react-core@1.75.0` declares `zod >=3.25`, while
 Read the range with `npm view @ag-ui/core@<version> dependencies`, for the `@ag-ui/core`
 version the target `@copilotkit/*` release requires, and plan the latest version inside it.
 Where the project already depends on that package, keep its version if that tree accepts
-it. Otherwise name the move as above.
-
-The intersection includes what a `@copilotkit/*` package on its own version line declares
-about the `1.x` line. `@copilotkit/angular` is the one that has this, and its declaration
-is materialized at publish time rather than written in the repository, so read it from the
-registry rather than from any checkout. Where it cannot be satisfied by the version the
-floor requires, there is no upgrade to plan: return `Status: blocked` and name
-`unsupported/no-validated-path` as the outcome.
-
-An exact pin is usually deliberate. Naming the move here is what makes it a step the
-developer approved rather than a repair the run invents halfway through. Do not move a pin
-the developer did not approve moving. Where the developer needs one held, return
-`Status: blocked` and name `unsupported/no-validated-path` as the outcome. The upgrade
-step's revert is the way back.
-
-Name the exact version the target requires. A caret does not stand in for it below `0.1.0`:
-`^0.0.59` admits only `0.0.59`, so a pin rewritten that way is the same pin under a
-different spelling, and it breaks again as soon as CopilotKit moves to `0.0.60`.
-
-Plan the upgrade as its own step before the Intelligence runtime wiring, and plan to
-re-run the recorded baseline checks immediately after it. Name the revert: restore the
-manifest and lockfile to their recorded state and report the break, rather than wiring
-Intelligence onto a baseline the upgrade broke.
+it. Otherwise name the move in the plan, with the version it moves to.
 
 Where the SDK requires an application-level value that the repository cannot supply, such
 as an end-user identity for threads, use one clearly marked local placeholder and name what
@@ -183,7 +176,7 @@ here is work the developer did not ask for.
 Plan the threads drawer itself: add it from the selected drawer page, where this frontend
 does not already render one. Where this journey's frontend framework ships no threads
 drawer -- React Native --, plan that the thread is proved by
-`npx --prefer-offline --yes copilotkit@4.21.0 verify --round-trip`, which needs no browser. Do not plan a
+`npx --prefer-offline --yes copilotkit@4.23.0 verify --round-trip`, which needs no browser. Do not plan a
 step that opens the managed Intelligence dashboard.
 
 ## Name the files the run writes itself

package/onboarding/prompts/subagent/implement-and-validate.md

@@ -110,44 +110,32 @@ upgrade, Intelligence runtime wiring, and the approved threads drawer: the drawe
 in that list because the approved plan already named it, not because this step invents a
 new one. After wiring, run the recorded baseline checks and report any regression.
 
-Where the plan names a CopilotKit dependency upgrade:
-
-1. Apply the planned CopilotKit dependency upgrade before you wire Intelligence.
-2. Report each `@copilotkit/*` version before and after the upgrade.
-3. Prove that every dependency the app declares directly resolves to exactly one version in
-   the installed tree.
-4. Then re-run the recorded baseline checks.
-
-The package manager does not fail on this. Where the app pins a package exactly and the
-upgraded CopilotKit needs a different version of it, npm keeps the pin at the top of the
-tree and nests the other copy, so the install exits zero and `--dry-run` shows nothing.
-Two copies of a package that carries types fail the type check in some field that has
-nothing to do with either version, so the developer reads it as a bug in their own code.
-Read the installed tree, not the manifest: ask the package manager how many versions of
-each direct dependency it resolved, with `npm ls <name>`, `pnpm why <name>`, or the
-equivalent for the lockfile this project uses. Direct dependencies are a short list, and
-they are the ones whose duplicate breaks a build, so this catches `react`, `zod`,
-`graphql`, and the next protocol package as well as `@ag-ui/*`.
-
-`@copilotkit/*` counts here, not only third-party packages. `@copilotkit/angular`
-publishes on a version line of its own and declares a `@copilotkit/core` chosen when that
-Angular release was cut, so the upgrade can install one `@copilotkit/core` while the
-Angular package demands another. That is the case this catches most expensively, because
-it fails in the threads drawer rather than at the install.
-
-If one of them resolves to more than one version, restore the manifest and lockfile to
-their recorded state, leave Intelligence unwired, and report which package resolved to more
-than one version, which versions, and which declared range held the top of the tree. Then
-end your turn. Do not wire Intelligence onto a tree carrying two copies of a package.
-
-Never add an `overrides`, `resolutions`, or `pnpm.overrides` block to collapse the two
-copies. It forces a version the developer did not approve onto their whole tree, and it
-turns a reportable mismatch between two published packages into a local workaround nobody
-else can see.
-
-If the baseline regresses, restore the manifest and lockfile to their recorded state, leave
-Intelligence unwired, and report the regression with the failing check. Then end your
-turn. Where the plan names no dependency change, report that the installed versions met
+Where the plan names a CopilotKit dependency upgrade, apply its moves before you wire
+Intelligence: declare each exact version in its app's manifest, then install with the
+project's package manager. Then check the installed tree:
+
+```text
+npx --prefer-offline --yes copilotkit@4.23.0 onboard upgrade-plan --check --json
+```
+
+`single` means every direct dependency resolved to one version. `duplicates` names each
+package that resolved to more than one, and the versions. `no-tree` means the apps in
+`unread` have no `node_modules` to read. Install first. Under Yarn Plug'n'Play, ask
+`yarn why <name>` for each direct dependency. The install does not fail on this. npm
+keeps a pin at the top of the tree and nests the copy the upgrade needs. Two copies of a
+package that carries types then fail the type check in an unrelated field. Then re-run
+the recorded baseline checks.
+
+If the check finds duplicates or the baseline regresses, put the manifests and lockfiles
+back, leave Intelligence unwired, and report what failed:
+
+```text
+npx --prefer-offline --yes copilotkit@4.23.0 onboard upgrade-plan --revert --json
+```
+
+Then end your turn. Never add an `overrides`, `resolutions`, or `pnpm.overrides` block to
+collapse two copies. It forces a version the developer did not approve onto their whole
+tree. Where the plan names no dependency change, report that the installed versions met
 the floor.
 
 When the documentation uses the framework's scaffolder,
@@ -181,6 +169,38 @@ constructor for it, and never write an id the plan does not name: a selector poi
 id the platform does not hold answers `LEARNING_CONTAINER_NOT_FOUND` on every thread create.
 Where the plan names no container, write no selector.
 
+## Install the CopilotKit Skills
+
+The main coding agent gives you the developer's answer on the Skills install. Where the
+whole-plan implementation handoff carries no answer, read the approved plan. Approving the
+plan without a word on the Skills approves the install. A repair handoff that carries no
+Skills answer never installs them.
+
+Where `.agents/skills` already holds the CopilotKit skills, do not install them again.
+Report that they are in place.
+
+Install the Skills only when the developer approved them. Where the developer declined
+them, do not install them, and do not call that a change from the plan. Report in the
+Validation section that the developer declined them.
+
+Install them after you run the full validation list. Tell the developer what the skills
+install writes into this project before you run it: a `.agents/skills` directory holding
+one folder per CopilotKit skill, linked into `.claude/skills`. Both sit in the working tree,
+so the install shows up in `git status` and can land in a commit. You cannot know whether
+this project keeps those directories in version control, so name them before you write them
+rather than after.
+
+Then run `npx skills add CopilotKit/CopilotKit/skills -y` in the target app directory.
+
+The plan names both directories under `Files the run writes itself`, so they are not
+departures. Name them under Files changed. Do not register an MCP server: the Skills read
+the CopilotKit documentation without one.
+
+Check whether the install succeeded, and record the command result in the Validation
+section. A failed install does not change your status. Report it and continue.
+
+## Report the result
+
 Report the runtime constructor you wrote. Name whether it passes `intelligence` or
 `runner`, and whether it carries `getLearningContainerId`, with the id it returns.
 A runtime built with `runner` is the SSE runtime and never reads the credential,

package/onboarding/prompts/subagent/inspect-repository.md

@@ -7,7 +7,7 @@ Work only on the packet you were assigned. Inspect the repository without changi
 Run this first, from the target project directory:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.21.0 onboard inspect --json
+npx --prefer-offline --yes copilotkit@4.23.0 onboard inspect --json
 ```
 
 It answers the deterministic half of both packets exactly, from the same code
@@ -50,6 +50,9 @@ Find evidence for:
 - whether the target project directory contains any entries
 - any existing agent framework and frontend, confirming or contradicting the
   `detection` block the CLI proposed
+- for an existing agent in no listed framework, whether it speaks AG-UI: a class that
+  extends `AbstractAgent` and implements `run`, or an endpoint that streams AG-UI events.
+  Cite the file
 - current CopilotKit integration and configuration
 - authentication boundaries
 - initial changed and untracked paths, without file contents

package/onboarding/prompts/subagent/prove-oss-baseline.md

@@ -32,7 +32,7 @@ Prove the live runtime in this order:
 4. Confirm from project files that the runtime constructor passes a `runner` option rather
    than an `intelligence` option. A package, import, project file, or key is not use proof.
 5. Run
-   `npx --prefer-offline --yes copilotkit@4.21.0 verify --expect-runtime oss --round-trip --agent <expected-agent-id> --json`,
+   `npx --prefer-offline --yes copilotkit@4.23.0 verify --expect-runtime oss --round-trip --agent <expected-agent-id> --json`,
    with the runtime URL or auth header options that this project needs. Require exit zero
    and the JSON `ok` field to be `true`.
 6. Drive one real request through the existing frontend, CopilotKit runtime, and expected