copilotkit 4.26.0 → 4.28.0

package/README.md

@@ -291,7 +291,10 @@ Under `--json`, the first `authentication_url` record is the URL with the code
 in it, and it also carries `user_code` and `expires_at`. A renewed code writes
 another `authentication_url` record, with `renewed: true` and its `renewal`
 number, and another `action_required` record. The old page then shows an
-expired code, so show the developer the new one. A sign-in that ends without a session writes a `failed`
+expired code, so show the developer the new one. If an earlier `login` on this
+machine stopped while its code was still valid, the next one reuses that code
+instead of requesting a new one, and its `authentication_url` record carries
+`resumed: true`. A sign-in that ends without a session writes a `failed`
 record with `reason: expired` or `reason: access_denied`, and with
 `retry: ask_developer`: a person must act before a new code can work. If a
 code expired and the request for its replacement failed, for example on a rate
@@ -323,10 +326,12 @@ Run `onboard start` in the project folder, or in an empty folder for a new app.
 
 `onboard start` is meant for a coding agent. If stdout is a terminal and the CLI
 detects no coding agent, it prints the agent prompt as usual and then a short
-note for a person. The note tells them to open their coding agent in the
-folder and paste the prompt that they copied. It also gives a line to paste
-that continues the same run. An agent that the CLI does not detect reads the
-full prompt above the note, so the note does not block it.
+note for a person. Most such people came from a coding agent that asked them
+to run the command. The note sends them back to that agent, or tells them to
+open one in the folder, with a line to paste. The line tells the agent to run
+the command itself, because it is not interactive, and continues the same run.
+An agent that the CLI does not detect reads the full prompt above the note, so
+the note does not block it.
 
 ### Where a run keeps its state
 
@@ -452,6 +457,10 @@ The fields:
   events do not have it. The total always has it when setup finished.
 - The total carries `duration_ms`, `outcome`, and `phase_count`. A failed setup adds
   `failed_setup_phase`.
+- The total also carries `learning_model`: `configured` when the stack gets a Learning
+  model, or `deferred` when setup ran with `--defer-model` or "configure later". A resumed
+  setup reports the choice it saved. The total has no `learning_model` when setup stopped
+  before the choice was known, for example at the Docker check.
 - A failed setup also adds `failure_reason` to the total and to the failed phase. It is
   a fixed slug that comes from the error's type, never from its message. Examples:
   `docker_unavailable`, `authentication_required`, `memory_short`, `cpu_short`,
@@ -461,7 +470,7 @@ The fields:
 - `local setup` and `local update` check Docker before their progress starts. If that
   check fails, the CLI still sends a failed setup. Its `failed_setup_phase` is
   `docker-check`, and it carries a `failure_reason`.
-- On Ctrl-C or SIGTERM, the open phase and the total send `outcome: abandoned` before
+- On Ctrl-C, SIGTERM, or SIGHUP, the open phase and the total send `outcome: abandoned` before
   the CLI exits. The total adds `abandoned_setup_phase` and the `bytes_downloaded` so
   far. The CLI waits at most 2 seconds for these sends, then exits with the signal's
   usual status.
@@ -1058,6 +1067,13 @@ is. The onboarding run keeps the choice for that directory only, so later
 `onboard credentials` and `onboard model-key` calls from there use `.env.local`
 without the flag, and calls from any other directory use `.env`.
 
+Once the project key is in a `.env.local` that git ignores and the app's runtime
+reads, beside a `.env` that git tracks, the CLI treats that file as your choice
+for the app. A new onboarding run,
+`license`, and `local connect` write there too, and none of them asks you to
+untrack `.env` again. The Channels setup commands still read and write `.env`
+only.
+
 ## Onboarding backups and restore
 
 `copilotkit onboard start` backs up the project before the run changes anything.
@@ -1067,23 +1083,38 @@ It prints one line on stderr that names the run whose backup it is.
   untracked file, kept under the private ref `refs/copilotkit/backup/<run-id>`.
   The CLI builds it in a temporary index, so your index, working tree, branch and
   stash do not change. Env and credential files (`.env`, `.env.*`, `.dev.vars`,
-  `.envrc`, `credentials`, `*.tfvars`, `secrets.*`, `.npmrc`, `.pypirc`, `*.pem`,
+  `.envrc`, `credentials`, `*.tfvars`, `*.tfstate`, `secrets.*`, `.npmrc`,
+  `.pypirc`, `.git-credentials`, `.pgpass`, `kubeconfig`, `auth.json`, `*.pem`,
   `*.key` and similar) never go into that ref, because `git push --mirror` sends
