copilotkit 4.26.0 → 4.28.0

package/onboarding/index.json

@@ -1,5 +1,5 @@
 {
-  "graphTree": "62f012b65ba17a579b853bdbbd55bc81dc4759ac",
+  "graphTree": "7638f7b001415b1dbd5bdd5204b9c296810439f7",
   "intentRoots": {
     "add-a2ui": "feature/a2ui/start",
     "add-chat-suggestions": "feature/chat-suggestions/start",
@@ -9,7 +9,7 @@
     "add-rich-threads": "feature/rich-threads/start",
     "add-voice": "feature/voice/start"
   },
-  "packageSpec": "copilotkit@4.26.0",
+  "packageSpec": "copilotkit@4.28.0",
   "root": "authenticate/start",
   "prompts": [
     {
@@ -620,6 +620,7 @@
     {
       "edges": [
         "subagent/inspect-repository",
+        "setup/questions",
         "research/preflight",
         "stopped/run-failed"
       ],

package/onboarding/prompts/authenticate/start.md

@@ -6,34 +6,46 @@ This run executes the CopilotKit CLI through `npx`.
 It spawns read-only inspection subagents inside the target project. It sends checkpoints
 and optional friction reports to CopilotKit under the developer's telemetry setting. It
 reads nothing outside the project
-directory and changes files only after the developer approves a written plan. CopilotKit
+directory. It changes files only after writing the plan, and asks before any change the
+plan says needs the developer's approval. CopilotKit
 Intelligence has a free Developer plan, and this run needs no paid subscription.
 
 ## Command approvals
 
 Run each CLI call exactly as written, as its own command: no pipe, `tee`, `&&`, redirect,
 or variable prefix. Every CLI call in this run matches the prefix rule
-`["npx", "--prefer-offline", "--yes", "copilotkit@4.26.0"]`. If a command can request
-escalation with a prefix rule, request this one on the `onboard identify` call. If your
-harness asks the developer to approve commands, tell them one approval of that prefix covers
-every CLI call. Say then that the install, the dev servers, `curl` to the local app, and
+`["npx", "--prefer-offline", "--yes", "copilotkit@4.28.0"]`.
+
+<!-- sandboxed-harness -->
+
+If a command can request escalation with a prefix rule, request this one on the
+`onboard identify` call.
+
+<!-- /sandboxed-harness -->
+
+If your harness asks the developer to approve commands, tell them one approval of that
+prefix covers every CLI call. Say then that the install, the dev servers, `curl` to the local app, and
 `ps`, `lsof`, and `kill` ask for approval later.
 
 Never add or edit a permission rule or a settings file yourself. That choice belongs to
 the developer.
 
 If your harness refuses a CLI call without asking the developer, do not retry it or run it
-another way. Report the pause: `npx --prefer-offline --yes copilotkit@4.26.0 onboard checkpoint --phase awaiting-developer`.
+another way. Report the pause: `npx --prefer-offline --yes copilotkit@4.28.0 onboard checkpoint --phase awaiting-developer`.
 Name the refused command, ask the developer to approve it or to switch to a
 mode that asks them, and end your turn. When they answer, run it once more.
 That refusal is a pause, not a stop.
 
 ## First, say which coding agent you are
 
-Run this first, before the welcome message below:
+Before you run any other command, write this one line in your own reply: "Setting up
+CopilotKit: I check your sign-in and your project, then show you the setup." The developer
+does not see your tool output, and the welcome comes later, with the setup message.
+
+Then run this:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.26.0 onboard identify --coding-agent <coding-agent-slug> --model <model-id> --model-family <model-family>
+npx --prefer-offline --yes copilotkit@4.28.0 onboard identify --coding-agent <coding-agent-slug> --model <model-id> --model-family <model-family>
 ```
 
 Report your product slug, such as `codex` or `claude-code`.
@@ -58,36 +70,20 @@ the whole run. Every later command reports against it.
 
 `onboard read research/gather` gives the rules for the rest of the run.
 
-Send this exact message once, as your first message in this onboarding run, before
-anything else:
-
-Welcome to CopilotKit! By the end of this run, your application talks to an AI agent and
-keeps each conversation as Rich Threads. Users can return to earlier work. Where enabled,
-Automatic Learning then helps your agent improve from that history: it finds usage patterns
-and proposes reusable Skills, and you approve which Skills it gets.
-
-I will check sign-in, inspect your project, recommend a setup, and show you a plan before
-I change files. After you approve the plan, I will build the integration, prove the full
-round trip, and leave the app running with its URLs.
-
-Everything I need from you comes before that approval: sign-in, a few short setup questions,
-and the plan itself. If I need you to approve a command, or something blocks me, I will ask
-you here. Otherwise you hear from me next when the app is running and I hand you its URLs.
-To self-host on your machine with Docker, say so before you sign in.
-
-That message belongs to the run. Send it only once, including after a second read of this prompt.
-Then run `npx --prefer-offline --yes copilotkit@4.26.0 onboard checkpoint --phase welcome-sent`.
+Do not write a welcome of your own. The CLI puts the run's welcome at the top of the setup
+message, which says to write it in your own reply, because the developer does not see your
+tool output.
 
 ## Report a stop, wherever it happens
 
 If you stop this run at any point, send one short report before you stop. This includes
 unexpected stops and stops caused by your harness.
 A turn that ends while the run waits is a pause, not a stop, even when your harness ends it.
-Report the pause: `npx --prefer-offline --yes copilotkit@4.26.0 onboard checkpoint --phase awaiting-developer`.
+Report the pause: `npx --prefer-offline --yes copilotkit@4.28.0 onboard checkpoint --phase awaiting-developer`.
 A terminal that sends the report itself, or says to file none, overrides this.
 
 ```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.
@@ -105,15 +101,15 @@ rule that stopped you says next: send the report, then stop.
 Take the local route only when the developer already asked to run CopilotKit locally,
 with Docker, or self-hosted: in their request, the copied prompt, or a later reply, or
 when this run already recorded local. Then run
-`npx --prefer-offline --yes copilotkit@4.26.0 onboard read deployment/choose-local` instead.
+`npx --prefer-offline --yes copilotkit@4.28.0 onboard read deployment/choose-local` instead.
 
 Otherwise keep managed. Do not ask the developer to choose. Run
-`npx --prefer-offline --yes copilotkit@4.26.0 onboard deployment --choice managed`, then continue with
+`npx --prefer-offline --yes copilotkit@4.28.0 onboard deployment --choice managed`, then continue with
 “Check sign-in”. If it refuses because of a local stack, take the local route.
 
 ## Check sign-in
 
-Run `npx --prefer-offline --yes copilotkit@4.26.0 login --json` before any project work. It checks the
+Run `npx --prefer-offline --yes copilotkit@4.28.0 login --json --onboarding` before any project work. It checks the
 session and starts sign-in only as needed. Treat this as a long-lived
 streaming process. Do not wait for the command to exit before you read its standard output.
 
@@ -121,40 +117,36 @@ Read each JSON Lines record as it arrives:
 
 1. If the process emits `type: completed` without an `authentication_url`, continue: the
    existing session is valid.
-2. If the process emits `authentication_url`, read the first `authentication_url` without
-   changing it. The process is still running.
-   When that first URL arrives, send this exact message once. Add no feature list or other
-   explanation:
-
-   I am opening a sign-in page. Signing in gives this project a managed CopilotKit project
-   and its API key. That key is what lets your users reopen past conversations. You can
-   remove it later to disconnect this workspace.
-
-   If it carries `user_code`, add: `Check that the page shows this code: <user_code>`.
-
-3. The CLI opens the page in the default browser itself when it can, and the
-   `action_required` record says whether it did. With `"browser_opened": true`, do not open
-   it again. With `"browser_opened": false`, show the clickable URL to the developer and ask
-   them to finish sign-in there. Your own built-in browser
-   does not carry the session the developer already signed in with, so do not use it.
+2. If the process emits `authentication_url`, the developer must sign in. The process is
+   still running.
+3. The CLI does not open the page. The first `action_required` record carries a `message`:
+   why to sign in, then the link and the code. Write that `message` in your own reply, word
+   for word, and add nothing else. The developer does not see your tool output. Do not open
+   the page yourself: the developer opens it from your message. Then report the pause with
+   `npx --prefer-offline --yes copilotkit@4.28.0 onboard checkpoint --phase awaiting-developer` and end your
+   turn. Until the developer says they signed in, send them nothing more. When the research or
+   another helper returns, record what it found and end your turn without a message. Your own
+   built-in browser does not carry the session the developer already signed in with,
+   so do not use it.
    A later `authentication_url` record with `"renewed": true` means the earlier code expired.
-   Do not resend the sign-in message. Show only the new code, and the URL if
-   `browser_opened` is false.
+   Write its `message` the same way.
 4. Keep monitoring the same login process. Do not start a second login command.
 5. Go past the research only after that same process emits `type: completed`.
 6. On `type: failed` with `reason: expired` or `reason: renewal_failed`, ask once whether to
-   retry. If yes, start one new `login --json`. Use `--force` only when the developer asks.
+   retry. If yes, start one new `login --json --onboarding`. Use `--force` only when the
+   developer asks.
 7. If that process emits `type: failed`, report the error and stop onboarding. On
    `reason: repeated_expiry`, rerun `login` with `--force` only if the developer asks.
 
-On `type: completed`, run `npx --prefer-offline --yes copilotkit@4.26.0 onboard checkpoint --phase sign-in-settled`
+On `type: completed`, run `npx --prefer-offline --yes copilotkit@4.28.0 onboard checkpoint --phase sign-in-settled`
 before you continue.
 
 If your harness ends the login process or your turn before the process emits
-`type: completed` or `type: failed`, that is a pause, not a failed sign-in. Report the pause: `npx --prefer-offline --yes copilotkit@4.26.0 onboard checkpoint --phase awaiting-developer`.
+`type: completed` or `type: failed`, that is a pause, not a failed sign-in. Report the pause: `npx --prefer-offline --yes copilotkit@4.28.0 onboard checkpoint --phase awaiting-developer`.
 If the process
 still runs, end your turn and wait for the developer to say they signed in, then read the
-same process. If the process ended without emitting `type: failed`, run `login --json`
+same process. If the process ended without emitting `type: failed`, run
+`login --json --onboarding`
 again and handle a new `authentication_url` as above. Step 4 forbids a second login only while the first one runs.
 
 Do not use `whoami` for this check. Do not put account tokens or credentials in the
@@ -162,9 +154,9 @@ conversation.
 
 Research reads only this project and needs no account. Start it as soon as the session is
 valid or the developer has the sign-in page, and keep monitoring the login process while it
-runs: `npx --prefer-offline --yes copilotkit@4.26.0 onboard read research/gather`. If this run already
+runs: `npx --prefer-offline --yes copilotkit@4.28.0 onboard read research/gather`. If this run already
 started the research, do not start it again.
 
 If sign-in stops onboarding, run
-`npx --prefer-offline --yes copilotkit@4.26.0 onboard read stopped/run-failed`. It does not judge
+`npx --prefer-offline --yes copilotkit@4.28.0 onboard read stopped/run-failed`. It does not judge
 this project's stack.

package/onboarding/prompts/conversion/plan.md

@@ -100,7 +100,7 @@ of this journey, and a drawer that lists nothing is not a reason to mint one. Li
 tokens stay a self-hosted concern.
 
 Where this journey's frontend framework ships no threads drawer -- React Native --, the
-fifth item is proved by `npx --prefer-offline --yes copilotkit@4.26.0 verify --round-trip`, which sends a
+fifth item is proved by `npx --prefer-offline --yes copilotkit@4.28.0 verify --round-trip`, which sends a
 real request and reads the answer back off the thread it landed on. The run says which of
 the two it proved. Do not send a run to the managed Intelligence dashboard to prove this.
 An authenticated browser session at a hosted dashboard is the one thing an agent-driven run
@@ -116,7 +116,7 @@ and passed -- so a run scored on either one was scored on the same fact. Every r
 resolves that condition from, while `licenseStatus` is a compatibility projection of it
 for older thread surfaces and outlives them only until those surfaces go.
 
-Then run `npx --prefer-offline --yes copilotkit@4.26.0 onboard read credentials/finalize-plan`.
+Then run `npx --prefer-offline --yes copilotkit@4.28.0 onboard read credentials/finalize-plan`.
 
 If a selected page does not load after the second method, run
-`npx --prefer-offline --yes copilotkit@4.26.0 onboard read unsupported/no-validated-path`.
+`npx --prefer-offline --yes copilotkit@4.28.0 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/credentials/finalize-plan.md

@@ -1,23 +1,26 @@
 # Select the Intelligence project
 
 For a recorded local choice, run
-`npx --prefer-offline --yes copilotkit@4.26.0 onboard read deployment/local-evaluation`.
-That path obtains approval and connects the local project. Skip hosted selection.
+`npx --prefer-offline --yes copilotkit@4.28.0 onboard read deployment/local-evaluation`.
+That path connects the local project with the approval the setup message took.
+Skip hosted selection.
 Keep the implementation and feature-proof requirements.
 
 Use the selected framework, frontend, model vendor, model, documentation URLs, and
-repository findings. On a conversion, use the values the conversion prompt recorded, and
+repository findings. When the framework, frontend or vendor is not in your context, read it
+from `npx --prefer-offline --yes copilotkit@4.28.0 onboard setup-answers`, and do not ask again. On a conversion, use the values the conversion prompt recorded, and
 ask no framework or frontend question. Do not change application code in this phase. Do
 not read, show, store, or request a secret value.
 
 Ask every choice that is still open at this point in one message, one numbered line per
-choice, and end your turn to wait for the answer. Put the recommendation first, with its
-evidence in one sentence. Keep plan approval a separate, later question.
+choice, and end your turn to wait for the answer. Write each as the options view of `onboard setup-message`
+does: the recommendation first, in bold, and the alternatives on one `Other:` line. Add a short
+reason only when it names something in the developer's own project. Do not ask about the plan here.
 
 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
 ```
 
 ## Record the audit cell
@@ -35,12 +38,12 @@ Choose the starting state from the repository findings:
 A run served `proof/oss-baseline` records one of the last two.
 
 ```text
-npx --prefer-offline --yes copilotkit@4.26.0 onboard classify --starting-state <starting-state> --agent-framework <agent-framework> --frontend <frontend> --model-vendor <model-vendor> --model-vendor-choice <model-vendor-choice>
+npx --prefer-offline --yes copilotkit@4.28.0 onboard classify --starting-state <starting-state> --agent-framework <agent-framework> --frontend <frontend> --model-vendor <model-vendor> --model-vendor-choice <model-vendor-choice>
 ```
 
-`<model-vendor>` is `openai`, `anthropic`, `google`, or `other`. `<model-vendor-choice>` is
-how the framework step chose it: `developer`, `default`, or `existing`. If the run
-recorded no vendor, leave out both flags.
+`<model-vendor>` is `openai`, `anthropic`, `google`, `openai-compatible`, or `other`.
+`<model-vendor-choice>` is how the framework step chose it: `developer`, `default`, or
+`existing`. If the run recorded no vendor, leave out both flags.
 
 If a value is refused, fix it from the choices the earlier prompts gave, and run the
 command again.
@@ -52,7 +55,7 @@ runtime `.env` file, that directory is the target, not the repository root. Do n
 the developer to another terminal.
 
 ```text
-npx --prefer-offline --yes copilotkit@4.26.0 onboard credentials --json
+npx --prefer-offline --yes copilotkit@4.28.0 onboard credentials --json
 ```
 
 Every credential this run writes goes to the environment path: the target's `.env`, or
@@ -71,11 +74,14 @@ Read `status`:
 
 ### Ask the question
 
-Use the project answer that `setup/questions` recorded. A new project runs `--create` with
-the name the developer accepted or gave. A new project with no recorded name takes
-`suggestedName`. A project they already have runs `--project`. Ask
-the developer only when `question.taken` or `question.notFound` is present, or when no
-answer was recorded.
+The developer answered this in the setup message. `question.recorded` carries the answer
+the CLI kept: run `--create` with `question.recorded.create`, or `--project` with
+`question.recorded.project`, and do not ask again. Without `question.recorded`, use the
+project answer `setup/questions` gave you. A new project with no recorded name takes
+`suggestedName`. Ask the developer only when `question.taken` or `question.notFound` is
+present, or when no answer was recorded. When they then give another project, record it
+with `npx --prefer-offline --yes copilotkit@4.28.0 onboard setup-answers --create <name>` or
+`--project <slug>`.
 
 `project-name` means that no project is bound here, so creating a project for this
 directory is the default. Ask one question: use `suggestedName`, give another name, or ask
@@ -87,7 +93,7 @@ unless the developer says that it is this app's.
 Before you end your turn to wait for the developer, report the pause:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.26.0 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.28.0 onboard checkpoint --phase awaiting-developer
 ```
 
 If no developer answers, create with the derived name in `suggestedName`. Never select a
@@ -96,9 +102,9 @@ project from a listing without an answer that names it.
 `--runtime-url` is the URL port research settled, mount path included:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.26.0 onboard credentials --create <name> \
+npx --prefer-offline --yes copilotkit@4.28.0 onboard credentials --create <name> \
   --runtime-url http://localhost:<port>/api/copilotkit --json
-npx --prefer-offline --yes copilotkit@4.26.0 onboard credentials --project <slug-or-id> \
+npx --prefer-offline --yes copilotkit@4.28.0 onboard credentials --project <slug-or-id> \
   --runtime-url http://localhost:<port>/api/copilotkit --json
 ```
 
@@ -110,12 +116,12 @@ show only what they asked for, and do not order it by creation time:
 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
 ```
 
 ```text
-npx --prefer-offline --yes copilotkit@4.26.0 project list --json
-npx --prefer-offline --yes copilotkit@4.26.0 project list --search <query> --json
+npx --prefer-offline --yes copilotkit@4.28.0 project list --json
+npx --prefer-offline --yes copilotkit@4.28.0 project list --search <query> --json
 ```
 
 `app-directory` means that the key landed where no app reads it. Pick the directory in
@@ -123,10 +129,14 @@ npx --prefer-offline --yes copilotkit@4.26.0 project list --search <query> --jso
 the `--project` command from there with `project.slug`. Do not copy or link the key file.
 
 `env-file-exposed` means that git tracks the env file the key goes into, or does not
-ignore it. So nothing was written. If the developer already approved that line in the setup
-message, apply it without asking again. An accepting reply to the setup message never
-approves a line with `question.untrack`. Ask it now as its own question, unless the
-developer answered that line itself. For a line that is still open, ask the developer
+ignore it. So nothing was written. Read `envFile` from
+`npx --prefer-offline --yes copilotkit@4.28.0 onboard setup-answers`, which keeps the developer's answer to
+that line in the setup message: `approved` approves the change the line asks for,
+`alternative` chose `question.alternative`, and `declined` declined both. Act on it without
+asking again. An accepting reply to the setup message never approves a line with
+`question.untrack`: it takes `question.alternative` when there is one. Without `envFile`,
+ask it now as its own question, and record the answer with `onboard setup-answers
+--env-line <approved|alternative|declined>`. For a line that is still open, ask the developer
 `question.ask` in those words. When `question.alternative` is present, the question offers
 two choices. If the developer chose `question.alternative`, here or in the setup message,
 run the same command again with `question.alternative.rerun` added. The CLI adds
@@ -134,7 +144,7 @@ run the same command again with `question.alternative.rerun` added. The CLI adds
 If they approve the untrack, add
 `question.ignoreLine` to `question.ignoreFile`. If `question.untrack` is present, run it
 too. Or the developer does both. Report the pause with
-`npx --prefer-offline --yes copilotkit@4.26.0 onboard checkpoint --phase awaiting-developer`, end your
+`npx --prefer-offline --yes copilotkit@4.28.0 onboard checkpoint --phase awaiting-developer`, end your
 turn, and wait for the answer. Then run the same command again. Write the key only to
 `question.file`, or to `question.alternative.file` by rerunning with
 `question.alternative.rerun`.
@@ -142,9 +152,12 @@ turn, and wait for the answer. Then run the same command again. Write the key on
 ## Carry the result into the plan
 
 - `planChanges`: list each file in the plan. Mark each one that has uncommitted changes, so
-  the developer sees it when they approve the plan. It does not end the run.
+  the developer sees it in the plan. It is a change that needs approval, so the plan asks
+  about it. It does not end the run.
+- `backup`: give it to the planning subagent. A `partial` or `failed` backup needs
+  approval, because `onboard restore` cannot put back what the backup does not hold.
 - `project.slug` is the selected project. `"key": "unverified"` means the project was
   reused. The round-trip proof later runs the authenticated Intelligence checks, so record
   the reused project credentials as unverified in the plan until those checks pass.
 
-Then run `npx --prefer-offline --yes copilotkit@4.26.0 onboard read credentials/settle-credentials`.
+Then run `npx --prefer-offline --yes copilotkit@4.28.0 onboard read credentials/settle-credentials`.

package/onboarding/prompts/credentials/plan.md

@@ -1,16 +1,31 @@
 # Select the agent framework
 
-Use the framework and the model vendor that `setup/questions` recorded. That node asked the
-developer, so ask nothing here. A run that proved its existing agent, frontend, and
+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. Use its `framework` and
+its `vendor`, with `vendor.choice`, `vendor.baseUrl` and `vendor.modelId`. That node asked
+the developer, so ask nothing here. A run that proved its existing agent, frontend, and
 CopilotKit integration did not read that node: keep the agent's framework from the
-findings, with the vendor `existing`.
+findings. Record it with
+`onboard setup-answers --framework <name> --vendor <vendor> --vendor-choice existing`, or
+with `--vendor other --vendor-choice existing` when the findings do not show its vendor.
+`existing` is a choice, not a vendor.
 
-If no setup answers are in your context at all, as after a context reset or a resumed
-session, do not guess. Ask the framework and model provider lines in one message. Recommend
-the framework that the repository findings show, or, for an empty project, a documented
-default. For the provider, offer the vendors the framework's CopilotKit pages document.
+Ask only for what the record lacks and no other path settles. When it holds no
+framework and no vendor, ask the framework and model provider lines in one message.
+Write each as the options view of `onboard setup-message` does: the recommendation first, in bold, and the
+alternatives on one `Other:` line. When
+it holds a framework and no vendor, ask the model provider line alone: without an answer, the
+framework node uses OpenAI, which the developer never chose. Recommend the framework that
+the repository findings show, or, for an empty project, a documented default. For the
+provider, recommend the framework's default vendor, and offer only the other vendors it takes:
+`onboard setup-answers` refuses any other and names the ones it takes. On most frameworks that is OpenAI or an
+OpenAI-compatible provider: if the developer names Anthropic or Google for a new agent
+there, say that this release supports the row's vendors on that framework, that Anthropic
+and Google come in a later release, and offer the Built-in CopilotKit agent if they need
+them now. Record the answers with
+`onboard setup-answers --framework <name> --vendor <vendor> --vendor-choice <choice>`.
 Report the pause with
-`npx --prefer-offline --yes copilotkit@4.26.0 onboard checkpoint --phase awaiting-developer`, then end your
+`npx --prefer-offline --yes copilotkit@4.28.0 onboard checkpoint --phase awaiting-developer`, then end your
 turn and wait for the answer. A route that records no framework or vendor on purpose is not
 this case: an empty project with Slack or Microsoft Teams, a "Project-defined" vendor, or
 "The agent's own" vendor.
@@ -34,36 +49,37 @@ Microsoft Teams docs page, do not ask the framework question. So does an empty p
 whose frontend `setup/questions` recorded as Slack or Microsoft Teams: it recorded no
 framework. The Channel starter brings its own agent, so an answer here decides nothing. Tell the developer that the Channel
 starter decides the agent, then run
-`npx --prefer-offline --yes copilotkit@4.26.0 onboard read frontend/plan`.
+`npx --prefer-offline --yes copilotkit@4.28.0 onboard read frontend/plan`.
 
 ## Route on the recorded framework
 
-The framework and vendor come from `setup/questions`, with how the vendor was chosen:
-`developer`, `default`, or `existing`. The framework route uses this vendor.
+The framework and vendor come from `onboard setup-answers`, with how the vendor was
+chosen: `developer`, `default`, or `existing`. The framework route uses this vendor.
 
 Use exactly one matching internal route:
 
-1. AG2: `npx --prefer-offline --yes copilotkit@4.26.0 onboard read framework/ag2`
-2. Agno: `npx --prefer-offline --yes copilotkit@4.26.0 onboard read framework/agno`
-3. Built-in CopilotKit agent: `npx --prefer-offline --yes copilotkit@4.26.0 onboard read framework/built-in`
-4. Claude Agent SDK Python: `npx --prefer-offline --yes copilotkit@4.26.0 onboard read framework/claude-sdk-python`
-5. Claude Agent SDK TypeScript: `npx --prefer-offline --yes copilotkit@4.26.0 onboard read framework/claude-sdk-typescript`
-6. CrewAI Flows: `npx --prefer-offline --yes copilotkit@4.26.0 onboard read framework/crewai-flows`
-7. Existing AG-UI agent: `npx --prefer-offline --yes copilotkit@4.26.0 onboard read framework/custom-ag-ui`
-8. Deep Agents: `npx --prefer-offline --yes copilotkit@4.26.0 onboard read framework/deep-agents`
-9. LangGraph Python: `npx --prefer-offline --yes copilotkit@4.26.0 onboard read framework/langgraph-python`
-10. LangGraph FastAPI: `npx --prefer-offline --yes copilotkit@4.26.0 onboard read framework/langgraph-fastapi`
-11. LangGraph TypeScript: `npx --prefer-offline --yes copilotkit@4.26.0 onboard read framework/langgraph-typescript`
-12. LlamaIndex: `npx --prefer-offline --yes copilotkit@4.26.0 onboard read framework/llamaindex`
-13. ADK: `npx --prefer-offline --yes copilotkit@4.26.0 onboard read framework/google-adk`
-14. Microsoft Agent Framework Python: `npx --prefer-offline --yes copilotkit@4.26.0 onboard read framework/ms-agent-python`
-15. Microsoft Agent Framework .NET: `npx --prefer-offline --yes copilotkit@4.26.0 onboard read framework/ms-agent-dotnet`
-16. Mastra: `npx --prefer-offline --yes copilotkit@4.26.0 onboard read framework/mastra`
-17. MS Agent Harness .NET: `npx --prefer-offline --yes copilotkit@4.26.0 onboard read framework/ms-agent-harness-dotnet`
-18. Pydantic AI: `npx --prefer-offline --yes copilotkit@4.26.0 onboard read framework/pydantic-ai`
-19. Strands Agents Python: `npx --prefer-offline --yes copilotkit@4.26.0 onboard read framework/strands-python`
-20. Strands Agents TypeScript: `npx --prefer-offline --yes copilotkit@4.26.0 onboard read framework/strands-typescript`
+1. AG2: `npx --prefer-offline --yes copilotkit@4.28.0 onboard read framework/ag2`
+2. Agno: `npx --prefer-offline --yes copilotkit@4.28.0 onboard read framework/agno`
+3. Built-in CopilotKit agent: `npx --prefer-offline --yes copilotkit@4.28.0 onboard read framework/built-in`
+4. Claude Agent SDK Python: `npx --prefer-offline --yes copilotkit@4.28.0 onboard read framework/claude-sdk-python`
+5. Claude Agent SDK TypeScript: `npx --prefer-offline --yes copilotkit@4.28.0 onboard read framework/claude-sdk-typescript`
+6. CrewAI Flows: `npx --prefer-offline --yes copilotkit@4.28.0 onboard read framework/crewai-flows`
+7. Custom agent: `npx --prefer-offline --yes copilotkit@4.28.0 onboard read framework/custom-ag-ui`
+8. Deep Agents: `npx --prefer-offline --yes copilotkit@4.28.0 onboard read framework/deep-agents`
+9. LangGraph Python: `npx --prefer-offline --yes copilotkit@4.28.0 onboard read framework/langgraph-python`
+10. LangGraph FastAPI: `npx --prefer-offline --yes copilotkit@4.28.0 onboard read framework/langgraph-fastapi`
+11. LangGraph TypeScript: `npx --prefer-offline --yes copilotkit@4.28.0 onboard read framework/langgraph-typescript`
+12. LlamaIndex: `npx --prefer-offline --yes copilotkit@4.28.0 onboard read framework/llamaindex`
+13. ADK: `npx --prefer-offline --yes copilotkit@4.28.0 onboard read framework/google-adk`
+14. Microsoft Agent Framework Python: `npx --prefer-offline --yes copilotkit@4.28.0 onboard read framework/ms-agent-python`
+15. Microsoft Agent Framework .NET: `npx --prefer-offline --yes copilotkit@4.28.0 onboard read framework/ms-agent-dotnet`
+16. Mastra: `npx --prefer-offline --yes copilotkit@4.28.0 onboard read framework/mastra`
+17. MS Agent Harness .NET: `npx --prefer-offline --yes copilotkit@4.28.0 onboard read framework/ms-agent-harness-dotnet`
+18. Pydantic AI: `npx --prefer-offline --yes copilotkit@4.28.0 onboard read framework/pydantic-ai`
+19. Strands Agents Python: `npx --prefer-offline --yes copilotkit@4.28.0 onboard read framework/strands-python`
+20. Strands Agents TypeScript: `npx --prefer-offline --yes copilotkit@4.28.0 onboard read framework/strands-typescript`
 
-If the project has an agent in another framework that does not speak AG-UI, or no
-listed framework fits, keep the developer's current agent and run
-`npx --prefer-offline --yes copilotkit@4.26.0 onboard read unsupported/no-validated-path`.
+An agent in any other framework takes route 7, whether or not it speaks AG-UI. So does a
+new agent on a framework that is not listed. If the developer declines route 7 and every
+listed framework, keep their current agent and run
+`npx --prefer-offline --yes copilotkit@4.28.0 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/credentials/settle-credentials.md

@@ -8,7 +8,7 @@ application code here. Do not read, show, store, or request a secret value.
 Read `learningContainer` from the `onboard credentials` result:
 
 - `exists`: reuse `id` and create nothing.
-- `plan-create`: plan `id`, and create it after the developer approves the plan.
+- `plan-create`: plan `id`, and create it after the run shows the plan.
 - `skipped`: plan no container and no selector. Name `reason` in the plan and in the
   closing report. Do not stop.
 
@@ -21,10 +21,11 @@ The plan names the model credential variables. Run this from the directory that
 `environmentPath` in the project step's result, with one `--model-key` for each variable:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.26.0 onboard credentials --model-key <variable> --json
+npx --prefer-offline --yes copilotkit@4.28.0 onboard credentials --model-key <variable> --json
 ```
 
-If `setup/questions` recorded a key file, add `--env-path <file>` to the first check.
+Run `npx --prefer-offline --yes copilotkit@4.28.0 onboard setup-answers` for the key answer the setup
+message recorded. If it holds `key.file`, add `--env-path <key.file>` to the first check.
 When the framework node names another env file for the credential, add
 `--env-path <file>`. When the agent runs as its own service, such as a remote AG-UI agent,
 that service reads its own env file. Add `--copy-to <service>/.env` for it. The command
@@ -38,25 +39,43 @@ never prints a value. Read `status`:
   itself. By default, plan to copy the key into `environmentPath`, the app's env file that git ignores.
   The copy is a file the run writes itself, so list the copy under
   `Files the run writes itself`.
-  The developer's approval of the plan is their consent to the copy. After the approval,
-  copy the key with the command that `next` names. It has this form:
-  `npx --prefer-offline --yes copilotkit@4.26.0 onboard credentials --model-key <variable> --env-path <file> --copy-to <env file> --json`.
+  The developer's answer to the key file line in the setup questions is their consent to
+  the copy. After the run shows the plan, copy the key with the command that `next` names. It has this form:
+  `npx --prefer-offline --yes copilotkit@4.28.0 onboard credentials --model-key <variable> --env-path <file> --copy-to <env file> --json`.
   `<env file>` is `environmentPath`, never the tracked `.env` of a run that chose
   `question.alternative.file`. It writes the key without printing it. Do not copy the key
   yourself, and do not write a `sed`, `grep`, or `cat` command for it. If you cannot run
   the command, for example because a sandbox refuses the path, ask the developer to run it.
   Give them exactly this one line, with `<app directory>` as the directory that holds
   `environmentPath`:
-  `! cd <app directory> && npx --prefer-offline --yes copilotkit@4.26.0 onboard credentials --model-key <variable> --env-path <file> --copy-to <env file>`.
+  `! cd <app directory> && npx --prefer-offline --yes copilotkit@4.28.0 onboard credentials --model-key <variable> --env-path <file> --copy-to <env file>`.
   The command needs no input. Without `!`, they run the same command in a terminal.
   Report the pause with
-  `npx --prefer-offline --yes copilotkit@4.26.0 onboard checkpoint --phase awaiting-model-credential`,
+  `npx --prefer-offline --yes copilotkit@4.28.0 onboard checkpoint --phase awaiting-model-credential`,
   end your turn, and wait. When they reply, run the same command with `--json` and read `copiedKeys`.
   If the developer declines the copy, the plan has the app read the key from an
   environment variable that the developer sets. The plan then says how to set it. Never
   write the outside path into a project file, not even in a config file such as
   `langgraph.json`. A committed file that names a folder in the developer's home directory
   gives every other machine no key. In the closing report, say where the app reads the key from.
+  The `reason` `keyless-local-endpoint` means that the base URL is a local server, such as
+  Ollama or LM Studio, that answered without a key. The key holds the stand-in
+  `not-needed`.
+  The `reason` `unread-base-url` means that the env file sets `OPENAI_API_BASE`. This app
+  reads only `OPENAI_BASE_URL`, so it sends the key to OpenAI. Rename the variable to
+  `OPENAI_BASE_URL` in that file, and run this step again.
+  The `reason` `base-url-query` means that the base URL has a query string, and
+  `base-url-redirect` means that it redirects. Name either one in the closing report.
+  The `reason` `compatible-base-url-missing` or `key-not-openai` means that the key belongs
+  to an OpenAI-compatible provider, but no file names its base URL, so nothing was sent.
+  Ask the developer for the provider's base URL, record it with
+  `npx --prefer-offline --yes copilotkit@4.28.0 onboard setup-answers --vendor openai-compatible --base-url <url> --model-id <id>`,
+  and run this step again.
+- `needs-developer` with `question.reason` `local-endpoint-no-key`: the base URL is a local
+  server that needs no key, such as Ollama or LM Studio. The OpenAI SDKs refuse an empty
+  key. Do what `next` says: write `<variable>=not-needed` to `question.envFile`, the key's
+  own file, and run this step again. For the Microsoft Agent Framework Python starter,
+  that file is `agent/.env`.
 - `needs-developer` with `question.status` `missing`: if the developer said they will add the
   key later, do not ask or pause here. Carry the missing key into the plan: name the
   variable and `question.envFile`, then continue. Otherwise ask the developer `question.ask` in
@@ -65,10 +84,14 @@ never prints a value. Read `status`:
   with `--env-path <path>`. If they add the key, rerun it as it is. Do not replace the
   question with an instruction to paste the value into a file. The key can already be in a
   file that you can point the check at.
-- `needs-developer` with `question.status` `fail`: tell the developer `question.cause`.
-  `model_quota` means that the key has no credits, and `model_auth` means that the vendor
-  rejected it. Offer three choices: add credits, use another key, or switch the model
-  provider.
+- `needs-developer` with `question.status` `fail`: ask the developer `question.ask` in
+  those words. It says why the vendor refused the key and how to fix it. If they choose
+  another provider that the framework can use, record that vendor and its variable, and
+  run this step again with that variable. The plan changes the model code. With the cause
+  `model_unavailable`, the key works and the app's model does not: the vendor does not
+  serve the model that `COPILOTKIT_AGENT_MODEL` names. When the developer agrees to the
+  model that `question.ask` names, or names another, change `COPILOTKIT_AGENT_MODEL`
+  where `question.ask` says, and run this step again.
 - `needs-developer` with `question.kind` `env-file-exposed`: git tracks an env file the
   key goes into, or does not ignore it. So nothing was written. Ask the developer `question.ask` in those
   words. If they choose `question.alternative`, run the command again with the same flags
@@ -83,10 +106,11 @@ the run continues when they reply or resume this session. Under a harness that e
 session with your turn, such as `codex exec`, that message is the only thing the developer
 sees. This is a pause, not a stop. The command already reported it.
 End your turn. When the developer answers, run the command again. Do not write a
-placeholder or an empty value.
+placeholder or an empty value. The one exception is `not-needed` for the reason
+`local-endpoint-no-key` above.
 
 Never read a file outside the project directory to find a credential: a key found that way
 bills another project. Asking for a path is not requesting a secret. A path the developer
 names is theirs to give, including one outside the project. A path this run finds is not.
 
-Then run `npx --prefer-offline --yes copilotkit@4.26.0 onboard read credentials/write-plan`.
+Then run `npx --prefer-offline --yes copilotkit@4.28.0 onboard read credentials/write-plan`.