copilotkit 4.17.0 → 4.18.0

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

@@ -1,228 +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.17.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.
+- `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.
 
-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.
+Carry it into the planning handoff. Never spell the id yourself: two spellings give one
+project two containers.
 
-## Settle the Learning Container for this project
+## Check the model credential
 
-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:
+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.17.0 learning containers default-id --json
+npx --prefer-offline --yes copilotkit@4.18.0 onboard credentials --model-key <variable> --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.17.0 learning containers get <id> --json
-```
+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`:
 
-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.
-
-Never invent an id, scrape a dashboard, or treat an arbitrary string as a container.
-
-Report what the read found, before anything is planned:
-
-```text
-npx --prefer-offline --yes copilotkit@4.17.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.17.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.
-
-## Check that the vendor accepts the model credential
-
-When a model credential is in place, ask the vendor whether the key can pay for a model
-call. Run this once for each model credential variable the plan names, from the
-target app directory, with the env file the application reads it from:
-
-```text
-npx --prefer-offline --yes copilotkit@4.17.0 onboard model-key --key <variable name> --env-file <env file> --json
-```
-
-The command reads the value itself and sends one request with a one-token answer to that
-vendor. It never prints the value, so you still do not read it. Read `status` from the
-payload:
-
-- `pass`: the vendor served a model call with this key. Continue.
-- `fail`: the vendor refused the key, and it will refuse every model call the application
-  makes. `cause` says why. `model_quota` means the key has no credits. `model_auth` means
-  the vendor rejected the key. Tell the developer that exact cause, and offer the choices:
-  add credits, use another key, or switch the model provider. Then report the pause the
-  way the section above does, and end your turn. When the developer answers, place the
-  new credential and run this check again.
-- `missing`: there is no real value to check. `reason` says which file or key is empty.
-  Go back to the section above and ask the developer where the credential lives.
-- `unsupported` or `undetermined`: the check did not settle it. Name the `reason` in the
-  closing report and continue. `custom-endpoint` means a base URL sends the key to
-  another endpoint, such as a local Ollama, so the vendor was not asked.
-  `environment-override` means the shell sets a different value for the key, and the
-  application reads that value first. Do not stop the
-  run for either status.
-
-Do not skip a `fail` to save time. The next model call is the round-trip proof, after the
-whole build, and it reports a dead key only as a timeout that names no key.
-
-## Protect the credential paths
-
-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.17.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:
-
-```text
-npx --prefer-offline --yes copilotkit@4.17.0 onboard protect --rebaseline --path <path>
-```
-
-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.
-
-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.17.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. Then run the vendor check above
-  for the credential the developer added.
-- `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.17.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.17.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.
@@ -62,8 +62,17 @@ proof subagents:
 
 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.17.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
@@ -74,7 +83,7 @@ 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.17.0 onboard read stopped/run-failed`. A plan this run cannot
+`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
@@ -122,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.17.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.17.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

@@ -9,14 +9,14 @@ This fallback contains unproved steps. Use the approved plan in step order.
 
 Several rules below stop onboarding: a blocked or third failed implementation result, a
 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. Run the friction
-command without another developer question. Do not ask the developer about telemetry: the
-command applies the setting they already have.
+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.17.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.
@@ -62,19 +62,19 @@ or frontend, stop onboarding.
 
 Use these rules for every protected-path check in this fallback:
 
-- Run `npx --prefer-offline --yes copilotkit@4.17.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 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.17.0 onboard protect --accept-credential --path <path>`,
+  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.17.0 onboard protect --accept-external --path <path>`, run the
+  `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.
 - 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
@@ -127,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.17.0 onboard complete`, carrying the
+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.17.0 onboard complete --visual-check <outcome>
-npx --prefer-offline --yes copilotkit@4.17.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

@@ -18,7 +18,7 @@ without exposing secrets.
 Before you spawn the implementation subagent, take the authorized list from the CLI:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.17.0 onboard audit
+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
@@ -37,7 +37,7 @@ still go on the record. Name the file and why the work needs it, then end your t
 for the developer's answer. If they allow it, record their answer before any edit:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.17.0 onboard protect --authorize --unplanned --path <path> --reason "<what the developer said>"
+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
@@ -49,7 +49,7 @@ feature stop route below.
 After validation and each repair, run:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.17.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
