copilotkit 4.26.0 → 4.28.0

package/onboarding/prompts/proof/round-trip.md

@@ -1,15 +1,17 @@
 # Prove the user journey
 
 Do not do the proof work yourself. Spawn one proof subagent. Tell it to run
-`npx --prefer-offline --yes copilotkit@4.26.0 onboard read subagent/prove-round-trip` first and follow the
+`npx --prefer-offline --yes copilotkit@4.28.0 onboard read subagent/prove-round-trip` first and follow the
 prompt it returns. Tell it to return at once, and say so, if that read is refused or fails,
 and not to wait for an approval. If it returns that way, stop that subagent. Run the same
 command yourself, then spawn a fresh subagent with the returned prompt and the same handoff.
 Give it the selected framework, frontend, model, approved plan, selected documentation URLs,
 and validation evidence. Give it the documentation policy recorded during framework
 selection or conversion planning. On a conversion, also give it the frozen criterion. Give
-it the paths that had uncommitted changes when the run started. Give it the developer's answer on the Skills install and the
-Skills result the implementation returned.
+it the paths that had uncommitted changes when the run started.
+
+When you start a subagent in the background, tell the developer in one sentence what it
+does. Then send nothing more until it returns. This holds for a repair subagent too.
 
 Give it the frontend files that publish the page context and register the tools, by path,
 from the Files changed sections the implementation returned. The subagent sends what those
@@ -32,16 +34,13 @@ device control, and have it report `skipped-cloned-starter` rather than a missin
 capability: nothing was unavailable, the run declined to spend it. That outcome completes
 the run.
 
-Give the subagent this guide for continued-development tools:
-https://docs.copilotkit.ai/build-with-agents.md
-
 Wait for the subagent to finish. Its result arrives as a notification. Do not sleep to
 pass the time.
 
 Record what that proof returned before you route on it:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.26.0 onboard proof --step round-trip --outcome <passed|failed|skipped>
+npx --prefer-offline --yes copilotkit@4.28.0 onboard proof --step round-trip --outcome <passed|failed|skipped>
 ```
 
 Report the gate whatever it returned. A proof that never ran is `skipped`, not failed. A
@@ -53,7 +52,7 @@ the next one starts. Until then, `onboard proof-check` counts the next failure a
 If the CLI prints `## Stop: this run deleted or moved the developer's work` instead of a
 step, show the developer the list it printed, and run what they choose:
 the `onboard restore` command the tripwire stop prints, which names each deleted file, or
-`npx --prefer-offline --yes copilotkit@4.26.0 onboard tripwire --continue`. Then read the step again. If
+`npx --prefer-offline --yes copilotkit@4.28.0 onboard tripwire --continue`. Then read the step again. If
 you cannot ask, use the route-out rules below.
 
 Never repair, reset, or revert a file the developer changed outside this run. That holds for
@@ -66,16 +65,15 @@ This prompt pauses for the developer in several places. Before you end your turn
 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 the proof result starts with `Status: passed`, run
-`npx --prefer-offline --yes copilotkit@4.26.0 onboard read proof/complete`. A performed surface outcome with
-the full round trip is core success even if a continued-development tool fails. A skipped
+`npx --prefer-offline --yes copilotkit@4.28.0 onboard read proof/complete`. A skipped
 surface outcome still enters `proof/complete`. The CLI records `skipped-cloned-starter` and
 `skipped-no-browser-tool` after a passed round trip as complete, and `skipped-no-device` as
 blocked. Do not describe a
-skipped surface as proved. Keep the Skills result separate from the proof result.
+skipped surface as proved.
 
 A passed result can carry the surface-check outcome `failed` with the cause
 `browser-control-unresponsive`. It means that the browser tool stopped answering, not that
@@ -97,7 +95,7 @@ credentials step found the model key missing, or the vendor refused it, and the
 started nothing. Do not send it to a repair worker. Run the `onboard credentials` command
 that its detail names, and act on its answer as `credentials/settle-credentials` says. Ask
 the developer its question, report the pause with
