copilotkit 4.9.60 → 4.10.0

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

@@ -1,4 +1,4 @@
-# Select the Intelligence project and create the plan
+# Select the Intelligence project
 
 Use the selected framework, frontend, model vendor, model, documentation URLs, and
 repository findings. On a conversion these were read from the baseline rather than
@@ -19,14 +19,18 @@ that reports a false field, a failed credential check, a model credential nobody
 place. Each one ends a run that reached project selection and never got a plan, and more
 runs stop here than anywhere else. Name the exact file, value, or check that stopped you:
 a report that names only the step cannot be acted on. Send one short report before you
-stop. Run the feedback command without another developer question. The CLI telemetry gate
+stop. Run the friction command without another developer question. The CLI telemetry gate
 decides whether the report is sent.
 
 ```text
-npx --yes copilotkit@4.9.60 onboard feedback
+npx --yes copilotkit@4.10.0 onboard friction --phase stop --category <slug>
 ```
 
-Write at most four lines to standard input: the step you stopped at and what stopped it.
+Write one or two sentences to standard input: 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. The command refuses a report that
 carries any of those, prints the reason, and exits zero. A refused report is not a failed
 step. Send the report, then stop the way the rule that stopped you says to. Reporting is
@@ -54,7 +58,7 @@ the command refuses one of them from a run that was served that node.
 Run this command with the exact selected slugs:
 
 ```text
-npx --yes copilotkit@4.9.60 onboard classify --starting-state <starting-state> --agent-framework <agent-framework> --frontend <frontend>
+npx --yes copilotkit@4.10.0 onboard classify --starting-state <starting-state> --agent-framework <agent-framework> --frontend <frontend>
 ```
 
 Do not continue if a value is refused. Fix the value from the choices that the earlier
@@ -148,7 +152,7 @@ passes against the wrong one.
 Create it, from the target directory:
 
 ```text
-npx --yes copilotkit@4.9.60 project select --create <name> --json
+npx --yes copilotkit@4.10.0 project select --create <name> --json
 ```
 
 If the command fails as a duplicate, the organization already holds that display name and
@@ -162,13 +166,13 @@ Take this branch only when the developer asks for an existing project, or asks t
 projects they have. Read the choices:
 
 ```text
-npx --yes copilotkit@4.9.60 project list --json
+npx --yes copilotkit@4.10.0 project list --json
 ```
 
 Narrow them:
 
 ```text
-npx --yes copilotkit@4.9.60 project list --search <query> --json
+npx --yes copilotkit@4.10.0 project list --search <query> --json
 ```
 
 With `--json` the payload is the only thing on standard output, so it is safe to parse. Do
@@ -180,7 +184,7 @@ this directory's.
 Then record the project they name, from the target directory:
 
 ```text
-npx --yes copilotkit@4.9.60 project select --project <slug-or-id> --json
+npx --yes copilotkit@4.10.0 project select --project <slug-or-id> --json
 ```
 
 The two flags cannot be combined. A slug that does not exist fails and lists the real ones,
@@ -221,123 +225,5 @@ Continue only if the environment follow-up result starts with `Status: passed`.
 project-record path and environment path as the credential setup path list. Do not add them
 to the baseline yet.
 
