copilotkit 4.16.0 → 4.18.0

package/onboarding/prompts/credentials/settle-credentials.md

@@ -1,192 +1,55 @@
-# Settle the Learning Container and the model credential
+# Settle the model credential
 
-The Intelligence project is selected. This phase settles what the project stores and
-which model credential the application uses. Do not change application code here, and do
-not read, show, store, or request a secret value.
+The project is selected. This phase settles the model credential. Do not change
+application code here. Do not read, show, store, or request a secret value.
 
-## If you stop in this phase
+## Carry the Learning Container into the plan
 
-Name the exact file, value, or check that stopped you, then send one short report. Run the
-friction command without another developer question. Do not ask the developer about
-telemetry: the command applies the setting they already have.
+Read `learningContainer` from the `onboard credentials` result:
 
-```text
-npx --prefer-offline --yes copilotkit@4.16.0 onboard friction --phase stop --category <slug> --message "<sentences>"
-```
-
-`--message` takes one or two sentences: the step you stopped at and what stopped it.
-Pick the category that fits from docs-missing, docs-wrong, docs-sequential, cli-gap,
-sdk-gap, environment, port-collision, credential, validation-loop, and other. Leave
---cost-seconds off. A run that stopped cannot separate one papercut's cost from the cost of
-the whole run, so the estimate is optional on a stop report and only there. Send no secrets,
-source code, logs, or command output. A refused report is not a failed step: reword it and
-send it again, or stop without a report.
-
-## Check that the key landed where the application reads it
-
-Do this first, before the Learning Container, and only on a run that selected a project.
-A run that reused one wrote no key and has nothing to read.
-
-`environment_file_written` in the selection result says a file was written. It does not say
-which file, and it does not say whether the application reads it. `environment_file` says
-both: `path` is the file, and `loadable_by_app` is whether an application loads env files
-from that directory. Project selection is the only step that can answer the second one.
-
-- `pass`: the key is where the application's own process reads it. Continue.
-- `fail`: it is not. `environment_file.apps` names the directories that do load env files.
-  Run the selection again from one of them, with `--project <selected slug>` and the same
-  `--runtime-url`, then read the new result.
-- `undetermined`: no application package was found, so the question has no answer. Record
-  that and continue.
-
-Do not repair a `fail` by copying the file, linking it, or writing the key a second time.
-One key in two files is a secret in a place nobody tracks, and the copy goes stale as soon
-as the original is rotated.
-
-A key the application cannot load stops nothing here. It fails the round-trip proof
-instead, which is the most expensive step in the run.
-
-## Settle the Learning Container for this project
-
-Do this now, directly after project selection reports `selected_project_slug`, and before
-the plan. On a run that reused a project rather than selecting one, take the slug from the
-`projectSlug` field in the project record, which the follow-up check above already proved
-is non-empty. Both paths reach this step. Learning assigns real threads to a Learning Container once.
-New and existing threads can receive their first assignment, including after agent runs.
-Set up the container here so new conversations contribute from the start. Existing threads
-can join later, and Learning can collect only history whose source events still survive.
-
-One container for this project is the default scope, so the id comes from the selected
-project slug. Ask the CLI for it, from the target directory:
-
-```text
-npx --prefer-offline --yes copilotkit@4.16.0 learning containers default-id --json
-```
-
-The command reads the local project record. It needs no credential and makes no network
-call, so it answers before the run asks the platform anything. Read `status` from the
-payload:
-
-- `"status": "success"` carries the id in `containerId`. Use that exact string.
-- `"status": "skipped"` means there is no id to use. `slug-unusable` means the slug leaves
-  nothing the id contract accepts. `no-project-record` means no project is selected in
-  this directory. Skip this step and name the skip, rather than inventing a name.
-
-Never spell the id yourself. Two spellings of one project's id give it two containers,
-each below the 15-conversation line on its own, and nothing reports that the split
-happened.
-
-Then ask the platform about that id, from the target directory:
-
-```text
-npx --prefer-offline --yes copilotkit@4.16.0 learning containers get <id> --json
-```
-
-The read carries the same availability gate as the create, so it answers the entitlement
-question in one call and writes nothing. Read `status` and `error.code` from the payload.
-Route on the code rather than on the exit status:
-
-- `"status": "success"` means the container already exists. Reuse it and create nothing.
-- `LEARNING_CONTAINER_NOT_FOUND` means it does not exist yet. This is the normal first run.
-  Plan it, and create it after the developer approves the plan.
-- `LEARNING_NOT_ENABLED` means this organization cannot use Learning. Skip the whole step:
-  plan no container, plan no selector, and name the skip in the plan and again in the
-  closing report. Do not stop. Learning is not on every plan, and a stop here ends a
-  paying customer's onboarding over a feature they never asked for.
-- `LEARNING_AVAILABILITY_UNAVAILABLE` means the platform did not resolve the answer. It is
-  unknown rather than denied. Run the same command once more. If the second call answers the
-  same way, report the code and stop onboarding.
-- Any other code: report it and stop onboarding, the way a false `api_key_provisioned`
-  stops the run.
+- `exists`: reuse `id` and create nothing.
+- `plan-create`: plan `id`, and create it after the developer approves the plan.
+- `skipped`: plan no container and no selector. Name `reason` in the plan and in the
+  closing report. Do not stop.
 