-`npx --prefer-offline --yes copilotkit@4.26.0 onboard checkpoint --phase awaiting-model-credential`, and
+`npx --prefer-offline --yes copilotkit@4.28.0 onboard checkpoint --phase awaiting-model-credential`, and
 end your turn. When the key settles, run the proof subagent again. If you have not recorded
 this attempt yet, record it first, with the outcome it ended with. This attempt does not
 count toward the three.
@@ -124,7 +122,7 @@ fault, so this is not a route-out. Ask the developer to send one message in the
 thread, and to give you that thread's id. Give them the app URL and the request words from
 the result. Tell them where the id is: in the browser's network tools, the request the page
 sends to the runtime URL carries `threadId` in its body. Report the pause with
-`npx --prefer-offline --yes copilotkit@4.26.0 onboard checkpoint --phase awaiting-developer` and end your
+`npx --prefer-offline --yes copilotkit@4.28.0 onboard checkpoint --phase awaiting-developer` and end your
 turn. When the developer gives the id, start a new proof subagent with
 the full original proof handoff, the pinned Step 1 record, and the thread id. Tell it to run
 the proof checks with `--thread <id>`. This attempt does not count toward the three. Use the
@@ -167,19 +165,19 @@ that returns blocked because the repair needs a file the plan does not name. Han
 way `implementation/build-and-validate` does: pause and ask the developer, add the file to
 the handoff if they allow it, and use the route-out rules below if they decline. Then spawn a
 fresh repair worker with this repair handoff, not the whole-plan implementation handoff: the
-plan, the proof evidence, the paths that had uncommitted changes when the run started, the
-files the developer allowed, and the developer's answer on the Skills install.
+plan, the proof evidence, the paths that had uncommitted changes when the run started, and
+the files the developer allowed.
 
 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
 ```
 
 Restart each project-owned process changed by the repair. Then spawn a fresh proof subagent
 with the full original proof handoff, failed proof evidence, and new validation evidence.
 This handoff includes the plan, documentation, policy, current process IDs, ports,
-surface-control state, the continued-tools guide, and the failed attempt's pinned Step 1
+surface-control state, and the failed attempt's pinned Step 1
 record. Carry that record so the second attempt sends the request the first one failed on.
 A fresh subagent given the plan alone writes its own request where the plan named none, and
 its grounding check then speaks about a question the failed attempt never asked.
@@ -191,7 +189,7 @@ takes the developer path above instead.
 
 Route out only when the failure is not yours to fix, when the same proof still fails after
 three attempts, or when no evidence of the round trip can be produced. In those cases run
-`npx --prefer-offline --yes copilotkit@4.26.0 onboard read stopped/run-failed`. The stack is supported:
+`npx --prefer-offline --yes copilotkit@4.28.0 onboard read stopped/run-failed`. The stack is supported:
 this run did not finish, which is a different ending and a different report. All three are
 about the round trip itself. A round trip that proved is not one of them, whatever failed
 after it.
@@ -202,7 +200,7 @@ friction command follows the telemetry setting the developer already chose, so i
 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 it.

package/onboarding/prompts/research/gather.md

@@ -3,7 +3,8 @@
 The developer can still be signing in. Keep reading the login process as
 `authenticate/start` says while this phase runs. This phase inspects the project and proves
 what this environment can drive. Do not change application code here, and do not ask the
-developer a setup question yet: every read-only investigation finishes first.
+developer a setup question yet, except the setup message below: every other read-only
+investigation finishes first.
 
 ## Rules for the whole run
 
@@ -14,10 +15,10 @@ own bookkeeping. Say what the run is doing in the developer's words instead.
 
 Every later command must run from the directory this run is bound to. Elsewhere, the
 command cannot find its run and refuses. Do not report that refusal as a stop. Run
-`npx --prefer-offline --yes copilotkit@4.26.0 onboard start --run <onboarding_run_id>` where you are
+`npx --prefer-offline --yes copilotkit@4.28.0 onboard start --run <onboarding_run_id>` where you are
 standing, then run the refused command again.
 
-If you no longer hold the id, run `npx --prefer-offline --yes copilotkit@4.26.0 onboard start` in the
+If you no longer hold the id, run `npx --prefer-offline --yes copilotkit@4.28.0 onboard start` in the
 directory this run started in, with no `--run` and no `--intent`. It reprints the id
 and starts nothing. An id this project does not already hold starts a second
 run, and the work already done stops counting toward the first.
@@ -82,7 +83,7 @@ When that thing arrives, continue. A pause waits for one of two things:
 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
 ```
 
 When the answer or the result arrives, continue from the step that paused. Do not read an
