copilotkit 4.27.0 → 4.29.0

package/onboarding/prompts/credentials/write-plan.md

@@ -2,16 +2,14 @@
 
 The project and its credentials are settled. This phase wires the runtime, has a
 subagent write the plan, and shows the plan to the developer. The run waits for their
-answer only when the plan makes a risky change or still needs the model key.
+answer only when the plan makes a change that needs approval or still needs the model key.
 
 ## If you stop in this phase
 
-Name the exact file, value, or check that stopped you, then send one short report. The
-friction command follows the telemetry setting the developer already chose, so it needs no
-separate question.
+Name the exact file, value, or check that stopped you, then send one short report.
 
 ```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 it.
@@ -38,11 +36,10 @@ so either mount works. Keep the mount the project already has, together with its
 setting: `mode: "single-route"` with `useSingleEndpoint` true or unset, or the full route
 subtree with `useSingleEndpoint={false}`. For a new mount, use the full route subtree below.
 
-Below 1.73.1, mount the runtime on the full route subtree. An Intelligence runtime serves
-its runs over two REST paths: `/agent/<id>/run` and `/agent/<id>/connect`, and the
-Intelligence client of those versions addresses them for every transport the provider
-selects. A runtime mounted with `mode: "single-route"` answers every other call. It
-returns not found for every run and every thread reopen. The other fix is an upgrade of
+Below 1.73.1, mount the runtime on the full route subtree. The Intelligence client of those
+versions calls `/agent/<id>/run` and `/agent/<id>/connect` for every transport, so a
+runtime mounted with `mode: "single-route"` returns not found for every run and every
+thread reopen. The other fix is an upgrade of
 the CopilotKit packages to 1.73.1 or later, which the plan can name as its dependency
 upgrade. The round-trip check passes with either mount, so nothing later in this run
 catches the mistake.
@@ -58,7 +55,7 @@ proof subagents:
 - https://docs.copilotkit.ai/backend/runtime-endpoints.md
 - https://docs.copilotkit.ai/intelligence/managed-intelligence-platform.md
 
-Fetch them together with the pages already selected rather than on their own.
+Fetch them with the pages already selected, not on their own.
 
 The planning subagent adds a threads drawer from the selected drawer page. If no drawer
 page is selected yet, add the one for the frontend selected above to the same list:
@@ -69,24 +66,41 @@ page is selected yet, add the one for the frontend selected above to the same li
 4. React Native: select no drawer page. No page documents a threads drawer for React
    Native, so the planner proves the thread with `verify --round-trip` instead.
 
+When you start a subagent in the background, tell the developer in one sentence what it
+does. Then send nothing more until it returns.
+
 Spawn one planning subagent. Tell it to run
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard read subagent/create-plan` first and follow the
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard read subagent/create-plan` first and follow the
 prompt it returns. Tell it to return at once, and say so, if that read is refused or fails,
-and not to wait for an approval. If it returns that way, stop that subagent. Run the same
-command yourself, then spawn a fresh subagent with the returned prompt and the same handoff.
+and not to wait for an approval.
 Give it the repository findings, selected framework, frontend, model, credential variable
 names, selected documentation URLs, and documentation policy. Give it each finding that the
 framework route told you to record, such as how the agent connects or a `clone()` finding.
-Some of those rules, such as the `clone()` override, are on no documentation page. On a
+On a
 conversion, also give it the frozen criterion. Give the planning subagent the paths that
 had uncommitted changes when the run started, from the repository findings, and the
-`backup` result from `onboard credentials`. Wait for the subagent to finish.
+`backup` result from `onboard credentials`. Also give it the JSON that
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard setup-answers` prints, so the plan does not ask again
+for a change the setup message settled. Wait for the subagent to finish.
+
+If only its closing `subagent-returned` checkpoint was refused, the subagent finished.
+Record no `refused` return and spawn nothing: run that checkpoint yourself, with the result
+the subagent returned.
+
+If the subagent returns because its harness refused any other command, record that return:
+
+```text
+npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase subagent-returned --brief create-plan --result refused
+```
+
+Then run that command yourself, from the directory the subagent named. Spawn at most one
+fresh subagent for each refused command, with the same handoff and that command's result.
+If the fresh subagent is refused a command too, spawn no other. Follow the brief yourself.
 
 Continue only if the planning result starts with `Status: passed`. For `Status: failed`,
 send the result back to the planning subagent for repair, up to three attempts. For
 `Status: blocked`, or a third failed result, run
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard read stopped/run-failed`. A plan this run cannot
-write is a run that broke, not a stack the documentation does not cover. The exception is
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard read stopped/run-failed`. The exception is
 a blocked result that names `unsupported/no-validated-path`: the planning subagent found
 that no page supports the plan, so take the no-supported-path route at the end of this
 prompt instead. Do not show a
