copilotkit 4.27.0 → 4.29.0

package/onboarding/prompts/starter/clone.md

@@ -1,6 +1,6 @@
 # Clone a starter
 
-First run `npx --prefer-offline --yes copilotkit@4.27.0 onboard setup-answers`. It prints the answers that
+First run `npx --prefer-offline --yes copilotkit@4.29.0 onboard setup-answers`. It prints the answers that
 `setup/questions` recorded, even after this conversation lost them: `framework`, `frontend`,
 `vendor`, `project`, `key`, and on the local route `learning`. Take every "recorded" answer
 below from the record, or this conversation when the record lacks it. Do not ask a question
@@ -22,7 +22,7 @@ project to use, or to open the coding agent in a new empty folder.
 Before you end your turn to wait for the developer, report the pause:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase awaiting-developer --about existing-folder
 ```
 
 Match the selected agent framework and frontend to this table:
@@ -68,7 +68,7 @@ again.
 
 If neither the record nor this conversation holds a project answer, ask here. If the developer did not name a
 project, create one for the app being cloned. This directory is new, so no existing project is already its own: take the project
-name from the target directory name derived above, and ask as the setup message does:
+name from the target directory name derived above, and ask as the options view of `onboard setup-message` does:
 "Project: **new project "<name>"**", then "Other: another name · a project you already
 have". Do not list the projects in the organization. If no developer answers, use
 the derived name.
@@ -76,7 +76,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.27.0 project list --json`
+`npx --prefer-offline --yes copilotkit@4.29.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
@@ -85,7 +85,7 @@ store a secret value.
 Before you end your turn to wait for the developer, report the pause:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase awaiting-developer --about project-name
 ```
 
 ## Ask where the model credential lives
@@ -119,7 +119,7 @@ stops the clone. Pass the new file with `--model-key-file`, as for any other key
 Before you end your turn to wait for the developer, report the pause:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard checkpoint --phase awaiting-model-credential
+npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase awaiting-model-credential
 ```
 
 A path the developer names is theirs to give, including one outside the project. A path
@@ -132,7 +132,7 @@ This route skips the plan step that records the path, so record it here, once, b
 the clone:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard classify --starting-state <starting-state> --agent-framework <agent-framework> --frontend <frontend> --model-vendor <model-vendor> --model-vendor-choice <model-vendor-choice>
+npx --prefer-offline --yes copilotkit@4.29.0 onboard classify --starting-state <starting-state> --agent-framework <agent-framework> --frontend <frontend> --model-vendor <model-vendor> --model-vendor-choice <model-vendor-choice>
 ```
 
 - `<starting-state>`: the starting state the research recorded, usually `empty`.
@@ -155,13 +155,15 @@ Do not inspect another entry in the parent directory. Replace each placeholder w
 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.27.0 init --dir <absolute-target-directory> --framework <framework-id> --channel none --no-banner --no-key-prompt --create <name> --install`
+`npx --prefer-offline --yes copilotkit@4.29.0 init --dir <absolute-target-directory> --framework <framework-id> --channel none --no-banner --no-key-prompt --create <name> --install`
 
 `--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
+`--create <name>`. If `init` says that the account already has a project with that name,
+ask the developer for a new name, or which of their projects to use. Do not select the
+existing project until they name it. 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`.
@@ -176,23 +178,23 @@ the developer for the right path, or run the command again without the flag.
 Before you end your turn to wait for the developer, report the pause:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard checkpoint --phase awaiting-model-credential
+npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase awaiting-model-credential
 ```
 
 If you cannot pass the key file to `init`, for example because a sandbox refuses the path,
 clone without `--model-key-file`. Then copy the key from `<target>` with one command:
-`cd <target> && npx --prefer-offline --yes copilotkit@4.27.0 onboard credentials --model-key <VARIABLE> --env-path <key-file> --copy-to <env file> --json`.
+`cd <target> && npx --prefer-offline --yes copilotkit@4.29.0 onboard credentials --model-key <VARIABLE> --env-path <key-file> --copy-to <env file> --json`.
 `<env file>` is `.env`, or `agent/.env` for the Microsoft Agent Framework Python starter.
 The command writes the key into that file without printing it. If the
 command is refused too, ask the developer to run it. Give them exactly this one line:
-`! cd <target> && npx --prefer-offline --yes copilotkit@4.27.0 onboard credentials --model-key <VARIABLE> --env-path <key-file> --copy-to <env file>`.
+`! cd <target> && npx --prefer-offline --yes copilotkit@4.29.0 onboard credentials --model-key <VARIABLE> --env-path <key-file> --copy-to <env file>`.
 The command needs no input. Without `!`, they run the same command in a terminal.
 Do not write a `sed`, `grep`, or `cat` command to copy the key.
 
 Before you end your turn to wait for the developer, report the pause:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard checkpoint --phase awaiting-model-credential
+npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase awaiting-model-credential
 ```
 
 ### For a recorded local choice
@@ -202,7 +204,7 @@ command instead of the hosted command above. Do not ask the project questions ab
 Local evaluation creates its own empty project, and `init --local` refuses `--create` and
 `--project`.
 
-`npx --prefer-offline --yes copilotkit@4.27.0 init --dir <absolute-target-directory> --framework <framework-id> --channel none --no-banner --no-key-prompt --local --defer-model --install`
+`npx --prefer-offline --yes copilotkit@4.29.0 init --dir <absolute-target-directory> --framework <framework-id> --channel none --no-banner --no-key-prompt --local --defer-model --install`
 
 Use the `learning` answer from the record, or this conversation. Use the default only when
 neither holds one.
@@ -212,12 +214,12 @@ file. The CLI selects the latest stable release. If the developer gave a candida
 manifest for release testing, add `--candidate <manifest.json>`. Otherwise, do not add it.
 The `--dir`, `--no-install` and `--model-key-file` rules above apply here too.
 
-Before `init`, run `npx --prefer-offline --yes copilotkit@4.27.0 onboard local-terms --json`. If `accepted`
+Before `init`, run `npx --prefer-offline --yes copilotkit@4.29.0 onboard local-terms --json`. If `accepted`
 is false, pause here. Give the developer this exact command to run in their own terminal:
-`npx --prefer-offline --yes copilotkit@4.27.0 local accept-terms`. Never accept the agreement yourself.
+`npx --prefer-offline --yes copilotkit@4.29.0 local accept-terms`. Never accept the agreement yourself.
 Report the pause with
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard checkpoint --phase awaiting-developer`, end your turn,
-and wait for "done". Then run `local-terms` again, and continue only when `accepted` is
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase awaiting-developer --about local-terms`, end your
+turn, and wait for "done". Then run `local-terms` again, and continue only when `accepted` is
 true. A local command that fails with `eula_acceptance_required` comes back to this step.
 
 For `learning.guided`, keep `--defer-model`.
@@ -226,7 +228,7 @@ After `init` reports the stack ready:
 Ask the developer to run this command in their own terminal window, in `<target>`:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 local setup
+npx --prefer-offline --yes copilotkit@4.29.0 local setup
 ```
 
 Do not give it as a `!` line, and do not run it yourself. Its guided model prompt needs a
@@ -235,9 +237,9 @@ changes nothing. The prompt asks for the model and its key, and it saves them pr
 On a running stack, it restarts only Learning. Do not ask for a model file.
 
 Say that the run continues when they reply or resume this session. Report the pause with
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard checkpoint --phase awaiting-model-credential`, end your
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase awaiting-model-credential`, end your
 turn, and wait. When the developer replies, run
-`npx --prefer-offline --yes copilotkit@4.27.0 local status --json` from `<target>` and read `learning.configuration`.
+`npx --prefer-offline --yes copilotkit@4.29.0 local status --json` from `<target>` and read `learning.configuration`.
 
 The command installs the local stack, then connects the starter to it. It writes the
 gitignored `.copilotkit/local.json` stack reference and `.copilotkit/project.json` with the