@@ -102,7 +103,7 @@ Both research subagents failing means this harness has no working subagent at al
 is worth recording once:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.26.0 onboard checkpoint --phase delegation-unavailable
+npx --prefer-offline --yes copilotkit@4.28.0 onboard checkpoint --phase delegation-unavailable
 ```
 
 Then say once, in your own words, that this environment has no working subagents. Say that
@@ -112,14 +113,14 @@ For the rest of this run, do not spawn a subagent where a prompt tells you to. R
 `subagent/` brief yourself and follow it.
 
 Before you ask the developer any setup question, finish every read-only investigation and
-preflight check in this section.
+preflight check in this section. The setup message below is the one exception.
 
 Prepare two research assignments. Before you spawn either subagent, run these two
 read-only commands yourself, from the target project directory:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.26.0 onboard read subagent/inspect-repository
-npx --prefer-offline --yes copilotkit@4.26.0 onboard inspect --json
+npx --prefer-offline --yes copilotkit@4.28.0 onboard read subagent/inspect-repository
+npx --prefer-offline --yes copilotkit@4.28.0 onboard inspect --json
 ```
 
 Give each research subagent the prompt that the first command returns, the whole JSON that
@@ -137,11 +138,38 @@ Start both research subagents in parallel:
 2. Spawn a second research subagent. Assign it the environment evidence packet.
 3. Start both research subagents. Then continue.
 
+## Show the setup message while the research runs
+
+For some folders the setup message needs nothing that the research finds. Then the
+developer reads it while the research runs. That is the case when the developer's request
+names no Channel (as `research/route` lists), and the `onboard inspect` JSON shows one of:
+
+- `appDiscovery.reason` is `no-project`: the folder holds no project.
+- A frontend and no agent: `detection.frontend` has a `match`, and
+  `detection.agentFramework` has an empty `matched` and an empty `unmatched`.
+
+Once `login --json` has emitted `type: completed`, read the setup questions now:
+`npx --prefer-offline --yes copilotkit@4.28.0 onboard read setup/questions`. Record the frontend from
+`detection` first.
+Show the message. 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
+```
+
+Then continue below: the preflight and the merge do not wait for the reply. When the
+developer replies, record the reply as that prompt says. If `research/route` sends you back
+to the setup questions before the developer replied, do not show the message again: the
+pause above still holds.
+
+In any other folder, such as one with an agent, the research can change the message. Keep
+the research first.
+
 The research is under way. Continue to the surface-control preflight while it runs:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.26.0 onboard read research/preflight
+npx --prefer-offline --yes copilotkit@4.28.0 onboard read research/preflight
 ```
 
 If inspection stops onboarding, run
-`npx --prefer-offline --yes copilotkit@4.26.0 onboard read stopped/run-failed`.
+`npx --prefer-offline --yes copilotkit@4.28.0 onboard read stopped/run-failed`.

package/onboarding/prompts/research/merge.md