@@ -100,28 +114,28 @@ move with them, and the revert it falls back to. It must not contain secret valu
 
 ## Show the plan
 
-Show the plan as one short message, one line per item, in this order: the agent, the app
-changes, the packages, Learning, Skills, the notes, and the risky changes last. Leave out a
-line with nothing to say, except the risky changes. When `Risky changes` says `none`:
+Show the plan as one short message. Under `What I will change`, write one line per item,
+in this order: the agent, the app changes, the packages, Learning, and the notes. Leave out
+a line with nothing to say. The changes that need approval have a heading of their own, and
+the approval question is about them alone. When `Changes that need your approval` says `none`:
 
 ```text
 Plan: no approval needed. Reply **stop** at any time.
 
+What I will change:
 - Agent: built-in CopilotKit agent on Groq (openai/gpt-oss-120b)
 - App changes: runtime route, provider, chat with order status cards and a Threads drawer (7 files)
 - Packages added: @copilotkit/runtime and @copilotkit/react-core 1.78.0, @ai-sdk/openai, zod. No upgrades.
 - Learning: new container order-assistant
-- Skills: CopilotKit skills into .agents/skills/ (say **no Skills** to skip)
 - Note: the fixed test user identity works only in development (this app has no sign-in)
 
-Risky changes: none. `onboard restore` puts back what the backup holds.
+Changes that need your approval: none. `onboard restore` puts back what the backup holds.
 ```
 
 - App changes: what the app gains, and how many files change.
 - Packages: each package added, with the CopilotKit version. Name each version a move
   changes, or end with "No upgrades."
 - Learning: the container id, or that Learning is not available to this organization.
-- Skills: the `Skills install` line, or "in place".
 - A note is only for something that changes behavior or security, such as a local
   placeholder, a side effect the plan blocks, a TypeScript upgrade, or an ignore-file line
   this run adds.
@@ -129,67 +143,79 @@ Risky changes: none. `onboard restore` puts back what the backup holds.
 Leave out what a feature does, the validation and proof steps, and the files the run
 writes itself. They stay in the plan.
 
-A plan with a risky change puts its risky lines at the top, from the plan's `Risky
-changes` section, and waits:
+A plan with a change that needs approval puts those lines at the top, under their own
+heading, from the plan's `Changes that need your approval` section. Every other line goes under
+`What I will change`. Then the plan waits:
 
 ```text
-Plan: reply **go** to make the risky changes below, or name the ones to leave out. Reply **stop** at any time.
+Plan: reply **go** to make the changes that need your approval, or name the ones to leave out. Reply **stop** at any time.
 
-Risky changes:
+Changes that need your approval:
 - package.json: moves @copilotkit/react-core from 1.70.2 to 1.78.0, which Intelligence needs
 
