copilotkit 4.27.0 → 4.28.0

package/onboarding/prompts/setup/questions.md

@@ -1,246 +1,65 @@
 # Ask the setup questions together
 
 Do not change application code in this phase. Do not read, show, store, or request a secret value.
-
-## Settle what the findings already answer
-
-Do not ask the developer for a fact that the repository or their request answers.
-
-- If the project already has an agent in a listed framework, keep that framework and its
-  model setup. Record its vendor, or `other` if you cannot tell, with the choice
-  `existing`.
-- An existing agent in no framework the table below lists takes the Custom agent route,
-  which keeps it and connects it through AG-UI, directly or through an adapter.
-- If the project already has a frontend, keep it.
-- A choice the developer already named in their request or a later reply is settled. So
-  is a framework the project's README names, even in an otherwise empty target.
-
-## Frameworks this machine cannot run yet
-
-The research findings' `unready` list names each framework this machine cannot run yet,
-and the toolchain it needs.
-
-- Do not recommend a framework on that list.
-- List a framework on that list last, by name only.
-- Do not install a toolchain yourself.
-
-## The questions
-
-Ask every open choice in one message, one line each, numbered in order. Leave out a settled line.
-Do not ask about the plan here.
-
-Open the message with "Reply **go** to use all <count>, or tell me what to change."
-`<count>` is the number of lines that **go** answers. Write each line as the topic, a
-colon, and the recommendation in bold. Add a short reason only when it names something in the
-developer's own project, such as "from your README". On the next line, indented, write
-"Other:" and the alternatives, separated by " · ". Write "Other, for example:" when the
-developer can pick an option the line does not list. Say what an option needs only after
-the developer picks it. In an empty target:
-
-```text
-Reply **go** to use all five, or tell me what to change.
-
-1. Framework: **LangGraph TypeScript**
-   Other, for example: LangGraph Python · Mastra · ADK
-2. Model: **OpenAI**
-   Other, for example: Groq · OpenRouter (any OpenAI-compatible provider)
-3. Key: **I ask for the key file after I build the app**
-   Other: name the file now (outside this folder)
-4. Frontend: **Next.js**
-   Other: React SPA · Vue 3 · React Native · Angular · Slack · Microsoft Teams
-5. Project: **new project "copilotkit-assistant"**
-   Other: another name · a project you already have
-```
-
-A line that recommends nothing keeps its own wording and has no "Other:" line: the
-`env-file-exposed` line with `question.untrack` and no `question.alternative`, the
-uncommitted-changes line, or a held-back vendor, with the note "Read the reply" gives.
-**go** does not answer it. Open with "Reply **go** to use the other <count>, and answer
-line <number>." For several, "Reply **go** to use the others, and answer lines <a> and
-<b>." With one line: "Reply **go** to use it, or tell me what to change." When every line
-needs its own answer, write no **go** sentence: open with "Answer each line."
-
-**The purpose line.**
-
-Ask this line only when neither the request nor the repository shows what the project is
-for. Recommend "a general assistant", and give two short examples. In an empty target, do
-not ask it: record the purpose the request names, or "a general assistant".
-
-**The framework line.**
-
-If the project has no agent, ask this line. Recommend a framework in the repository's
-language. In an empty target, use the example's line.
-
-The vendors each framework takes in this release, default first:
-
-| Framework                          | Vendors                                      |
-| ---------------------------------- | -------------------------------------------- |
-| AG2                                | OpenAI, OpenAI-compatible                    |
-| ADK                                | Google, OpenAI, OpenAI-compatible            |
-| Agno                               | OpenAI, OpenAI-compatible                    |
-| Built-in CopilotKit agent          | OpenAI, Anthropic, Google, OpenAI-compatible |
-| Claude Agent SDK (Python)          | Anthropic only                               |
-| Claude Agent SDK (TypeScript)      | Anthropic only                               |
-| CrewAI Flows                       | Project-defined                              |
-| Custom agent                       | The agent's own                              |
-| Deep Agents                        | OpenAI, OpenAI-compatible                    |
-| LangGraph FastAPI                  | OpenAI, OpenAI-compatible                    |
-| LangGraph Python                   | OpenAI, OpenAI-compatible                    |
-| LangGraph TypeScript               | OpenAI, OpenAI-compatible                    |
-| LlamaIndex                         | OpenAI, OpenAI-compatible                    |
-| Mastra                             | OpenAI, OpenAI-compatible                    |
-| Microsoft Agent Framework (.NET)   | OpenAI, OpenAI-compatible                    |
-| Microsoft Agent Framework (Python) | OpenAI, OpenAI-compatible                    |
-| MS Agent Harness (.NET)            | OpenAI, OpenAI-compatible                    |
-| Pydantic AI                        | OpenAI, OpenAI-compatible                    |
-| Strands Agents (Python)            | OpenAI, OpenAI-compatible                    |
-| Strands Agents (TypeScript)        | OpenAI, OpenAI-compatible                    |
-
-"Project-defined" keeps the repository's vendor, or asks once when it shows none.
-
-"The agent's own" keeps the existing agent's vendor, with no vendor question. A new agent
-on the Custom agent route asks the model and key lines like any new agent, with OpenAI as
-its default vendor.
-
-For a new agent in a framework the table does not list, record its name and take the Custom
-agent route.
-
-**The model and key lines.**
-
-For a new agent, ask the model line, even if the framework needed no question. Skip it for
-"Project-defined" or "The agent's own". The model line names providers only: the row's
-default vendor, then its other vendors on "Other, for example:", except on an "only" row,
-where the model line has no "Other:" line.
-
-Ask the key line for a new agent only. Never ask for the key itself. Recommend the key file
-the developer named, or the project's env file under the rule below, or else "I ask for the
-key file after I build the app", which **go** takes. Its "Other:" is the example's, or
-"later" after a file.
-
-An OpenAI-compatible provider uses `OPENAI_API_KEY`. When the developer names one, ask in
-the same line for its model id, and its base URL unless the key file sets
-`OPENAI_BASE_URL`. Neither is a secret.
-
-When the developer has no key yet, name the ways forward on the key line: credit on the
-vendor's account, and, when the chosen framework can use Google, a free key from Google AI
-Studio at https://aistudio.google.com/apikey. The free tier limits requests per minute, so
-tell them that a slow first reply is that limit and not a fault.
-
-A path the developer names is theirs to give, even outside the project. Recommend the
-project's env file only when it exists, holds the key, and git ignores and does not track
-it, and no `env-file-exposed` line is open. In an empty target, a new key file goes outside
-the target directory, because `init` refuses a target with a `.env` file. Tell the
-developer only where it goes.
-
-**The frontend line.**
-
-If the project has no frontend, ask this line. Recommend the one the developer names, or
-Next.js. "Other:" is the example's list.
-
-**The project line.** On the local route, ask the local lines below instead. For an
-existing app, first run `npx --prefer-offline --yes copilotkit@4.27.0 onboard credentials --json` from the target app
-directory. It only reads: it creates no project and writes no file. Read `status`:
-
-- `ready`: the app has a project. Leave the line out.
-- `needs-developer` with `project-name`: recommend `suggestedName`, with the
-  example's "Other:" line. If there is no `suggestedName`, ask for a name. Do not list
-  the organization's projects.
-- `needs-developer` with `env-file-exposed`: git tracks the env file the key goes into, or
-  does not ignore it. Add `question.ask` as its own line, word for word: never shorten it or
-  drop what it says about teammates. Without `question.untrack`, recommend approving it:
-  without it, the run writes no key, and **go** approves it. With `question.untrack`, git
-  tracks the file: recommend `question.alternative` if present, since the key then goes into
-  `question.alternative.file`, which affects no teammate, and **go** takes it. Otherwise
-  recommend nothing. Untracking removes the file for everyone who pulls the next commit. A
-  reply that accepts every recommendation never approves the untrack. Never suggest a
-  reply that approves it. Then offer a new project for this app, or a project the developer
-  already has.
-- `stopped`: the command already filed the stop report. Tell the developer
-  `stopReason.detail` in one sentence, then stop onboarding.
-
-For an empty target, recommend a new project named after the target directory, with the
-same "Other:" line. When that name is generic, such as `project`, `app`,
-`web`, `frontend`, or `src`, name it after the README title or the `package.json` `name`
-instead.
-
-**Local lines.** On the local route only:
-
-- Run `npx --prefer-offline --yes copilotkit@4.27.0 onboard local-terms --json` and follow `next`.
-- "Learning model: **configure later**", then "Other:
-  guided setup in your own terminal · a private model file you have".
-- "Local connection: **install the local stack, then write `<app directory>/<env file>`
-  and `<app directory>/.copilotkit/project.json`**", then "Other: not now". A reply that
-  accepts every recommendation approves the connection.
-- When the env file or `.copilotkit/project.json` has uncommitted changes, add one line that
-  names every one of them: "Uncommitted changes: `<files>` have edits that are not
-  committed, and the connection changes their settings. Allow it, or commit first?" One
-  answer covers every file on that line. A reply that accepts every
-  recommendation never approves those writes.
-
-Before you end your turn to wait for the developer, report the pause:
+Never ask for the key itself: the message asks only for the file that holds it.
+
+## Record what the findings already answer
+
+Do not ask the developer for a fact that the repository or their request answers. Record
+each one with `npx --prefer-offline --yes copilotkit@4.28.0 onboard setup-answers` before you build the
+message, so the message leaves it out:
+
+- An agent the project already has: `--framework <name>` with its vendor and the choice
+  `existing`: `--vendor <vendor> --vendor-choice existing`, or `--vendor other
+--vendor-choice existing` if you cannot tell the vendor. An
+  agent in no framework the CLI names takes the Custom agent route: add
+  `--custom-framework`. It keeps the agent and connects it through AG-UI.
+- A frontend the project already has: `--frontend <name>`.
+- What the project is for, when the request or the repository shows it: `--purpose <text>`.
+- A choice the developer named in their request or a later reply, and a framework the
+  project's README names, even in an otherwise empty target: the matching flag. For a
+  framework, add `--framework-choice developer`. A vendor the developer named goes on the
+  command below as `--vendor`, not here.
+- For a project with no agent, you can infer the language's usual framework. Record it
+  without `--framework-choice`, and the CLI keeps it as a default the developer can change.
+- A key file the developer named: `--key-file <path>`. Record the project's env file only
+  when it exists, holds the key, and git ignores it and does not track it.
+
+## Build the message
+
+For an existing app on the managed route, the command reads the app's project itself, so its
+env-file and project lines are in the same message as the key. That read creates no project
+and writes no file. If the command prints `status: stopped`, do what its `next` says.
+
+On the local route, first run `npx --prefer-offline --yes copilotkit@4.28.0 onboard local-terms --json`.
+If it reports `signed-out` or `unavailable`, follow its `next`. Do not add its
+`question.ask` yourself: the setup message already carries the agreement line.
+
+From the target app directory, run:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.28.0 onboard setup-message --target <empty|existing> [--language <typescript|python|dotnet>] [--vendor <vendor>]
 ```
 
-With no line open, ask nothing and continue.
-
-## Read the reply
-
-A reply such as "go", "yes" or "go ahead" accepts every recommendation. A line the reply
-changes takes the new answer. A line it does not mention keeps its recommendation.
-
-If a changed line makes another answer invalid, ask again, in one message:
-
-- A vendor that the chosen framework's own model layer cannot use, such as OpenAI for the
-  Claude Agent SDK: say so, and offer the framework with its default vendor, or another
-  framework for their vendor.
-- Anthropic or Google for a new agent on a row without it: say that this release supports
-  the row's vendors there, that Anthropic and Google come in a later release, and offer the Built-in
-  CopilotKit agent if they need them now.
-- Slack or Microsoft Teams as the frontend of an empty project: the Channel starter brings
-  its own agent, so the framework, model, and key lines decide nothing. Drop all three:
-  `<count>` counts only the lines shown.
-
-If the developer chooses a framework on the `unready` list, or the repository already has
-an agent in one, keep that framework. Before the run changes the project, tell the
-developer in one message:
-
-1. Which toolchain to install, and its install page.
-2. That the coding agent sees the toolchain only after a restart, since its shell
-   reads PATH at start.
-3. That the run resumes after the restart with
-   `npx --prefer-offline --yes copilotkit@4.27.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.27.0 onboard checkpoint --phase awaiting-developer
-```
-
-Then end your turn and wait for the developer. That restart is a step here, not an error.
-
-## Record the answers
-
-Record every answer in the CLI. They answer
-the framework, provider, and frontend questions for the rest of the run. Give them to each
-subagent too. Pass the flags that apply:
+- `--target empty` for a target with no project yet, `existing` for one with a project.
+- `--language` is the project's language, for a project with no agent.
+- `--vendor` is a model vendor the developer named, as `openai`, `anthropic`, `google`, or
+  `openai-compatible`.
 
-- `--purpose <text>`, `--framework <name>` (a name from the table, or another
-  framework's name), and `--frontend <name>`.
-- `--vendor <vendor>`: `openai`, `anthropic`, `google`, `openai-compatible`, or `other`,
-  with `--vendor-choice <choice>`: `developer`, `default` (the row's default), or `existing`
-  (an existing agent's). For
-  `openai-compatible`, add `--model-id <id>`, and `--base-url <url>` unless the CLI
-  printed `keyFileBaseUrl`: show that one.
-- `--create <name>` for a new project or `--project <slug>` for theirs, and
-  `--key-file <path>` or `--key-later`.
-- On the local route: `--learning later`, `--learning guided`, or `--learning-file <path>`.
-  Then `--connection approved` or `declined`. For an uncommitted-changes line the reply
-  answered, add `--uncommitted-writes approved` or `declined`.
+Then do what its `next` says. With no `message`, as for `settled` or `needs-credentials`,
+ask the developer nothing and go on as `next` says. When it prints a `message`, write it in
+your own reply word for word. The developer does not see your tool output. Before it you can
+put the one short line `next` names, and add nothing else. Before you end your turn to wait for the developer, report the pause:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard setup-answers --framework <name> --vendor <vendor> --create <name> --key-file <path>
+npx --prefer-offline --yes copilotkit@4.28.0 onboard checkpoint --phase awaiting-developer
 ```
 
-Then run `npx --prefer-offline --yes copilotkit@4.27.0 onboard read credentials/plan`.
+Then end your turn and wait for the developer. When the developer replies, record their
+answers with `onboard setup-answers`, and run `onboard setup-message` again with
+`--accept-defaults`, as `next` says. When it prints `status: settled`, run
+`npx --prefer-offline --yes copilotkit@4.28.0 onboard read credentials/plan`. If you came here from
+`research/gather` before the research merged, do not read `credentials/plan` yet: finish the
+research. If it returns and the developer has not replied, record what the findings settle
+with `onboard setup-answers`, then end your turn and send the developer nothing. Report
+the pause with `onboard checkpoint --phase awaiting-developer` first.

package/onboarding/prompts/starter/clone.md

@@ -1,6 +1,6 @@
 # Clone a starter
 
-First run `npx --prefer-offline --yes copilotkit@4.27.0 onboard setup-answers`. It prints the answers that
+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
@@ -22,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.27.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:
@@ -68,7 +68,7 @@ again.
 
 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 as the setup message does:
+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.
@@ -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.27.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
@@ -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.27.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
@@ -119,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.27.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
@@ -132,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.27.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`.
@@ -155,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.27.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`.
@@ -176,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.27.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.27.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.27.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.27.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
@@ -202,7 +204,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.27.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.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.
@@ -212,11 +214,11 @@ file. The CLI selects the latest stable release. If the developer gave a candida
 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.27.0 onboard local-terms --json`. If `accepted`
+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.27.0 local accept-terms`. Never accept the agreement yourself.
+`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.27.0 onboard checkpoint --phase awaiting-developer`, end your turn,
+`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.
 
@@ -226,7 +228,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.27.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
@@ -235,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.27.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.27.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
@@ -275,7 +277,7 @@ later release, and offer the Built-in CopilotKit agent if they need them now.
 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,
+--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
@@ -299,7 +301,15 @@ 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
@@ -313,18 +323,17 @@ The two Microsoft Agent Framework starters keep their key outside `<target>/.env
 
 - 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.27.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.
@@ -340,7 +349,7 @@ 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.27.0 onboard credentials --model-key <VARIABLE> --json
+npx --prefer-offline --yes copilotkit@4.28.0 onboard credentials --model-key <VARIABLE> --json
 ```
 
 The command never prints a value. If `status` is `ready`, continue. Otherwise do what
@@ -353,7 +362,7 @@ works and the app's model does not: the vendor does not serve the model that
 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.27.0 onboard read proof/round-trip`.
+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
@@ -366,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.27.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.27.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>`.
@@ -381,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.27.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
@@ -391,6 +400,6 @@ 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.27.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

@@ -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.27.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.27.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
@@ -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.27.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