@@ -275,7 +277,7 @@ later release, and offer the Built-in CopilotKit agent if they need them now.
 2. For an OpenAI-compatible provider, set `COPILOTKIT_AGENT_MODEL` to
    `openai:<vendor.modelId>`, and `OPENAI_BASE_URL` to `vendor.baseUrl`.
 3. If the developer named a key file, copy the key with the `onboard credentials
-   --model-key <VARIABLE> --env-path <key-file> --copy-to <env file> --json` command above,
+--model-key <VARIABLE> --env-path <key-file> --copy-to <env file> --json` command above,
    with the recorded vendor's variable. Otherwise the next section pauses for it.
 
 For the Microsoft Agent Framework .NET starter, set these values with
@@ -299,7 +301,15 @@ grep -c '^<VARIABLE>=.' <target>/.env
 `1` means the variable holds a value. `0` means it is empty or absent. The command prints
 a count and never the value.
 
-If a variable is empty, ask the developer to add it to `<target>/.env` themselves.
+If a variable is empty, run
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard credentials --model-key <VARIABLE> --json` from
+`<target>`, and show the developer `question.ask` word for word. It names the file by its
+full path and the line to add. If they reply with the path of a file that holds the key, run
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard credentials --model-key <VARIABLE> --env-path <file> --copy-to <question.envFile> --json`
+from `<target>`. Ask nothing else first. Quote a path that holds a space. The command copies
+the key without printing it. When it reports `ready`, the key is in `question.envFile`. Run
+the check above again, and continue. Follow this paragraph, not the packet's `next`, which is
+written for an existing app that copies the key only after its plan.
 
 A local server needs no key. That is a server such as Ollama or LM Studio, with
 `OPENAI_BASE_URL` on `localhost`, `127.0.0.1` or `::1` in `<target>/.env`. A local base
@@ -313,18 +323,17 @@ The two Microsoft Agent Framework starters keep their key outside `<target>/.env
 
 - For the Python starter, a key file passed to `init` fills `<target>/agent/.env`, and the
   output says so. Otherwise, run the same check for `OPENAI_API_KEY` against
-  `<target>/agent/.env`. A missing file counts as `0`. If it is empty, ask the developer to
-  add it there themselves.
+  `<target>/agent/.env`. A missing file counts as `0`. If it is empty, ask as above, with
+  `--env-path agent/.env` added to the first command.
 - For the .NET starter, the key lives in `dotnet user-secrets`, and no check can read it
   without printing the value. Ask the developer to run
   `cd <target>/agent && dotnet user-secrets set OPENAI_API_KEY "<key>"` themselves, even
   if they named a key file.
 
-When you ask, name each variable and the file it goes in, and say that the run continues
-when they reply or resume this session. Then report the pause and end your turn:
+When you ask, say that the run continues when they reply or resume this session. Then report the pause and end your turn:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard checkpoint --phase awaiting-model-credential
+npx --prefer-offline --yes copilotkit@4.29.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.
@@ -340,7 +349,7 @@ Run this from `<target>`, with one `--model-key` for each variable. For the Micr
 Framework Python starter, add `--env-path agent/.env`. Skip it for the .NET starter.
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard credentials --model-key <VARIABLE> --json
+npx --prefer-offline --yes copilotkit@4.29.0 onboard credentials --model-key <VARIABLE> --json
 ```
 
 The command never prints a value. If `status` is `ready`, continue. Otherwise do what
@@ -353,7 +362,7 @@ works and the app's model does not: the vendor does not serve the model that
 names, or names another, change `COPILOTKIT_AGENT_MODEL` where `question.ask` says, and
 run the command again.
 
-Then run `npx --prefer-offline --yes copilotkit@4.27.0 onboard read proof/round-trip`.
+Then run `npx --prefer-offline --yes copilotkit@4.29.0 onboard read proof/round-trip`.
 
 If the local command fails, `init` keeps the cloned starter in `<target>`, and its error
 says whether it installed the starter's dependencies, or names the command that does. Do
@@ -366,14 +375,14 @@ available memory, or 40 GiB storage. Tell the developer what to change in Docker
 memory, pass on the amount the message names. Then report the pause and end your turn:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase awaiting-developer --about environment-fix
 ```
 
 When the developer says that Docker is ready, resume from `<target>` with the same model
 choice. If the run used a `--candidate`, add the same one:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 local setup --defer-model --json