-  it. When they are changed, untracked or ignored, the CLI copies them to the
-  backups folder, readable by you only.
+  it. When they are changed, untracked or ignored, also inside an ignored
+  folder, the CLI copies them to the backups folder, readable by you only.
 - Outside a repository, the backup is a copy of the folder, except
   `node_modules`, `dist`, `build`, `.next`, `venv`, `.venv`, `__pycache__`,
   `.cache` and `.turbo`.
 - A file over 20 MB, or an untracked folder with more than 5,000 files, is left
   out and named in the closing report. The run still starts.
+- The backup cannot hold a changed submodule, a nested repository, a symlink, or
+  a staged version of a file that the working tree no longer has. The start line
+  counts them, and the closing report names each one with its reason. An ignored
+  folder that takes too long to search for credential files is named the same
+  way.
 - A run that starts in a folder holding several projects takes its backup when
   it moves to the one you choose with `onboard start --move`.
+- A backup that fails is recorded for the run. When a run has no backup, the
+  closing report says that a restore has nothing to put back.
+- `onboard credentials` reports the backup as `backup.status`: `ok`, `partial`
+  with each path it left out and why, `pending` when the backup waits for
+  `onboard start --move`, or `failed` with the cause. A symlink to a file or
+  folder the backup holds does not count as left out. The onboarding plan lists
+  a `partial` or `failed` backup under the changes that need your approval, and
+  waits for your answer.
 
 Backups live in `~/.copilotkit/backups/<run-id>/`, or in
 `$COPILOTKIT_CONFIG_DIR/backups/` when that is set. Besides the current run, the
 CLI keeps the newest four ended runs for up to 14 days, and the newest five runs
 that have not ended for up to 90 days, because such a run can still be going on
-in another project. It deletes the git ref with the folder. A run that a start
+in another project. A run that has not ended is ranked by the last step it was
+served, so a long run is not deleted by later starts. It deletes the git ref with the folder. A run that a start
 re-enters or `onboard resume` carries on counts as not ended again, and its age
 counts from then.
 
@@ -1099,7 +1130,8 @@ copilotkit onboard restore --run <run-id> --path src/app.ts
 A restore keeps the files the run added. It skips a file you changed after the
 run ended, unless you add `--force`. A run that stopped with no closing report
 has no recorded end, so the CLI cannot tell its edits from yours: a restore then
-puts back deleted files only, and a changed file needs `--force`. It exits 1 when the run has no backup or a
+puts back deleted files, and files that hold only the version committed at the
+start, which git keeps. Any other changed file needs `--force`. It exits 1 when the run has no backup or a
 `--path` is not in the backup.
 
 ### Tripwire
@@ -1108,13 +1140,34 @@ Before each step, the CLI checks the project against the backup. It stops the ru
 and shows you what changed when:
 
 - a file you had uncommitted changes in is deleted,
+- a file you had uncommitted changes in loses lines you added, in whole or in
+  part, and nothing new takes their place: `git checkout -- .`, `git restore .`
+  and `git checkout -p` do this, and so does a revert followed by an edit
+  elsewhere in the file, or a file put back to its staged version,
 - more than 10 files are deleted,
 - HEAD no longer contains the commit the run started on, or
 - a stash entry of this worktree was added or removed.
 
-Edits, new files, env files and dependency files never stop it. A file whose
-content moved to a new path counts as renamed, not deleted. A new branch that
-still contains the start commit does not stop it.
+Other edits, new files, env files and dependency files never stop it. A file
+whose content moved to a new path counts as renamed, not deleted. One deleted
+committed file does not stop it either: git and the backup both hold it, and the
+closing report lists it with the restore command. A new branch that still
+contains the start commit does not stop it.
+
+The revert check ignores trailing whitespace, line endings and blank lines. A
+formatter that strips them does not stop the run. Leading indentation counts,
+because it is content in Python, YAML and Makefiles. A line the run rewrites is
+an edit, not a revert. A line the run moves, sorts or swaps is still in the
+file, so it does not stop the run. Lines count by occurrence: when you wrote a
+line twice and the run removes one copy, the run stops. Credential files such
+as `.npmrc` count too. The check reads only files that changed since the
+start. A file over 1 MB, or a file that is not text, counts only when it holds
+the committed version exactly. After `copilotkit onboard tripwire --continue`,
+a reverted file stays accepted until its content changes. A new modification
+time alone does not end it.
+
+A restore from the stop puts back each file as it was at the start. The run's
+other edits to those files are lost.
 
 Every worktree of a repository shares one stash list, so the tripwire compares
 stash entries by commit. An entry that existed at the start always counts, so
@@ -1149,10 +1202,11 @@ Outside a repository, `copilotkit init` runs `git init` in the new app and makes
 an initial commit when a git identity is configured, so you have a restore point
 before you start editing.
 