+What I will change:
 - Agent: ...
 
 `onboard restore` puts back what the backup holds.
 ```
 
-The Skills install is not a risky change, so the plan does not wait for it. If the developer
-says no to it, at any point, carry that into the implementation and proof handoffs. If the
-no arrives after the install, tell the developer that the install wrote `.agents/skills/`
-and its links in `.claude/skills/`, and that deleting both removes it.
-
-An upgrade to a working install is the developer's call. Do not upgrade a dependency the
-plan does not name.
+Do not upgrade a dependency the plan does not name.
 
 ## Go on, or wait for one answer
 
-Check `Risky changes` first. Where the plan makes one of these and does not list it, send
+Check `Changes that need your approval` first. Where the plan makes one of these and does not list it, send
 the plan back to the planning subagent: a write outside the project, any CopilotKit
 dependency version change, and a backup that is `partial` or `failed`.
 
-When `Risky changes` says `none`, do not wait for an answer. Send the plan message and
+When `Changes that need your approval` says `none`, do not wait for an answer. Send the plan message and
 start the build at once, in the same turn, with the read at the end of this section. Do not
 ask the developer to approve the plan, and do not end your turn.
 
-Otherwise, the plan's first line asks the risky-change question, as above. A reply
-such as "go" approves every risky change except an untrack: only an answer to that line
-approves an untrack. Add one line: this is the last thing you need from them, unless a command needs their
+Otherwise, the plan's first line asks the approval question, as above. A reply such as
+"go" approves every change that needs approval except an untrack. An untrack needs its own yes
+to the line that names it: **go** alone never approves an untrack. Add one line: this is the last thing you need from them, unless a command needs their
 approval or something blocks you. Before you end your turn to
 wait for the answer, report the pause, each time you show the plan:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard checkpoint --phase awaiting-plan-approval
+npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase awaiting-plan-approval --reason <reasons>
 ```
 
-When the developer leaves a risky change out, send the plan back to the planning subagent
+`--reason` names why the plan stopped, one reason for each kind of line that needs approval, separated
+by commas, such as `--reason dependency_upgrade,file_count`:
+
+- `dependency_upgrade`: a major version upgrade, or a move of an exact pin.
+- `dependency_removal`: a dependency removed, or moved outside the declared range.
+- `file_removal`: a file the developer wrote is deleted, moved, or renamed.
+- `uncommitted_file`: a change to a file with uncommitted changes.
+- `gitignore`: an untrack, or a `.gitignore` change.
+- `env_file`: a write to an env file the app already uses.
+- `existing_agent_change`: a change to the existing agent's behavior.
+- `file_count`: more than 10 files change.
+- `outside_project`: a write outside the project directory.
+- `copilotkit_version`: a CopilotKit version change.
+- `backup_partial`: the backup does not hold every file.
+- `other`: a line that needs approval and fits none of these.
+
+When the developer leaves a change out, send the plan back to the planning subagent
 without it. Show the new plan the same way.
 
 If the plan carries a missing model key, the run cannot build without it, so wait for it
-even when `Risky changes` says `none`. Name the variable and its file in the plan message,
-and ask the developer to add the key. Ask the risky-change question in the same message, if
-there is one. When the plan has no risky change, report the pause with
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard checkpoint --phase awaiting-model-credential`
+even when `Changes that need your approval` says `none`. Name the variable and its file in the plan message,
+and ask the developer to add the key. Ask the approval question in the same message, if
+there is one. When the plan has no change that needs approval, report the pause with
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase awaiting-model-credential`
 instead. When the developer answers, run the same `onboard credentials --model-key` check
 again. On `ready`, continue. If the key is still missing, ask the developer `question.ask`
 in those words. Report the pause with
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard checkpoint --phase awaiting-model-credential`, end
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase awaiting-model-credential`, end
 your turn, and run the check again when they answer.
 
 When the plan needs no answer, or after the developer answers, run
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard read implementation/build-and-validate`.
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard read implementation/build-and-validate`.
 
 If no exact supported path or documentation URL exists, run
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard read unsupported/no-validated-path`.
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard read unsupported/no-validated-path`.
 
 ## If the developer replies **stop**
 
@@ -199,10 +225,10 @@ run added stay, and that the restore also undoes any edit the developer made to
 during the run. Before you end your turn to wait for the answer, 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 restore-files
 ```
 
-If they say yes, run `npx --prefer-offline --yes copilotkit@4.27.0 onboard restore --force`. The run has
+If they say yes, run `npx --prefer-offline --yes copilotkit@4.29.0 onboard restore --force`. The run has
 not ended yet, so without `--force` the restore cannot tell the run's edits from the
 developer's and skips every changed file. Show the developer what it restored and what it
 skipped. If they say no, change nothing. Then send the stop report from the start of this

package/onboarding/prompts/deployment/choose-local.md

@@ -9,15 +9,15 @@ A local request can arrive after this run created a hosted project: `init --crea
 Tell the developer that this run already created a hosted project, so it stays managed.
 Return to the step you were on.
 