+npx --prefer-offline --yes copilotkit@4.29.0 local setup --defer-model --json
 ```
 
 If the run used model settings, replace `--defer-model` with `--model-config <private-file>`.
@@ -381,7 +390,7 @@ Read blockers and the recorded failed step. Do not delete or recreate a failed s
 setup reports the stack ready, connect the starter from `<target>`:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 local connect --approve-connection --json
+npx --prefer-offline --yes copilotkit@4.29.0 local connect --approve-connection --json
 ```
 
 The connection writes `.copilotkit/local.json`, `.copilotkit/project.json`, and the local
@@ -391,6 +400,6 @@ take the route below.
 
 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.27.0 onboard read stopped/run-failed`. The starter is one this
+`npx --prefer-offline --yes copilotkit@4.29.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

@@ -42,13 +42,13 @@ put to them, stop here and send the report below.
 Before you end your turn to wait for the developer, report the pause:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase awaiting-developer --about scoped-fix
 ```
 
 If they approve it, make that one fix and nothing else. Then come back into this run:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard resume --message "<approval>"
+npx --prefer-offline --yes copilotkit@4.29.0 onboard resume --message "<approval>"
 ```
 
 Put the developer's approval in `--message`, in one or two sentences: the fix they
@@ -71,7 +71,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.27.0 onboard friction --phase stop --category <slug> --message "<sentences>"
+npx --prefer-offline --yes copilotkit@4.29.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

@@ -22,6 +22,19 @@ override copies.
 List the required credential variable names. Do not read or return credential values.
 Preserve each agent or frontend that already exists.
 
+## When a command is refused
+
+If you are a subagent and your harness refuses a command, return at once. Name the
+command, the directory you ran it from, and the refusal, and run nothing else. Do not wait
+for an approval: nobody sees it. The main coding agent runs the command itself and passes
+the result on. The one wait allowed is a harness escalation request that this brief tells
+you to make for a command. Make that request and wait for its answer.
+
+If your handoff holds a command's result, use it and do not run that command again.
+
+If you are the main coding agent and follow this brief yourself, this section is not for
+you. Do not return: handle a refused command as the run's other prompts say.
+
 ## What the existing agent's behavior is
 
 The existing agent's behavior is four things: its system prompt and instructions, its
@@ -32,8 +45,8 @@ Wiring is not behavior. The CopilotKit SDK dependency, the middleware the agent
 in, the runtime mount, the AG-UI connection, and a frontend that renders what the agent
 already returns are wiring. Plan them as ordinary steps.
 
-Every item on the behavior list is a change the developer has to approve, so it is a risky
-change. Where a step needs one, plan it as its own item, name the file and the exact change, and state that it
+Every item on the behavior list is a change the developer has to approve, so it goes under
+`Changes that need your approval`. Where a step needs one, plan it as its own item, name the file and the exact change, and state that it
 changes how the agent answers everywhere, not only in CopilotKit. A system prompt the
 developer wrote is the agent's behavior rather than a setting this run tunes until a
 component renders. Where the plan cannot be written without such a change and you cannot
@@ -97,7 +110,7 @@ against a dead host, and the failure arrives as an empty-body 404 with no cause
 Ask the CLI for the dependency upgrade, from the target directory:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard upgrade-plan --json