-Inside a repository you already have, it does neither. A second `git init` would
-make the new app a nested repository: commits made in it would go to the inner
-repository, while the outer one saw only an untracked directory. The CLI names
-the repository it found and leaves the new app for you to commit. A repository
+Inside a repository you already have, it does neither. This includes a target
+folder that is a repository itself. A second `git init` would make the new app a
+nested repository: commits made in it would go to the inner repository, while the
+outer one saw only an untracked directory. The CLI names the repository it found,
+commits nothing, and leaves the new app for you to review with `git status`. A repository
 at your home directory, or above it, does not count here, so an app created below
 it gets its own `git init`.
 
@@ -1283,6 +1337,10 @@ browser. `verify` reads the runtime's own reported license to tell the two
 apart, and only a running runtime can answer that, so the check stays `UNKNOWN`
 when the runtime is unreachable.
 
+For SSE runtimes, `--round-trip` reports an AG-UI `RUN_ERROR` message before
+polling for a saved answer. Intelligence JSON responses do not carry these
+events; inspect runtime and agent logs when that transport reports no answer.
+
 Every check reports `PASS`, `FAIL`, or `UNKNOWN`, and `UNKNOWN` never means the
 check passed — an unreachable Intelligence API leaves the API key unproven
 rather than condemning it. `verify` exits non-zero unless every check passed, so
@@ -1295,6 +1353,12 @@ wired app returns too. The report shows it as `WARN`, `--json` names it in
 warns when the agent answers without the context value, because a correctly
 wired agent that keeps to its own task answers that way too.
 
+`page_context_reaches_agent` runs after every passing round trip, also for a
+frontend whose files call no context hook. CopilotKit's frontend sends context
+entries of its own, such as the A2UI catalog, and an agent that breaks on
+context fails every browser chat while a plain request still answers. For such a
+frontend, any answer passes, and a run with no answer fails.
+
 With `--json` the payload is the only thing on stdout and every diagnostic goes
 to stderr, so piping is safe.
 
@@ -1330,7 +1394,10 @@ checks.
 2. `"runtimeUrl"` in `.copilotkit/project.json` — an absolute URL for a
    project whose runtime is somewhere none of the below can find it. Add it by
    hand, or let `project select --runtime-url <url>` or