@@ -60,7 +60,7 @@ 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.17.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
@@ -73,17 +73,17 @@ 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.17.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.17.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.17.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

@@ -27,7 +27,7 @@ still go on the record. Name the file and why the fix needs it, then end your tu
 for the developer's answer. If they allow it, record their answer before any edit:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.17.0 onboard protect --authorize --unplanned --path <path> --reason "<what the developer said>"
+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
@@ -39,23 +39,23 @@ route below.
 Report each attempt at the proof as it ends, counting from one:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.17.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.17.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.17.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.17.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
@@ -70,9 +70,9 @@ the path and the change the audit reports. Run the audit again after each accept
 If the audit still fails, or starts with `Status: blocked`, route out and stop:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.17.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.17.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.

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

@@ -1,13 +1,57 @@
 # Add A2UI to the existing CopilotKit app
 
 Treat this as an additive OSS feature integration, not a new-app scaffold. Act as the
-orchestrator and delegate inspection, implementation, and proof to focused subagents.
-Work only inside the target project. Do not show internal prompt names to the developer.
+orchestrator and delegate inspection, implementation, and proof to focused subagents. Work
+only inside the target project. Prompt names are this graph's own bookkeeping. Say what the
+run is doing in the developer's words instead.
+
+## Waits, stops, and subagents
+
+A run that starts here has not read these rules yet, so they come first. They cover this
+prompt and every later one.
+
+Spawning a subagent returns almost at once. That return is the dispatch succeeding, not the
+work finishing: the result reaches you as a notification, or with the dispatch itself where
+your harness works that way. Do the work that does not depend on the result, then end your
+turn and wait for the result. That wait is a pause. Do not sleep or poll.
+
+A subagent that returns no usable result failed in your harness, not in this graph. Every
+assignment here is work you can do yourself, slower, so run that assignment yourself and
+carry on. Keep a read-only assignment read-only. If no subagent works at all, report it
+once:
+
+```text
+npx --prefer-offline --yes copilotkit@4.18.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.18.0 onboard checkpoint --phase awaiting-developer
+```
+
+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.
+
+If you stop this run, 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.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.
+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. 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. A stop that
+routes to `feature/stop` sends no report here: that prompt first asks the developer about
+one scoped fix, and sends the report itself when no fix is approved.
 
 Before any subagent or project process runs, capture the developer's existing work:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.17.0 onboard protect
+npx --prefer-offline --yes copilotkit@4.18.0 onboard protect
 ```
 
 Keep the exact protected path list it prints and give that list to every subagent. No
@@ -22,13 +66,13 @@ 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.17.0 verify --expect-runtime oss --round-trip --agent <agent-id> --json`.
+`npx --prefer-offline --yes copilotkit@4.18.0 verify --expect-runtime oss --round-trip --agent <agent-id> --json`.
 Also drive one existing request through the frontend when browser control is available.
 
 Wait for the inspection subagent to finish. Then report that the inspection came back:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.17.0 onboard checkpoint --phase research-returned
+npx --prefer-offline --yes copilotkit@4.18.0 onboard checkpoint --phase research-returned
 ```
 
 A refused checkpoint prints its reason and leaves onboarding unaffected. It is not a
@@ -38,7 +82,7 @@ If the inspection did not prove the baseline this intent extends, stop here with
 changing files:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.17.0 onboard read feature/stop
+npx --prefer-offline --yes copilotkit@4.18.0 onboard read feature/stop
 ```
 
 Do not run `login`, select an Intelligence project, add an Intelligence client, mint a
@@ -62,7 +106,7 @@ one.
 After approval, record each approved path before implementation:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.17.0 onboard protect --authorize --path <path> --reason "<the plan's sentence>"
+npx --prefer-offline --yes copilotkit@4.18.0 onboard protect --authorize --path <path> --reason "<the plan's sentence>"
 ```
 
 If an approved path changed after capture and no implementation step has run, add
@@ -72,7 +116,7 @@ authorize a path the approved plan did not list.
 Then report the plan this run is about to implement:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.17.0 onboard checkpoint --phase plan-written
+npx --prefer-offline --yes copilotkit@4.18.0 onboard checkpoint --phase plan-written
 ```
 
-Then run `npx --prefer-offline --yes copilotkit@4.17.0 onboard read feature/a2ui/implement`.
+Then run `npx --prefer-offline --yes copilotkit@4.18.0 onboard read feature/a2ui/implement`.