-First run `npx --prefer-offline --yes copilotkit@4.27.0 local --help`. If it does not list `setup`
+First run `npx --prefer-offline --yes copilotkit@4.29.0 local --help`. If it does not list `setup`
 ("Configure model access and install or resume the local stack"), this release has no
 local evaluation. Tell the developer so, and keep managed. If this run has not recorded
-managed yet, run `npx --prefer-offline --yes copilotkit@4.27.0 onboard deployment --choice managed`.
+managed yet, run `npx --prefer-offline --yes copilotkit@4.29.0 onboard deployment --choice managed`.
 Then return to “Check sign-in” in the start prompt. If a login process from it still
 runs, keep reading that process and start no second one. Otherwise record the choice:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard deployment --choice local
+npx --prefer-offline --yes copilotkit@4.29.0 onboard deployment --choice local
 ```
 
 Explain these conditions before sign-in:
@@ -48,10 +48,10 @@ choices:
 
 1. Configure later, the default. Install with `--defer-model`. In the closing report, write
    "Learning configuration incomplete". Name the command that adds the model later:
-   `npx --prefer-offline --yes copilotkit@4.27.0 local setup`, run in a terminal in the app directory.
+   `npx --prefer-offline --yes copilotkit@4.29.0 local setup`, run in a terminal in the app directory.
 2. Guided setup. If the developer named Learning as a goal, offer it first. Install
    the stack with `--defer-model`. After the stack is ready, the developer runs
-   `npx --prefer-offline --yes copilotkit@4.27.0 local setup` in their own terminal window, in the app
+   `npx --prefer-offline --yes copilotkit@4.29.0 local setup` in their own terminal window, in the app
    directory. Never give it as a `!` line: its guided prompt needs a terminal, and a coding
    agent's shell has none. The prompt asks for the model and its key, and it saves them
    privately. On a running stack, it restarts only Learning. Do not ask the developer to
@@ -71,7 +71,7 @@ If the managed sign-in message was already sent, send this once and no other sig
 message: “You asked to run it locally, so this project gets no managed CopilotKit project.
 Signing in only gets the renewable evaluation license.”
 
-Otherwise run `npx --prefer-offline --yes copilotkit@4.27.0 login --json`. Follow the streaming sign-in
+Otherwise run `npx --prefer-offline --yes copilotkit@4.29.0 login --json`. Follow the streaming sign-in
 protocol from “Check sign-in” in the start prompt: open the first authentication URL
 once, keep the same process running, and continue only after its completed record.
 When the first authentication URL arrives, send this message in place of the managed
@@ -79,9 +79,9 @@ sign-in message: “Sign in to get the renewable evaluation license. Your local
 will use CLI approval.”
 On failed or declined sign-in, take the failure path below.
 
-After sign-in completes, report it: `npx --prefer-offline --yes copilotkit@4.27.0 onboard checkpoint --phase sign-in-settled`.
+After sign-in completes, report it: `npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase sign-in-settled`.
 Then continue with
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard read research/gather`, unless research already started.
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard read research/gather`, unless research already started.
 If it already started, return to the step you were on. `starter/clone` and
 `credentials/finalize-plan` each have a branch for a recorded local choice.
 Keep the local choice and collected paths in the run's plan and worker context.
@@ -89,4 +89,4 @@ Keep the local choice and collected paths in the run's plan and worker context.
 ## Failure path
 
 If sign-in fails or is declined, stop before cluster creation.
-Run `npx --prefer-offline --yes copilotkit@4.27.0 onboard read stopped/run-failed`.
+Run `npx --prefer-offline --yes copilotkit@4.29.0 onboard read stopped/run-failed`.

package/onboarding/prompts/deployment/local-evaluation.md

@@ -19,7 +19,7 @@ settings are saved in private CLI state before the app changes. `local cancel` r
 settings that still match this setup's writes and reports conflicting setting names. It
 preserves later edits and the stack's data.
 
-Run `npx --prefer-offline --yes copilotkit@4.27.0 onboard setup-answers`. It holds the setup message's
+Run `npx --prefer-offline --yes copilotkit@4.29.0 onboard setup-answers`. It holds the setup message's
 answers, even after this conversation lost them. Take each answer below from the record,
 or this conversation when the record lacks it. A field the record lacks is not a "no".
 
@@ -41,7 +41,7 @@ authorize replacing an existing app's connection.
 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 local-connection
 ```
 
 ## Run the shared installer