+npx --prefer-offline --yes copilotkit@4.29.0 onboard upgrade-plan --json
 ```
 
 It reads the installed tree and the registry. Read `status`:
@@ -118,7 +131,7 @@ It reads the installed tree and the registry. Read `status`:
 
 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 a move of one is a risky change the developer
+An exact pin is usually deliberate, so a move of one is a change 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.
 
@@ -185,33 +198,22 @@ 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.27.0 verify --round-trip`, which needs no browser. Do not plan a
+`npx --prefer-offline --yes copilotkit@4.29.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
 
 List these in the plan under `Files the run writes itself`, apart from the implementation
-steps. They are not steps, and they are not risky changes.
+steps. They are not steps, and they need no approval, except a file that is also under
+`Uncommitted files`: list that one under `Changes that need your approval` too.
 
 - Each `planChanges` entry from `onboard credentials`: the project key in the env file
   `environmentPath` names, the project record, and, where it lists `ignore-entries`, the
-  lines `project select` adds to `.gitignore` so that no credential env file can be
-  committed.
+  lines `project select` adds to `.gitignore` so that no credential env file and no
+  `.playwright-mcp/` browser snapshot can be committed.
 - `.copilotkit/proof/`, where the proof writes its evidence. It holds no source. The
   developer can delete it after the run.
 
-## Name the Skills install
-
-List the CopilotKit Skills install under `Skills install`, as its own line:
-`npx skills add CopilotKit/CopilotKit/skills -y`. It writes `.agents/skills/` and links it
-into `.claude/skills/`. End the line with "say **no Skills** to skip". Where
-`.agents/skills` already holds the CopilotKit skills, write `in place` instead, and plan no
-install.
-
-The Skills install is not a risky change. It adds agent-rule files only, holds no secret,
-changes nothing the app runs, and comes out with one delete. Do not list it under
-`Risky changes`.
-
 ## Scaffold an empty project
 
 This section applies when the starting state is `empty` and a step runs a scaffolder, such
@@ -243,7 +245,7 @@ the plan under `Uncommitted files`, one line each, with the path and one sentenc
 what the step changes there and why no other file will do. Keep the step in the plan.
 Adding a feature to an app the developer already built is the case this exists for: the
 option lives in a file they wrote, and on an app whose work was never committed that file
-has uncommitted changes. Each of those edits is a risky change, so the developer's answer
+has uncommitted changes. Each of those edits needs approval, so the developer's answer
 to the plan is their consent. The CLI records none.
 
 Installing or upgrading a package changes the manifest that lists it, such as `package.json`
@@ -288,15 +290,16 @@ Do not add compiler strictness the project did not have. Nothing later in the ru
 allowed to weaken type safety, so a stricter gate named here is one the run cannot get
 back out of.
 
-## Name the risky changes
+## Name the changes that need approval
 
 The run shows the plan to the developer and goes on to build it without waiting. It stops
-for an answer only when the plan makes a risky change. `onboard start` took a backup, so
-`onboard restore` undoes any other change the backup holds.
+for an answer only when the plan makes a change that needs approval. `onboard start` took a
+backup, so `onboard restore` undoes any other change the backup holds.
 
-List each risky change under `Risky changes`, one line each: the path or package, what the
-step does to it, and why the plan needs it. Write `none` when there is no risky change. A
-step makes a risky change when it:
+List each change that needs approval under `Changes that need your approval`, one line each: the path
+or package, what the step does to it, and why the plan needs it. Write `none` when there is
+none. List every other change under `What I will change`. A step makes a change that needs
+approval when it:
 
 - upgrades a dependency by a major version: a move whose `to` has a different major version
   than `from`, or a move of an exact pin
@@ -306,31 +309,51 @@ step makes a risky change when it:
 - changes a file that has uncommitted changes, from `Uncommitted files`
 - untracks a file or changes `.gitignore`, other than the lines under
   `Files the run writes itself`
-- writes to an env file the app already uses, other than the key line the developer
-  approved in the setup questions
+- writes to an env file the app already uses, other than the key line for the key file
+  the setup answers recorded
 - changes the existing agent's behavior, as `What the existing agent's behavior is`
   defines it
-- changes more than 10 files in all, the same limit the backup tripwire sets for deleted
-  files
+- changes more than 10 files in all. Count only the files the plan's own steps change. Do
+  not count a file the framework's own tooling writes by itself, such as the `AGENTS.md`
+  and `CLAUDE.md` that `next dev` writes, or a file under `Files the run writes itself`.
+  The limit is the same one the backup tripwire sets for deleted files
 - writes a file outside the project directory
 - changes the version of any CopilotKit dependency: an `@copilotkit/*` package or the
   `copilotkit` Python package, by any amount
 
