copilotkit 4.16.0 → 4.17.0

package/onboarding/index.json

@@ -1,5 +1,5 @@
 {
-  "graphTree": "a8ea88ef874865c0c245c2ae4df6221a8667b569",
+  "graphTree": "fa93f36f3c0d982c90097ddd1e4c056a286cd83a",
   "intentRoots": {
     "add-a2ui": "feature/a2ui/start",
     "add-chat-suggestions": "feature/chat-suggestions/start",

package/onboarding/prompts/authenticate/start.md

@@ -15,7 +15,7 @@ does is hidden from the developer.
 Run each CLI call exactly as written, as its own command: no pipe, `tee`, `&&`, redirect,
 or variable prefix. If your harness asks the developer to approve commands, request
 escalation on the `onboard identify` call with the prefix rule
-`["npx", "--prefer-offline", "--yes", "copilotkit@4.16.0"]`. Every CLI call in this run
+`["npx", "--prefer-offline", "--yes", "copilotkit@4.17.0"]`. Every CLI call in this run
 matches it. Say then that the install, the dev servers, `curl` to the local app, and `ps`,
 `lsof`, and `kill` ask for approval later.
 
@@ -24,10 +24,12 @@ matches it. Say then that the install, the dev servers, `curl` to the local app,
 Run this before anything else in this prompt, including the welcome message below:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.16.0 onboard identify --coding-agent <coding-agent-slug>
+npx --prefer-offline --yes copilotkit@4.17.0 onboard identify --coding-agent <coding-agent-slug> --model <model-id>
 ```
 
-Report your own product with one short slug, such as `codex` or `claude-code`.
+Report your own product with one short slug, such as `codex` or `claude-code`. For
+`--model`, give the exact model id your instructions name. If they name none, leave out
+`--model` rather than guess.
 
 ## How to run this onboarding
 
@@ -47,10 +49,10 @@ printed once.
 Every later command must run from the directory this run started in. A command run
 somewhere else is refused, because the run it belongs to cannot be found from there. That
 refusal is a step, not a stop to report: run
-`npx --prefer-offline --yes copilotkit@4.16.0 onboard start --run <onboarding_run_id>` where you are
+`npx --prefer-offline --yes copilotkit@4.17.0 onboard start --run <onboarding_run_id>` where you are
 standing, then run the refused command again.
 
-If you no longer hold the id, run `npx --prefer-offline --yes copilotkit@4.16.0 onboard start` in the
+If you no longer hold the id, run `npx --prefer-offline --yes copilotkit@4.17.0 onboard start` in the
 directory this run started in, with no `--run` and no `--intent`. It reprints the id of the
 run under way and starts nothing. An id this project does not already hold starts a second
 run, and the work already done stops counting toward the first.
@@ -113,11 +115,12 @@ record to the repository root by itself and prints where it put it.
 This run reports its own stops. If you stop this run at any point, send one short report
 before you stop. That covers a stop this prompt names, a stop a later prompt names, and a
 stop no prompt anticipated, including one your own harness causes. A turn that ends while
-the run waits is a pause, not a stop, even when your harness ends it. Run the friction
-command without another developer question.
+the run waits is a pause, not a stop, even when your harness ends it. A terminal that
+sends the report itself, or says to file none, overrides this.
+Run the friction command without another developer question.
 
 ```text
-npx --prefer-offline --yes copilotkit@4.16.0 onboard friction --phase stop --category <slug> --message "<sentences>"
+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.
@@ -127,13 +130,12 @@ sdk-gap, environment, port-collision, credential, validation-loop, and other. Le
 report that carries any of those, prints the reason, and exits zero. A refused report is
 not a failed step. Reword it and send it again, or stop without a report.
 
-Reporting a stop is not a route change. It does not resume the run, it is not a question
-for the developer, and it does not replace whatever the rule that stopped you says to do
-next: send the report, then stop.
+Reporting a stop is not a route change. It does not resume the run or replace what the
+rule that stopped you says next: send the report, then stop.
 
 ## Check sign-in
 
-Run `npx --prefer-offline --yes copilotkit@4.16.0 login --json` before any project work. This command
+Run `npx --prefer-offline --yes copilotkit@4.17.0 login --json` before any project work. This command
 checks the current session. It starts sign-in only as needed. Treat this as a long-lived
 streaming process. Do not wait for the command to exit before you read its standard output.
 
@@ -167,7 +169,7 @@ Read each JSON Lines record as the running command writes it:
    second login command. Do not treat the opener command finishing as sign-in finishing.
 6. Continue onboarding only after that same process emits `type: completed`.
 7. On `type: failed` with `reason: expired`, ask once whether to retry. If yes, start one
-   new `login --json`.
+   new `login --json`. Use `--force` only when the developer asks.
 8. If that process emits `type: failed`, report the error and stop onboarding.
 
 If your harness ends the login process or your turn before the process emits
@@ -180,8 +182,8 @@ Do not use `whoami` for this check. Do not put account tokens or credentials in
 conversation.
 
 When sign-in is settled, run
-`npx --prefer-offline --yes copilotkit@4.16.0 onboard read research/gather`.
+`npx --prefer-offline --yes copilotkit@4.17.0 onboard read research/gather`.
 
 If sign-in stops onboarding, run
-`npx --prefer-offline --yes copilotkit@4.16.0 onboard read stopped/run-failed`. It says nothing about
+`npx --prefer-offline --yes copilotkit@4.17.0 onboard read stopped/run-failed`. It says nothing about
 whether this project's stack is supported, which is not yet known at this point.

package/onboarding/prompts/conversion/plan.md

@@ -100,7 +100,7 @@ of this journey, and a drawer that lists nothing is not a reason to mint one. Li
 tokens stay a self-hosted concern.
 
 Where this journey's frontend framework ships no threads drawer -- React Native --, the
-fifth item is proved by `npx --prefer-offline --yes copilotkit@4.16.0 verify --round-trip`, which sends a
+fifth item is proved by `npx --prefer-offline --yes copilotkit@4.17.0 verify --round-trip`, which sends a
 real request and reads the answer back off the thread it landed on. The run says which of
 the two it proved. Do not send a run to the managed Intelligence dashboard to prove this.
 An authenticated browser session at a hosted dashboard is the one thing an agent-driven run
@@ -116,7 +116,7 @@ and passed -- so a run scored on either one was scored on the same fact. Every r
 resolves that condition from, while `licenseStatus` is a compatibility projection of it
 for older thread surfaces and outlives them only until those surfaces go.
 
-Then run `npx --prefer-offline --yes copilotkit@4.16.0 onboard read credentials/finalize-plan`.
+Then run `npx --prefer-offline --yes copilotkit@4.17.0 onboard read credentials/finalize-plan`.
 
 If a selected page does not load after the second method, run
-`npx --prefer-offline --yes copilotkit@4.16.0 onboard read unsupported/no-validated-path`.
+`npx --prefer-offline --yes copilotkit@4.17.0 onboard read unsupported/no-validated-path`.

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

@@ -15,23 +15,22 @@ question.
 
 ## If you stop in this phase
 
-Several rules below stop onboarding: a refused classification value, a project selection
-that reports a false field, a failed credential check, a model credential nobody can
-place. Each one ends a run that reached project selection and never got a plan. 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 friction command without another
+Several rules below stop onboarding: an environment path that cannot be made ignored, a
+project selection that reports a false field, a project record written somewhere other
+than the expected path, and a failed credential check. Each one ends a run that never got
+a plan. Name the exact file, value, or check that stopped you, not only the step. 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.
 
 ```text
-npx --prefer-offline --yes copilotkit@4.16.0 onboard friction --phase stop --category <slug> --message "<sentences>"
+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.
+--cost-seconds off: a stopped run cannot separate one papercut's cost from the whole run's.
 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
@@ -59,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 --prefer-offline --yes copilotkit@4.16.0 onboard classify --starting-state <starting-state> --agent-framework <agent-framework> --frontend <frontend>
+npx --prefer-offline --yes copilotkit@4.17.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
@@ -72,7 +71,8 @@ the runtime `.env` file, do not default to the repository root.
 Set the environment path to `<target>/.env`.
 
 Every credential this run writes goes to the environment path. That covers the project
-key and the model credential. Do not write a credential to `.env.local`, or to any second
+key and the model credential, unless the framework node names another location for the
+model credential. Do not write a credential to `.env.local`, or to any second
 env file beside it. A project ignore file usually covers `.env` and not
 `.env.local`, so a credential written there is untracked, visible, and added by the first
 `git add -A`. And a second env file beside `.env` outranks it when a key is read back, so
@@ -125,9 +125,8 @@ that provisions its key.
 
 If an output path overlaps a `protected` path, do not stop. Name the path, say what
 project selection writes there, list that file in the plan with every other change, and
-carry on. Nothing before project selection ends the run. It is the step that provisions
-this project's key, so a run that stops earlier leaves the developer with no key and no
-way to finish.
+carry on. A `protected` path overlap does not end the run. Project selection provisions
+this project's key, so a stop here leaves the developer with no key and no way to finish.
 
 ### Create a project for this directory
 
@@ -156,7 +155,7 @@ passes against the wrong one.
 Create it, from the target directory, passing the port research settled:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.16.0 project select --create <name> \
+npx --prefer-offline --yes copilotkit@4.17.0 project select --create <name> \
   --runtime-url http://localhost:<port>/api/copilotkit --json
 ```
 
@@ -174,13 +173,13 @@ Take this branch only when the developer asks for an existing project, or asks t
 projects they have. Read the choices:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.16.0 project list --json
+npx --prefer-offline --yes copilotkit@4.17.0 project list --json
 ```
 
 Narrow them:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.16.0 project list --search <query> --json
+npx --prefer-offline --yes copilotkit@4.17.0 project list --search <query> --json
 ```
 
 With `--json` the payload is the only thing on standard output, so it is safe to parse. Do
@@ -193,7 +192,7 @@ Then record the project they name, from the target directory, with the same
 `--runtime-url`:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.16.0 project select --project <slug-or-id> \
+npx --prefer-offline --yes copilotkit@4.17.0 project select --project <slug-or-id> \
   --runtime-url http://localhost:<port>/api/copilotkit --json
 ```
 
@@ -220,8 +219,9 @@ onboarding.
 Never print the payload or any secret value.
 
 After project reuse or a warning-free selection result, send the environment
-research subagent a focused follow-up check. Give it the exact target app directory and both
-credential paths. Require it to report these facts without values:
+research subagent a focused follow-up check. Give it the exact target app directory, both
+credential paths, and the `.env` modification time the inspection returned. Require it to
+report these facts without values:
 
 - The project-record path has non-empty `projectId` and `projectSlug` fields. Unless
   `COPILOTKIT_DEPLOYMENT` is `self-hosted`, it also has a non-empty `clerkOrgId` field.
@@ -238,4 +238,4 @@ project-record path and environment path as the credential setup path list. Do n
 to the baseline yet.
 
 When project selection is settled, run
-`npx --prefer-offline --yes copilotkit@4.16.0 onboard read credentials/settle-credentials`.
+`npx --prefer-offline --yes copilotkit@4.17.0 onboard read credentials/settle-credentials`.

package/onboarding/prompts/credentials/plan.md

@@ -20,7 +20,7 @@ If the target directory holds no project and the copied prompt came from the Sla
 Microsoft Teams docs page, do not ask the framework question. The Channel starter brings
 its own agent, so an answer here decides nothing. Tell the developer that the Channel
 starter decides the agent, then run
-`npx --prefer-offline --yes copilotkit@4.16.0 onboard read frontend/plan`.
+`npx --prefer-offline --yes copilotkit@4.17.0 onboard read frontend/plan`.
 
 Use a gentle wizard. Ask one short question at a time. Do not combine separate choices in
 one question. Put the recommendation first, give its evidence in one sentence, and keep
@@ -74,26 +74,26 @@ another framework. Do not show the internal route.
 
 Use exactly one matching internal route:
 
-1. AG2: `npx --prefer-offline --yes copilotkit@4.16.0 onboard read framework/ag2`
-2. Agno: `npx --prefer-offline --yes copilotkit@4.16.0 onboard read framework/agno`
-3. Built-in CopilotKit agent: `npx --prefer-offline --yes copilotkit@4.16.0 onboard read framework/built-in`
-4. Claude Agent SDK Python: `npx --prefer-offline --yes copilotkit@4.16.0 onboard read framework/claude-sdk-python`
-5. Claude Agent SDK TypeScript: `npx --prefer-offline --yes copilotkit@4.16.0 onboard read framework/claude-sdk-typescript`
-6. CrewAI Flows: `npx --prefer-offline --yes copilotkit@4.16.0 onboard read framework/crewai-flows`
-7. Deep Agents: `npx --prefer-offline --yes copilotkit@4.16.0 onboard read framework/deep-agents`
-8. LangGraph Python: `npx --prefer-offline --yes copilotkit@4.16.0 onboard read framework/langgraph-python`
-9. LangGraph FastAPI: `npx --prefer-offline --yes copilotkit@4.16.0 onboard read framework/langgraph-fastapi`
-10. LangGraph TypeScript: `npx --prefer-offline --yes copilotkit@4.16.0 onboard read framework/langgraph-typescript`
-11. LlamaIndex: `npx --prefer-offline --yes copilotkit@4.16.0 onboard read framework/llamaindex`
-12. ADK: `npx --prefer-offline --yes copilotkit@4.16.0 onboard read framework/google-adk`
-13. Microsoft Agent Framework Python: `npx --prefer-offline --yes copilotkit@4.16.0 onboard read framework/ms-agent-python`
-14. Microsoft Agent Framework .NET: `npx --prefer-offline --yes copilotkit@4.16.0 onboard read framework/ms-agent-dotnet`
-15. Mastra: `npx --prefer-offline --yes copilotkit@4.16.0 onboard read framework/mastra`
-16. MS Agent Harness .NET: `npx --prefer-offline --yes copilotkit@4.16.0 onboard read framework/ms-agent-harness-dotnet`
-17. Pydantic AI: `npx --prefer-offline --yes copilotkit@4.16.0 onboard read framework/pydantic-ai`
-18. Strands Agents Python: `npx --prefer-offline --yes copilotkit@4.16.0 onboard read framework/strands-python`
-19. Strands Agents TypeScript: `npx --prefer-offline --yes copilotkit@4.16.0 onboard read framework/strands-typescript`
+1. AG2: `npx --prefer-offline --yes copilotkit@4.17.0 onboard read framework/ag2`
+2. Agno: `npx --prefer-offline --yes copilotkit@4.17.0 onboard read framework/agno`
+3. Built-in CopilotKit agent: `npx --prefer-offline --yes copilotkit@4.17.0 onboard read framework/built-in`
+4. Claude Agent SDK Python: `npx --prefer-offline --yes copilotkit@4.17.0 onboard read framework/claude-sdk-python`
+5. Claude Agent SDK TypeScript: `npx --prefer-offline --yes copilotkit@4.17.0 onboard read framework/claude-sdk-typescript`
+6. CrewAI Flows: `npx --prefer-offline --yes copilotkit@4.17.0 onboard read framework/crewai-flows`
+7. Deep Agents: `npx --prefer-offline --yes copilotkit@4.17.0 onboard read framework/deep-agents`
+8. LangGraph Python: `npx --prefer-offline --yes copilotkit@4.17.0 onboard read framework/langgraph-python`
+9. LangGraph FastAPI: `npx --prefer-offline --yes copilotkit@4.17.0 onboard read framework/langgraph-fastapi`
+10. LangGraph TypeScript: `npx --prefer-offline --yes copilotkit@4.17.0 onboard read framework/langgraph-typescript`
+11. LlamaIndex: `npx --prefer-offline --yes copilotkit@4.17.0 onboard read framework/llamaindex`
+12. ADK: `npx --prefer-offline --yes copilotkit@4.17.0 onboard read framework/google-adk`
+13. Microsoft Agent Framework Python: `npx --prefer-offline --yes copilotkit@4.17.0 onboard read framework/ms-agent-python`
+14. Microsoft Agent Framework .NET: `npx --prefer-offline --yes copilotkit@4.17.0 onboard read framework/ms-agent-dotnet`
+15. Mastra: `npx --prefer-offline --yes copilotkit@4.17.0 onboard read framework/mastra`
+16. MS Agent Harness .NET: `npx --prefer-offline --yes copilotkit@4.17.0 onboard read framework/ms-agent-harness-dotnet`
+17. Pydantic AI: `npx --prefer-offline --yes copilotkit@4.17.0 onboard read framework/pydantic-ai`
+18. Strands Agents Python: `npx --prefer-offline --yes copilotkit@4.17.0 onboard read framework/strands-python`
+19. Strands Agents TypeScript: `npx --prefer-offline --yes copilotkit@4.17.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 --prefer-offline --yes copilotkit@4.16.0 onboard read unsupported/no-validated-path`.
+`npx --prefer-offline --yes copilotkit@4.17.0 onboard read unsupported/no-validated-path`.

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

@@ -11,7 +11,7 @@ friction command without another developer question. Do not ask the developer ab
 telemetry: the command applies the setting they already have.
 
 ```text
-npx --prefer-offline --yes copilotkit@4.16.0 onboard friction --phase stop --category <slug> --message "<sentences>"
+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.
@@ -60,7 +60,7 @@ One container for this project is the default scope, so the id comes from the se
 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
+npx --prefer-offline --yes copilotkit@4.17.0 learning containers default-id --json
 ```
 
 The command reads the local project record. It needs no credential and makes no network
@@ -79,7 +79,7 @@ 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
+npx --prefer-offline --yes copilotkit@4.17.0 learning containers get <id> --json
 ```
 
 The read carries the same availability gate as the create, so it answers the entitlement
@@ -104,7 +104,7 @@ Never invent an id, scrape a dashboard, or treat an arbitrary string as a contai
 Report what the read found, before anything is planned:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.16.0 onboard checkpoint --phase container-surveyed
+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
@@ -128,7 +128,7 @@ 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
+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".
@@ -136,12 +136,47 @@ Do not send a stop report, and do not take a stop route. When the developer answ
 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.16.0 onboard protect --path <path>
+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
@@ -155,7 +190,7 @@ Then re-capture the files this graph wrote itself. For each path the first captu
 as `deferred` that this run has now written, run:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.16.0 onboard protect --rebaseline --path <path>
+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
@@ -174,14 +209,15 @@ environment path. The command below is what to run at that point, from the targe
 directory:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.16.0 onboard protect --accept-credential --path <environment path>
+npx --prefer-offline --yes copilotkit@4.17.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.
+  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.
@@ -189,4 +225,4 @@ now. Read its result:
   is not a failed step. It answers the question and the run carries on.
 
 When the credential question is answered, run
-`npx --prefer-offline --yes copilotkit@4.16.0 onboard read credentials/write-plan`.
+`npx --prefer-offline --yes copilotkit@4.17.0 onboard read credentials/write-plan`.

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

@@ -11,7 +11,7 @@ friction command without another developer question. Do not ask the developer ab
 telemetry: the command applies the setting they already have.
 
 ```text
-npx --prefer-offline --yes copilotkit@4.16.0 onboard friction --phase stop --category <slug> --message "<sentences>"
+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.
@@ -29,30 +29,41 @@ 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.
 
 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.17.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 +74,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.17.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 +109,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 +122,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.17.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.17.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
+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.
 
 ```text
-npx --prefer-offline --yes copilotkit@4.16.0 onboard friction --phase stop --category <slug> --message "<sentences>"
+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.
@@ -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.17.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.17.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
   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.17.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.17.0 onboard complete --visual-check <outcome>
+npx --prefer-offline --yes copilotkit@4.17.0 onboard complete --device-check <outcome>
 ```
 
 `--visual-check` is for a web frontend and takes `performed`, `skipped-no-browser-tool`, or