@@ -50,16 +50,16 @@ From the exact app directory, use the `learning` answer from the record, or this
 conversation:
 
 ```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
 ```
 
 For `learning.file`, replace `--defer-model` with `--model-config <learning.file>`.
-Before setup, run `npx --prefer-offline --yes copilotkit@4.27.0 onboard local-terms --json`. If `accepted`
+Before setup, 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.
 The CLI selects the latest stable release. Add `--candidate <manifest.json>` only when the
 developer gave a candidate manifest for release testing.
@@ -75,7 +75,7 @@ A copied app needs explicit `--share-stack`. Do not infer sharing from a copied
 After setup reports the stack ready, run the approved connection step from that directory:
 
 ```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
 ```
 
 Read the local `.copilotkit/project.json` for its project ID and slug. Do not run hosted
@@ -95,7 +95,7 @@ this conversation, wait until the stack is ready. Then:
 Ask the developer to run this command in their own terminal window, in the app directory:
 
 ```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
@@ -104,9 +104,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` and read `learning.configuration`.
+`npx --prefer-offline --yes copilotkit@4.29.0 local status --json` and read `learning.configuration`.
 
 If the model is still missing or was deferred, report “Learning configuration incomplete”
 and name the same command, run in a terminal window. No Learning run is required to finish
@@ -120,6 +120,6 @@ must not block Threads, the dashboard, or later Learning configuration.
 If the developer cancels the connection, run `local cancel --json` from the app directory.
 Report conflict names only. Keep the stack unless deletion is separately confirmed.
 
-Continue with `npx --prefer-offline --yes copilotkit@4.27.0 onboard read credentials/settle-credentials`.
+Continue with `npx --prefer-offline --yes copilotkit@4.29.0 onboard read credentials/settle-credentials`.
 For this local route, skip the hosted selection-result checks and use the local project
 record. Continue the existing implementation and proof paths against local endpoints.

package/onboarding/prompts/fallback/best-effort.md

@@ -14,7 +14,7 @@ you stop. The friction command follows the telemetry setting the developer alrea
 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 it.
@@ -28,6 +28,9 @@ step. Send the report, then stop the way the rule that stopped you says to. This
 runs because the documentation already fell short once, so a stop inside it is the second
 gap in the same run and neither is recorded anywhere else.
 
+When you start a subagent in the background, tell the developer in one sentence what it
+does. Then send nothing more until it returns.
+
 Spawn one implementation subagent. Give it the approved plan, repository findings, and
 target project directory. Tell it which steps lack direct documentation. Give it all
 official documentation that you fetched for the plan. Give it the paths that had
@@ -61,7 +64,7 @@ or frontend, stop onboarding.
 If the CLI prints `## Stop: this run deleted or moved the developer's work` instead of a
 step, show the developer the list it printed, and run what they choose:
 the `onboard restore` command the tripwire stop prints, which names each deleted file, or
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard tripwire --continue`. Then read the step again. If
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard tripwire --continue`. Then read the step again. If
 you cannot ask, stop onboarding. Never repair, reset, or revert a file the developer changed
 outside this run.
 
@@ -97,29 +100,22 @@ new validation evidence. The handoff includes the paths that had uncommitted cha
 the run started. Wait for the fresh proof subagent and apply the same proof-result rules.
 Continue only if the proof result starts with `Status: passed`.
 