-Never invent an id, scrape a dashboard, or treat an arbitrary string as a container.
+Carry it into the planning handoff. Never spell the id yourself: two spellings give one
+project two containers.
 
-Report what the read found, before anything is planned:
+## Check the model credential
 
-```text
-npx --prefer-offline --yes copilotkit@4.16.0 onboard checkpoint --phase container-surveyed
-```
-
-Carry the derived id into the planning subagent's handoff, with whether the platform
-already holds it. Where the step was skipped, carry the skip instead, so the plan names no
-container and no selector.
-
-## Where a model credential comes from
-
-The plan names the model credential variables. Finding their values is not its job.
-
-If the project has no value for one, ask the developer where it lives. Never read a file
-outside the project directory to find one. A key found that way belongs to another
-project: it bills that project for these model calls, points attribution at a project
-nobody chose, and leaves no trace, because the scaffold works.
-
-Asking where a credential lives is not requesting a secret value. Ask for a path, or ask
-the developer to write the value into the project's env file themselves. A path the
-developer names is theirs to give, including one outside the project. A path this run
-finds is not.
-
-Until the developer answers, the run waits. Report the pause and end your turn:
-
-```text
-npx --prefer-offline --yes copilotkit@4.16.0 onboard checkpoint --phase awaiting-developer
-```
-
-This is a pause, not a stop. `research/gather` describes it under "Pausing vs stopping".
-Do not send a stop report, and do not take a stop route. When the developer answers,
-continue from this step. Do not write a placeholder or an empty value. A scaffold carrying
-a dummy key looks finished and fails at the first model call.
-
-After model credential placement is complete, add each credential setup path to the
-protected path list. Also add each project file that the developer changed for model
-credentials. Record them in the baseline from the target app directory:
-
-```text
-npx --prefer-offline --yes copilotkit@4.16.0 onboard protect --path <path>
-```
-
-Pass one `--path` for each. The command captures a digest for each path and never re-reads
-a path the baseline already holds.
-
-Give each path relative to the project root, exactly as the capture printed it. A relative
-path is read against the run's own root, not against the directory you are standing in, so
-one path names one file from anywhere in the project.
-
-Then re-capture the files this graph wrote itself. For each path the first capture printed
-as `deferred` that this run has now written, run:
+The plan names the model credential variables. Run this from the directory that holds
+`environmentPath` in the project step's result, with one `--model-key` for each variable:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.16.0 onboard protect --rebaseline --path <path>
+npx --prefer-offline --yes copilotkit@4.18.0 onboard credentials --model-key <variable> --json
 ```
 
-From that point they are protected like any other path, so a later step that rewrites
-`.env` and drops its key fails the audit rather than passing it. Continue only if every
-result starts with `Status: passed`.
-
-### When the developer writes a credential after the baseline
-
-Asking the developer to place a credential themselves means their edit lands when they get
-to it, and often after the paths above are captured. A later audit then reports the
-environment path as changed. That change is the one this run asked for, so it is not
-damage, and the credential route is how the run says so.
+When the framework node names another env file for the credential, add
+`--env-file <file>`. Add one `--path <file>` for each project file the developer changed for the
+credential. The command asks the vendor whether each key can pay for a model call, and it
+never prints a value. When every key settles, it protects the credential paths. Read
+`status`:
 
-Do not run that route here as a step of its own. Run it only when an audit names the
-environment path. The command below is what to run at that point, from the target app
-directory:
-
-```text
-npx --prefer-offline --yes copilotkit@4.16.0 onboard protect --accept-credential --path <environment path>
-```
+- `ready`: continue. Name each `unsupported` or `undetermined` `reason` in `modelKeys` in
+  the closing report.
+- `needs-developer` with `question.status` `missing`: ask the developer where the
+  credential lives.
+- `needs-developer` with `question.status` `fail`: tell the developer `question.cause`.
+  `model_quota` means that the key has no credits, and `model_auth` means that the vendor
+  rejected it. Offer three choices: add credits, use another key, or switch the model
+  provider.
+- `stopped`: the command already filed the stop report. Stop onboarding.
 
-The command compares the variable names the baseline recorded with the names the file holds
-now. Read its result:
+Until the developer answers, the run waits. 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. Under a
+harness that ends the session with your turn, such as `codex exec`, that message is the only
+thing the developer sees. This is a pause, not a stop. The command already reported it.
+End your turn. When the developer answers, run the command again. Do not write a
+placeholder or an empty value.
 
-- `Status: passed` means the developer added a credential and every recorded credential is
-  still there. Carry the accepted path into the summary.
-- `credential-lost` means a variable the baseline recorded is gone or empty, and the
-  refusal names it. Do not repair or rewrite the file. Report the named variable and stop
-  onboarding. A run that lost the project key has nothing to prove a round trip with.
-- `unchanged-path` means the file matches its baseline, so nothing was placed in it. That
-  is not a failed step. It answers the question and the run carries on.
+Never read a file outside the project directory to find a credential: a key found that way
+bills another project. Asking for a path is not requesting a secret, and neither is asking
+the developer to write the value into the env file. A path the developer names is theirs
+to give, including one outside the project. A path this run finds is not.
 
-When the credential question is answered, run
-`npx --prefer-offline --yes copilotkit@4.16.0 onboard read credentials/write-plan`.
+Then run `npx --prefer-offline --yes copilotkit@4.18.0 onboard read credentials/write-plan`.

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

@@ -6,12 +6,12 @@ the run asks them.
 
 ## If you stop in this phase
 
-Name the exact file, value, or check that stopped you, then send one short report. Run the
-friction command without another developer question. Do not ask the developer about
-telemetry: the command applies the setting they already have.
+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.
 
 ```text
-npx --prefer-offline --yes copilotkit@4.16.0 onboard friction --phase stop --category <slug> --message "<sentences>"
+npx --prefer-offline --yes copilotkit@4.18.0 onboard friction --phase stop --category <slug> --message "<sentences>"
 ```
 
 `--message` takes one or two sentences: the step you stopped at and what stopped it.
@@ -29,30 +29,50 @@ it. The credential reaches the platform only when the runtime is constructed wit
 Intelligence client, and a runtime built without one compiles, serves, answers in a
 browser, and never touches the platform.
 
-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`. The Intelligence client
-addresses those paths 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.
-
-For a Next.js app, mount the handler at `app/api/copilotkit/[[...slug]]/route.ts`. Export
-`GET`, `POST`, `PATCH` and `DELETE`. Pass `useSingleEndpoint={false}` to the React
-provider.
-
-One page below offers single-route as an equal option. It is not an equal option here. The
-round-trip check passes either way, so nothing later in this run catches the mistake.
+Which mount works depends on the `@copilotkit/core` version the app runs: the installed
+version the inspection reported, or the version the plan upgrades to. Do not detect it
+again. Where the inspection reports no `@copilotkit/core`, as a pnpm tree often does, read
+the `@copilotkit/react-core` or `@copilotkit/runtime` version: the three release together.
+Give this rule and that version to the planning subagent below.
+
+From `@copilotkit/core` 1.73.1, the Intelligence client honors a single-route transport,
+so either mount works. Keep the mount the project already has, together with its provider
+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
+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.
+
+For the full route subtree in a Next.js app, mount the handler at
+`app/api/copilotkit/[[...slug]]/route.ts`. Export `GET`, `POST`, `PATCH` and `DELETE`.
+Pass `useSingleEndpoint={false}` to the React provider.
 
 Add these pages to the selected documentation URLs for the planning, implementation, and
 proof subagents:
 
-- https://docs.copilotkit.ai/intelligence/connect-your-runtime.md
+- https://docs.copilotkit.ai/intelligence/quickstart.md
 - 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.
 
+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:
+
+1. React SPA or Next.js: https://docs.copilotkit.ai/prebuilt-components/copilot-threads-drawer.md
+2. Angular: https://docs.copilotkit.ai/angular/guides/threads-memory-attachments-headless.md
+3. Vue 3: https://docs.copilotkit.ai/vue/guides/threads-and-drawer.md
+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.
+
 Spawn one planning subagent. Tell it to run
-`npx --prefer-offline --yes copilotkit@4.16.0 onboard read subagent/create-plan` first and follow the prompt
+`npx --prefer-offline --yes copilotkit@4.18.0 onboard read subagent/create-plan` first and follow the prompt
 it returns. If that read fails because the subagent cannot use the shell, stop that subagent.
 Run the same command yourself, then spawn a fresh subagent with the returned prompt and the
 same handoff. Give it the repository findings, selected framework, frontend, model, credential
@@ -63,8 +83,11 @@ Wait for the subagent to finish.
 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.16.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. Do not show or
+`npx --prefer-offline --yes copilotkit@4.18.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
+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 or
 ask for approval of a non-pass plan.
 
 Make sure that the plan preserves each part that already exists. The plan must name the
@@ -95,7 +118,8 @@ developer did not approve.
 When you ask for approval, tell the developer in one line that this is the last thing you
 need from them, and, unless your harness makes the developer approve commands before they
 run, that they can leave the run once they approve. That is a fact about this graph rather
-than a reassurance: no step after approval asks the developer a question, and the steps
+than a reassurance: no step after approval asks the developer a question unless a step
+cannot be built as approved, and the steps
 that follow are the longest ones in the run. A developer who does not know that waits at
 the terminal through all of them for a question that never comes. Say it in the same
 message as the plan, and do not turn it into a second question.
@@ -107,7 +131,7 @@ build. Keep this window open until the app runs." Decide from your own approval
 as the welcome did, not from your coding-agent slug.
 
 If the developer approves the plan, run
-`npx --prefer-offline --yes copilotkit@4.16.0 onboard read implementation/build-and-validate`.
+`npx --prefer-offline --yes copilotkit@4.18.0 onboard read implementation/build-and-validate`.
 
 If no exact supported path or documentation URL exists, run
-`npx --prefer-offline --yes copilotkit@4.16.0 onboard read unsupported/no-validated-path`.
+`npx --prefer-offline --yes copilotkit@4.18.0 onboard read unsupported/no-validated-path`.

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

@@ -8,13 +8,15 @@ This fallback contains unproved steps. Use the approved plan in step order.
 ## If you stop in this fallback
 
 Several rules below stop onboarding: a blocked or third failed implementation result, a
-changed protected path, a blocked or third failed proof, a fix that needs changes to the
-existing agent or frontend. Send one short report before you stop. Run the friction
-command without another developer question. Do not ask the developer about telemetry: the
-command applies the setting they already have.
+blocked audit, a changed protected path this run wrote, a changed path that no Files
+changed section accounts for after a proof subagent ran, a credential acceptance refused
+for a lost variable, a blocked or third failed proof, a blocked or third failed repair, and
+a fix that needs changes to the existing agent or frontend. Send one short report before
+you stop. The friction command follows the telemetry setting the developer already chose,
+so it needs no separate question.
 
 ```text
-npx --prefer-offline --yes copilotkit@4.16.0 onboard friction --phase stop --category <slug> --message "<sentences>"
+npx --prefer-offline --yes copilotkit@4.18.0 onboard friction --phase stop --category <slug> --message "<sentences>"
 ```
 
 `--message` takes one or two sentences: the step you stopped at and what stopped it.
@@ -60,17 +62,23 @@ or frontend, stop onboarding.
 
 Use these rules for every protected-path check in this fallback:
 
-- Run `npx --prefer-offline --yes copilotkit@4.16.0 onboard audit` from the target app directory.
+- Run `npx --prefer-offline --yes copilotkit@4.18.0 onboard audit` from the target app directory.
 - If a result starts with `Status: blocked`, stop onboarding and report the printed reason.
   It proved nothing changed, so do not report a preservation failure.
 - If a result reports a changed protected path this run wrote, stop onboarding.
-- If a result reports a changed path that no Files changed section from this run names,
-  the change came from outside the run. Accept it by name with
-  `npx --prefer-offline --yes copilotkit@4.16.0 onboard protect --accept-external --path <path>`, run the
+- If a result reports a changed env file, this rule replaces the one above, even when this
+  run wrote the file. This run asked the developer to place a
+  credential there, so take the credential route rather than the external one. Accept it
+  with `npx --prefer-offline --yes copilotkit@4.18.0 onboard protect --accept-credential --path <path>`,
+  run the audit again, and name it in the closing report. If the command refuses because
+  it names a lost variable, stop onboarding.
+- Before any proof subagent runs, a changed path that no Files changed section from this
+  run names came from outside the run. Accept it by name with
+  `npx --prefer-offline --yes copilotkit@4.18.0 onboard protect --accept-external --path <path>`, run the
   audit again, and name it in the closing report.
-- If no Files changed section from this run covers the step that wrote it, stop
-  onboarding. The proof subagent here returns no such section, so a finding it raises is
-  unsettled rather than outside the run.
+- After a proof subagent runs, a changed path that no Files changed section from this run
+  names is unsettled rather than outside the run, because the proof subagent here returns
+  no such section. Stop onboarding.
 - Never repair, reset, or revert a protected path.
 
 Run the protected-path check now. Apply the protected-path rules. Continue only when the
@@ -119,13 +127,13 @@ application passes proof. Report each tool result separately from the proof resu
 Report the documentation gap and each assumption with the proof evidence. Do not claim
 that the selected documentation proved an inferred step.
 
-When the proof is complete, run `npx --prefer-offline --yes copilotkit@4.16.0 onboard complete`, carrying the
-surface-check result the proof subagent returned. Pass exactly one flag, matching this
-journey's surface:
+When the proof is complete, run `npx --prefer-offline --yes copilotkit@4.18.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.16.0 onboard complete --visual-check <outcome>
-npx --prefer-offline --yes copilotkit@4.16.0 onboard complete --device-check <outcome>
+npx --prefer-offline --yes copilotkit@4.18.0 onboard complete --visual-check <outcome>
+npx --prefer-offline --yes copilotkit@4.18.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

@@ -15,10 +15,41 @@ Start the app with its documented command. Confirm `/info` reports the expected
 capability, but do not treat that flag as proof. Record changed paths and validation output
 without exposing secrets.
 
+Before you spawn the implementation subagent, take the authorized list from the CLI:
+
+```text
+npx --prefer-offline --yes copilotkit@4.18.0 onboard audit
+```
+
+From its result, copy the paths under `Authorized to modify:`. A passed or failed audit with
+no such block means that nothing is authorized. Read only that block now, and decide the
+findings of a failed audit after implementation, with the audit rules below. If this audit
+starts with `Status: blocked`, the CLI cannot supply the list. Report the printed reason and
+take the feature stop route below.
+
+Give the implementation subagent the protected path list and the authorized list. Tell it
+this rule: it can change a path on the authorized list. When the work needs any other
+protected path, it must not edit it. It returns a result that starts with `Status: blocked`
+and names the file under Blockers.
+
+That result is a question for the developer. The file has not changed yet, so consent can
+still go on the record. Name the file and why the work needs it, then end your turn and wait
+for the developer's answer. If they allow it, record their answer before any edit:
+
+```text
+npx --prefer-offline --yes copilotkit@4.18.0 onboard protect --authorize --unplanned --path <path> --reason "<what the developer said>"
+```
+
+Continue only when the result starts with `Status: passed`. Run the audit again, take the
+new list from its `Authorized to modify:` block, and spawn a fresh implementation subagent
+with the same handoff and that list. A subagent that already returned cannot pick up consent
+recorded after it was spawned. If you cannot ask, or the developer declines, take the
+feature stop route below.
+
 After validation and each repair, run:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.16.0 onboard audit
+npx --prefer-offline --yes copilotkit@4.18.0 onboard audit
 ```
 
 Continue only when it starts with `Status: passed`. A path under `Authorized to modify:` is
@@ -29,33 +60,30 @@ with the implementation subagent's `Files changed` section. If that section does
 the path, accept the developer's external change:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.16.0 onboard protect --accept-external --path <path>
+npx --prefer-offline --yes copilotkit@4.18.0 onboard protect --accept-external --path <path>
 ```
 
 For an env file where the developer placed a requested credential, use
 `onboard protect --accept-credential --path <path>` instead. If the subagent names the path,
-or its report does not settle who changed it, ask the developer to allow the unplanned
-change. Only after they agree, record their answer:
-
-```text
-npx --prefer-offline --yes copilotkit@4.16.0 onboard protect --authorize --unplanned --path <path> --reason "<what the developer said>"
-```
+or its report does not settle who changed it, the change is this run's own, made without
+consent. Do not ask the developer to allow it: the CLI refuses consent for a path that
+already changed. Route out, and name the path and the change the audit reports.
 
-Run the audit again after each accepted or authorized change. If it still fails, or starts
+Run the audit again after each accepted change. If it still fails, or starts
 with `Status: blocked`, route out and stop:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.16.0 onboard read feature/stop
+npx --prefer-offline --yes copilotkit@4.18.0 onboard read feature/stop
 ```
 
 When implementation validation passes, report it:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.16.0 onboard checkpoint --phase build-validated
+npx --prefer-offline --yes copilotkit@4.18.0 onboard checkpoint --phase build-validated
 ```
 
 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.16.0 onboard read feature/a2ui/proof`.
+`npx --prefer-offline --yes copilotkit@4.18.0 onboard read feature/a2ui/proof`.

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

@@ -16,26 +16,46 @@ is unavailable, report that the browser proof is blocked rather than claiming su
 Fix proof failures caused by changed files, then repeat the same proof. Do not replace the
 user's agent response with a hard-coded UI.
 
+Give the proof subagent the protected path list and the authorized list. Take that list from
+the latest audit, and copy the paths under `Authorized to modify:`. Tell it this rule: a fix
+can change a path on the authorized list. When a fix needs any other protected path, it must
+not edit it. It returns a result that starts with `Status: blocked` and names the file under
+Blockers.
+
+That result is a question for the developer. The file has not changed yet, so consent can
+still go on the record. Name the file and why the fix needs it, then end your turn and wait
+for the developer's answer. If they allow it, record their answer before any edit:
+
+```text
+npx --prefer-offline --yes copilotkit@4.18.0 onboard protect --authorize --unplanned --path <path> --reason "<what the developer said>"
+```
+
+Continue only when the result starts with `Status: passed`. Run the audit again, take the
+new list from its `Authorized to modify:` block, and spawn a fresh proof subagent with the
+same handoff and that list. A subagent that already returned cannot pick up consent recorded
+after it was spawned. If you cannot ask, or the developer declines, take the feature stop
+route below.
+
 Report each attempt at the proof as it ends, counting from one:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.16.0 onboard checkpoint --phase journey-attempted --attempt 1
+npx --prefer-offline --yes copilotkit@4.18.0 onboard checkpoint --phase journey-attempted --attempt 1
 ```
 
 Report each repair cycle the same way, counting from one:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.16.0 onboard checkpoint --phase repair-attempted --attempt 1
+npx --prefer-offline --yes copilotkit@4.18.0 onboard checkpoint --phase repair-attempted --attempt 1
 ```
 
 After the final attempt, report the gate exactly once:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.16.0 onboard proof --step round-trip --outcome <passed|failed|skipped>
+npx --prefer-offline --yes copilotkit@4.18.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,
-and `skipped` when the proof could not run. Then run `npx --prefer-offline --yes copilotkit@4.16.0 onboard audit`.
+and `skipped` when the proof could not run. Then run `npx --prefer-offline --yes copilotkit@4.18.0 onboard audit`.
 Continue only when it starts with `Status: passed`.
 
 If the audit fails, never repair, reset, or revert a protected path. Compare each named path
@@ -43,16 +63,16 @@ with the proof subagent's `Files changed` section. If that section does not name
 run `onboard protect --accept-external --path <path>`, or
 `onboard protect --accept-credential --path <path>` for an env file where the developer
 placed a requested credential. If the subagent names the path, or its report does not settle
-who changed it, ask the developer to allow it. Only after they agree, run
-`onboard protect --authorize --unplanned --path <path> --reason "<what the developer said>"`.
-Run the audit again after each accepted or authorized change.
+who changed it, the change is this run's own, made without consent. Do not ask the developer
+to allow it: the CLI refuses consent for a path that already changed. Route out, and name
+the path and the change the audit reports. Run the audit again after each accepted change.
 
 If the audit still fails, or starts with `Status: blocked`, route out and stop:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.16.0 onboard read feature/stop
+npx --prefer-offline --yes copilotkit@4.18.0 onboard read feature/stop
 ```
 
 When the audit passes, run
-`npx --prefer-offline --yes copilotkit@4.16.0 onboard read feature/complete` with the actual browser-proof
+`npx --prefer-offline --yes copilotkit@4.18.0 onboard read feature/complete` with the actual browser-proof
 outcome.