-   `onboard runtime-url --url <url>` write it. The CLI never removes one.
+   `onboard runtime-url --url <url>` write it. The CLI never removes one, but
+   in an onboarding run it can replace one that refuses connections:
+   `verify --round-trip --runtime-url <url>` and `onboard proof-check` can
+   write the new URL. See [`verify` probes port 3000 while the app runs on another port](#verify-probes-port-3000-while-the-app-runs-on-another-port).
 3. `COPILOTKIT_RUNTIME_URL` in the project's `.env` / `.env.local`, when it is
    absolute.
 4. The port the app's own dev configuration declares: `PORT` in its env files,
@@ -1408,10 +1475,33 @@ request in hand is a `resource/request`, and an `info` call never is. A runtime
 below `@copilotkit/runtime` 1.70.2 reports no `singleRoute` block and therefore
 cannot say, so the check is `UNKNOWN` there and names the upgrade.
 
+### Sending one run body and reading its events
+
+`--send-run <file>` sends the AG-UI run body in `<file>` to the agent that
+`--agent` names, and writes the events the run streams to
+`<file name>.events.jsonl` beside it. It runs no check. It prints the answer
+text, the tool calls, and the events path, and exits non-zero when the run did
+not finish or ended in a `RUN_ERROR`.
+
+```bash
+copilotkit verify --send-run .copilotkit/proof/context-run.json --agent incident_triage --json
+```
+
+A runtime wired to Intelligence answers the run with a join token instead of an
+event stream, and the events travel over the realtime gateway. The token is
+single-use and expires 30 seconds after the run starts. The command joins the
+gateway channel as soon as the run answers. If the gateway still refuses the
+token, the command asks the runtime's `/connect` route for a fresh one, once,
+and reads only this run from the channel's replay. Every send gets a new
+`runId`, and a body without `threadId` gets one. A runtime mounted
+`mode: "single-route"` gets the run inside its envelope. A second send of the
+same file replaces its events file. `--timeout` bounds the whole capture
+(default: 90 seconds).
+
 ### Proving the agent runs, not just that it is configured
 
 Every check above describes the project. `--round-trip` makes it work: it sends
-one real request through the runtime and reads the answer back from the thread.
+one real request through the runtime and reads the agent's answer.
 
 ```bash
 copilotkit verify --round-trip
@@ -1419,14 +1509,23 @@ copilotkit verify --round-trip --agent incident_triage      # several declared
 copilotkit verify --round-trip --header "Cookie: session=…" # auth-gated app
 ```
 
-It reads the answer back from `GET /threads/:id/messages` rather than from the
-run's response, because those responses differ by mode. In Intelligence mode the
-run returns a thread lock and a gateway URL, and the agent's events travel to the
-browser over the realtime gateway — so a 200 there proves a run started, which is
-precisely the outcome a runtime that dies mid-turn also produces. Reading the
-thread is one assertion for both modes, and it proves the stronger fact: the
-answer was recorded, not merely emitted. The thread the run reports wins over the
-one the CLI sent, because Intelligence rewrites both ids when it takes the lock.
+In Intelligence mode, the run returns a thread lock, a join token and a gateway
+URL. The agent's events travel over the realtime gateway, on the stream that the
+app's chat shows. `verify` joins that stream as soon as the run answers, and
+reads the answer from it. A 200 on the run proves only that a run started. A
+runtime that stops mid-turn also returns that 200, so the answer itself must
+arrive. The platform saves the thread from the same events later. Under load,
+the saved thread can lag the run by minutes, so it does not decide the verdict.
+
+In four cases, `verify` reads the answer back from `GET /threads/:id/messages`:
+
+- The runtime streams SSE.
+- This Node.js has no `WebSocket`.
+- The gateway refuses the join.
+- The stream ends with no text.
+
+The thread that the run reports wins over the thread that the CLI sent, because
+Intelligence rewrites both ids when it takes the lock.
 
 The assertion is that a non-empty answer came back, never what it said, so the
 verdict does not depend on the model behind the agent. It costs a model call and
@@ -1437,7 +1536,9 @@ is the project's own code and usually reads a signed-in session, which a CLI
 request does not carry, so an auth-gated app refusing it is that app working
 correctly. Pass what it reads with `--header`, repeatable. `verify` sends
 the header on every request to the runtime, `/info` included, so a runtime
-behind auth needs no local proxy.
+behind auth needs no local proxy. If `/info` answers 401 or 403,
+`runtime_reachable` names `--header` as the fix, not `--runtime-url`. If the run
+already sent headers, it names the headers that the runtime refused.
 
 ### Proving a thread the app created
 
@@ -1456,7 +1557,10 @@ no thread. It reads the thread from app-api with the project key, so it needs no
 `--expect-learning-container` checks that same thread. A pass proves that the
 agent's answer was recorded on that thread. It does not prove which end user the
 thread belongs to. A thread app-api does not hold for this project is a `FAIL`.
-Only an answer after the thread's newest user message counts. Inside an
+Only an answer after the thread's newest user message counts. App-api can save
+that answer minutes after the run under load. If the newest user message has no
+answer yet, `--thread` reads the thread again once a second. It waits up to 60
+seconds before it reports a `FAIL`. Inside an
 onboarding run, a thread that did not change after the run started is a `FAIL`,
 because its answer can predate the app as it is now. With `--agent`, a thread
 of another agent is a `FAIL`, and the evidence names the thread's own agent.
@@ -1475,6 +1579,15 @@ the coding agent, decides three things about it:
   to the run's code. `developer` means an answer or an action only the developer
   can give. Where the check started a server, the step carries the last lines of
   its log.
+- A failing `runtime-answers` or `round-trip:agent_answers` check names why in
+  `failureKind`, such as `runtime-timeout`, `run-error`, `run-refused`,
+  `read-refused`, `agent-missing` or `agent-ambiguous`. `run-refused` is a run
+  the runtime refused with 401, 402, 403 or 429. That status usually comes from
+  the Intelligence platform key or the app's own auth, so it names no provider.
+  A failed run whose error carried the provider's own code also names it in
+  `providerError`: `auth`, `quota`, `model-not-found`, `rate-limit` or `other`.
+  It is read from that code, never from a status or a message.
+  `verify --round-trip --json` reports both on `roundTrip` too.
 - When the same check fails three proof checks in a row, the command prints
   `Status: stopped`. A later `onboard proof-check` in the same attempt starts no
   server and prints the same stop. Recording the attempt with `onboard proof`
@@ -1571,6 +1684,33 @@ It needs no bound run. The URL must name the mount path: a bare
 `http://localhost:3001` is refused, because `verify` would probe `/`. With no
 project record, it writes nothing and exits non-zero.
 
+Inside an onboarding run, a `verify --round-trip --runtime-url <url>` that
+passes on a runtime other than the recorded one does not count for the run.
+`verify` says so on stderr, and in `roundTripNotRecorded` with `--json`, and
+names this command.
+
+There is one exception. The pass counts, and `verify` writes `<url>` into the
+record, when all of these are true:
+
+- the recorded URL refuses the connection. A timeout, a TLS error, or any
+  answer, even an error, keeps the record;
+- `<url>` is on this machine;
+- a process whose working directory is inside this project listens on the
+  port of `<url>`.
+
+`verify` asks the recorded URL without the `--header` values. In the same
+run, `onboard proof-check` replaces a recorded URL where nothing answers when
+the app's server was already running. It writes the port that server holds. `onboard proof` then names that runtime too. The CLI reads
+`localhost`, `127.0.0.1`, `0.0.0.0`, and `[::1]` on the same port and path as
+one runtime.
+
+`onboard proof-check` restarts a server of the app that started before an env file it reads
+was written, and names the old pids under `servers[].restarted`. After it starts a server, it
+waits up to 90 seconds for the runtime's `/info`. It waits only while nothing answers or the
+server answers with an error, as a dev server does while it compiles. A runtime still not up
+after the wait fails `runtime-answers` with `runtime-not-found`. Any other answer, such as a
+401, goes on to `verify`. `serverWaitMs` says how long the wait took.
+
 ### A model key has no credits or is rejected
 
 A key with no credits passes every static check. The first model call then
@@ -1597,18 +1737,92 @@ in the environment instead. A key you export in the shell, or set with direnv or
 the value came from: `env-file` or `environment`.
 
 - `pass`: the vendor served a model call with the key.
-- `fail`: the vendor refused the key. The cause is `model_quota` (no credits) or
-  `model_auth` (a rejected key).
+- `fail`: the vendor refused the key or the app's model. The cause is
+  `model_quota` (no credits), `model_auth` (a rejected key), or
+  `model_unavailable` (the vendor does not serve the app's model to this key).
 - `missing`: neither the env file nor the environment holds a real value for
   the key.
 - `unsupported` or `undetermined`: the check did not settle it. A rate limit, a
   vendor outage, or a probe model the key may not use proves nothing about the
   key, so none of them is a `fail`.
 
-It does not send the key when a base URL such as `OPENAI_BASE_URL` points the
-SDK at another endpoint, or when the shell exports a different value for the
-key. It never prints the key, and it never prints the vendor's error message,
-because a vendor can echo part of the key in it.
+The probe proves the key, not the app's model. When `COPILOTKIT_AGENT_MODEL` names the
+app's model as `provider:model` or `provider/model`, for the same vendor as the key, the
+command also sends a one-token call with that model. For OpenAI, that call goes through
+the Responses API, which the AI SDK uses. The JSON reports the model as `model`, where
+it was set as `modelSource`, and the env file that holds it as `modelFile`. The fix for a
+refused model names that file. The key and the model can live in different files, as in
+the Microsoft Agent Framework Python starter. A model the vendor says it does not serve is a `fail` with
+the cause `model_unavailable`. When the probe passed, the message names the model that the
+app's `.env.example` sets in `COPILOTKIT_AGENT_MODEL`, if it is a different model for the same
+vendor. It never names the probe model: the probe sends a plain request, and the app sends
+system messages and page context, so a model that answers the probe can still fail every chat. After the probe passed, a 403 or a spent quota on the app's
+model is `model_unavailable` too: the key works, and Google gives some models no free-tier
+quota. A bare 404 is `undetermined`, because a wrong base URL path answers 404 too. The command reads the variable from the shell first, then from the service whose base URL
+the key goes to, or else from the first service that sets it (see below). The JSON names
+that file as `modelFile`, and the fix for a refused model names it too.
+
+A base URL on OpenAI's own hosts, including a regional one such as
+`eu.api.openai.com`, is still OpenAI: the command sends its usual calls to that host.
+
+When `OPENAI_BASE_URL` points at an OpenAI-compatible
+provider, such as OpenRouter, Groq, or a local Ollama, the command asks that
+endpoint for its model list instead. A Python agent also reads the older
+`OPENAI_API_BASE`: LlamaIndex reads only that name, and LangChain's `ChatOpenAI` falls back
+to it. So when the key's env file belongs to a Python agent, the command counts
+`OPENAI_API_BASE` as the endpoint. A Python agent's env file is one whose directory, or the `agent` directory below it,
+holds `pyproject.toml`, `requirements.txt`, `setup.py`, `Pipfile` or `uv.lock`. A
+JavaScript app with `BuiltInAgent` or the AI SDK reads only `OPENAI_BASE_URL`. When only
+`OPENAI_API_BASE` points at another provider there, the app sends the key to OpenAI. So
+the command sends it nowhere and reports `undetermined` with the reason `unread-base-url`.
+The AI SDK adds the route after the whole base URL, so a base URL with a query string
+makes the app call a URL such as `…/v1?x=1/chat/completions`. The command sends nothing
+for it and reports `undetermined` with the reason `base-url-query`. The command reads the base URL from each service
+that loads env files: the app, whose directory holds the key's `.env` or `.env.local`
+(never the working directory), and, in `onboard credentials`, the directory of each
+`--copy-to` target, such as an agent service that runs from `agent/`. Each service reads
+its `.env.local` before its `.env`, as the app loads them, and its base URL and model go
+together. The key's own file counts too when it is outside the app, and so do the key
+file and the base URL that `onboard setup-answers` recorded: `--copy-to` copies the base
+URL along with the key, from the key file or else from the recorded answer. When the run
+chose an OpenAI-compatible provider, in `onboard classify` or the setup answers, and no
+base URL is found, the command sends nothing and reports `undetermined` with the reason
+`compatible-base-url-missing`. A key with another provider's prefix, such as `gsk_` or
+`sk-or-`, never goes to OpenAI either: with no base URL it is `undetermined` with the
+reason `key-not-openai`. So a key in `.env.local` is checked against a base URL in `.env`, and a key kept in
+a file outside the app is checked against the right endpoint. When the shell and the
+services name different base URLs (the scheme and host compare without regard to case),
+the command sends nothing and reports `undetermined` with the reason
+`endpoint-conflict`. The JSON names the vendor `openai-compatible` and the endpoint's
+host as `endpointHost`. With `COPILOTKIT_AGENT_MODEL` set, the command sends a
+one-token chat with that model to `{base}/chat/completions` instead, which gives a
+real `pass` or `fail`. A key that the endpoint calls invalid is a `fail`, including
+OpenRouter's numeric code 401. A 402 is a `fail` with the cause `model_quota`: OpenRouter
+answers a key with no credit that way. A 404 whose message names the app's model, as
+Ollama answers a model it has not pulled, is a `fail` with the cause
+`model_unavailable`. Any
+other refusal is `undetermined` with the reason `endpoint-refused-key`, because
+a gateway can want a header that the app adds itself. An accepted key is
+`undetermined` with the reason `endpoint-accepted-key`, because a model list
+does not prove that a model call is paid for. The command does not send the key
+when an Anthropic or Google base URL points the SDK at another endpoint, when
+only the shell sets the base URL for a key in the env file, or when the shell
+exports a different value for the key. It never prints the key,
+the base URL's path, or the vendor's error message, because a vendor can echo part of
+the key in it. It refuses a redirect, so the key never reaches a host that the base URL
+does not name. A redirect is `undetermined` with the reason `base-url-redirect`: set the
+base URL to the final address.
+
+A local server, such as Ollama or LM Studio, needs no key. A local server is an
+`OPENAI_BASE_URL` in an env file on `localhost`, `127.0.0.1` or `::1`. The OpenAI SDKs
+still refuse an empty key, so the app needs the stand-in value `not-needed`. When the key
+is empty or a placeholder, it is `missing` with the reason `local-endpoint-no-key`, and
+nothing is sent. `onboard credentials` then tells the agent to write `not-needed` to the
+key's own env file. When the key is `not-needed`, the command asks the server without a
+key. A model list answer is `undetermined` with the reason `keyless-local-endpoint`. With
+`COPILOTKIT_AGENT_MODEL` set, the one-token chat gives a `pass` or a `fail`. When the
+server answers 401 or 403, the key is `missing` with the reason `endpoint-refused-key`.
+For any other base URL, `not-needed` is an ordinary key value.
 
 During an onboarding run, a `pass` also replaces a `missing` or `fail` that the
 credentials step kept for the same key in the same env file. So after the
@@ -1630,6 +1844,143 @@ binds with a key. Otherwise it asks for the project name. With `--create` or
 `--project`, it runs `project select`, retries once when no key was written, and
 checks the record and the key. Then it reads the default Learning Container.
 
+When the run recorded the developer's project answer from the setup message, the
+project-name question carries it as `question.recorded`, and the run uses it
+without asking again. `onboard setup-answers` records that answer:
+
+```bash
+copilotkit onboard setup-answers --create billing-portal --key-file ~/keys/openai.env
+copilotkit onboard setup-answers
+```
+
+It records every answer from the setup message for the bound run, so a later
+step reads it even after the coding agent lost its context:
+
+- `--purpose <text>`, `--framework <name>`, and `--frontend <name>`.
+  `--framework` takes a framework slug or a name from the framework table that
+  `onboard setup-message --options` lists. Another framework's name is recorded as `frameworkName`, with
+  `framework` set to `custom-ag-ui`, the route that builds it. A name close to
+  a table row is refused with that row named. Add `--custom-framework` to
+  record it as given. A framework recorded before any setup message, for a
+  project with no agent of its own, is kept as a default
+  (`frameworkChoice: default`), because research only inferred it. A provider
+  the developer names later can then replace it with one that takes that
+  provider. Add `--framework-choice developer` for a framework the developer
+  named. A framework recorded with `--vendor-choice existing`, or after the
+  message, is the developer's.
+- `--vendor <openai|anthropic|google|openai-compatible|other>`, with
+  `--vendor-choice <developer|default|existing>`. An OpenAI-compatible provider
+  also needs `--base-url <url>`, an http or https URL with no user, password, or
+  key in its query or path, and `--model-id <id>`.
+- The project answer: `--create <name>` or `--project <slug-or-id>`.
+- The key-file answer: `--key-file <path>` or `--key-later`.
+- On the local route, the Learning model answer (`--learning later`,
+  `--learning guided`, or `--learning-file <path>`), the connection approval
+  (`--connection approved|declined`), and the approval to write to an env file
+  or `.copilotkit/project.json` with uncommitted changes
+  (`--uncommitted-writes approved|declined`).
+- The env-file answer, when git tracks the env file the key goes into or does
+  not ignore it: `--env-line approved|alternative|declined`.
+  `credentials/finalize-plan` reads it, so the developer is not asked twice.
+
+A later call replaces only the answers it names. The vendor flags replace the
+recorded vendor answer as a whole. With no flag, it prints what the run recorded
+as JSON. It never reads the key from the key file or the model file, but `--key-file`
+must name an existing file. When the key file sets `OPENAI_BASE_URL`, the JSON shows it as
+`keyFileBaseUrl`, and `--vendor openai-compatible` takes it in place of `--base-url`. Any other value is refused, and the message does not repeat it.
+A free-text answer shaped like a key, such as an `sk-`, `gsk_`, or `AIza` key or
+a long random token, is refused the same way.
+
+`onboard setup-message` writes the setup message the coding agent shows the
+developer. The agent first records what the repository already settles with
+`setup-answers`, then runs it from the target app directory:
+
+```bash
+copilotkit onboard setup-message --target empty --json
+copilotkit onboard setup-message --target empty --options --json
+copilotkit onboard setup-message --target empty --options framework --json
+copilotkit onboard setup-message --target empty --accept-defaults --json
+```
+
+It prints `status`, the `message` to show word for word, the `open` lines, and
+`next`, what the agent does after it:
+
+- `ask`: show `message`, wait, and record the reply. The message puts every
+  default on one line that **go** accepts. The model key is the one question
+  **go** never answers: the developer names the file that holds it, or says
+  "later". The message also holds every line that needs the developer's own
+  answer, such as an env file to untrack or files with uncommitted changes.
+- `settled`: every line is answered. The run goes on to `credentials/plan`.
+- `needs-credentials`: an existing app on the managed route has no project
+  finding yet. The command runs the read-only `onboard credentials` check
+  itself first, so the env-file and project lines go into the one message with
+  the key. Only a check that settles neither line leaves this status, and the
+  agent then runs `onboard credentials --json` itself.
+- `stopped`: that check stopped onboarding. It already filed the stop report,
+  and `stopReason` says why.
+- `needs-toolchain`: the developer chose a framework this machine cannot run
+  yet. The message names what to install, and the run resumes after a restart.
+
+The summary line names every line, the recorded ones too, while one of them
+still holds a default. `--options` shows every line with its recommendation
+first and its likeliest two or three alternatives. `--options <line>`, such as
+`--options framework` or `--options frontend`, lists every choice on that one
+line. `--accept-defaults`
+records the defaults the reply did not change, then prints what is still open.
+`--language <typescript|python|dotnet>` picks the framework for a project with
+no agent, and `--vendor` names a model vendor the developer asked for. A vendor
+the framework does not take becomes a line of its own. On the local route,
+which `onboard deployment` now records, the message holds the Learning model,
+the agreement and the connection lines instead of a project.
+
+Only the developer accepts the local evaluation agreement, in their own
+terminal, with `copilotkit local accept-terms`. The command refuses to run
+without a terminal or when a coding agent runs it. It shows the agreement, its
+version, the organization, and the signed-in email, and stores the acceptance in
+`local/eula-acceptance.json` in the CLI configuration directory (mode 600).
+New local setup and `init --local` use a stored acceptance while it matches the
+current agreement, organization, and user. Renewal asks every time: under a
+coding agent, the developer runs `local renew` in their own terminal. A coding
+agent cannot pass `--accept-eula-version`; scripts still can.
+
+`onboard local-terms --json` reads the agreement and prints its URL, version,
+organization, and `accepted`. It creates nothing and requests no license. On the
+local route, the setup message says the developer accepts the agreement in their
+own terminal, and `starter/clone` and `deployment/local-evaluation` stop before
+the install until `accepted` is true.
+
+When `init --local --install` stops after it cloned the starter, it still
+installs the starter's dependencies, and its error says so or names the install
+command.
+
+#### Model vendors in this release
+
+Onboarding offers a new agent only the vendors in this table. When onboarding
+chooses the vendor for a new agent, `onboard setup-answers` refuses another
+vendor for the framework, and `onboard credentials` and `onboard model-key`
+refuse another vendor's key before they read or send it. The message names the
+vendors the framework takes, and never a key value. Each refusal sends the
+`cli.onboarding.vendor_held_back` event with the framework and the vendor.
+
+An existing agent keeps its own vendor and model. A vendor recorded with
+`--vendor-choice existing`, or a run that `onboard classify` placed on an
+existing agent, is never refused.
+
+| Framework                              | Vendors                                      |
+| -------------------------------------- | -------------------------------------------- |
+| Built-in CopilotKit agent              | OpenAI, OpenAI-compatible, Anthropic, Google |
+| ADK                                    | Google, OpenAI, OpenAI-compatible            |
+| Claude Agent SDK (Python, TypeScript)  | Anthropic                                    |
+| Every other framework and Custom agent | OpenAI, OpenAI-compatible                    |
+
+Anthropic and Google come to the other frameworks in a later release. Their
+CopilotKit middleware sends the page context as a second system message, after
+the user message. Anthropic and Google refuse that message order, so every chat
+fails. The built-in agent sends the context in one leading system message, and
+ADK puts it in its one system instruction. To use Anthropic or Google for a new
+agent now, choose the built-in CopilotKit agent. An existing agent on Anthropic
+or Google can see page context fail until a CopilotKit SDK release fixes it.
+
 Read `status`:
 
 - `ready`: the project, key, and container are settled.
@@ -1738,6 +2089,26 @@ explicitly re-enabled. `copilotkit telemetry reset` restores the full
 fresh-install state: the decision is forgotten and the one-time notice shows
 again on the next interactive run.
 
+Every event carries `invocation_via`, which tells where the call came from. The
+CopilotKit skills append a hidden `--via` flag to each command they give, for
+example `--via skill:copilotkit-cli`. The CLI removes the flag before the
+command reads its arguments, so the flag never changes what the command does.
+The values are:
+
+- `skill:copilotkit`, `skill:copilotkit-cli` or `skill:copilotkit-channels`:
+  the caller passed that tag.
+- `other`: the caller passed `--via` with a value that is not on that list. The
+  command still runs.
+- `onboarding`: an untagged call inside an onboarding run, or any `onboard`
+  command. A tag wins over a run, because `onboarding_run_id` already records
+  the run.
+- `direct`: any other call.
+
+`cli.command.invoked` also carries `detected_coding_agent` and
+`detected_coding_agent_source`, read the same way as for onboarding. The CLI
+reads them once for each command. On Windows it does not read the parent
+processes for this event, because the PowerShell call can take three seconds.
+
 ## Preview and release builds
 
 Tester-facing prerelease builds are produced by CI via `workflow_dispatch` on
@@ -1917,6 +2288,10 @@ when the flag is off. A candidate file overrides release selection. The CLI down
 its private Helm tool, checks chart support, and pins the chart checksum and runtime
 image digests. Saved stacks resume with their saved release.
 
+The private chart overlay gives app-api the browser realtime address
+`ws://localhost:<selected-gateway-port>/client`. Trajectory live views use this
+address, including when setup selects a different port for a second local stack.
+
 The September 28 check found that release 0.13.8 lacks the local evaluation profile.
 Automatic setup reports `release_unavailable` before license issuance or cluster creation for this release.
 This is a release packaging blocker, not a request for user configuration.
@@ -1932,10 +2307,10 @@ or prove fresh-install acceptance.
 Use `--candidate /path/to/candidate.json` only to override release selection during
 development or release testing. Full fresh-install acceptance remains incomplete.
 
-Use Docker with at least 4 CPUs, 12 GiB of memory available to containers, and
+Use Docker with at least 4 CPUs, 4 GiB of memory available to containers, and
 40 GiB free storage for each stack. The CLI measures Docker resources after existing
 workloads. Docker keeps part of its memory limit for itself, so set the limit to
-14 GiB or more. If the check fails, the message shows the total and available memory
+6 GiB or more. If the check fails, the message shows the total and available memory
 and how much to add.
 The CLI downloads private, checksum-verified Helm and k3d tools.
 
@@ -1956,8 +2331,11 @@ browser. Review it, type `accept` exactly, and press Enter. The link stays visib
 if the browser cannot open. Opening the page does not accept; there is no scroll requirement.
 Esc/Ctrl-C/Ctrl-D cancels. The published agreement is usable once Ops enforcement is enabled.
 Template acceptance uses the normal license request and audit write, marked `status: template`.
-Scripts must supply `--accept-eula-version <version>` to `local setup` or `local renew`.
-`local start` also accepts this option when it performs first-time setup.
+Scripts must supply `--accept-eula-version <version>` to `local setup` or `local renew`,
+or, for setup, use an acceptance stored by `copilotkit local accept-terms`. `local start` also accepts
+this option when it performs first-time setup. When a coding agent runs the command, the
+option is refused and no license is requested: the developer runs `local accept-terms` in
+their own terminal.
 Generic confirmation does not accept terms. Declining requests no license and preserves saved data.
 
 Local `init` (including `--existing`) uses the same EULA review as `local setup`.