-Do not block core proof on the CopilotKit Skills. Tell the developer that the skills
-install writes a `.agents/skills` directory and `.claude/skills` links into the working
-tree before you run it, because both show up in `git status` and this run cannot know
-whether the project keeps them in version control. Install them after the application
-passes proof. Do not register an MCP server: the Skills read the CopilotKit documentation
-without one. Report the Skills result separately from the proof result.
-
 Report the documentation gap and each assumption with the proof evidence. Do not claim
 that the selected documentation proved an inferred step.
 
 Record what the proof returned before you complete:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard proof --step round-trip --outcome <passed|failed|skipped>
+npx --prefer-offline --yes copilotkit@4.29.0 onboard proof --step round-trip --outcome <passed|failed|skipped>
 ```
 
-When the proof is complete, run `npx --prefer-offline --yes copilotkit@4.27.0 onboard complete`, carrying the
+When the proof is complete, run `npx --prefer-offline --yes copilotkit@4.29.0 onboard complete`, carrying the
 surface-check result the proof subagent returned. Pass exactly one of `--visual-check` or
 `--device-check`, matching this journey's surface:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard complete --visual-check <outcome>
-npx --prefer-offline --yes copilotkit@4.27.0 onboard complete --device-check <outcome>
+npx --prefer-offline --yes copilotkit@4.29.0 onboard complete --visual-check <outcome>
+npx --prefer-offline --yes copilotkit@4.29.0 onboard complete --device-check <outcome>
 ```
 
 `--visual-check` is for a web frontend and takes `performed`, `skipped-no-browser-tool`, or

package/onboarding/prompts/feature/a2ui/implement.md

@@ -24,7 +24,7 @@ That result is a question for the developer. Name the file and why the work need
 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 uncommitted-file
 ```
 
 Then end your turn and wait for the developer's answer. If they allow it, spawn a fresh
@@ -34,16 +34,16 @@ cannot ask, or the developer declines, take the feature stop route below.
 If the CLI prints `## Stop: this run deleted or moved the developer's work` instead of
 a step, show the developer the list it printed, and run what they choose:
 the `onboard restore` command the tripwire stop prints, which names each deleted file, or
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard tripwire --continue`. Then read the step again.
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard tripwire --continue`. Then read the step again.
 
 To route out and stop:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard read feature/stop
+npx --prefer-offline --yes copilotkit@4.29.0 onboard read feature/stop
 ```
 
 If validation cannot pass, or this intent needs a prerequisite the app does not have, use
 the feature stop route above without further changes.
 
 Otherwise run
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard read feature/a2ui/proof`.
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard read feature/a2ui/proof`.

package/onboarding/prompts/feature/a2ui/plan.md

@@ -12,7 +12,7 @@ The approval is a wait for the developer. Before you end your turn to wait, repo
 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-plan-approval
 ```
 
 A turn that ends while the run waits is a pause, not a stop, even when your harness ends it.
@@ -49,7 +49,7 @@ renders a compact visible surface. Ask for approval as its own question.
 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-plan-approval
+npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase awaiting-plan-approval
 ```
 
 Ask the developer before you edit a file that has uncommitted changes. List those files in
@@ -57,4 +57,4 @@ the plan under `Uncommitted files`, each with one sentence explaining why, or wr
 `git status` names them. The CLI records no consent: the approved plan is the record. The
 plan must not delete, move, or rename one of those files.
 
-Then run `npx --prefer-offline --yes copilotkit@4.27.0 onboard read feature/a2ui/implement`.
+Then run `npx --prefer-offline --yes copilotkit@4.29.0 onboard read feature/a2ui/implement`.

package/onboarding/prompts/feature/a2ui/proof.md

@@ -25,7 +25,7 @@ That result is a question for the developer. Name the file and why the fix needs
 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 uncommitted-file
 ```
 
 Then end your turn and wait for the developer's answer. If they allow it, spawn a fresh