-## 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.
-
-If no answer comes, stop. Do not write a placeholder or an empty value. A scaffold
-carrying a dummy key looks finished and fails at the first model call, which is worse
-than stopping here.
-
-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 --yes copilotkit@4.9.60 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.
-
-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 --yes copilotkit@4.9.60 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 --yes copilotkit@4.9.60 onboard protect --accept-credential --path <environment path>
-```
-
-The command compares the variable names the baseline recorded with the names the file holds
-now. Read its result:
-
-- `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.
-
-## Wire the runtime to Intelligence
-
-The key in `.env` does nothing on its own. The runtime reads no environment variable for
-it. The credential reaches the platform only when the runtime is constructed with an
-Intelligence client, and a runtime built without one compiles, serves, answers in a
-browser, and never touches the platform.
-
-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/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.
-
-Spawn one planning subagent. Tell it to run
-`npx --yes copilotkit@4.9.60 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
-variable names, selected documentation URLs, and documentation policy. On a conversion, also
-give it the frozen criterion. Give the planning subagent the updated protected path list.
-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, use the unsupported route below. 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
-credential variables, the Intelligence runtime wiring, the application the project asks
-for, implementation steps, validation steps, and proof steps. Where the plan upgrades the
-CopilotKit dependencies, it must name the versions it moves, every other pin it has to
-move with them, and the revert it falls back to. It must not contain secret values.
-
-Show only the selected framework, frontend, model, planned file changes, any ignore-file line this run adds, the CopilotKit dependency upgrade and the versions it moves, every other dependency the upgrade moves and the versions it moves them to, validation commands, and proof steps.
-
-An upgrade to a working install is the developer's call, so it belongs in the plan they
-approve rather than in the implementation that follows. Do not upgrade a dependency the
-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 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 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.
-
-If the developer approves the plan, run
-`npx --yes copilotkit@4.9.60 onboard read implementation/build-and-validate`.
-
-If no exact supported path or documentation URL exists, run
-`npx --yes copilotkit@4.9.60 onboard read unsupported/no-validated-path`.
+When project selection is settled, run
+`npx --yes copilotkit@4.10.0 onboard read credentials/settle-credentials`.

package/onboarding/prompts/credentials/plan.md

@@ -68,26 +68,26 @@ another framework. Do not show the internal route.
 
 Use exactly one matching internal route:
 
-1. AG2: `npx --yes copilotkit@4.9.60 onboard read framework/ag2`
-2. Agno: `npx --yes copilotkit@4.9.60 onboard read framework/agno`
-3. Built-in CopilotKit agent: `npx --yes copilotkit@4.9.60 onboard read framework/built-in`
-4. Claude Agent SDK Python: `npx --yes copilotkit@4.9.60 onboard read framework/claude-sdk-python`
-5. Claude Agent SDK TypeScript: `npx --yes copilotkit@4.9.60 onboard read framework/claude-sdk-typescript`
-6. CrewAI Flows: `npx --yes copilotkit@4.9.60 onboard read framework/crewai-flows`
-7. Deep Agents: `npx --yes copilotkit@4.9.60 onboard read framework/deep-agents`
-8. LangGraph Python: `npx --yes copilotkit@4.9.60 onboard read framework/langgraph-python`
-9. LangGraph FastAPI: `npx --yes copilotkit@4.9.60 onboard read framework/langgraph-fastapi`
-10. LangGraph TypeScript: `npx --yes copilotkit@4.9.60 onboard read framework/langgraph-typescript`
-11. LlamaIndex: `npx --yes copilotkit@4.9.60 onboard read framework/llamaindex`
-12. ADK: `npx --yes copilotkit@4.9.60 onboard read framework/google-adk`
-13. Microsoft Agent Framework Python: `npx --yes copilotkit@4.9.60 onboard read framework/ms-agent-python`
-14. Microsoft Agent Framework .NET: `npx --yes copilotkit@4.9.60 onboard read framework/ms-agent-dotnet`
-15. Mastra: `npx --yes copilotkit@4.9.60 onboard read framework/mastra`
-16. MS Agent Harness .NET: `npx --yes copilotkit@4.9.60 onboard read framework/ms-agent-harness-dotnet`
-17. Pydantic AI: `npx --yes copilotkit@4.9.60 onboard read framework/pydantic-ai`
-18. Strands Agents Python: `npx --yes copilotkit@4.9.60 onboard read framework/strands-python`
-19. Strands Agents TypeScript: `npx --yes copilotkit@4.9.60 onboard read framework/strands-typescript`
+1. AG2: `npx --yes copilotkit@4.10.0 onboard read framework/ag2`
+2. Agno: `npx --yes copilotkit@4.10.0 onboard read framework/agno`
+3. Built-in CopilotKit agent: `npx --yes copilotkit@4.10.0 onboard read framework/built-in`
+4. Claude Agent SDK Python: `npx --yes copilotkit@4.10.0 onboard read framework/claude-sdk-python`
+5. Claude Agent SDK TypeScript: `npx --yes copilotkit@4.10.0 onboard read framework/claude-sdk-typescript`
+6. CrewAI Flows: `npx --yes copilotkit@4.10.0 onboard read framework/crewai-flows`
+7. Deep Agents: `npx --yes copilotkit@4.10.0 onboard read framework/deep-agents`
+8. LangGraph Python: `npx --yes copilotkit@4.10.0 onboard read framework/langgraph-python`
+9. LangGraph FastAPI: `npx --yes copilotkit@4.10.0 onboard read framework/langgraph-fastapi`
+10. LangGraph TypeScript: `npx --yes copilotkit@4.10.0 onboard read framework/langgraph-typescript`
+11. LlamaIndex: `npx --yes copilotkit@4.10.0 onboard read framework/llamaindex`
+12. ADK: `npx --yes copilotkit@4.10.0 onboard read framework/google-adk`
+13. Microsoft Agent Framework Python: `npx --yes copilotkit@4.10.0 onboard read framework/ms-agent-python`
+14. Microsoft Agent Framework .NET: `npx --yes copilotkit@4.10.0 onboard read framework/ms-agent-dotnet`
+15. Mastra: `npx --yes copilotkit@4.10.0 onboard read framework/mastra`
+16. MS Agent Harness .NET: `npx --yes copilotkit@4.10.0 onboard read framework/ms-agent-harness-dotnet`
+17. Pydantic AI: `npx --yes copilotkit@4.10.0 onboard read framework/pydantic-ai`
+18. Strands Agents Python: `npx --yes copilotkit@4.10.0 onboard read framework/strands-python`
+19. Strands Agents TypeScript: `npx --yes copilotkit@4.10.0 onboard read framework/strands-typescript`
 
 If the project has an agent in another framework, or no listed framework fits, keep the
 developer's current agent and run
-`npx --yes copilotkit@4.9.60 onboard read unsupported/no-validated-path`.
+`npx --yes copilotkit@4.10.0 onboard read unsupported/no-validated-path`.

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

@@ -0,0 +1,153 @@
+# Settle the Learning Container and 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.
+
+## 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. The CLI telemetry gate decides whether
+the report is sent.
+
+```text
+npx --yes copilotkit@4.10.0 onboard friction --phase stop --category <slug>
+```
+
+Write one or two sentences to standard input: 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.
+
+## 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, and a thread takes its
+container before its first agent run. A thread whose agent already ran can never receive a
+first assignment later, so every thread the developer creates between this run and some
+later `add-learning` run is lost to Learning for good. Setting it up here is not a
+convenience. It is the only point at which this project's first threads can be reached.
+
+Derive the id from the selected project slug: lowercase it, replace each run of characters
+outside `a-z0-9` with one hyphen, drop a leading or trailing hyphen, cut the result to 64
+characters, and drop a trailing hyphen the cut leaves behind. The container id contract is
+1-64 lowercase letters, numbers, and single hyphens, so an id that skips the last step
+fails the create call on the developer's behalf. Derive it this exact way: the
+`add-learning` intent derives the same id from the same slug, and two spellings of one
+project's id give it two containers, each below the 15-conversation line on its own.
+
+One container for this project is the default scope. If the slug leaves nothing usable,
+skip this step and name the skip, rather than inventing a name.
+
+Then ask the platform about that id, from the target directory:
+
+```text
+npx --yes copilotkit@4.10.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.
+
+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 --yes copilotkit@4.10.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.
+
+If no answer comes, stop. Do not write a placeholder or an empty value. A scaffold
+carrying a dummy key looks finished and fails at the first model call, which is worse
+than stopping here.
+
+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 --yes copilotkit@4.10.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 --yes copilotkit@4.10.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 --yes copilotkit@4.10.0 onboard protect --accept-credential --path <environment path>
+```
+
+The command compares the variable names the baseline recorded with the names the file holds
+now. Read its result:
+
+- `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.
+
+When the credential question is answered, run
+`npx --yes copilotkit@4.10.0 onboard read credentials/write-plan`.

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

