copilotkit 4.28.0 → 4.30.0

package/onboarding/prompts/starter/clone.md

@@ -1,6 +1,6 @@
 # Clone a starter
 
-First run `npx --prefer-offline --yes copilotkit@4.28.0 onboard setup-answers`. It prints the answers that
+First run `npx --prefer-offline --yes copilotkit@4.30.0 onboard setup-answers`. It prints the answers that
 `setup/questions` recorded, even after this conversation lost them: `framework`, `frontend`,
 `vendor`, `project`, `key`, and on the local route `learning`. Take every "recorded" answer
 below from the record, or this conversation when the record lacks it. Do not ask a question
@@ -22,28 +22,28 @@ project to use, or to open the coding agent in a new empty folder.
 Before you end your turn to wait for the developer, report the pause:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.28.0 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.30.0 onboard checkpoint --phase awaiting-developer --about existing-folder
 ```
 
 Match the selected agent framework and frontend to this table:
 
-| Agent framework                  | Frontend | Framework ID                       | Model key                                 |
-| -------------------------------- | -------- | ---------------------------------- | ----------------------------------------- |
-| Agno                             | Next.js  | `agno`                             | `OPENAI_API_KEY`                          |
-| Claude Agent SDK Python          | Next.js  | `claude-sdk-python`                | `ANTHROPIC_API_KEY`                       |
-| Claude Agent SDK TypeScript      | Next.js  | `claude-sdk-typescript`            | `ANTHROPIC_API_KEY`                       |
-| CrewAI Flows                     | Next.js  | `flows`                            | `OPENAI_API_KEY`                          |
-| LangGraph Python                 | Next.js  | `langgraph-py`                     | `OPENAI_API_KEY`                          |
-| LangGraph TypeScript             | Next.js  | `langgraph-js`                     | `OPENAI_API_KEY`                          |
-| LlamaIndex                       | Next.js  | `llamaindex`                       | `OPENAI_API_KEY`                          |
-| ADK                              | Next.js  | `adk`                              | `GOOGLE_API_KEY`                          |
-| ADK                              | Angular  | `adk-angular`                      | `GOOGLE_API_KEY`                          |
-| Microsoft Agent Framework Python | Next.js  | `microsoft-agent-framework-py`     | `OPENAI_API_KEY` in `agent/.env`          |
-| Microsoft Agent Framework .NET   | Next.js  | `microsoft-agent-framework-dotnet` | `OPENAI_API_KEY` in `dotnet user-secrets` |
-| Mastra                           | Next.js  | `mastra`                           | `OPENAI_API_KEY`                          |
-| Pydantic AI                      | Next.js  | `pydantic-ai`                      | `OPENAI_API_KEY`                          |
-| Strands Agents Python            | Next.js  | `aws-strands-py`                   | `OPENAI_API_KEY`                          |
-| Strands Agents TypeScript        | Next.js  | `aws-strands-ts`                   | `OPENAI_API_KEY`                          |
+| Agent framework                  | Frontend | Framework ID                       | Model key                                 | Other vendors                                    |
+| -------------------------------- | -------- | ---------------------------------- | ----------------------------------------- | ------------------------------------------------ |
+| Agno                             | Next.js  | `agno`                             | `OPENAI_API_KEY`                          | an OpenAI-compatible provider, Anthropic, Google |
+| Claude Agent SDK Python          | Next.js  | `claude-sdk-python`                | `ANTHROPIC_API_KEY`                       | none                                             |
+| Claude Agent SDK TypeScript      | Next.js  | `claude-sdk-typescript`            | `ANTHROPIC_API_KEY`                       | none                                             |
+| CrewAI Flows                     | Next.js  | `flows`                            | `OPENAI_API_KEY`                          | an OpenAI-compatible provider                    |
+| LangGraph Python                 | Next.js  | `langgraph-py`                     | `OPENAI_API_KEY`                          | an OpenAI-compatible provider, Anthropic, Google |
+| LangGraph TypeScript             | Next.js  | `langgraph-js`                     | `OPENAI_API_KEY`                          | an OpenAI-compatible provider, Anthropic, Google |
+| LlamaIndex                       | Next.js  | `llamaindex`                       | `OPENAI_API_KEY`                          | an OpenAI-compatible provider                    |
+| ADK                              | Next.js  | `adk`                              | `GOOGLE_API_KEY`                          | OpenAI, an OpenAI-compatible provider, Anthropic |
+| ADK                              | Angular  | `adk-angular`                      | `GOOGLE_API_KEY`                          | OpenAI, an OpenAI-compatible provider, Anthropic |
+| Microsoft Agent Framework Python | Next.js  | `microsoft-agent-framework-py`     | `OPENAI_API_KEY` in `agent/.env`          | an OpenAI-compatible provider, Anthropic         |
+| Microsoft Agent Framework .NET   | Next.js  | `microsoft-agent-framework-dotnet` | `OPENAI_API_KEY` in `dotnet user-secrets` | an OpenAI-compatible provider                    |
+| Mastra                           | Next.js  | `mastra`                           | `OPENAI_API_KEY`                          | an OpenAI-compatible provider, Anthropic, Google |
+| Pydantic AI                      | Next.js  | `pydantic-ai`                      | `OPENAI_API_KEY`                          | an OpenAI-compatible provider, Anthropic, Google |
+| Strands Agents Python            | Next.js  | `aws-strands-py`                   | `OPENAI_API_KEY`                          | an OpenAI-compatible provider, Anthropic         |
+| Strands Agents TypeScript        | Next.js  | `aws-strands-ts`                   | `OPENAI_API_KEY`                          | an OpenAI-compatible provider, Anthropic         |
 
 Each Framework ID selects a starter that the CLI ships with Intelligence. Do not infer a
 different pair from a similar name. AG2 does not use this shortcut because its starter does
@@ -76,7 +76,7 @@ the derived name.
 Only if the developer asks for an existing project, or asks to see the projects they have,
 read the choices:
 
-`npx --prefer-offline --yes copilotkit@4.28.0 project list --json`
+`npx --prefer-offline --yes copilotkit@4.30.0 project list --json`
 
 Then ask which one to use. Do not order the projects by creation time. If the developer
 already gave this answer, do not ask again. Do not read a secret value. Do not show or
@@ -85,7 +85,7 @@ store a secret value.
 Before you end your turn to wait for the developer, report the pause:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.28.0 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.30.0 onboard checkpoint --phase awaiting-developer --about project-name
 ```
 
 ## Ask where the model credential lives
@@ -95,10 +95,9 @@ Use the recorded `key` answer. A named file (`key.file`) goes to
 `--model-key-file`. An answer of "later" (`key.later`) clones without one: the step after the clone pauses
 for the key. Do not ask again.
 
-When the recorded vendor is not the vendor of the Model key column, `init` copies the
-wrong variable from a key file. An OpenAI-compatible provider counts as another vendor,
-although its key is `OPENAI_API_KEY`. So clone without `--model-key-file` in that case, and
-follow `## Switch the starter to the recorded vendor` after the clone.
+When the recorded vendor is not the vendor of the Model key column, `init` takes the
+vendor as a flag, below, and then copies that vendor's key from the key file. An
+OpenAI-compatible provider counts as another vendor, although its key is `OPENAI_API_KEY`.
 
 If neither the record nor this conversation holds a key answer, ask for it now, while the developer is still
 here, and not after the clone. The variable is the Model key column of the row you
@@ -119,7 +118,7 @@ stops the clone. Pass the new file with `--model-key-file`, as for any other key
 Before you end your turn to wait for the developer, report the pause:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.28.0 onboard checkpoint --phase awaiting-model-credential
+npx --prefer-offline --yes copilotkit@4.30.0 onboard checkpoint --phase awaiting-model-credential
 ```
 
 A path the developer names is theirs to give, including one outside the project. A path
@@ -132,7 +131,7 @@ This route skips the plan step that records the path, so record it here, once, b
 the clone:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.28.0 onboard classify --starting-state <starting-state> --agent-framework <agent-framework> --frontend <frontend> --model-vendor <model-vendor> --model-vendor-choice <model-vendor-choice>
+npx --prefer-offline --yes copilotkit@4.30.0 onboard classify --starting-state <starting-state> --agent-framework <agent-framework> --frontend <frontend> --model-vendor <model-vendor> --model-vendor-choice <model-vendor-choice>
 ```
 
 - `<starting-state>`: the starting state the research recorded, usually `empty`.
@@ -155,7 +154,7 @@ Do not inspect another entry in the parent directory. Replace each placeholder w
 recorded value. Do not run a placeholder as a shell argument. If the path holds a space,
 put it in double quotes.
 
-`npx --prefer-offline --yes copilotkit@4.28.0 init --dir <absolute-target-directory> --framework <framework-id> --channel none --no-banner --no-key-prompt --create <name> --install`
+`npx --prefer-offline --yes copilotkit@4.30.0 init --dir <absolute-target-directory> --framework <framework-id> --channel none --no-banner --no-key-prompt --create <name> --install`
 
 `--dir` is always the absolute path of the target directory. `init` builds the app in that
 directory and gives the app the directory's name. Do not add `--name`: `init` refuses
@@ -175,26 +174,37 @@ variable name and never the value. Do not read or copy the key file yourself. If
 reports that it cannot read the model key file, it stopped before it cloned anything. Ask
 the developer for the right path, or run the command again without the flag.
 
+When the recorded `vendor.vendor` is not the vendor of the Model key column, also add
+`--model-vendor <vendor.vendor>`. For an OpenAI-compatible provider, add
+`--model-vendor openai-compatible --model-id <vendor.modelId> --base-url <vendor.baseUrl>`.
+`init` writes `COPILOTKIT_AGENT_MODEL` into the starter's env file, with a model the vendor
+serves to a new key today, and `OPENAI_BASE_URL` for an OpenAI-compatible provider. It then
+names that vendor's key in its output, and `--model-key-file` copies that key. The .NET starter
+takes no `--model-vendor`. A refusal stops `init` before it clones anything. If it says that the
+starter does not run the vendor, follow `## Switch the starter to the recorded vendor`. If it
+refuses `--model-id` or `--base-url`, ask the developer for the model id or base URL again, and
+run the command again.
+
 Before you end your turn to wait for the developer, report the pause:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.28.0 onboard checkpoint --phase awaiting-model-credential
+npx --prefer-offline --yes copilotkit@4.30.0 onboard checkpoint --phase awaiting-model-credential
 ```
 
 If you cannot pass the key file to `init`, for example because a sandbox refuses the path,
 clone without `--model-key-file`. Then copy the key from `<target>` with one command:
-`cd <target> && npx --prefer-offline --yes copilotkit@4.28.0 onboard credentials --model-key <VARIABLE> --env-path <key-file> --copy-to <env file> --json`.
+`cd <target> && npx --prefer-offline --yes copilotkit@4.30.0 onboard credentials --model-key <VARIABLE> --env-path <key-file> --copy-to <env file> --json`.
 `<env file>` is `.env`, or `agent/.env` for the Microsoft Agent Framework Python starter.
 The command writes the key into that file without printing it. If the
 command is refused too, ask the developer to run it. Give them exactly this one line:
-`! cd <target> && npx --prefer-offline --yes copilotkit@4.28.0 onboard credentials --model-key <VARIABLE> --env-path <key-file> --copy-to <env file>`.
+`! cd <target> && npx --prefer-offline --yes copilotkit@4.30.0 onboard credentials --model-key <VARIABLE> --env-path <key-file> --copy-to <env file>`.
 The command needs no input. Without `!`, they run the same command in a terminal.
 Do not write a `sed`, `grep`, or `cat` command to copy the key.
 
 Before you end your turn to wait for the developer, report the pause:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.28.0 onboard checkpoint --phase awaiting-model-credential
+npx --prefer-offline --yes copilotkit@4.30.0 onboard checkpoint --phase awaiting-model-credential
 ```
 
 ### For a recorded local choice
@@ -204,7 +214,7 @@ command instead of the hosted command above. Do not ask the project questions ab
 Local evaluation creates its own empty project, and `init --local` refuses `--create` and
 `--project`.
 
-`npx --prefer-offline --yes copilotkit@4.28.0 init --dir <absolute-target-directory> --framework <framework-id> --channel none --no-banner --no-key-prompt --local --defer-model --install`
+`npx --prefer-offline --yes copilotkit@4.30.0 init --dir <absolute-target-directory> --framework <framework-id> --channel none --no-banner --no-key-prompt --local --defer-model --install`
 
 Use the `learning` answer from the record, or this conversation. Use the default only when
 neither holds one.
@@ -212,14 +222,15 @@ For `learning.later`, keep `--defer-model`. For `learning.file`, replace
 `--defer-model` with `--model-config <learning.file>`. Do not read or print that
 file. The CLI selects the latest stable release. If the developer gave a candidate
 manifest for release testing, add `--candidate <manifest.json>`. Otherwise, do not add it.
-The `--dir`, `--no-install` and `--model-key-file` rules above apply here too.
+The `--dir`, `--no-install`, `--model-key-file` and `--model-vendor` rules above apply here
+too.
 
-Before `init`, run `npx --prefer-offline --yes copilotkit@4.28.0 onboard local-terms --json`. If `accepted`
+Before `init`, run `npx --prefer-offline --yes copilotkit@4.30.0 onboard local-terms --json`. If `accepted`
 is false, pause here. Give the developer this exact command to run in their own terminal:
-`npx --prefer-offline --yes copilotkit@4.28.0 local accept-terms`. Never accept the agreement yourself.
+`npx --prefer-offline --yes copilotkit@4.30.0 local accept-terms`. Never accept the agreement yourself.
 Report the pause with
-`npx --prefer-offline --yes copilotkit@4.28.0 onboard checkpoint --phase awaiting-developer`, end your turn,
-and wait for "done". Then run `local-terms` again, and continue only when `accepted` is
+`npx --prefer-offline --yes copilotkit@4.30.0 onboard checkpoint --phase awaiting-developer --about local-terms`, end your
+turn, and wait for "done". Then run `local-terms` again, and continue only when `accepted` is
 true. A local command that fails with `eula_acceptance_required` comes back to this step.
 
 For `learning.guided`, keep `--defer-model`.
@@ -228,7 +239,7 @@ After `init` reports the stack ready:
 Ask the developer to run this command in their own terminal window, in `<target>`:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.28.0 local setup
+npx --prefer-offline --yes copilotkit@4.30.0 local setup
 ```
 
 Do not give it as a `!` line, and do not run it yourself. Its guided model prompt needs a
@@ -237,9 +248,9 @@ changes nothing. The prompt asks for the model and its key, and it saves them pr
 On a running stack, it restarts only Learning. Do not ask for a model file.
 
 Say that the run continues when they reply or resume this session. Report the pause with
-`npx --prefer-offline --yes copilotkit@4.28.0 onboard checkpoint --phase awaiting-model-credential`, end your
+`npx --prefer-offline --yes copilotkit@4.30.0 onboard checkpoint --phase awaiting-model-credential`, end your
 turn, and wait. When the developer replies, run
-`npx --prefer-offline --yes copilotkit@4.28.0 local status --json` from `<target>` and read `learning.configuration`.
+`npx --prefer-offline --yes copilotkit@4.30.0 local status --json` from `<target>` and read `learning.configuration`.
 
 The command installs the local stack, then connects the starter to it. It writes the
 gitignored `.copilotkit/local.json` stack reference and `.copilotkit/project.json` with the
@@ -261,29 +272,17 @@ and validation commands.
 
 ## Switch the starter to the recorded vendor
 
-Each starter reads its model from `COPILOTKIT_AGENT_MODEL`, and `init` sets it to the
-starter's default in the starter's env file. When the recorded `vendor.vendor` is another
-vendor, the clone ran without `--model-key-file`. Switch the starter before you settle its
-key. The Claude Agent SDK starters run only Anthropic, so never switch them. Switch an ADK
-starter only to OpenAI or an OpenAI-compatible provider, and every other starter only to an
-OpenAI-compatible provider: this release does not run them on Anthropic or Google. If the
-recorded vendor is Anthropic or Google on such a starter, do not switch: say that this
-release supports the row's vendors on that framework, that Anthropic and Google come in a
-later release, and offer the Built-in CopilotKit agent if they need them now.
-
-1. Set `COPILOTKIT_AGENT_MODEL` in the starter's env file to the recorded vendor and a
-   model that the vendor serves to a new key today: `openai:<model>` on an ADK starter.
-   Do not change the starter's code.
-2. For an OpenAI-compatible provider, set `COPILOTKIT_AGENT_MODEL` to
-   `openai:<vendor.modelId>`, and `OPENAI_BASE_URL` to `vendor.baseUrl`.
-3. If the developer named a key file, copy the key with the `onboard credentials
---model-key <VARIABLE> --env-path <key-file> --copy-to <env file> --json` command above,
-   with the recorded vendor's variable. Otherwise the next section pauses for it.
-
-For the Microsoft Agent Framework .NET starter, set these values with
-`dotnet user-secrets set` from the agent directory, because .NET does not read the env
-file. In the next section, check the recorded vendor's variable in place of the Model key
-column's.
+Each starter reads its model from `COPILOTKIT_AGENT_MODEL`. With `--model-vendor`, `init`
+already switched it to the recorded vendor, and set `OPENAI_BASE_URL` for an
+OpenAI-compatible provider. Do not change the starter's code.
+
+Switch a starter only to a vendor in the Other vendors column of its row. A row with none, such as the Claude Agent SDK rows, runs only its own vendor: never switch it. This release does not run Anthropic or Google on a starter whose row leaves them out. If `init` refused the recorded vendor, say that this release supports the row's vendors on that framework, that Anthropic and Google come in a later release, and offer the Built-in CopilotKit agent if they need them now.
+
+For the Microsoft Agent Framework .NET starter, set `COPILOTKIT_AGENT_MODEL`, and
+`OPENAI_BASE_URL` for an OpenAI-compatible provider, with `dotnet user-secrets set` from the
+agent directory, because .NET does not read the env file. Use the recorded vendor and a model
+that the vendor serves to a new key today. In the next section, check the recorded vendor's
+variable in place of the Model key column's.
 
 ## Settle the model credential
 
@@ -302,10 +301,10 @@ grep -c '^<VARIABLE>=.' <target>/.env
 a count and never the value.
 
 If a variable is empty, run
-`npx --prefer-offline --yes copilotkit@4.28.0 onboard credentials --model-key <VARIABLE> --json` from
+`npx --prefer-offline --yes copilotkit@4.30.0 onboard credentials --model-key <VARIABLE> --json` from
 `<target>`, and show the developer `question.ask` word for word. It names the file by its
 full path and the line to add. If they reply with the path of a file that holds the key, run
-`npx --prefer-offline --yes copilotkit@4.28.0 onboard credentials --model-key <VARIABLE> --env-path <file> --copy-to <question.envFile> --json`
+`npx --prefer-offline --yes copilotkit@4.30.0 onboard credentials --model-key <VARIABLE> --env-path <file> --copy-to <question.envFile> --json`
 from `<target>`. Ask nothing else first. Quote a path that holds a space. The command copies
 the key without printing it. When it reports `ready`, the key is in `question.envFile`. Run
 the check above again, and continue. Follow this paragraph, not the packet's `next`, which is
@@ -333,7 +332,7 @@ The two Microsoft Agent Framework starters keep their key outside `<target>/.env
 When you ask, say that the run continues when they reply or resume this session. Then report the pause and end your turn:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.28.0 onboard checkpoint --phase awaiting-model-credential
+npx --prefer-offline --yes copilotkit@4.30.0 onboard checkpoint --phase awaiting-model-credential
 ```
 
 This is a pause, not a stop. Do not send a stop report, and do not take a stop route.
@@ -349,20 +348,21 @@ Run this from `<target>`, with one `--model-key` for each variable. For the Micr
 Framework Python starter, add `--env-path agent/.env`. Skip it for the .NET starter.
 
 ```text
-npx --prefer-offline --yes copilotkit@4.28.0 onboard credentials --model-key <VARIABLE> --json
+npx --prefer-offline --yes copilotkit@4.30.0 onboard credentials --model-key <VARIABLE> --json
 ```
 
 The command never prints a value. If `status` is `ready`, continue. Otherwise do what
 `next` says. When it says to ask `question.ask`, end your turn. The command already
 reported the pause. When the developer replies, run the command again. If they choose
-another provider that the framework can use, set `COPILOTKIT_AGENT_MODEL` to it, as the
-previous section describes, and check that provider's variable instead. With the cause `model_unavailable`, the key
+another provider that the framework can use, set `COPILOTKIT_AGENT_MODEL` in the starter's
+env file to `<provider>:<model>`, and `OPENAI_BASE_URL` for an OpenAI-compatible provider,
+as `init --model-vendor` does. Then check that provider's variable instead. With the cause `model_unavailable`, the key
 works and the app's model does not: the vendor does not serve the model that
 `COPILOTKIT_AGENT_MODEL` names. When the developer agrees to the model that `question.ask`
 names, or names another, change `COPILOTKIT_AGENT_MODEL` where `question.ask` says, and
 run the command again.
 
-Then run `npx --prefer-offline --yes copilotkit@4.28.0 onboard read proof/round-trip`.
+Then run `npx --prefer-offline --yes copilotkit@4.30.0 onboard read proof/round-trip`.
 
 If the local command fails, `init` keeps the cloned starter in `<target>`, and its error
 says whether it installed the starter's dependencies, or names the command that does. Do
@@ -375,14 +375,14 @@ available memory, or 40 GiB storage. Tell the developer what to change in Docker
 memory, pass on the amount the message names. Then report the pause and end your turn:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.28.0 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.30.0 onboard checkpoint --phase awaiting-developer --about environment-fix
 ```
 
 When the developer says that Docker is ready, resume from `<target>` with the same model
 choice. If the run used a `--candidate`, add the same one:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.28.0 local setup --defer-model --json
+npx --prefer-offline --yes copilotkit@4.30.0 local setup --defer-model --json
 ```
 
 If the run used model settings, replace `--defer-model` with `--model-config <private-file>`.
@@ -390,7 +390,7 @@ Read blockers and the recorded failed step. Do not delete or recreate a failed s
 setup reports the stack ready, connect the starter from `<target>`:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.28.0 local connect --approve-connection --json
+npx --prefer-offline --yes copilotkit@4.30.0 local connect --approve-connection --json
 ```
 
 The connection writes `.copilotkit/local.json`, `.copilotkit/project.json`, and the local
@@ -400,6 +400,8 @@ take the route below.
 
 If the command fails, report its exact error and do not claim that the starter is ready.
 Then run
-`npx --prefer-offline --yes copilotkit@4.28.0 onboard read stopped/run-failed`. The starter is one this
+`npx --prefer-offline --yes copilotkit@4.30.0 onboard read stopped/run-failed --reason <reason>`. The starter is one this
 graph ships and the stack was chosen from its own supported list, so a command that
-returned an error is a run that broke, not a setup this release does not support.
+returned an error is a run that broke, not a setup this release does not support. For
+`<reason>`, pick `dependency-install` for an install that failed, `build` for a build that
+failed, and `other` for anything else.

package/onboarding/prompts/starter/setup.md

@@ -0,0 +1,111 @@
+# Set up the starter
+
+This folder is empty, so this run builds a CopilotKit starter app here. The CLI clones the
+starter, creates the project, copies the model key, installs the dependencies, starts the
+app and proves it, in two commands. You show the developer two messages and run a few
+commands.
+
+Do not research this folder, read other prompts, change code, or start subagents on this
+route. Never read, show, store, or request a secret value. Ask only for the file that holds
+the model key.
+
+## Stay on this route
+
+If the developer asks for a Slack, Microsoft Teams, or other Channel app, run
+`npx --prefer-offline --yes copilotkit@4.30.0 onboard read feature/channels/start` instead, and follow it.
+
+To stop onboarding, tell the developer what failed in one sentence, with any log path the
+CLI named. Send the stop report:
+
+```text
+npx --prefer-offline --yes copilotkit@4.30.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 from docs-missing, docs-wrong, docs-sequential, cli-gap, sdk-gap, environment,
+port-collision, credential, validation-loop, or other. Leave --cost-seconds off: a stop
+report needs no estimate. Send no secrets, source code, logs, or command output.
+
+Then run `npx --prefer-offline --yes copilotkit@4.30.0 onboard read stopped/run-failed --reason <reason>`.
+For `<reason>`, pick `dependency-install` for an install that failed, `model-call` for a
+model key or a chat round trip that failed, `build` for a build that failed, and `other`
+for anything else. Do this when sign-in stops onboarding, and when a step below says to
+stop onboarding.
+
+## Ask the setup questions
+
+When `onboard begin` printed a setup message after this prompt, that is the first setup
+message: do what its `next` says, and skip to the last paragraph of this section.
+
+If this folder's README names the agent framework to build on, record it first, with the
+name the README gives, such as `Agno` or `LangGraph Python`:
+
+```text
+npx --prefer-offline --yes copilotkit@4.30.0 onboard setup-answers --framework <name> --framework-choice developer
+```
+
+On the local route, first run `npx --prefer-offline --yes copilotkit@4.30.0 onboard local-terms --json`.
+If it reports `signed-out` or `unavailable`, follow its `next`. The setup message carries
+the agreement line, so do not add it yourself.
+
+Run this from this folder. Add `--vendor <vendor>` only for a model vendor the developer
+named, as `openai`, `anthropic`, `google`, or `openai-compatible`:
+
+```text
+npx --prefer-offline --yes copilotkit@4.30.0 onboard setup-message --target empty
+```
+
+Do what its `next` says. It tells you how to show the message, how to report the pause,
+and how to record each reply. Repeat until it prints `status: settled`. If the developer
+declines, such as **no**, run
+`npx --prefer-offline --yes copilotkit@4.30.0 onboard read stopped/declined --message "<their reason>"`.
+
+## Build the starter
+
+If a sign-in process runs, wait until it emits `type: completed`. Then write this line in
+your reply, word for word:
+
+> Creating your app now. This takes about a minute: I copy the starter, install its
+> packages, and send one chat message through your agent to prove that it works.
+
+Then run:
+
+```text
+npx --prefer-offline --yes copilotkit@4.30.0 onboard starter create
+```
+
+It builds from the recorded answers and waits up to 90 seconds. While it prints
+`running`, run `npx --prefer-offline --yes copilotkit@4.30.0 onboard starter status --wait` again.
+While you wait, write nothing about the command, its process, or its output. If you write
+anything, write only the `Still working` line it prints.
+
+- If it names a framework and frontend with no starter, run
+  `npx --prefer-offline --yes copilotkit@4.30.0 onboard read research/gather` and follow that route.
+- If it failed on an answer, such as a project name the account already has, ask the
+  developer for a new answer. Report the pause with
+  `npx --prefer-offline --yes copilotkit@4.30.0 onboard checkpoint --phase awaiting-developer --about project-name`,
+  and end your turn. Record their answer with `onboard setup-answers`, then run
+  `onboard starter create` again.
+- If it says the step did not reach the network, ask the developer to approve network
+  access for the command, or to let it run outside the sandbox. Report the pause with
+  `npx --prefer-offline --yes copilotkit@4.30.0 onboard checkpoint --phase awaiting-developer --about harness-permission`,
+  and end your turn. When they reply, run `onboard starter create` again.
+- For any other failure, stop onboarding.
+
+## Prove it
+
+When `create` prints `done`, run:
+
+```text
+npx --prefer-offline --yes copilotkit@4.30.0 onboard starter prove
+```
+
+It checks the model key, starts the app, and runs a chat round trip. Wait for it as for
+`create`.
+
+- If it prints a message for the developer, write it in your reply word for word. Report the
+  pause with `npx --prefer-offline --yes copilotkit@4.30.0 onboard checkpoint --phase awaiting-model-credential`,
+  and end your turn. When the developer replies, run `onboard starter prove` again. If the
+  reply names a file that holds the key, add `--key-file <path>`.
+- If it failed, stop onboarding.
+- When it prints `done`, write its report in your reply word for word. The run is complete.

package/onboarding/prompts/stopped/declined.md

@@ -0,0 +1,44 @@
+# Stop because the developer said no
+
+This is the ending for a developer who decided not to go on: a reply such as **no**,
+**not now**, **do not install it**, or **do not add it**. Nothing broke. Do not report
+this run as a failure, and do not tell the developer their setup is unsupported.
+
+It is the same ending for an onboarding run and for a run that adds one feature. A
+feature run that reads this step does not also read `feature/stop`.
+
+The read that served this step recorded the developer's reason, from
+`onboard read stopped/declined --message "<the developer's reason, in one line>"`. Do not
+read this step again to add a reason.
+
+This run ends here. Make no more repository changes, and do not try to change the
+developer's mind.
+
+## What to tell the developer
+
+Write a short reply:
+
+1. Thank them for trying CopilotKit.
+2. Say that this run stopped and nothing else will change in their project.
+3. Say what this run left behind. This step prints `## Your files` below: relay that
+   report as printed. When it names a restore command, offer it as the way to put their
+   files back. A run that started in an empty folder prints no such section: list no
+   files and offer no restore.
+4. Name any process this run started that is still running, and offer to stop it.
+5. Say they can start again at any time with the same prompt they used for this run.
+
+## If the developer asks you to clean up
+
+Run the restore command the report printed, for example:
+
+```text
+npx --prefer-offline --yes copilotkit@4.30.0 onboard restore --run <onboarding_run_id>
+```
+
+It puts back each file this run changed, from the backup taken when the run started. It
+keeps files this run added. If the developer also wants those removed, list each one and
+delete only the files they confirm. Stop any process this run started. Do not delete
+anything this run did not create.
+
+The CLI keeps the run's own record outside the project, so there is nothing else to clean
+up in the project folder.

package/onboarding/prompts/stopped/run-failed.md

@@ -20,9 +20,9 @@ files changed cannot be acted on: nobody reading it can tell which file moved.
 Say what the developer has now. Name the processes still running and the files this run
 changed, so they can carry on by hand or start again from a known state. A run that stops
 without saying what it left behind leaves the developer to discover it. This step prints
-`## The developer's files` below: relay that report as printed, with its restore command.
-When the report says the run started in an empty folder, relay that one line alone in
-place of the files: list no files and offer no restore.
+`## Your files` below: relay that report as printed, with its restore command. A run
+that started in an empty folder prints no such section: list no files and offer no
+restore.
 
 A step can fail on a network error: `EAI_AGAIN`, `ECONNRESET`, `ETIMEDOUT`, a timeout,
 or a message that names a proxy. The CLI has already tried that step again. Ask the
@@ -42,13 +42,13 @@ put to them, stop here and send the report below.
 Before you end your turn to wait for the developer, report the pause:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.28.0 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.30.0 onboard checkpoint --phase awaiting-developer --about scoped-fix
 ```
 
 If they approve it, make that one fix and nothing else. Then come back into this run:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.28.0 onboard resume --message "<approval>"
+npx --prefer-offline --yes copilotkit@4.30.0 onboard resume --message "<approval>"
 ```
 
 Put the developer's approval in `--message`, in one or two sentences: the fix they
@@ -71,7 +71,7 @@ Send one short report. The friction command follows the telemetry setting the de
 already chose, so it needs no separate question.
 
 ```text
-npx --prefer-offline --yes copilotkit@4.28.0 onboard friction --phase stop --category <slug> --message "<sentences>"
+npx --prefer-offline --yes copilotkit@4.30.0 onboard friction --phase stop --category <slug> --message "<sentences>"
 ```
 
 `--message` takes one or two sentences: the step you stopped at and what stopped

package/onboarding/prompts/subagent/create-plan.md

@@ -22,6 +22,19 @@ override copies.
 List the required credential variable names. Do not read or return credential values.
 Preserve each agent or frontend that already exists.
 
+## When a command is refused
+
+If you are a subagent and your harness refuses a command, return at once. Name the
+command, the directory you ran it from, and the refusal, and run nothing else. Do not wait
+for an approval: nobody sees it. The main coding agent runs the command itself and passes
+the result on. The one wait allowed is a harness escalation request that this brief tells
+you to make for a command. Make that request and wait for its answer.
+
+If your handoff holds a command's result, use it and do not run that command again.
+
+If you are the main coding agent and follow this brief yourself, this section is not for
+you. Do not return: handle a refused command as the run's other prompts say.
+
 ## What the existing agent's behavior is
 
 The existing agent's behavior is four things: its system prompt and instructions, its
@@ -79,8 +92,8 @@ plan one container per end user: a project holds at most 500, the first automati
 run needs threads from 15 distinct conversations in one container, and a container per
 person needs those 15 conversations from that one person.
 
-Where the Learning step was skipped, plan no container and no selector, and say in the plan
-that Learning is not available to this organization.
+Where the Learning step was skipped, plan no container and no selector, and name the skip
+reason in the plan.
 
 When the starting state is `both-oss`, use its recorded live baseline evidence. Preserve
 the working agent, frontend, CopilotKit integration, and OSS behavior. Plan the project
@@ -97,7 +110,7 @@ against a dead host, and the failure arrives as an empty-body 404 with no cause
 Ask the CLI for the dependency upgrade, from the target directory:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.28.0 onboard upgrade-plan --json
+npx --prefer-offline --yes copilotkit@4.30.0 onboard upgrade-plan --json
 ```
 
 It reads the installed tree and the registry. Read `status`:
@@ -185,7 +198,7 @@ here is work the developer did not ask for.
 Plan the threads drawer itself: add it from the selected drawer page, where this frontend
 does not already render one. Where this journey's frontend framework ships no threads
 drawer -- React Native --, plan that the thread is proved by
-`npx --prefer-offline --yes copilotkit@4.28.0 verify --round-trip`, which needs no browser. Do not plan a
+`npx --prefer-offline --yes copilotkit@4.30.0 verify --round-trip`, which needs no browser. Do not plan a
 step that opens the managed Intelligence dashboard.
 
 ## Name the files the run writes itself
@@ -325,10 +338,22 @@ change. Say that in the plan.
 
 Do not leave a change that needs approval out of the list to keep the run moving.
 
+## Return the result
+
 Gather what you need in as few commands as possible. Combine independent reads into one
 command rather than running them one at a time. Split a command only when its result decides
 what you run next.
 
+Before you return, record that you are returning:
+
+```text
+npx --prefer-offline --yes copilotkit@4.30.0 onboard checkpoint --phase subagent-returned --brief create-plan --result <ok|failed>
+```
+
+The Status line of your result decides the value. Pass `ok` only for `Status: passed`.
+Pass `failed` for `Status: failed` or `Status: blocked`. If your harness refuses this command, say so in your result and return
+anyway: the main coding agent records it.
+
 Start with `Status: passed`, `Status: failed`, or `Status: blocked`.
 Return the plan, the URLs that you read, and each documentation gap. End your turn after you return
 the findings to the main coding agent.