@@ -35,13 +35,13 @@ or the developer declines, take the feature stop route below.
 If the CLI prints `## Stop: this run deleted or moved the developer's work` instead of
 a step, show the developer the list it printed, and run what they choose:
 the `onboard restore` command the tripwire stop prints, which names each deleted file, or
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard tripwire --continue`. Then read the step again.
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard tripwire --continue`. Then read the step again.
 
 Report the outcome of each attempt as it ends, before any repair. The command counts the
 attempts and the repairs:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard proof --step round-trip --outcome <passed|failed|skipped>
+npx --prefer-offline --yes copilotkit@4.29.0 onboard proof --step round-trip --outcome <passed|failed|skipped>
 ```
 
 Use `passed` only for a proved A2UI surface, `failed` for an attempted proof that failed,
@@ -50,9 +50,9 @@ and `skipped` when the proof could not run.
 To route out and stop:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard read feature/stop
+npx --prefer-offline --yes copilotkit@4.29.0 onboard read feature/stop
 ```
 
 When the proof is recorded, run
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard read feature/complete` with the actual browser-proof
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard read feature/complete` with the actual browser-proof
 outcome.

package/onboarding/prompts/feature/a2ui/start.md

@@ -10,7 +10,7 @@ run is doing in the developer's words instead.
 Run this before anything else in this prompt:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard identify --coding-agent <coding-agent-slug> --model <model-id> --model-family <model-family>
+npx --prefer-offline --yes copilotkit@4.29.0 onboard identify --coding-agent <coding-agent-slug> --model <model-id> --model-family <model-family>
 ```
 
 Report your product slug, such as `codex` or `claude-code`. The command needs no sign-in,
@@ -39,15 +39,24 @@ carry on. Keep a read-only assignment read-only. If no subagent works at all, re
 once:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard checkpoint --phase delegation-unavailable
+npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase delegation-unavailable
 ```
 
 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 <question>
 ```
 
+Name the question with `--about`. Use the one the prompt that asks it names, or else the
+closest of: `harness-permission`, `sign-in`, `setup-answers`, `stack-choice`,
+`project-name`, `which-project`, `env-file-tracked`, `local-connection`, `local-terms`,
+`existing-folder`,
+`environment-fix`, `uncommitted-file`, `agent-change`, `restore-files`, `thread-id`,
+`scoped-fix`, `feature-binding`, `other`. Report the pause before every turn that ends while
+the run is still open, even a turn where you asked nothing, with `other` then. A run that
+goes quiet without it reads as a run that died.
+
 A turn that ends while the run waits is a pause, not a stop, even when your harness ends it.
 When the answer or the result arrives, continue from the step that paused.
 
@@ -55,7 +64,7 @@ If you stop this run, send one short report before you stop. The friction comman
 the telemetry setting the developer 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 it.
@@ -77,7 +86,7 @@ development/test commands. It must return paths and secret-safe presence checks
 
 Require an existing frontend, agent, and CopilotKit round trip. Start only project-owned
 processes when needed, inspect `/info`, and run
-`npx --prefer-offline --yes copilotkit@4.27.0 verify --expect-runtime oss --round-trip --agent <agent-id> --json`.
+`npx --prefer-offline --yes copilotkit@4.29.0 verify --expect-runtime oss --round-trip --agent <agent-id> --json`.
 Also drive one existing request through the frontend when browser control is available.
 The `verify` report names the runtime URL it probed. If the dev server serves the
 runtime at another URL, add `--runtime-url <url>`.
@@ -85,20 +94,20 @@ runtime at another URL, add `--runtime-url <url>`.
 Wait for the inspection subagent to finish. Then report that the inspection came back:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard checkpoint --phase research-returned
+npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase research-returned
 ```
 
 If the inspection did not prove the baseline this intent extends, stop here without
 changing files:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard read feature/stop
+npx --prefer-offline --yes copilotkit@4.29.0 onboard read feature/stop
 ```
 
 When the inspection proved what this intent needs, read the next prompt now, in this turn:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard read feature/a2ui/plan
+npx --prefer-offline --yes copilotkit@4.29.0 onboard read feature/a2ui/plan
 ```
 
 That prompt holds the plan, the developer's approval, and the paths the plan changes.