@@ -51,11 +51,11 @@ waits on the developer, end your turn and wait for it: that is a pause.
 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
 ```
 
 When both research results are merged and sign-in is done, run
-`npx --prefer-offline --yes copilotkit@4.26.0 onboard read research/route`.
+`npx --prefer-offline --yes copilotkit@4.28.0 onboard read research/route`.
 
 If inspection stops onboarding, run
-`npx --prefer-offline --yes copilotkit@4.26.0 onboard read stopped/run-failed`.
+`npx --prefer-offline --yes copilotkit@4.28.0 onboard read stopped/run-failed`.

package/onboarding/prompts/research/preflight.md

@@ -32,8 +32,8 @@ Where the device probe found no booted device, that is the whole finding.
 Then merge the research:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.26.0 onboard read research/merge
+npx --prefer-offline --yes copilotkit@4.28.0 onboard read research/merge
 ```
 
 If inspection stops onboarding, run
-`npx --prefer-offline --yes copilotkit@4.26.0 onboard read stopped/run-failed`.
+`npx --prefer-offline --yes copilotkit@4.28.0 onboard read stopped/run-failed`.

package/onboarding/prompts/research/route.md

@@ -21,7 +21,7 @@ On any one of them, run this before you read the three findings below, and witho
 the purpose question:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.26.0 onboard read feature/channels/start
