copilotkit 4.26.0 → 4.28.0

package/onboarding/prompts/starter/clone.md

@@ -1,5 +1,11 @@
 # Clone a starter
 
+First run `npx --prefer-offline --yes copilotkit@4.28.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
+that either one answers.
+
 Use this shortcut only when the repository findings prove that the target project
 directory holds no project yet: no source directory such as `src/`, `app/`, `agent/` or
 `web/`, no dependency manifest such as `package.json` or `pyproject.toml`, and no `.env`.
@@ -16,7 +22,7 @@ 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.26.0 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.28.0 onboard checkpoint --phase awaiting-developer
 ```
 
 Match the selected agent framework and frontend to this table:
@@ -50,28 +56,27 @@ directory as it is, so a name such as `MyApp` is valid. Do not rename the direct
 the shortcut in each of these cases:
 
 - The selected pair is not in the table.
-- The developer chose a model vendor whose key is not the Model key of the matched row.
-  Each starter runs on the vendor in that column only.
 - The directory name is not valid.
 
 Do not run `init`. No command ran, so this is not a failed shortcut. Go back to the
 `## Documentation` section of the frontend prompt you read before this one, and build the
 project from its pages.
 
-Use the project answer that `setup/questions` recorded. A new project takes the recorded
-name. A project the developer already has takes `--project` in the command below. Do not ask
+Use the recorded `project` answer. A new project (`project.create`) takes the recorded
+name. A project the developer already has (`project.project`) takes `--project` in the command below. Do not ask
 again.
 
-If `setup/questions` recorded no project answer, ask here. If the developer did not name a
+If neither the record nor this conversation holds a project answer, ask here. If the developer did not name a
 project, create one for the app being cloned. This directory is new, so no existing project is already its own: take the project
-name from the target directory name derived above, and ask the developer to confirm it or
-give another. Do not list the projects in the organization. If no developer answers, use
+name from the target directory name derived above, and ask as the options view of `onboard setup-message` does:
+"Project: **new project "<name>"**", then "Other: another name · a project you already
+have". Do not list the projects in the organization. If no developer answers, use
 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.26.0 project list --json`
+`npx --prefer-offline --yes copilotkit@4.28.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
@@ -80,19 +85,26 @@ store a secret value.
 Before you end your turn to wait for the developer, report the pause:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.26.0 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.28.0 onboard checkpoint --phase awaiting-developer
 ```
 
 ## Ask where the model credential lives
 
 The starter reads a model credential, and the `init` command below does not ask for one.
-Use the key file answer that `setup/questions` recorded. A named file goes to
-`--model-key-file`. An answer of "later" clones without one: the step after the clone pauses
+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.
 
-If `setup/questions` recorded no 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 matched. Do not guess it from the framework name.
+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.
+
+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
+matched. When the recorded vendor is another one, the variable is that vendor's:
+`ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, `OPENAI_API_KEY` for OpenAI, or `OPENAI_API_KEY`
+for an OpenAI-compatible provider. Do not guess it from the framework name.
 
 Ask the developer one question: which file holds that key, or whether they will add it
 themselves after the clone. Asking where a credential lives is not requesting a secret
@@ -107,7 +119,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.26.0 onboard checkpoint --phase awaiting-model-credential
+npx --prefer-offline --yes copilotkit@4.28.0 onboard checkpoint --phase awaiting-model-credential
 ```
 
 A path the developer names is theirs to give, including one outside the project. A path
@@ -120,7 +132,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.26.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.28.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`.
@@ -128,7 +140,7 @@ npx --prefer-offline --yes copilotkit@4.26.0 onboard classify --starting-state <
   `langgraph-typescript` for `framework/langgraph-typescript`. It is not the Framework ID
   in the table.
 - `<frontend>`: the Frontend column of the matched row, `nextjs` or `angular`.
-- `<model-vendor>`: `openai`, `anthropic`, `google`, or `other`.
+- `<model-vendor>`: `openai`, `anthropic`, `google`, `openai-compatible`, or `other`.
 - `<model-vendor-choice>`: if the developer chose the provider, `developer`. Otherwise,
   `default`.
 
@@ -143,13 +155,15 @@ 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.26.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.28.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
 `--name` together with `--dir`. Pass the confirmed project name to `--create` only. If the
 developer names an existing project, use `--project <slug-or-id>` instead of
-`--create <name>`. If the developer asked to skip the dependency install, use
+`--create <name>`. If `init` says that the account already has a project with that name,
+ask the developer for a new name, or which of their projects to use. Do not select the
+existing project until they name it. If the developer asked to skip the dependency install, use
 `--no-install` instead of `--install`. Do not wait for an interactive prompt. Pass every
 answer as a flag. `--no-key-prompt` stops `init` from asking for a model key. The `init`
 output still names each missing key as `Set <VARIABLE> in .env`.
@@ -164,23 +178,23 @@ the developer for the right path, or run the command again without the flag.
 Before you end your turn to wait for the developer, report the pause:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.26.0 onboard checkpoint --phase awaiting-model-credential
+npx --prefer-offline --yes copilotkit@4.28.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.26.0 onboard credentials --model-key <VARIABLE> --env-path <key-file> --copy-to <env file> --json`.
+`cd <target> && npx --prefer-offline --yes copilotkit@4.28.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.26.0 onboard credentials --model-key <VARIABLE> --env-path <key-file> --copy-to <env file>`.
+`! cd <target> && npx --prefer-offline --yes copilotkit@4.28.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.26.0 onboard checkpoint --phase awaiting-model-credential
+npx --prefer-offline --yes copilotkit@4.28.0 onboard checkpoint --phase awaiting-model-credential
 ```
 
 ### For a recorded local choice
@@ -190,22 +204,31 @@ 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.26.0 init --dir <absolute-target-directory> --framework <framework-id> --channel none --no-banner --no-key-prompt --local --defer-model --install`
-
-Use the model choice from `deployment/choose-local`. If the developer deferred it, keep
-`--defer-model`. If the developer gave model settings, replace `--defer-model` with
-`--model-config <private-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.
-
-If the developer chose guided model setup in `deployment/choose-local`, keep `--defer-model`.
+`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`
+
+Use the `learning` answer from the record, or this conversation. Use the default only when
+neither holds one.
+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.
+
+Before `init`, run `npx --prefer-offline --yes copilotkit@4.28.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.
+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
+true. A local command that fails with `eula_acceptance_required` comes back to this step.
+
+For `learning.guided`, keep `--defer-model`.
 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.26.0 local setup
+npx --prefer-offline --yes copilotkit@4.28.0 local setup
 ```
 
 Do not give it as a `!` line, and do not run it yourself. Its guided model prompt needs a
@@ -214,9 +237,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.26.0 onboard checkpoint --phase awaiting-model-credential`, end your
+`npx --prefer-offline --yes copilotkit@4.28.0 onboard checkpoint --phase awaiting-model-credential`, end your
 turn, and wait. When the developer replies, run
-`npx --prefer-offline --yes copilotkit@4.26.0 local status --json` from `<target>` and read `learning.configuration`.
+`npx --prefer-offline --yes copilotkit@4.28.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
@@ -236,11 +259,37 @@ Do not rebuild the starter by hand. Then inspect only the generated
 paths inside the target directory. Record the files, install result, project connection,
 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.
+
 ## Settle the model credential
 
 The `init` output names each key it copied from a key file as
-`Copied <VARIABLE> from the model key file into <file>`. A copied key is in place, so do
-not check it. If the key file did not hold a variable, the output warns by name.
+`Copied <VARIABLE> from the model key file into <file>`. A copied key is in place, so it
+needs no `grep` check. If the key file did not hold a variable, the output warns by name.
 
 The `init` output names each missing credential as `Set <VARIABLE> in .env`. For each
 one, check the starter's own `.env` without reading the value:
@@ -252,54 +301,88 @@ grep -c '^<VARIABLE>=.' <target>/.env
 `1` means the variable holds a value. `0` means it is empty or absent. The command prints
 a count and never the value.
 
-If a variable is empty, ask the developer to add it to `<target>/.env` themselves.
+If a variable is empty, run
+`npx --prefer-offline --yes copilotkit@4.28.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`
+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
+written for an existing app that copies the key only after its plan.
+
+A local server needs no key. That is a server such as Ollama or LM Studio, with
+`OPENAI_BASE_URL` on `localhost`, `127.0.0.1` or `::1` in `<target>/.env`. A local base
+URL that only your shell sets does not count, because it can be your own proxy. When
+`<target>/.env` sets that base URL and the developer said it needs no key, do not ask for
+one. Write `OPENAI_API_KEY=not-needed` to the file that the key goes in. The OpenAI SDKs
+refuse an empty key, and a local server ignores the value. Write no other stand-in value.
 
 The two Microsoft Agent Framework starters keep their key outside `<target>/.env`, so
 `init` prints no `Set` line for them. Settle the key from the Model key column instead:
 
 - For the Python starter, a key file passed to `init` fills `<target>/agent/.env`, and the
   output says so. Otherwise, run the same check for `OPENAI_API_KEY` against
-  `<target>/agent/.env`. A missing file counts as `0`. If it is empty, ask the developer to
-  add it there themselves.
+  `<target>/agent/.env`. A missing file counts as `0`. If it is empty, ask as above, with
+  `--env-path agent/.env` added to the first command.
 - For the .NET starter, the key lives in `dotnet user-secrets`, and no check can read it
   without printing the value. Ask the developer to run
   `cd <target>/agent && dotnet user-secrets set OPENAI_API_KEY "<key>"` themselves, even
   if they named a key file.
 
-When you ask, name each variable and the file it goes in, and say that the run continues
-when they reply or resume this session. Then report the pause and end your turn:
+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.26.0 onboard checkpoint --phase awaiting-model-credential
+npx --prefer-offline --yes copilotkit@4.28.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.
 When the developer says the credential is in place, run the check again, and continue
 when every variable holds a value. For the .NET starter, continue on the developer's word. Do not write a placeholder or an empty value to get
 past this step. A starter with a dummy key looks finished and fails at the first model
-call.
+call. The one exception is the `not-needed` value for a local server above.
 
 If no credential is missing, report no pause and continue.
 
-Then run `npx --prefer-offline --yes copilotkit@4.26.0 onboard read proof/round-trip`.
+When every variable holds a value, ask its vendor whether the key can pay for a model call.
+Run this from `<target>`, with one `--model-key` for each variable. For the Microsoft Agent
+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
+```
 
-If the local command fails, `init` keeps the cloned starter in `<target>`. Do not run
-`init` again, because the target is no longer empty. Do not delete the starter or the stack.
-Report the exact error, and do not claim that the starter is ready. A failure that names
-Docker is an environment blocker, not a broken run. For example, Docker is stopped or
-missing, or `Docker available resources` or `Docker memory` is below 4 CPUs, 12 GiB of
+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
+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`.
+
+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
+not run `init` again, because the target is no longer empty. Do not delete the starter or
+the stack. Report the exact error, and do not claim that the starter is ready. A failure
+with `eula_acceptance_required` goes back to the agreement step above, then resumes with
+the `local setup` command below. A failure that names Docker is an environment blocker, not a broken run. For example, Docker is stopped or
+missing, or `Docker available resources` or `Docker memory` is below 4 CPUs, 4 GiB of
 available memory, or 40 GiB storage. Tell the developer what to change in Docker. For
 memory, pass on the amount the message names. Then report the pause and end your turn:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.26.0 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.28.0 onboard checkpoint --phase awaiting-developer
 ```
 
 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.26.0 local setup --defer-model --json
+npx --prefer-offline --yes copilotkit@4.28.0 local setup --defer-model --json
 ```
 
 If the run used model settings, replace `--defer-model` with `--model-config <private-file>`.
@@ -307,15 +390,16 @@ 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.26.0 local connect --approve-connection --json
+npx --prefer-offline --yes copilotkit@4.28.0 local connect --approve-connection --json
 ```
 
 The connection writes `.copilotkit/local.json`, `.copilotkit/project.json`, and the local
 keys in `<target>/.env`. Then continue with the credential check above. If the resumed
-setup fails again with an error that does not name Docker, take the route below.
+setup fails again with an error that names neither Docker nor `eula_acceptance_required`,
+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.26.0 onboard read stopped/run-failed`. The starter is one this
+`npx --prefer-offline --yes copilotkit@4.28.0 onboard read stopped/run-failed`. 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.

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

@@ -21,6 +21,8 @@ Say what the developer has now. Name the processes still running and the files t
 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.
 
 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
@@ -40,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.26.0 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.28.0 onboard checkpoint --phase awaiting-developer
 ```
 
 If they approve it, make that one fix and nothing else. Then come back into this run:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.26.0 onboard resume --message "<approval>"
+npx --prefer-offline --yes copilotkit@4.28.0 onboard resume --message "<approval>"
 ```
 
 Put the developer's approval in `--message`, in one or two sentences: the fix they
@@ -69,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.26.0 onboard friction --phase stop --category <slug> --message "<sentences>"
+npx --prefer-offline --yes copilotkit@4.28.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

@@ -32,8 +32,8 @@ Wiring is not behavior. The CopilotKit SDK dependency, the middleware the agent
 in, the runtime mount, the AG-UI connection, and a frontend that renders what the agent
 already returns are wiring. Plan them as ordinary steps.
 
-Every item on the behavior list is a change the developer has to approve. Where a step
-needs one, plan it as its own item, name the file and the exact change, and state that it
+Every item on the behavior list is a change the developer has to approve, so it goes under
+`Changes that need your approval`. Where a step needs one, plan it as its own item, name the file and the exact change, and state that it
 changes how the agent answers everywhere, not only in CopilotKit. A system prompt the
 developer wrote is the agent's behavior rather than a setting this run tunes until a
 component renders. Where the plan cannot be written without such a change and you cannot
@@ -56,7 +56,7 @@ shows a `runner` option instead, the Intelligence quickstart wins.
 The main coding agent gives you a Learning Container id, or tells you the Learning step was
 skipped for this organization.
 
-Where it gives you an id, plan two things and name both in the plan the developer approves:
+Where it gives you an id, plan two things and name both in the plan:
 the container id itself, and a `getLearningContainerId` callback returning that id on the
 `CopilotKitIntelligence` instance. Take the callback from the Learning page, and fetch it
 here rather than expecting the run to have handed it over:
@@ -97,7 +97,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.26.0 onboard upgrade-plan --json
+npx --prefer-offline --yes copilotkit@4.28.0 onboard upgrade-plan --json
 ```
 
 It reads the installed tree and the registry. Read `status`:
@@ -118,8 +118,8 @@ It reads the installed tree and the registry. Read `status`:
 
 The floor is 1.70.0 because the runtime resolves managed Intelligence entitlement
 authority from that version. Below it, the Intelligence features stay dark with no error.
-An exact pin is usually deliberate, so each move is a step the developer approves, not a
-repair the run invents halfway through. Where the developer needs a pin held, return
+An exact pin is usually deliberate, so a move of one is a change the developer
+approves, not a repair the run invents halfway through. Where the developer needs a pin held, return
 `Status: blocked` and name `unsupported/no-validated-path` as the outcome.
 
 A package the plan adds that a `@copilotkit/*` or `@ag-ui/*` package also depends on, such
@@ -131,6 +131,10 @@ version the target `@copilotkit/*` release requires, and plan the latest version
 Where the project already depends on that package, keep its version if that tree accepts
 it. Otherwise name the move in the plan, with the version it moves to.
 
+A version the documentation gives as a dist-tag, such as `ai-v6` in `@ai-sdk/openai@ai-v6`,
+is not a version. Resolve it with `npm view <package>@<tag> version`, and plan that exact
+version.
+
 Where the SDK requires an application-level value that the repository cannot supply, such
 as an end-user identity for threads, use one clearly marked local placeholder and name what
 production requires instead. Do not stop onboarding to ask the developer for it.
@@ -145,9 +149,10 @@ If the value of the journey depends on data the project already holds, name that
 name where it lives, and name how it reaches the agent. Rendering a list in the DOM does
 not give the agent access to it. An agent wired without the page's data answers from
 entities it invents, and the answer looks correct. Take the frontend-context step from
-the selected documentation, and never guess the API. Where no selected page documents it
-for this framework or frontend, the data has no documented way to reach the agent: return
-`Status: blocked` and name `unsupported/no-validated-path` as the outcome.
+the selected documentation, and never guess a CopilotKit API. Where no selected page shows
+how this framework reads that data, the agent reads it from the AG-UI run input `context`,
+as https://docs.copilotkit.ai/agent-app-context.md shows. Name the agent code that reads
+`context` and passes it to the model.
 
 Where that data exists, name the entities the proof compares against: the ids, names, or
 records the project holds and the answer has to reference. Where the outcome references
@@ -180,24 +185,21 @@ 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.26.0 verify --round-trip`, which needs no browser. Do not plan a
+`npx --prefer-offline --yes copilotkit@4.28.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
 
 List these in the plan under `Files the run writes itself`, apart from the implementation
-steps. They are not steps, and they need no separate approval. A developer who approved a plan
-without them reads each one later as a change they never agreed to.
+steps. They are not steps, and they need no approval, except a file that is also under
+`Uncommitted files`: list that one under `Changes that need your approval` too.
 
 - Each `planChanges` entry from `onboard credentials`: the project key in the env file
   `environmentPath` names, the project record, and, where it lists `ignore-entries`, the
-  lines `project select` adds to `.gitignore` so that no credential env file can be
-  committed.
+  lines `project select` adds to `.gitignore` so that no credential env file and no
+  `.playwright-mcp/` browser snapshot can be committed.
 - `.copilotkit/proof/`, where the proof writes its evidence. It holds no source. The
   developer can delete it after the run.
-- The CopilotKit Skills, as a line the developer approves or declines:
-  `npx skills add CopilotKit/CopilotKit/skills -y`. It writes `.agents/skills/` and links
-  it into `.claude/skills/`. Both sit in the working tree and show up in `git status`.
 
 ## Scaffold an empty project
 
@@ -230,7 +232,8 @@ the plan under `Uncommitted files`, one line each, with the path and one sentenc
 what the step changes there and why no other file will do. Keep the step in the plan.
 Adding a feature to an app the developer already built is the case this exists for: the
 option lives in a file they wrote, and on an app whose work was never committed that file
-has uncommitted changes. The approved plan is the developer's consent. The CLI records none.
+has uncommitted changes. Each of those edits needs approval, so the developer's answer
+to the plan is their consent. The CLI records none.
 
 Installing or upgrading a package changes the manifest that lists it, such as `package.json`
 or `pyproject.toml`, and its lockfile, such as `package-lock.json` or `uv.lock`. Install
@@ -241,8 +244,8 @@ Do not plan the deletion of a file that has uncommitted changes, and do not plan
 moves or renames one. If a step cannot be written any other way, return `Status: blocked`
 and name the path.
 
-Keep final validation and proof outside the implementation steps. The developer approves
-one plan.
+Keep final validation and proof outside the implementation steps. The developer sees one
+plan.
 
 Keep a production build out of the validation commands. A type check plus the real round
 trip is the proof, and the round trip runs in development mode. Name the production build
@@ -256,8 +259,8 @@ directory in `nextjsWithoutCopilotKit`, plan it as its own step, before the firs
 that imports a CopilotKit package in that directory. Name the migration `file` and each
 change in `changes`, and give its `reason` in one sentence. Under `node` or `node10`
 resolution, TypeScript ignores a package's `exports` map, so every CopilotKit subpath
-import fails the type check while the app still runs. A plan without this step stops after
-approval to ask for it. If the file has uncommitted changes, list it under
+import fails the type check while the app still runs. A plan without this step stops partway
+through the build to ask for it. If the file has uncommitted changes, list it under
 `Uncommitted files`. Where no migration is reported, do not change
 `moduleResolution` or `module`. This change does not weaken type safety.
 
@@ -274,6 +277,54 @@ Do not add compiler strictness the project did not have. Nothing later in the ru
 allowed to weaken type safety, so a stricter gate named here is one the run cannot get
 back out of.
 
+## Name the changes that need approval
+
+The run shows the plan to the developer and goes on to build it without waiting. It stops
+for an answer only when the plan makes a change that needs approval. `onboard start` took a
+backup, so `onboard restore` undoes any other change the backup holds.
+
+List each change that needs approval under `Changes that need your approval`, one line each: the path
+or package, what the step does to it, and why the plan needs it. Write `none` when there is
+none. List every other change under `What I will change`. A step makes a change that needs
+approval when it:
+
+- upgrades a dependency by a major version: a move whose `to` has a different major version
+  than `from`, or a move of an exact pin
+- removes a dependency the app already uses, or moves one outside the range the app
+  declares
+- deletes, moves, or renames a file the developer wrote
+- changes a file that has uncommitted changes, from `Uncommitted files`
+- untracks a file or changes `.gitignore`, other than the lines under
+  `Files the run writes itself`
+- writes to an env file the app already uses, other than the key line for the key file
+  the setup answers recorded
+- changes the existing agent's behavior, as `What the existing agent's behavior is`
+  defines it
+- changes more than 10 files in all. Count only the files the plan's own steps change. Do
+  not count a file the framework's own tooling writes by itself, such as the `AGENTS.md`
+  and `CLAUDE.md` that `next dev` writes, or a file under `Files the run writes itself`.
+  The limit is the same one the backup tripwire sets for deleted files
+- writes a file outside the project directory
+- changes the version of any CopilotKit dependency: an `@copilotkit/*` package or the
+  `copilotkit` Python package, by any amount
+
+A change the developer approved in the setup message needs no approval in the plan. The setup
+answers the main coding agent gives you show it: `envFile` is `approved` for the untrack or
+the `.gitignore` line that the env-file line named, and `alternative` for the key in the other
+env file. `uncommittedWrites: approved` allows the connection's writes to the env file and
+`.copilotkit/project.json`. Name each one under the notes instead.
+
+The plan also needs approval when the backup does not hold every file: `backup.status` is
+`partial` or `failed` in the `backup` result the main coding agent gives you. Name it as a
+line of its own. For `partial`, name each path in `backup.notHeld` with its `why`, which
+names the limit for a size skip, and the count in `backup.moreNotHeld` if any. For
+`failed`, name the cause in `backup.detail`, and that `onboard restore` puts nothing back.
+A step that changes one of those paths cannot be undone. `pending` needs no approval: the CLI
+takes the backup when the run moves to the chosen project, or at the next step, before any
+change. Say that in the plan.
+
+Do not leave a change that needs approval out of the list to keep the run moving.
+
 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.