@@ -0,0 +1,93 @@
+# Write the plan and get it approved
+
+The project and its credentials are settled. This phase wires the runtime, has a
+subagent write the plan, and asks the developer to approve it. This is the last thing
+the run needs from 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. The CLI telemetry gate decides whether
+the report is sent.
+
+```text
+npx --yes copilotkit@4.10.0 onboard friction --phase stop --category <slug>
+```
+
+Write one or two sentences to standard input: 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.
+
+## Wire the runtime to Intelligence
+
+The key in `.env` does nothing on its own. The runtime reads no environment variable for
+it. The credential reaches the platform only when the runtime is constructed with an
+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.
+
+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/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.
+
+Spawn one planning subagent. Tell it to run
+`npx --yes copilotkit@4.10.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
+variable names, selected documentation URLs, and documentation policy. On a conversion, also
+give it the frozen criterion. Give the planning subagent the updated protected path list.
+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 --yes copilotkit@4.10.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
+ask for approval of a non-pass plan.
+
+Make sure that the plan preserves each part that already exists. The plan must name the
+credential variables, the Intelligence runtime wiring, the application the project asks
+for, implementation steps, validation steps, and proof steps. Where the plan upgrades the
+CopilotKit dependencies, it must name the versions it moves, every other pin it has to
+move with them, and the revert it falls back to. It must not contain secret values.
+
+Show only the selected framework, frontend, model, planned file changes, any ignore-file line this run adds, the CopilotKit dependency upgrade and the versions it moves, every other dependency the upgrade moves and the versions it moves them to, validation commands, and proof steps.
+
+An upgrade to a working install is the developer's call, so it belongs in the plan they
+approve rather than in the implementation that follows. Do not upgrade a dependency the
+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 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 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.
+
+If the developer approves the plan, run
+`npx --yes copilotkit@4.10.0 onboard read implementation/build-and-validate`.
+
+If no exact supported path or documentation URL exists, run
+`npx --yes copilotkit@4.10.0 onboard read unsupported/no-validated-path`.

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

@@ -9,15 +9,18 @@ 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
 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 feedback
-command without another developer question. The CLI telemetry gate decides whether the
+existing agent or frontend. Send one short report before you stop. Run the friction command without another developer question. The CLI telemetry gate decides whether the
 report is sent.
 
 ```text
-npx --yes copilotkit@4.9.60 onboard feedback
+npx --yes copilotkit@4.10.0 onboard friction --phase stop --category <slug>
 ```
 
-Write at most four lines to standard input: the step you stopped at and what stopped it.
+Write one or two sentences to standard input: 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. The command refuses a report that
 carries any of those, prints the reason, and exits zero. A refused report is not a failed
 step. Send the report, then stop the way the rule that stopped you says to. This fallback
@@ -56,13 +59,13 @@ stop.
 
 Use these rules for every protected-path check in this fallback:
 
-- Run `npx --yes copilotkit@4.9.60 onboard audit` from the target app directory.
+- Run `npx --yes copilotkit@4.10.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 --yes copilotkit@4.9.60 onboard protect --accept-external --path <path>`, run the
+  `npx --yes copilotkit@4.10.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
@@ -115,13 +118,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 --yes copilotkit@4.9.60 onboard complete`, carrying the
+When the proof is complete, run `npx --yes copilotkit@4.10.0 onboard complete`, carrying the
 surface-check result the proof subagent returned. Pass exactly one flag, matching this
 journey's surface:
 
 ```text
-npx --yes copilotkit@4.9.60 onboard complete --visual-check <outcome>
-npx --yes copilotkit@4.9.60 onboard complete --device-check <outcome>
+npx --yes copilotkit@4.10.0 onboard complete --visual-check <outcome>
+npx --yes copilotkit@4.10.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,18 +15,47 @@ 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.
 
-When implementation validation passes, report it:
+After validation and each repair, run:
+
+```text
+npx --yes copilotkit@4.10.0 onboard audit
+```
+
+Continue only when it starts with `Status: passed`. A path under `Authorized to change:` is
+not a finding. Carry it into the final summary with its reason.
+
+If the audit fails, never repair, reset, or revert a protected path. Compare each named path
+with the implementation subagent's `Files changed` section. If that section does not name
+the path, accept the developer's external change:
+
+```text
+npx --yes copilotkit@4.10.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 --yes copilotkit@4.10.0 onboard protect --authorize --unplanned --path <path> --reason "<what the developer said>"
+```
+
+Run the audit again after each accepted or authorized change. If it still fails, or starts
+with `Status: blocked`, route out and stop:
 
 ```text
-npx --yes copilotkit@4.9.60 onboard checkpoint --phase build-validated
+npx --yes copilotkit@4.10.0 onboard read feature/stop
 ```
 
-If validation cannot pass, or this intent needs a prerequisite the app does not have, stop
-without further changes:
+When implementation validation passes, report it:
 
 ```text
-npx --yes copilotkit@4.9.60 onboard read feature/stop
+npx --yes copilotkit@4.10.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 --yes copilotkit@4.9.60 onboard read feature/a2ui/proof`.
+`npx --yes copilotkit@4.10.0 onboard read feature/a2ui/proof`.

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

@@ -19,16 +19,40 @@ user's agent response with a hard-coded UI.
 Report each attempt at the proof as it ends, counting from one:
 
 ```text
-npx --yes copilotkit@4.9.60 onboard checkpoint --phase journey-attempted --attempt 1
+npx --yes copilotkit@4.10.0 onboard checkpoint --phase journey-attempted --attempt 1
 ```
 
 Report each repair cycle the same way, counting from one:
 
 ```text
-npx --yes copilotkit@4.9.60 onboard checkpoint --phase repair-attempted --attempt 1
+npx --yes copilotkit@4.10.0 onboard checkpoint --phase repair-attempted --attempt 1
 ```
 
-When the actual surface was driven, run
-`npx --yes copilotkit@4.9.60 onboard complete --visual-check performed`. If it could not
-be driven because no browser tool is available, run the same command with
-`--visual-check skipped-no-browser-tool`; if it failed, use `--visual-check failed`.
+After the final attempt, report the gate exactly once:
+
+```text
+npx --yes copilotkit@4.10.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 --yes copilotkit@4.10.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
+with the proof subagent's `Files changed` section. If that section does not name the path,
+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.
+
+If the audit still fails, or starts with `Status: blocked`, route out and stop:
+
+```text
+npx --yes copilotkit@4.10.0 onboard read feature/stop
+```
+
+When the audit passes, run
+`npx --yes copilotkit@4.10.0 onboard read feature/complete` with the actual browser-proof
+outcome.