+npx --prefer-offline --yes copilotkit@4.28.0 onboard read feature/channels/start
 ```
 
 Name the provider to that node so it does not ask again. A `/slack` page names Slack. A
@@ -82,7 +82,7 @@ settle these three from your own reading of the project. Each one comes from the
 packets or it is not proved.
 
 If all three are proved, prove the live starting state before any project file changes. Run
-`npx --prefer-offline --yes copilotkit@4.26.0 onboard read proof/oss-baseline`.
+`npx --prefer-offline --yes copilotkit@4.28.0 onboard read proof/oss-baseline`.
 
 Route there before any other question to the developer. The questions after this prompt
 select a framework and a frontend that the findings already name, so a developer who
@@ -91,10 +91,16 @@ application is what that node protects. Whether it works is what the proof decid
 these three findings.
 
 For every other combination of the three, run
-`npx --prefer-offline --yes copilotkit@4.26.0 onboard read setup/questions`. That node asks every
+`npx --prefer-offline --yes copilotkit@4.28.0 onboard read setup/questions`. That node asks every
 remaining setup question in one message, including what the project is for when nothing
 proves it.
 
+On a blank folder the setup message can go out before the research ends. If the setup
+message is already out 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. Do not remind them,
+and do not restate the setup. Their reply continues the run.
+
 If authentication or inspection stops onboarding, run
-`npx --prefer-offline --yes copilotkit@4.26.0 onboard read stopped/run-failed`. Neither says anything
+`npx --prefer-offline --yes copilotkit@4.28.0 onboard read stopped/run-failed`. Neither says anything
 about whether this project's stack is supported, which is not yet known at this point.

package/onboarding/prompts/setup/questions.md

@@ -1,213 +1,65 @@
 # Ask the setup questions together
 
-The route is chosen. This node asks, in one message, every setup choice that the findings
-and the developer's request do not settle. 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 the vendor that the setup uses, or `other` if you cannot tell, with
-  the choice `existing`.
-- An existing agent that speaks AG-UI, but is none of the frameworks in the table below,
-  takes the Existing AG-UI agent route. For example, an `AbstractAgent` subclass that the
-  project wrote, or a service behind AG-UI middleware. Select it only for an agent that the
-  repository already has, and only when the findings prove that it speaks AG-UI. Do not
-  offer it for a new agent.
-- If the project already has a frontend, keep it.
-- A choice the developer already named in their request or a later reply is settled.
-
-## Frameworks this machine cannot run yet
-
-The research findings carry the CLI's toolchain reading. Its `unready` list names each
-framework that this machine cannot run until a toolchain is installed, and the toolchain
-it needs. Read that list before you ask the framework question, so the developer learns
-about a missing toolchain before they choose, and not after.
-
-- Do not recommend a framework on that list.
-- When you show a framework on that list, show it after the ready ones. In the same line,
-  name the toolchain it needs and its install page.
-- Do not install a toolchain yourself.
-
-## The questions
-
-Ask every choice that is still open at this point in one message, one numbered line per
-choice, so that one reply can accept every recommendation. Put the recommendation first,
-give its evidence in one sentence, and keep the alternatives short. Do not ask a yes-or-no
-question first. Leave out a line whose answer is settled. Do not ask about the plan
-here.
-
-**Line 1: what the project is for.**
-
-If neither the developer nor the repository findings prove what the project is for, ask
-this line. It asks what the developer wants to build before the framework is chosen.
-Give two or three short examples.
-
-Do not ask it when the target directory holds no project. The frontend they pick decides
-whether a starter exists. Next.js and Angular have starters for some agent frameworks.
-React SPA, Vue 3 and React Native have no starter, so the project is built from their
-documentation. Slack and Microsoft Teams are choices at that step. A purpose question here
-names a domain before that choice.
-
-**Line 2: the agent framework.**
-
-If the project has no agent, ask this line. Show the options and one
-recommendation based on repository evidence. Match the language the repository already
-uses. When the framework is unknown, give it one line that lists the recommendation and
-valid choices.
-
-If the project is empty, state that no repository-based recommendation exists. Give these
-documented defaults: LangGraph TypeScript, LangGraph Python, ADK, Microsoft Agent Framework
-Python, Microsoft Agent Framework .NET, and Mastra. Explain which default matches the
-developer's stated purpose. Show the other listed frameworks as options. Do not describe a
-documented default as a repository-based recommendation.
-
-These are the agent frameworks, their default vendors, and the vendors that this run can
-set up for a new agent. Each documented vendor has a credential variable and setup steps on
-the framework's CopilotKit pages:
-
-| Framework                          | Default vendor  | Documented vendors        |
-| ---------------------------------- | --------------- | ------------------------- |
-| AG2                                | OpenAI          | OpenAI                    |
-| ADK                                | Google          | Google                    |
-| Agno                               | OpenAI          | OpenAI                    |
-| Built-in CopilotKit agent          | OpenAI          | OpenAI, Anthropic, Google |
-| Claude Agent SDK (Python)          | Anthropic       | Anthropic                 |
-| Claude Agent SDK (TypeScript)      | Anthropic       | Anthropic                 |
-| CrewAI Flows                       | Project-defined |                           |
-| Existing AG-UI agent               | The agent's own |                           |
-| Deep Agents                        | OpenAI          | OpenAI                    |
-| LangGraph FastAPI                  | OpenAI          | OpenAI                    |
-| LangGraph Python                   | OpenAI          | OpenAI                    |
-| LangGraph TypeScript               | OpenAI          | OpenAI                    |
-| LlamaIndex                         | OpenAI          | OpenAI                    |
-| Mastra                             | OpenAI          | OpenAI, Anthropic         |
-| Microsoft Agent Framework (.NET)   | OpenAI          | OpenAI                    |
-| Microsoft Agent Framework (Python) | OpenAI          | OpenAI                    |
-| MS Agent Harness (.NET)            | OpenAI          | OpenAI                    |
-| Pydantic AI                        | OpenAI          | OpenAI                    |
-| Strands Agents (Python)            | OpenAI          | OpenAI, Anthropic         |
-| Strands Agents (TypeScript)        | OpenAI          | OpenAI, Anthropic         |
-
-"Project-defined" is not a missing default. It means that framework's own route settles
-the vendor with the developer: it keeps the one the repository already uses, and asks a
-single question when the repository shows none.
-
-"The agent's own" means that the route keeps the vendor the existing agent already uses.
-Ask no vendor question for it.
-
-Do not offer a framework that is not listed above. Do not port an existing agent to another
-framework.
-
-**Line 3: the model and its key.**
-
-Settle the vendor and where its key is here: without a key from that vendor, the developer
-cannot answer the later key question.
-
-For a new agent, ask this line, even if the framework needed no question. Skip it for an
-existing agent, and when the default vendor is "Project-defined" or "The agent's own":
-those routes settle the vendor themselves. Recommend the row's default vendor and, in the
-same sentence, ask where its key is: a file, or that they will add it later. When the row
-documents more than one vendor, name the others. Offer no vendor the row does not name. For
-example, for the built-in agent: "Model: OpenAI, with the key in a file outside this folder,
-or 'later'. Anthropic and Google work too." Never ask for the key itself.
-
-With no file named, record that they will add it later. A path the developer names is
-theirs to give, including one outside the project. Recommend the project's env file when it
-exists, git ignores and does not track it, and it already holds the key. Otherwise recommend
-a file outside the project, or "later". Never recommend an env file in the project while an
-`env-file-exposed` line is open, or when git tracks it or does not ignore it. For an empty
-target, a new key file goes outside the target directory, because `init` refuses a target
-that holds a `.env` file. Tell the developer only where the file goes, not that reason.
-
-**Line 4: the frontend.**
-
-If the project has no frontend, ask this line. The valid choices are React SPA,
-Next.js, Angular, Vue 3, React Native, Slack, and Microsoft Teams.
-
-Where there is no existing frontend, include Slack and Microsoft Teams in the frontend
-question. Then recommend the one the developer
-names, and say what each choice implies for where the CopilotKit runtime lives: Next.js
-hosts it in a route handler, Angular in its SSR server, and Vue 3, React SPA and React
-Native reach a runtime that runs as its own process. Slack and Microsoft Teams use a
-long-running Channel host, not a CopilotKit web app.
-
-**Line 5: the project.** Leave out the project line on the local route: local evaluation
-creates its own project. For an existing app, first
-run `npx --prefer-offline --yes copilotkit@4.26.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 already has a project. Leave the line out.
-- `needs-developer` with `project-name`: offer `suggestedName`, another name, or a project
-  the developer already has. 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. When
-  `question.untrack` is absent, recommend approving it: without it, the run writes no key. A
-  reply that accepts every recommendation approves it. When `question.untrack` is present,
-  git tracks the file. If `question.alternative` is present, recommend it: the key goes into
-  `question.alternative.file`, which affects no teammate, and a reply that accepts every
-  recommendation takes it. Without `question.alternative`, recommend nothing for this line.
-  Untracking removes the file for everyone who pulls the next commit, so only an answer to
-  this line approves it. 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, offer a new project named after the target directory, or a project the
-developer already has.
-
-Before you end your turn to wait for the developer, report the pause:
+Do not change application code in this phase. Do not read, show, store, or request a secret value.
+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.26.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>]
 ```
 
-If no line is open, ask nothing and continue.
+- `--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`.
 
-## Read the reply
-
-A reply that accepts, such as "yes" or "go ahead", accepts every recommendation. A line the
-reply changes takes the new answer. A line the reply 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 row does not name: tell the developer that this run
-  cannot set up that vendor for a new agent with this framework. Offer two choices. They
-  can keep the framework with its default vendor, or choose a framework whose row names
-  their vendor.
-- Slack or Microsoft Teams as the frontend of an empty project: the Channel starter brings
-  its own agent, so the framework and provider lines decide nothing. Drop them.
-
-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 three things in one message:
-
-1. Which toolchain to install, and its install page.
-2. That the coding agent's shell reads PATH when it starts, so it cannot see the new
-   toolchain until the developer restarts the coding agent.
-3. That the run resumes after the restart with
-   `npx --prefer-offline --yes copilotkit@4.26.0 onboard start --run <onboarding_run_id>`.
-
-Before you end your turn to wait for the developer, report the pause:
+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.26.0 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.28.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 the purpose, the framework, the frontend, the project answer, the key file answer,
-and the model vendor with how it was chosen. The developer named it: `developer`. The developer had no preference: `default`,
-which is the row's default vendor. An existing agent's vendor: `existing`. Give these to
-every later node and subagent. They answer the framework, provider, and frontend questions
-for the rest of the run. The project and key answers answer those questions too.
-
-Then run `npx --prefer-offline --yes copilotkit@4.26.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.