-The plan is also risky when the backup does not hold every file: `backup.status` is
+A change the developer approved in the setup message needs no approval in the plan. The setup
+answers the main coding agent gives you show it: `envFile` is `approved` for the untrack or
+the `.gitignore` line that the env-file line named, and `alternative` for the key in the other
+env file. `uncommittedWrites: approved` allows the connection's writes to the env file and
+`.copilotkit/project.json`. Name each one under the notes instead.
+
+The plan also needs approval when the backup does not hold every file: `backup.status` is
 `partial` or `failed` in the `backup` result the main coding agent gives you. Name it as a
 line of its own. For `partial`, name each path in `backup.notHeld` with its `why`, which
 names the limit for a size skip, and the count in `backup.moreNotHeld` if any. For
 `failed`, name the cause in `backup.detail`, and that `onboard restore` puts nothing back.
-A step that changes one of those paths cannot be undone. `pending` is not risky: the CLI
+A step that changes one of those paths cannot be undone. `pending` needs no approval: the CLI
 takes the backup when the run moves to the chosen project, or at the next step, before any
 change. Say that in the plan.
 
-Do not leave a risky change out of the list to keep the run moving.
+Do not leave a change that needs approval out of the list to keep the run moving.
+
+## Return the result
 
 Gather what you need in as few commands as possible. Combine independent reads into one
 command rather than running them one at a time. Split a command only when its result decides
 what you run next.
 
+Before you return, record that you are returning:
+
+```text
+npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase subagent-returned --brief create-plan --result <ok|failed>
+```
+
+The Status line of your result decides the value. Pass `ok` only for `Status: passed`.
+Pass `failed` for `Status: failed` or `Status: blocked`. If your harness refuses this command, say so in your result and return
+anyway: the main coding agent records it.
+
 Start with `Status: passed`, `Status: failed`, or `Status: blocked`.
 Return the plan, the URLs that you read, and each documentation gap. End your turn after you return
 the findings to the main coding agent.

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

@@ -32,7 +32,7 @@ listen on a port, and cannot connect to localhost. It does not always fail: a pa
 install can wait with no output until you stop it. So request escalation on the first run,
 not after a hang or an error, for these commands:
 
-- the dependency install and the Skills install,
+- the dependency install,
 - the commands that start the app and agent servers,
 - HTTP requests to those servers.
 
@@ -89,6 +89,19 @@ approved paths that do not overwrite such a file, unless the plan lists it under
 running the scaffolder. Ask the main coding agent to revise credential setup when a
 required variable is missing. Do not provision another key to repair a scaffold overwrite.
 
+## When a command is refused
+
+If you are a subagent and your harness refuses a command, return at once. Name the
+command, the directory you ran it from, and the refusal, and run nothing else. Do not wait
+for an approval: nobody sees it. The main coding agent runs the command itself and passes
+the result on. The one wait allowed is a harness escalation request that this brief tells
+you to make for a command. Make that request and wait for its answer.
+
+If your handoff holds a command's result, use it and do not run that command again.
+
+If you are the main coding agent and follow this brief yourself, this section is not for
+you. Do not return: handle a refused command as the run's other prompts say.
+
 ## What the existing agent's behavior is
 
 The existing agent's behavior is four things: its system prompt and instructions, its
@@ -100,6 +113,13 @@ Wiring is not behavior. Add the CopilotKit SDK dependency, wrap the agent in the
 middleware, mount the runtime, connect AG-UI, and render what the agent already returns.
 Those are the parts this run adds.
 
+Every install in this step follows one rule for a version the registry does not serve
+yet. npm reports it as `ETARGET`, pnpm as `ERR_PNPM_NO_MATCHING_VERSION`, Yarn as
+`Couldn't find any versions` or `No candidates found`, and Bun as `No version matching`.
+A package published minutes earlier can name a dependency whose publish has not reached
+the registry. Wait 30 seconds and run the same install once more. If it fails again,
+report the first error.
+
 A run whose `environmentPath` ends in `.env.local` hosts the CopilotKit runtime in that
 Next.js app, never in a separate server: no other process reads the key from that file.
 
@@ -126,10 +146,10 @@ new one. After wiring, run the recorded baseline checks and report any regressio
 
 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:
+project's package manager, under the install rule above. Then check the installed tree:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard upgrade-plan --check --json
+npx --prefer-offline --yes copilotkit@4.29.0 onboard upgrade-plan --check --json
 ```
 
 `single` means every direct dependency resolved to one version. `duplicates` names each
@@ -144,7 +164,7 @@ If the check finds duplicates or the baseline regresses, put the manifests and l
 back, leave Intelligence unwired, and report what failed:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard upgrade-plan --revert --json
+npx --prefer-offline --yes copilotkit@4.29.0 onboard upgrade-plan --revert --json
 ```
 
 Then end your turn. Never add an `overrides`, `resolutions`, or `pnpm.overrides` block to
@@ -176,11 +196,16 @@ project does not hold, and the rendered result looks the same either way.
 Run the full validation list. Record changed files, command results, and errors. Do not
 claim that the real user journey works in this phase.
 
+Your validation stops at `verify`. The proof step runs the round trip and records the
+proof, once. Do not run `verify --round-trip`, `onboard proof-check`, or `onboard proof`.
+Where the validation list names the round trip, leave it to the proof step and say so in
+the Validation section.
+
 Where the plan names a Learning Container id, check that the container exists first. Run
 this from the target app directory, before you write any selector:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 learning containers get <id> --json
+npx --prefer-offline --yes copilotkit@4.29.0 learning containers get <id> --json
 ```
 
 `"status": "success"` means the container exists. An `error.code` of
@@ -202,36 +227,6 @@ 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 plan names the Skills install on its own line, and the build does not wait for an
-answer on it. Install them in a whole-plan implementation. Skip it only when the developer
-said no, which the main coding agent passes in the handoff. A repair handoff never installs
-them.
-
-Where `.agents/skills` already holds the CopilotKit skills, do not install them again.
-Report that they are in place.
-
-Where the developer said no, 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 at the same time as the project's dependencies, not after validation: start both installs together. Where this run installs no dependencies,
-install them before you run the 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 `Skills install`, 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
@@ -243,6 +238,16 @@ Gather what you need in as few commands as possible. Combine independent reads i
 command rather than running them one at a time. Split a command only when its result decides
 what you run next.
 
+Before you return, record that you are returning:
+
+```text
+npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase subagent-returned --brief implement-and-validate --result <ok|failed>
+```
+
+The Status line of your result decides the value. Pass `ok` only for `Status: passed`.
+Pass `failed` for `Status: failed` or `Status: blocked`. If your harness refuses this command, say so in your result and return
+anyway: the main coding agent records it.
+
 Start with `Status: passed`, `Status: failed`, or `Status: blocked`.
 Return exactly four sections: Status, Files changed, Validation, and Blockers. Then end
 your turn.

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

@@ -8,13 +8,13 @@ Your handoff holds the JSON of this command, which the main coding agent ran fro
 target project directory:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard inspect --json
+npx --prefer-offline --yes copilotkit@4.29.0 onboard inspect --json
 ```
 
 Read that JSON. Do not run the command again. If the handoff holds no inspection JSON, run
-the command yourself. If your harness refuses it, return at once with no packet. Say that
-the harness refused the command, name it, and do not wait for an approval. That is not
-`Status: blocked`: the main coding agent can run the command and do this work itself.
+the command yourself. If your harness refuses it, return with no packet, as "When a command
+is refused" below says. That is not `Status: blocked`: the main coding agent can run the
+command and do this work itself.
 
 The JSON answers the deterministic half of both packets exactly, from the same code
 `copilotkit verify` uses: the project record by presence, and, for each app or runtime
@@ -48,6 +48,19 @@ target directory that holds no project yet, and `no-declared-dependency` for a p
 where no directory declares one. Report that reason as the finding. Do not report that
 the inspection found nothing.
 
+## When a command is refused
+
+If you are a subagent and your harness refuses a command, return at once. Name the
+command, the directory you ran it from, and the refusal, and run nothing else. Do not wait
+for an approval: nobody sees it. The main coding agent runs the command itself and passes
+the result on. The one wait allowed is a harness escalation request that this brief tells
+you to make for a command. Make that request and wait for its answer.
+
+If your handoff holds a command's result, use it and do not run that command again.
+
+If you are the main coding agent and follow this brief yourself, this section is not for
+you. Do not return: handle a refused command as the run's other prompts say.
+
 ## Project evidence packet
 
 Find evidence for: