copilotkit 4.27.0 → 4.29.0

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,16 +15,16 @@ 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.27.0 onboard start --run <onboarding_run_id>` where you are
+`npx --prefer-offline --yes copilotkit@4.29.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.27.0 onboard start` in the
+If you no longer hold the id, run `npx --prefer-offline --yes copilotkit@4.29.0 onboard start` in the
 directory this run started in, with no `--run` and no `--intent`. It reprints the id
 and starts nothing. An id this project does not already hold starts a second
 run, and the work already done stops counting toward the first.
 
 Read only inside the target project directory. Every subagent you spawn inherits that
-limit, including one this graph does not name. Answer a CopilotKit API or configuration
+limit. Answer a CopilotKit API or configuration
 question from the documentation this graph gives you. Another checkout on this machine is
 not a source.
 
@@ -34,7 +35,7 @@ pass.
 
 Telemetry and friction reports follow the CLI telemetry setting the developer controls with
 `copilotkit telemetry` or `DO_NOT_TRACK=1`. Each report is one or two sentences and carries
-no secrets and no source. The feedback commands enforce that setting on every send. Explain it once.
+no secrets and no source. The commands enforce that setting. Explain it once.
 
 The directory this run started in is the run root. Every `--path` argument is read against
 it, so one path names one file from anywhere in the project.
@@ -47,19 +48,33 @@ to the repository root and prints its path.
 
 This rule covers every subagent this run spawns, here and in every later prompt.
 
-Spawning a subagent returns almost at once. That return is the dispatch succeeding, not the
-work finishing: the subagent runs in the background, and its result reaches you as a
-notification. Where your own harness hands you the report from the dispatch itself instead,
-you already hold the result. Either way there is nothing to poll.
+Spawning a subagent returns almost at once. That return is the dispatch, not the result:
+the result reaches you as a notification, or with the dispatch in some harnesses. There is
+nothing to poll.
 
-After you dispatch, do the work that does not depend on the result. For example, dispatch
-the other subagent, or run the preflight that the next prompt gives you. Then end your turn
-and wait for the result. Wherever a prompt in this graph says to wait for a subagent to finish, that is
-what it means. It is a pause, as "Pausing vs stopping" below describes, and not a stop.
+After you dispatch, do the work that does not depend on the result, then end your turn
+and wait for the result. That is what "wait for a subagent to finish" means in this graph.
+It is a pause, as "Pausing vs stopping" below describes, and not a stop.
 
-Do not sleep to pass the time. Not `sleep`, not `/bin/sleep`, not a timer under another
-name, and not a loop that re-checks whether a result arrived. Sleeping tells you nothing
-that waiting for the result does not, and it spends wall clock.
+Do not sleep to pass the time: no `sleep`, no timer, and no loop that re-checks for a
+result. It spends wall clock and tells you nothing.
+
+## When a subagent is refused a command
+
+This rule covers every subagent this run spawns. A subagent whose harness refuses a command
+returns at once with the command, its directory, and the refusal. Then run that command
+yourself, from that directory. Spawn at most one fresh subagent for each refused command,
+with the same handoff and that result. If the fresh subagent is refused a command too,
+spawn no other: do the brief yourself.
+
+Record each research result, since a research subagent runs no onboarding command:
+
+```text
+npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase subagent-returned --brief inspect-repository --result <ok|refused|failed>
+```
+
+`ok` is `Status: passed`, `failed` is failed or blocked, and `refused` names a refused
+command.
 
 ## Pausing vs stopping
 
@@ -73,7 +88,7 @@ says to file none, follow it, so the run sends one report at most. Nothing else
 A pause keeps the run open. "End your turn and wait for" something means: end this turn.
 When that thing arrives, continue. A pause waits for one of two things:
 
-1. A subagent result. The section above says how to wait for one.
+1. A subagent result, waited for as the section above says.
 2. The developer. Ask the question, then end your turn and wait for the reply. The reply
    is the answer. A developer who replies without choosing, such as "go ahead" or "you
    pick", gives no answer, and the default that the prompt states applies. Where the
@@ -82,54 +97,57 @@ 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.27.0 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase awaiting-developer --about <question>
 ```
 
+Use the question the asking prompt names, or else the closest of: `harness-permission`,
+`sign-in`, `setup-answers`, `stack-choice`, `project-name`, `which-project`,
+`env-file-tracked`, `local-connection`, `local-terms`, `existing-folder`,
+`environment-fix`, `uncommitted-file`, `agent-change`, `restore-files`, `thread-id`,
+`scoped-fix`, `feature-binding`, `other`. Report it before every turn that ends while the
+run is open, with `other` if you asked nothing. A run that goes quiet without it reads as
+a run that died.
+
 When the answer or the result arrives, continue from the step that paused. Do not read an
-earlier prompt again, send the welcome again, or start a new run: the run id you hold still
-names this run. A pause is not a stop. It sends no stop report and takes no stop route.
+earlier prompt again, send the welcome again, or start a new run. If you lost the step you
+were on, run `npx --prefer-offline --yes copilotkit@4.29.0 onboard route`. Skip every `subagent/` entry: a
+subagent read that brief. The last step left is that step. Read it again with `onboard read`. A pause is not a stop. It sends no stop report.
 
 ## When a subagent cannot work
 
-This rule also covers every subagent this run spawns, here and in every later prompt.
+This rule covers every subagent too.
 
-A subagent that returns no usable result failed in your harness, not in this graph.
-Delegation buys parallelism and a clean context, not capability: every assignment in this
-run is work you can do yourself, slower. So run that assignment yourself and carry on,
-rather than treating it as the end of the run.
+A subagent that returns no usable result failed in your harness, not in this graph. Every
+assignment in this run is work you can do yourself, slower. So do it yourself and carry
+on. It is not the end of the run.
 
 Both research subagents failing means this harness has no working subagent at all, which
 is worth recording once:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard checkpoint --phase delegation-unavailable
+npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase delegation-unavailable
 ```
 
-Then say once, in your own words, that this environment has no working subagents. Say that
-you will do each step yourself, and that the run will take longer than usual.
+Then tell the developer once that this environment has no working subagents, so you do
+each step yourself and the run takes longer.
 
 For the rest of this run, do not spawn a subagent where a prompt tells you to. Read that
 `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.
-
 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.27.0 onboard read subagent/inspect-repository
-npx --prefer-offline --yes copilotkit@4.27.0 onboard inspect --json
+npx --prefer-offline --yes copilotkit@4.29.0 onboard read subagent/inspect-repository
+npx --prefer-offline --yes copilotkit@4.29.0 onboard inspect --json
 ```
 
 Give each research subagent the prompt that the first command returns, the whole JSON that
 the second command returns, and one assignment. Tell it that its handoff already holds both,
-so it runs no onboarding command. A coding agent's permission layer can refuse a registry
-package inside a subagent, even where it lets you run the same command.
-The run then waits for an approval that nobody sees. Require only its assigned packet.
+so it runs no onboarding command: a permission layer can refuse one inside a subagent, and
+the run then waits for an approval nobody sees. Require only its assigned packet.
 
-Give the same JSON to every later subagent that this research spawns, such as a retry, a
-focused directory check, or a conflict verifier.
+Give the same JSON to every later subagent this research spawns, such as a retry.
 
 Start both research subagents in parallel:
 
@@ -137,11 +155,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.29.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.29.0 onboard checkpoint --phase awaiting-developer --about setup-answers
+```
+
+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.27.0 onboard read research/preflight
+npx --prefer-offline --yes copilotkit@4.29.0 onboard read research/preflight
 ```
 
 If inspection stops onboarding, run
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard read stopped/run-failed`.
+`npx --prefer-offline --yes copilotkit@4.29.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.27.0 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase awaiting-developer --about sign-in
 ```
 
 When both research results are merged and sign-in is done, run
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard read research/route`.
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard read research/route`.
 
 If inspection stops onboarding, run
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard read stopped/run-failed`.
+`npx --prefer-offline --yes copilotkit@4.29.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.27.0 onboard read research/merge
+npx --prefer-offline --yes copilotkit@4.29.0 onboard read research/merge
 ```
 
 If inspection stops onboarding, run
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard read stopped/run-failed`.
+`npx --prefer-offline --yes copilotkit@4.29.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.27.0 onboard read feature/channels/start
+npx --prefer-offline --yes copilotkit@4.29.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.27.0 onboard read proof/oss-baseline`.
+`npx --prefer-offline --yes copilotkit@4.29.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.27.0 onboard read setup/questions`. That node asks every
+`npx --prefer-offline --yes copilotkit@4.29.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 --about setup-answers` 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.27.0 onboard read stopped/run-failed`. Neither says anything
+`npx --prefer-offline --yes copilotkit@4.29.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,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.29.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.29.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.29.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.29.0 onboard checkpoint --phase awaiting-developer --about setup-answers
 ```
 
-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.29.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 same pause first.