copilotkit 4.24.0 → 4.25.0

package/onboarding/index.json

@@ -1,5 +1,5 @@
 {
-  "graphTree": "29dcb290ab507cc1cc9d3f7263f9c39eafe4607b",
+  "graphTree": "443ace4b44587f8f7fb3de547ae2b4b566fcc08c",
   "intentRoots": {
     "add-a2ui": "feature/a2ui/start",
     "add-chat-suggestions": "feature/chat-suggestions/start",
@@ -9,7 +9,7 @@
     "add-rich-threads": "feature/rich-threads/start",
     "add-voice": "feature/voice/start"
   },
-  "packageSpec": "copilotkit@4.24.0",
+  "packageSpec": "copilotkit@4.25.0",
   "root": "authenticate/start",
   "prompts": [
     {

package/onboarding/prompts/authenticate/start.md

@@ -2,19 +2,18 @@
 
 ## What this run does
 
-Read this before you proceed. This run executes the CopilotKit CLI through `npx`.
+This run executes the CopilotKit CLI through `npx`.
 It spawns read-only inspection subagents inside the target project. It sends checkpoints
 and optional friction reports to CopilotKit under the developer's telemetry setting. It
 reads nothing outside the project
 directory and changes files only after the developer approves a written plan. CopilotKit
-Intelligence has a free Developer plan, and this run needs no paid subscription. Nothing it
-does is hidden from the developer.
+Intelligence has a free Developer plan, and this run needs no paid subscription.
 
 ## Command approvals
 
 Run each CLI call exactly as written, as its own command: no pipe, `tee`, `&&`, redirect,
 or variable prefix. Every CLI call in this run matches the prefix rule
-`["npx", "--prefer-offline", "--yes", "copilotkit@4.24.0"]`. If a command can request
+`["npx", "--prefer-offline", "--yes", "copilotkit@4.25.0"]`. If a command can request
 escalation with a prefix rule, request this one on the `onboard identify` call. If your
 harness asks the developer to approve commands, tell them one approval of that prefix covers
 every CLI call. Say then that the install, the dev servers, `curl` to the local app, and
@@ -24,25 +23,27 @@ Never add or edit a permission rule or a settings file yourself. That choice bel
 the developer.
 
 If your harness refuses a CLI call without asking the developer, do not retry it or run it
-another way. Name the refused command, ask the developer to approve it or to switch to a
+another way. Report the pause: `npx --prefer-offline --yes copilotkit@4.25.0 onboard checkpoint --phase awaiting-developer`.
+Name the refused command, ask the developer to approve it or to switch to a
 mode that asks them, and end your turn. When they answer, run it once more.
 That refusal is a pause, not a stop.
 
 ## First, say which coding agent you are
 
-Run this before anything else in this prompt, including the welcome message below:
+Run this first, before the welcome message below:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.24.0 onboard identify --coding-agent <coding-agent-slug> --model <model-id> --model-family <model-family>
+npx --prefer-offline --yes copilotkit@4.25.0 onboard identify --coding-agent <coding-agent-slug> --model <model-id> --model-family <model-family>
 ```
 
 Report your product slug, such as `codex` or `claude-code`.
 
-- `--model`: copy the model id exactly as your instructions write it. If they name no
-  exact model id, leave out `--model` rather than guess.
-- `--model-family`: your model's family, such as `claude-opus` or `gpt-5`. Give it even
-  without `--model`, and leave out `--model-family` if you do not know it.
-- Never give your product slug as a model or a family.
+- `--model`: copy the model id exactly as your instructions write it. Without an exact
+  model id, leave out `--model` rather than guess.
+- `--model-family`: give it even without `--model`. Closest of: `claude-opus`,
+  `claude-sonnet`, `claude-haiku`, `gpt-5`, `gemini`, `grok`, `glm`, `minimax`, `mimo`,
+  `deepseek`, `qwen`, `kimi`, else the model's series. Leave it out if you do not know it.
+- Never give your product slug as a model, or as an unlisted family.
 
 ## How to run this onboarding
 
@@ -58,14 +59,14 @@ one the developer chose is that directory.
 The first command printed `onboarding_run_id:` followed by an id, once. Keep it for
 the whole run. Every later command reports against it.
 
-Every later command must run from the directory this run started in. Elsewhere, the
+Every later command must run from the directory this run is bound to. Elsewhere, the
 command cannot find its run and refuses. Do not report that refusal as a stop. Run
-`npx --prefer-offline --yes copilotkit@4.24.0 onboard start --run <onboarding_run_id>` where you are
+`npx --prefer-offline --yes copilotkit@4.25.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.24.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
+If you no longer hold the id, run `npx --prefer-offline --yes copilotkit@4.25.0 onboard start` in the
+directory this run started in, with no `--run` and no `--intent`. It reprints the id
+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.
 
 Read only inside the target project directory. Every subagent you spawn inherits that
@@ -96,8 +97,10 @@ Everything I need from you comes before that approval: sign-in, a few short setu
 and the plan itself. After you approve it, I build and prove the integration, which is the
 long part of this run. If I need you to approve a command, or something blocks me, I will ask
 you here. Otherwise you hear from me next when the app is running and I hand you its URLs.
+To self-host on your machine with Docker, say so before you sign in.
 
 That message belongs to the run. Send it only once, including after a second read of this prompt.
+Then run `npx --prefer-offline --yes copilotkit@4.25.0 onboard checkpoint --phase welcome-sent`.
 
 Telemetry and friction reports follow the CLI telemetry setting the developer controls with
 `copilotkit telemetry` or `DO_NOT_TRACK=1`. Each report is one or two sentences and carries
@@ -114,13 +117,14 @@ to the repository root and prints its path.
 
 ## Report a stop, wherever it happens
 
-This run reports its own stops. If you stop this run at any point, send one short report
-before you stop. This includes unexpected stops and stops caused by your harness.
+If you stop this run at any point, send one short report before you stop. This includes
+unexpected stops and stops caused by your harness.
 A turn that ends while the run waits is a pause, not a stop, even when your harness ends it.
+Report the pause: `npx --prefer-offline --yes copilotkit@4.25.0 onboard checkpoint --phase awaiting-developer`.
 A terminal that sends the report itself, or says to file none, overrides this.
 
 ```text
-npx --prefer-offline --yes copilotkit@4.24.0 onboard friction --phase stop --category <slug> --message "<sentences>"
+npx --prefer-offline --yes copilotkit@4.25.0 onboard friction --phase stop --category <slug> --message "<sentences>"
 ```
 
 `--message` takes one or two sentences: the step you stopped at and what stopped it.
@@ -135,35 +139,29 @@ rule that stopped you says next: send the report, then stop.
 
 ## Choose where the app stores data
 
-Before sign-in, run `npx --prefer-offline --yes copilotkit@4.24.0 local --help`.
-If it lists `setup` ("Configure model access and install or resume the local stack") and no
-choice exists, offer managed or local Docker evaluation. Otherwise keep managed. Existing
-local recovery still works.
-Record the path with
-`npx --prefer-offline --yes copilotkit@4.24.0 onboard deployment --choice <managed|local>`.
+Take the local route only when the developer already asked to run CopilotKit locally,
+with Docker, or self-hosted: in their request, the copied prompt, or a later reply, or
+when this run already recorded local. Then run
+`npx --prefer-offline --yes copilotkit@4.25.0 onboard read deployment/choose-local` instead.
 
-For a local choice, run
-`npx --prefer-offline --yes copilotkit@4.24.0 onboard read deployment/choose-local`.
-It records the choice for new and existing apps, completes sign-in, and starts research.
-For managed service, continue with “Check sign-in”.
+Otherwise keep managed. Do not ask the developer to choose. Run
+`npx --prefer-offline --yes copilotkit@4.25.0 onboard deployment --choice managed`, then continue with
+“Check sign-in”. If it refuses because of a local stack, take the local route.
 
 ## Check sign-in
 
-Run `npx --prefer-offline --yes copilotkit@4.24.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
+Run `npx --prefer-offline --yes copilotkit@4.25.0 login --json` before any project work. It checks the
+session and 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.
 
-Read each JSON Lines record as the running command writes it:
+Read each JSON Lines record as it arrives:
 
 1. If the process emits `type: completed` without an `authentication_url`, continue: the
    existing session is valid.
 2. If the process emits `authentication_url`, read the first `authentication_url` without
    changing it. The process is still running.
-   When that first URL arrives, send this exact message once. Do not send it when the
-   existing session is already valid, and do not add a feature list or another explanation:
-
-   For local evaluation, say: “Sign in to get the renewable evaluation license. Your
-   local dashboard will use CLI approval.” For the managed choice, say:
+   When that first URL arrives, send this exact message once. Add no feature list or other
+   explanation:
 
    I am opening a sign-in page. Signing in gives this project a managed CopilotKit project
    and its API key. That key is what lets your users reopen past conversations. You can
@@ -174,17 +172,24 @@ Read each JSON Lines record as the running command writes it:
 3. The CLI opens the page in the default browser itself when it can, and the
    `action_required` record says whether it did. With `"browser_opened": true`, do not open
    it again. With `"browser_opened": false`, show the clickable URL to the developer and ask
-   them to finish sign-in there. The page works from any device. Your own built-in browser
+   them to finish sign-in there. Your own built-in browser
    does not carry the session the developer already signed in with, so do not use it.
+   A later `authentication_url` record with `"renewed": true` means the earlier code expired.
+   Do not resend the sign-in message. Show only the new code, and the URL if
+   `browser_opened` is false.
 4. Keep monitoring the same login process. Do not start a second login command.
 5. Go past the research only after that same process emits `type: completed`.
-6. On `type: failed` with `reason: expired`, ask once whether to retry. If yes, start one
-   new `login --json`. Use `--force` only when the developer asks.
+6. On `type: failed` with `reason: expired` or `reason: renewal_failed`, ask once whether to
+   retry. If yes, start one new `login --json`. Use `--force` only when the developer asks.
 7. If that process emits `type: failed`, report the error and stop onboarding. On
    `reason: repeated_expiry`, rerun `login` with `--force` only if the developer asks.
 
+On `type: completed`, run `npx --prefer-offline --yes copilotkit@4.25.0 onboard checkpoint --phase sign-in-settled`
+before you continue.
+
 If your harness ends the login process or your turn before the process emits
-`type: completed` or `type: failed`, that is a pause, not a failed sign-in. If the process
+`type: completed` or `type: failed`, that is a pause, not a failed sign-in. Report the pause: `npx --prefer-offline --yes copilotkit@4.25.0 onboard checkpoint --phase awaiting-developer`.
+If the process
 still runs, end your turn and wait for the developer to say they signed in, then read the
 same process. If the process ended without emitting `type: failed`, run `login --json`
 again and handle a new `authentication_url` as above. Step 4 forbids a second login only while the first one runs.
@@ -194,9 +199,9 @@ conversation.
 
 Research reads only this project and needs no account. Start it as soon as the session is
 valid or the developer has the sign-in page, and keep monitoring the login process while it
-runs: `npx --prefer-offline --yes copilotkit@4.24.0 onboard read research/gather`. If this run already
+runs: `npx --prefer-offline --yes copilotkit@4.25.0 onboard read research/gather`. If this run already
 started the research, do not start it again.
 
 If sign-in stops onboarding, run
-`npx --prefer-offline --yes copilotkit@4.24.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.
+`npx --prefer-offline --yes copilotkit@4.25.0 onboard read stopped/run-failed`. It does not judge
+this project's stack.

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.24.0 verify --round-trip`, which sends a
+fifth item is proved by `npx --prefer-offline --yes copilotkit@4.25.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.24.0 onboard read credentials/finalize-plan`.
+Then run `npx --prefer-offline --yes copilotkit@4.25.0 onboard read credentials/finalize-plan`.
 
 If a selected page does not load after the second method, run
-`npx --prefer-offline --yes copilotkit@4.24.0 onboard read unsupported/no-validated-path`.
+`npx --prefer-offline --yes copilotkit@4.25.0 onboard read unsupported/no-validated-path`.

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

@@ -1,7 +1,7 @@
 # Select the Intelligence project
 
 For a recorded local choice, run
-`npx --prefer-offline --yes copilotkit@4.24.0 onboard read deployment/local-evaluation`.
+`npx --prefer-offline --yes copilotkit@4.25.0 onboard read deployment/local-evaluation`.
 That path obtains approval and connects the local project. Skip hosted selection.
 Keep the implementation and feature-proof requirements.
 
@@ -14,6 +14,12 @@ Ask one short question at a time, and end your turn to wait for each answer. Do
 combine separate choices in one question. Put the recommendation first, with its evidence
 in one sentence. Keep plan approval a separate, later question.
 
+Before you end your turn to wait for the developer, report the pause:
+
+```text
+npx --prefer-offline --yes copilotkit@4.25.0 onboard checkpoint --phase awaiting-developer
+```
+
 ## Record the audit cell
 
 Choose the starting state from the repository findings:
@@ -29,9 +35,13 @@ Choose the starting state from the repository findings:
 A run served `proof/oss-baseline` records one of the last two.
 
 ```text
-npx --prefer-offline --yes copilotkit@4.24.0 onboard classify --starting-state <starting-state> --agent-framework <agent-framework> --frontend <frontend>
+npx --prefer-offline --yes copilotkit@4.25.0 onboard classify --starting-state <starting-state> --agent-framework <agent-framework> --frontend <frontend> --model-vendor <model-vendor> --model-vendor-choice <model-vendor-choice>
 ```
 
+`<model-vendor>` is `openai`, `anthropic`, `google`, or `other`. `<model-vendor-choice>` is
+how the framework step chose it: `developer`, `default`, or `existing`. If the run
+recorded no vendor, leave out both flags.
+
 If a value is refused, fix it from the choices the earlier prompts gave, and run the
 command again.
 
@@ -42,7 +52,7 @@ runtime `.env` file, that directory is the target, not the repository root. Do n
 the developer to another terminal.
 
 ```text
-npx --prefer-offline --yes copilotkit@4.24.0 onboard credentials --json
+npx --prefer-offline --yes copilotkit@4.25.0 onboard credentials --json
 ```
 
 Every credential this run writes goes to the target's `.env`, the environment path. The
@@ -66,15 +76,21 @@ not list the organization's projects as part of the question. When `question.tak
 present, an existing project already has that name. Do not select the colliding project
 unless the developer says that it is this app's.
 
+Before you end your turn to wait for the developer, report the pause:
+
+```text
+npx --prefer-offline --yes copilotkit@4.25.0 onboard checkpoint --phase awaiting-developer
+```
+
 If no developer answers, create with the derived name in `suggestedName`. Never select a
 project from a listing without an answer that names it.
 
 `--runtime-url` is the URL port research settled, mount path included:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.24.0 onboard credentials --create <name> \
+npx --prefer-offline --yes copilotkit@4.25.0 onboard credentials --create <name> \
   --runtime-url http://localhost:<port>/api/copilotkit --json
-npx --prefer-offline --yes copilotkit@4.24.0 onboard credentials --project <slug-or-id> \
+npx --prefer-offline --yes copilotkit@4.25.0 onboard credentials --project <slug-or-id> \
   --runtime-url http://localhost:<port>/api/copilotkit --json
 ```
 
@@ -83,9 +99,15 @@ id. Search for it and ask which project the developer meant. Do not run either l
 command unless the developer asks to see their projects, or `notFound` is present. Then
 show only what they asked for, and do not order it by creation time:
 
+Before you end your turn to wait for the developer, report the pause:
+
+```text
+npx --prefer-offline --yes copilotkit@4.25.0 onboard checkpoint --phase awaiting-developer
+```
+
 ```text
-npx --prefer-offline --yes copilotkit@4.24.0 project list --json
-npx --prefer-offline --yes copilotkit@4.24.0 project list --search <query> --json
+npx --prefer-offline --yes copilotkit@4.25.0 project list --json
+npx --prefer-offline --yes copilotkit@4.25.0 project list --search <query> --json
 ```
 
 `app-directory` means that the key landed where no app reads it. Pick the directory in
@@ -100,4 +122,4 @@ the `--project` command from there with `project.slug`. Do not copy or link the
   reused. The round-trip proof later runs the authenticated Intelligence checks, so record
   the reused project credentials as unverified in the plan until those checks pass.
 
-Then run `npx --prefer-offline --yes copilotkit@4.24.0 onboard read credentials/settle-credentials`.
+Then run `npx --prefer-offline --yes copilotkit@4.25.0 onboard read credentials/settle-credentials`.

package/onboarding/prompts/credentials/plan.md

@@ -4,6 +4,12 @@ Use the repository findings to select the agent framework. Ask the developer onl
 choices that the repository does not show. Do not change application code in this phase.
 Do not read, show, store, or request a secret value.
 
+Before you end your turn to wait for the developer, report the pause:
+
+```text
+npx --prefer-offline --yes copilotkit@4.25.0 onboard checkpoint --phase awaiting-developer
+```
+
 Keep `CPK_INTELLIGENCE_API_KEY` separate from every model-vendor credential. Do not read,
 show, store, or copy either credential.
 
@@ -20,7 +26,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.24.0 onboard read frontend/plan`.
+`npx --prefer-offline --yes copilotkit@4.25.0 onboard read frontend/plan`.
 
 ## Frameworks this machine cannot run yet
 
@@ -42,7 +48,13 @@ things in one message:
 2. That the coding agent's shell reads PATH when it starts, so it cannot see the new
    toolchain until the developer restarts the coding agent.
 3. That the run resumes after the restart with
-   `npx --prefer-offline --yes copilotkit@4.24.0 onboard start --run <onboarding_run_id>`.
+   `npx --prefer-offline --yes copilotkit@4.25.0 onboard start --run <onboarding_run_id>`.
+
+Before you end your turn to wait for the developer, report the pause:
+
+```text
+npx --prefer-offline --yes copilotkit@4.25.0 onboard checkpoint --phase awaiting-developer
+```
 
 Then end your turn and wait for the developer. That restart is a step here, not an error.
 
@@ -52,32 +64,41 @@ Use a gentle wizard. Ask one short question at a time. Do not combine separate c
 one question. Put the recommendation first, give its evidence in one sentence, and keep
 the alternatives short. When the framework is unknown, use this rule: Ask one framework
 question that lists the recommendation and valid choices. Do not ask a yes-or-no question
-first. Do not ask about the frontend, model, or project in this step.
-
-These are the agent frameworks and their default vendors:
-
-| Framework                          | Default vendor  |
-| ---------------------------------- | --------------- |
-| AG2                                | OpenAI          |
-| ADK                                | Google          |
-| Agno                               | OpenAI          |
-| Built-in CopilotKit agent          | OpenAI          |
-| Claude Agent SDK (Python)          | Anthropic       |
-| Claude Agent SDK (TypeScript)      | Anthropic       |
-| CrewAI Flows                       | Project-defined |
-| Existing AG-UI agent               | The agent's own |
-| Deep Agents                        | OpenAI          |
-| LangGraph FastAPI                  | OpenAI          |
-| LangGraph Python                   | OpenAI          |
-| LangGraph TypeScript               | OpenAI          |
-| LlamaIndex                         | OpenAI          |
-| Mastra                             | OpenAI          |
-| Microsoft Agent Framework (.NET)   | OpenAI          |
-| Microsoft Agent Framework (Python) | OpenAI          |
-| MS Agent Harness (.NET)            | OpenAI          |
-| Pydantic AI                        | OpenAI          |
-| Strands Agents (Python)            | OpenAI          |
-| Strands Agents (TypeScript)        | OpenAI          |
+first. Do not ask about the frontend or project in this step. Ask about the model
+provider only as "Choose the model provider" below says.
+
+Before you end your turn to wait for the developer, report the pause:
+
+```text
+npx --prefer-offline --yes copilotkit@4.25.0 onboard checkpoint --phase awaiting-developer
+```
+
+These are the agent frameworks, their default vendors, and the vendors that this run can
+set up for a new agent. Each documented vendor has a credential variable and setup steps on
+the framework's CopilotKit pages:
+
+| Framework                          | Default vendor  | Documented vendors        |
+| ---------------------------------- | --------------- | ------------------------- |
+| AG2                                | OpenAI          | OpenAI                    |
+| ADK                                | Google          | Google                    |
+| Agno                               | OpenAI          | OpenAI                    |
+| Built-in CopilotKit agent          | OpenAI          | OpenAI, Anthropic, Google |
+| Claude Agent SDK (Python)          | Anthropic       | Anthropic                 |
+| Claude Agent SDK (TypeScript)      | Anthropic       | Anthropic                 |
+| CrewAI Flows                       | Project-defined |                           |
+| Existing AG-UI agent               | The agent's own |                           |
+| Deep Agents                        | OpenAI          | OpenAI                    |
+| LangGraph FastAPI                  | OpenAI          | OpenAI                    |
+| LangGraph Python                   | OpenAI          | OpenAI                    |
+| LangGraph TypeScript               | OpenAI          | OpenAI                    |
+| LlamaIndex                         | OpenAI          | OpenAI                    |
+| Mastra                             | OpenAI          | OpenAI, Anthropic         |
+| Microsoft Agent Framework (.NET)   | OpenAI          | OpenAI                    |
+| Microsoft Agent Framework (Python) | OpenAI          | OpenAI                    |
+| MS Agent Harness (.NET)            | OpenAI          | OpenAI                    |
+| Pydantic AI                        | OpenAI          | OpenAI                    |
+| Strands Agents (Python)            | OpenAI          | OpenAI, Anthropic         |
+| Strands Agents (TypeScript)        | OpenAI          | OpenAI, Anthropic         |
 
 "Project-defined" is not a missing default. It means that framework's own route settles
 the vendor with the developer: it keeps the one the repository already uses, and asks a
@@ -99,6 +120,12 @@ offer it for a new agent.
 If the project needs an agent, show the options and one recommendation based on repository
 evidence. Match the language the repository already uses. Ask the developer to choose.
 
+Before you end your turn to wait for the developer, report the pause:
+
+```text
+npx --prefer-offline --yes copilotkit@4.25.0 onboard checkpoint --phase awaiting-developer
+```
+
 If the project is empty, state that no repository-based recommendation exists. Give these
 documented defaults: LangGraph TypeScript, LangGraph Python, ADK, Microsoft Agent Framework
 Python, Microsoft Agent Framework .NET, and Mastra. Explain which default matches the
@@ -109,29 +136,68 @@ Do not offer a framework that is not listed above. Do not port an existing agent
 framework. Route names are this graph's own bookkeeping. Say what the run is doing in the
 developer's words instead.
 
+## Choose the model provider
+
+The run asks for a model key later. A developer with no key from the vendor the run picked
+cannot answer that question, so settle the vendor now.
+
+If the project keeps an existing agent, ask no question here: its route keeps that agent's
+model setup. Record the vendor that the setup uses, or `other` if you cannot tell, with the
+choice `existing`. Then skip the rest of this section.
+
+If the default vendor is "Project-defined" or "The agent's own", skip this section. Those
+routes settle the vendor themselves.
+
+For a new agent, once the framework is settled, ask one more short question: which model
+provider the developer has an API key for. Ask it even when the framework needed no
+question. Offer the documented vendors of the chosen framework, then another provider, then
+no preference. Never ask for the key itself.
+
+Before you end your turn to wait for the developer, report the pause:
+
+```text
+npx --prefer-offline --yes copilotkit@4.25.0 onboard checkpoint --phase awaiting-developer
+```
+
+- A documented vendor: use it.
+- No preference: use the default vendor.
+- A vendor that the row does not name: tell the developer that this run cannot set up that
+  vendor for a new agent with this framework. Then offer two choices. They can keep the
+  framework with its default vendor, or choose a framework whose row names their vendor.
+  Ask the framework question again for a new choice.
+
+Before you end your turn to wait for the developer, report the pause:
+
+```text
+npx --prefer-offline --yes copilotkit@4.25.0 onboard checkpoint --phase awaiting-developer
+```
+
+Record the vendor and how it was chosen. The developer named it: `developer`. The
+developer had no preference: `default`. The framework route uses this vendor.
+
 Use exactly one matching internal route:
 
-1. AG2: `npx --prefer-offline --yes copilotkit@4.24.0 onboard read framework/ag2`
-2. Agno: `npx --prefer-offline --yes copilotkit@4.24.0 onboard read framework/agno`
-3. Built-in CopilotKit agent: `npx --prefer-offline --yes copilotkit@4.24.0 onboard read framework/built-in`
-4. Claude Agent SDK Python: `npx --prefer-offline --yes copilotkit@4.24.0 onboard read framework/claude-sdk-python`
-5. Claude Agent SDK TypeScript: `npx --prefer-offline --yes copilotkit@4.24.0 onboard read framework/claude-sdk-typescript`
-6. CrewAI Flows: `npx --prefer-offline --yes copilotkit@4.24.0 onboard read framework/crewai-flows`
-7. Existing AG-UI agent: `npx --prefer-offline --yes copilotkit@4.24.0 onboard read framework/custom-ag-ui`
-8. Deep Agents: `npx --prefer-offline --yes copilotkit@4.24.0 onboard read framework/deep-agents`
-9. LangGraph Python: `npx --prefer-offline --yes copilotkit@4.24.0 onboard read framework/langgraph-python`
-10. LangGraph FastAPI: `npx --prefer-offline --yes copilotkit@4.24.0 onboard read framework/langgraph-fastapi`
-11. LangGraph TypeScript: `npx --prefer-offline --yes copilotkit@4.24.0 onboard read framework/langgraph-typescript`
-12. LlamaIndex: `npx --prefer-offline --yes copilotkit@4.24.0 onboard read framework/llamaindex`
-13. ADK: `npx --prefer-offline --yes copilotkit@4.24.0 onboard read framework/google-adk`
-14. Microsoft Agent Framework Python: `npx --prefer-offline --yes copilotkit@4.24.0 onboard read framework/ms-agent-python`
-15. Microsoft Agent Framework .NET: `npx --prefer-offline --yes copilotkit@4.24.0 onboard read framework/ms-agent-dotnet`
-16. Mastra: `npx --prefer-offline --yes copilotkit@4.24.0 onboard read framework/mastra`
-17. MS Agent Harness .NET: `npx --prefer-offline --yes copilotkit@4.24.0 onboard read framework/ms-agent-harness-dotnet`
-18. Pydantic AI: `npx --prefer-offline --yes copilotkit@4.24.0 onboard read framework/pydantic-ai`
-19. Strands Agents Python: `npx --prefer-offline --yes copilotkit@4.24.0 onboard read framework/strands-python`
-20. Strands Agents TypeScript: `npx --prefer-offline --yes copilotkit@4.24.0 onboard read framework/strands-typescript`
+1. AG2: `npx --prefer-offline --yes copilotkit@4.25.0 onboard read framework/ag2`
+2. Agno: `npx --prefer-offline --yes copilotkit@4.25.0 onboard read framework/agno`
+3. Built-in CopilotKit agent: `npx --prefer-offline --yes copilotkit@4.25.0 onboard read framework/built-in`
+4. Claude Agent SDK Python: `npx --prefer-offline --yes copilotkit@4.25.0 onboard read framework/claude-sdk-python`
+5. Claude Agent SDK TypeScript: `npx --prefer-offline --yes copilotkit@4.25.0 onboard read framework/claude-sdk-typescript`
+6. CrewAI Flows: `npx --prefer-offline --yes copilotkit@4.25.0 onboard read framework/crewai-flows`
+7. Existing AG-UI agent: `npx --prefer-offline --yes copilotkit@4.25.0 onboard read framework/custom-ag-ui`
+8. Deep Agents: `npx --prefer-offline --yes copilotkit@4.25.0 onboard read framework/deep-agents`
+9. LangGraph Python: `npx --prefer-offline --yes copilotkit@4.25.0 onboard read framework/langgraph-python`
+10. LangGraph FastAPI: `npx --prefer-offline --yes copilotkit@4.25.0 onboard read framework/langgraph-fastapi`
+11. LangGraph TypeScript: `npx --prefer-offline --yes copilotkit@4.25.0 onboard read framework/langgraph-typescript`
+12. LlamaIndex: `npx --prefer-offline --yes copilotkit@4.25.0 onboard read framework/llamaindex`
+13. ADK: `npx --prefer-offline --yes copilotkit@4.25.0 onboard read framework/google-adk`
+14. Microsoft Agent Framework Python: `npx --prefer-offline --yes copilotkit@4.25.0 onboard read framework/ms-agent-python`
+15. Microsoft Agent Framework .NET: `npx --prefer-offline --yes copilotkit@4.25.0 onboard read framework/ms-agent-dotnet`
+16. Mastra: `npx --prefer-offline --yes copilotkit@4.25.0 onboard read framework/mastra`
+17. MS Agent Harness .NET: `npx --prefer-offline --yes copilotkit@4.25.0 onboard read framework/ms-agent-harness-dotnet`
+18. Pydantic AI: `npx --prefer-offline --yes copilotkit@4.25.0 onboard read framework/pydantic-ai`
+19. Strands Agents Python: `npx --prefer-offline --yes copilotkit@4.25.0 onboard read framework/strands-python`
+20. Strands Agents TypeScript: `npx --prefer-offline --yes copilotkit@4.25.0 onboard read framework/strands-typescript`
 
 If the project has an agent in another framework that does not speak AG-UI, or no
 listed framework fits, keep the developer's current agent and run
-`npx --prefer-offline --yes copilotkit@4.24.0 onboard read unsupported/no-validated-path`.
+`npx --prefer-offline --yes copilotkit@4.25.0 onboard read unsupported/no-validated-path`.

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

@@ -21,7 +21,7 @@ The plan names the model credential variables. Run this from the directory that
 `environmentPath` in the project step's result, with one `--model-key` for each variable:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.24.0 onboard credentials --model-key <variable> --json
+npx --prefer-offline --yes copilotkit@4.25.0 onboard credentials --model-key <variable> --json
 ```
 
 When the framework node names another env file for the credential, add
@@ -40,15 +40,17 @@ never prints a value. When every key settles, it protects the credential paths.
   list the copy under `Files the run writes itself`, not under `Authorization requested`.
   The developer's approval of the plan is their consent to the copy. After the approval,
   copy the key with the command that `next` names. It has this form:
-  `npx --prefer-offline --yes copilotkit@4.24.0 onboard credentials --model-key <variable> --env-path <file> --copy-to <env file> --json`.
+  `npx --prefer-offline --yes copilotkit@4.25.0 onboard credentials --model-key <variable> --env-path <file> --copy-to <env file> --json`.
   It writes the key without printing it and protects the env file. Do not copy the key
   yourself, and do not write a `sed`, `grep`, or `cat` command for it. If you cannot run
   the command, for example because a sandbox refuses the path, ask the developer to run it.
   Give them exactly this one line, with `<app directory>` as the directory that holds
   `environmentPath`:
-  `! cd <app directory> && npx --prefer-offline --yes copilotkit@4.24.0 onboard credentials --model-key <variable> --env-path <file> --copy-to <env file>`.
+  `! cd <app directory> && npx --prefer-offline --yes copilotkit@4.25.0 onboard credentials --model-key <variable> --env-path <file> --copy-to <env file>`.
   The command needs no input. Without `!`, they run the same command in a terminal.
-  When they reply, run the same command with `--json` and read `copiedKeys`.
+  Report the pause with
+  `npx --prefer-offline --yes copilotkit@4.25.0 onboard checkpoint --phase awaiting-model-credential`,
+  end your turn, and wait. When they reply, run the same command with `--json` and read `copiedKeys`.
   If the developer declines the copy, the plan has the app read the key from an
   environment variable that the developer sets. The plan then says how to set it. Never
   write the outside path into a project file, not even in a config file such as
@@ -78,4 +80,4 @@ Never read a file outside the project directory to find a credential: a key foun
 bills another project. Asking for a path is not requesting a secret. A path the developer
 names is theirs to give, including one outside the project. A path this run finds is not.
 
-Then run `npx --prefer-offline --yes copilotkit@4.24.0 onboard read credentials/write-plan`.
+Then run `npx --prefer-offline --yes copilotkit@4.25.0 onboard read credentials/write-plan`.

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

@@ -11,7 +11,7 @@ friction command follows the telemetry setting the developer already chose, so i
 separate question.
 
 ```text
-npx --prefer-offline --yes copilotkit@4.24.0 onboard friction --phase stop --category <slug> --message "<sentences>"
+npx --prefer-offline --yes copilotkit@4.25.0 onboard friction --phase stop --category <slug> --message "<sentences>"
 ```
 
 `--message` takes one or two sentences: the step you stopped at and what stopped it.
@@ -72,21 +72,21 @@ page is selected yet, add the one for the frontend selected above to the same li
    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.24.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. Give it each finding
-that the framework route told you to record, such as how the agent connects or a `clone()`
-finding. Some of those rules, such as the `clone()` override, are on no documentation page.
-On a conversion, also give it the frozen criterion. Give the planning subagent the updated
-protected path list.
-Wait for the subagent to finish.
+`npx --prefer-offline --yes copilotkit@4.25.0 onboard read subagent/create-plan` first and follow the
+prompt it returns. Tell it to return at once, and say so, if that read is refused or fails,
+and not to wait for an approval. If it returns that way, stop that subagent. Run the same
+command yourself, then spawn a fresh subagent with the returned prompt and the same handoff.
+Give it the repository findings, selected framework, frontend, model, credential variable
+names, selected documentation URLs, and documentation policy. Give it each finding that the
+framework route told you to record, such as how the agent connects or a `clone()` finding.
+Some of those rules, such as the `clone()` override, are on no documentation page. On a
+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 --prefer-offline --yes copilotkit@4.24.0 onboard read stopped/run-failed`. A plan this run cannot
+`npx --prefer-offline --yes copilotkit@4.25.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
@@ -132,11 +132,11 @@ Before you end your turn to wait for the answer, report the pause, each time you
 plan:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.24.0 onboard checkpoint --phase awaiting-plan-approval
+npx --prefer-offline --yes copilotkit@4.25.0 onboard checkpoint --phase awaiting-plan-approval
 ```
 
 If the developer approves the plan, run
-`npx --prefer-offline --yes copilotkit@4.24.0 onboard read implementation/build-and-validate`.
+`npx --prefer-offline --yes copilotkit@4.25.0 onboard read implementation/build-and-validate`.
 
 If no exact supported path or documentation URL exists, run
-`npx --prefer-offline --yes copilotkit@4.24.0 onboard read unsupported/no-validated-path`.
+`npx --prefer-offline --yes copilotkit@4.25.0 onboard read unsupported/no-validated-path`.