copilotkit 4.21.0 → 4.23.0

package/README.md

@@ -46,6 +46,14 @@ accepts the connection and then sends nothing therefore ends in a message that
 names the command and the wait, rather than in a CLI that never returns. A stall
 is not retried, because retrying it would spend the same wait a second time.
 
+npm 12 refuses a project install when `npm_config_allow_scripts` is set in the
+environment, and exits with `EALLOWSCRIPTS`. The CLI does not retry that refusal.
+It names the variable and prints one command that runs the install without it,
+such as `env -u npm_config_allow_scripts npm install`. The CLI does not remove the
+variable by itself: with no `allow-scripts` setting, npm 12 runs no install
+scripts, so removing it would change which scripts run. To keep the list, move
+it to the `allowScripts` field in `package.json`.
+
 ## Type-safe agent IDs
 
 `copilotkit typegen` reads a running CopilotKit runtime's `/info` route and
@@ -242,9 +250,9 @@ copilotkit login --json
 ```
 
 The command prints JSON lines for the sign-in URL, an instruction for the
-machine reader, and the final result. Every JSON login URL carries the
-`agent_onboarding` display hint because JSON mode is the machine-readable login
-contract.
+machine reader, and the final result. It signs in with a device code, so the
+browser can run on any machine. See
+[Signing in when the browser is on another machine](#signing-in-when-the-browser-is-on-another-machine).
 
 The command opens the page in the default browser itself when a browser can be
 reached. It does not try on CI, over SSH, in a container, on Linux with no
@@ -255,21 +263,16 @@ URL for manual sign-in. Either way, it keeps reading the same process until its
 terminal event. A failed sign-in prints one final failure object and exits
 nonzero.
 
-After the CLI exchanges the browser token and saves its credentials, the
-agent-onboarding callback page tries to close the tab. If the browser blocks
-closing, the page keeps a visible success message so the user can close it
-manually. Exchange or credential-save failures keep a visible error page open.
-
 The bundled onboarding prompt gives one short explanation before it opens the
 page: sign-in lets the coding agent create a project and API key, and the user
 can remove the key later to disconnect the workspace.
 
 ### Signing in when the browser is on another machine
 
-The flow above sends the browser back to a loopback server on the CLI's own
-machine. That fails over SSH, in a VM, or in a container, because the browser
-runs somewhere else. From 4.14.0, the CLI uses a device authorization grant
-(RFC 8628) instead:
+Plain `copilotkit login` sends the browser back to a loopback server on the
+CLI's own machine. That fails over SSH, in a VM, or in a container, because the
+browser runs somewhere else. `login --device` and `login --json` use a device
+authorization grant (RFC 8628) instead:
 
 ```bash
 copilotkit login --device   # at a terminal
@@ -291,8 +294,7 @@ codes in a row expire with nobody approving them, `login --json` refuses to
 request another. It writes a `failed` record with `reason: repeated_expiry` and
 exits non-zero. Run `copilotkit login --json --force` when someone is ready to
 approve. Any sign-in that succeeds resets the count, and the count lapses after
-a day. If the Ops service has no device routes, `login --json` falls back to the
-loopback flow.
+a day.
 
 Approve a code only if your own terminal or coding agent showed it to you. If
 someone sent you a code, deny the request: approving it signs their CLI in as
@@ -312,6 +314,13 @@ Run `onboard start` in the project folder, or in an empty folder for a new app.
 - A folder with its own Git repository is one project, even when its parts sit
   in subfolders such as `frontend/` and `backend/`.
 
+`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.
+
 ## Feature onboarding for existing apps
 
 Use the optional `--intent` flag when an existing CopilotKit app needs one
@@ -354,7 +363,9 @@ as `unreportable`. It records the coding agent the environment shows as
 `detected_coding_agent`, and sets `coding_agent_mismatch` when that agent differs
 from the declared one. `cli.onboarding.started` also carries
 `detected_coding_agent`, because a run that stops before `onboard identify` sends
-no identify event. Channel setup stage events include
+no identify event. It also carries `audience`: `detected-agent` when the
+environment shows an agent, `human-terminal` for a terminal with no detected
+agent, and `non-tty` otherwise. Channel setup stage events include
 the existing `onboarding_run_id` when the command runs inside an onboarding run;
 standalone commands omit it. These events use the CLI's existing telemetry consent gate.
 
@@ -472,6 +483,10 @@ copilotkit init -n my-agent -f langgraph-py \
   same way `copilotkit project select` does: a typo fails with the available
   slugs instead of creating something you did not ask for. A refused value fails
   before `init` writes any file, so you can retry into the same directory.
+- `--dir <path>` builds the app in that directory instead of
+  `<current directory>/<name>`, so the directory the shell is in does not
+  matter. The app takes the directory's name, and `--dir .` builds in the
+  current directory. `--dir` and `--name` cannot be combined.
 - `-y`/`--yes` installs dependencies without asking; `--no-install` answers the
   same question without installing. `--install` is a longhand for `--yes`.
 - `--no-key-prompt` skips the question about a missing model key. Use it where the
@@ -1043,19 +1058,39 @@ in `web/.env.local`, which is the file the app loads. Two such packages below, o
 none, adds nothing to the search, because a credential resolved from the wrong
 half is worse than one reported as absent.
 
+`project select` records the directory it wrote the key into as
+`"apiKeyDirectory"` in `.copilotkit/project.json`, relative to that file.
+`verify` (and `onboard proof-check`, which runs it) also reads the key from
+that directory. This is how a run from the root finds the key when the frontend
+and the runtime are sibling packages. Only the key is read from there, and only
+when no other directory in the search supplies one. A recorded directory outside
+the project is ignored, and the report says so. If another directory supplies a
+different key, `verify` uses that key and adds a warning that names both files.
+When no key is found, the report names every directory it read and every app
+package it did not read.
+
+The record also settles **The app can load the project API key** when the root
+holds more than one app. The check is made for the package that depends on
+`@copilotkit/runtime`, because its process reads the key. A key recorded in the
+frontend while a sibling package hosts the runtime fails this check. It never
+passes.
+
 Being found is not the same as being loadable. A framework's env loader does not
 walk up — Next.js, Vite, Nuxt and Astro all read env files from the application's
 own directory — so a key at the repository root is invisible to an app in a
 subdirectory. `verify` reports the two facts separately: **A project API key is
 present** says the credential exists somewhere in this repository, and **The app
 can load the project API key** says the directory the app runs in supplies it.
-The second is `UNKNOWN` rather than `FAIL` wherever it cannot decide: no package
+The second is `WARN` rather than `FAIL` wherever it cannot decide: no package
 declaring a `@copilotkit/*` dependency was found, more than one was, or a script
 in the app — or in any package above it, up to the project root — names an env
-file itself with `dotenv`, `env-cmd`, or `--env-file`. It is also `UNKNOWN` when
-a runtime answered and reported an Intelligence entitlement, because a runtime
+file itself with `dotenv`, `env-cmd`, or `--env-file`. A correctly wired app
+returns these too, so they do not fail the command. It is `UNKNOWN` when a
+runtime answered and reported an Intelligence entitlement, because a runtime
 cannot report one without having loaded a key: the report then names the
 disagreement instead of claiming the app cannot load a key the runtime is using.
+That one still fails the command, because a runtime URL that points at another
+app produces it too.
 
 That last check is the one a passing build cannot give you. A key in `.env`
 proves only that one was provisioned: the runtime reads no environment variable
@@ -1068,9 +1103,17 @@ when the runtime is unreachable.
 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
-a caller can branch on the command instead of parsing it. With `--json` the
-payload is the only thing on stdout and every diagnostic goes to stderr, so
-piping is safe.
+a caller can branch on the command instead of parsing it.
+
+The exception is labeled `WARN`: an `undetermined` result that a correctly
+wired app returns too. The report shows it as `WARN`, `--json` names it in
+`warnings` and keeps `ok` true, and the command exits zero. Two checks can warn.
+`api_key_loadable_by_app` warns in the cases above. `page_context_reaches_agent`
+warns when the agent answers without the context value, because a correctly
+wired agent that keeps to its own task answers that way too.
+
+With `--json` the payload is the only thing on stdout and every diagnostic goes
+to stderr, so piping is safe.
 
 Use `--expect-runtime oss` to prove an open-source runtime instead. In this
 mode, hosted project, key, and thread-route checks do not apply. The command
@@ -1316,9 +1359,13 @@ Ask the vendor about one key before the build:
 
 ```bash
 copilotkit onboard model-key --key OPENAI_API_KEY
-copilotkit onboard model-key --key ANTHROPIC_API_KEY --env-file agent/.env --json
+copilotkit onboard model-key --key ANTHROPIC_API_KEY --env-path agent/.env --json
 ```
 
+The flag is `--env-path`, not `--env-file`. Node 20 and 22 read `--env-file`
+anywhere on the command line, and they exit with code 9 on a missing file before
+the CLI starts.
+
 The command reads the key from the env file (`.env` by default) and sends one
 request with a one-token answer to that vendor. The call costs a fraction of a
 cent. It knows `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, and `GOOGLE_API_KEY`.
@@ -1368,7 +1415,22 @@ copilotkit onboard credentials --model-key OPENAI_API_KEY --json
 
 It asks the vendor about each key, as `onboard model-key` does. When every key
 settles, it protects the credential paths for the run's audit. A missing or
-refused key is a `needs-developer` answer.
+refused key is a `needs-developer` answer. For a missing `OPENAI_API_KEY`,
+`ANTHROPIC_API_KEY`, or `GOOGLE_API_KEY`, `question.ask` also names the vendor
+page that creates a key and the vendor account that pays for the model calls.
+
+When the agent runs as its own service, that service reads its own env file.
+Name that file with `--copy-to`:
+
+```bash
+copilotkit onboard credentials --model-key OPENAI_API_KEY \
+  --copy-to ../agent/.env --json
+```
+
+The step copies each key into that `.env` file and protects it with the other
+credential paths. `copiedKeys` gives the outcome for each copy. A file that
+already holds another real value keeps it. The step stops when git does not
+ignore the file, because the key would then be committed.
 
 It needs a bound run and exits zero for every answer. A `stopped` answer files
 the stop report itself. It never prints a key.
@@ -1573,3 +1635,337 @@ A failed install leaves the configured app in place: run `npm install`, then `np
 The starter listens on localhost and uses one local developer identity. Before deployment, add verified user authentication, request limits, and durable Managed Agents session mappings. Intelligence thread storage does not replace that adapter mapping.
 
 Release ordering: merge the CopilotKit starter before releasing this command. The shared starter catalog includes `examples/integrations/claude-managed-agents`, so the release source gate rejects a template revision that omits it. The command uses the build-pinned CopilotKit revision, like the existing starters.
+
+## Local evaluation candidate setup
+
+This preview accepts macOS with Docker Desktop and Linux with rootful Docker Engine.
+The CLI checks daemon identity and refuses unknown engines, rootless Docker, Podman,
+non-Desktop macOS engines, Windows, and Docker Desktop on Linux. The Windows init picker
+does not offer local evaluation. Native Linux still requires runtime acceptance before
+publication. Linux sign-in requires a Docker gateway on a host IPv4 interface. On restart,
+the CLI checks the auth port on both loopback and that gateway before Docker changes.
+If another process holds either address, stop that process and retry.
+Linux Docker builds may omit platform branding; the CLI still requires an Engine component,
+rootful mode, and a host gateway. A failed Docker query reports `docker_unavailable` with
+start/retry guidance, rather than claiming the engine is unsupported.
+
+For local evaluation testing, start with the
+[local evaluation tester guide](../../docs/runbooks/local-evaluation-testing.md).
+
+`local setup` selects the latest stable published chart automatically. It does
+require `self-hosted.local-evaluation` for a new stack. Existing records remain manageable
+when the flag is off. A candidate file overrides release selection. The CLI downloads
+its private Helm tool, checks chart support, and pins the chart checksum and runtime
+image digests. Saved stacks resume with their saved release.
+
+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.
+The Ops service still controls evaluation license issuance separately.
+
+For a local or prerelease CLI build, the release operator can set `CLI_LOCAL_CHART_VERSION`
+to an exact published candidate version. The built CLI then uses that version for plain
+`local setup`. It rejects mismatched chart metadata and retains the chart checksum and image checks.
+The build rejects version ranges, build metadata, and pins in production distribution builds.
+An unset pin retains stable release selection. This build input does not enable Ops issuance
+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 RAM, and 40 GiB free storage available
+for each stack. The CLI measures Docker resources after existing workloads.
+The CLI downloads private, checksum-verified Helm and k3d tools.
+
+1. Sign in with `copilotkit login`.
+2. Open the app directory.
+3. Run `copilotkit local setup --defer-model`.
+4. Run `copilotkit local connect` to review the app connection changes.
+5. After approval, run `copilotkit local connect --approve-connection`.
+
+The local organization uses the ID and name from your verified evaluation license.
+It represents the organization selected during CLI sign-in, with a separate local database.
+Setup does not copy hosted projects or data. Renewal cannot change the stack's organization.
+If a license does not match the local database, App API and the Learning scheduler refuse
+startup and retain saved data. Older test stacks with a generic organization ID need an
+explicit data migration; setup will not reassign their existing projects.
+
+For a new app, full init uses the same installer and connects the new scaffold:
+
+```bash
+copilotkit init -n local-app -f langgraph-js --local --defer-model --no-install
+```
+
+For an existing app, run full init from its directory:
+
+```bash
+copilotkit init --local --existing
+```
+
+At a terminal, init asks the same questions as `local setup`: the guided model prompt
+(provider, key, model, or configure later), then whether to add sample data. It installs
+the latest release, completes sign-in when needed, and asks before replacing the app
+connection. `--candidate` overrides the release for testing only. Installed-stack recovery
+uses saved inputs without requiring an Ops session.
+
+For an unattended existing-app setup, supply inputs and approve the connection separately:
+
+```bash
+copilotkit init --local --existing --json --defer-model
+copilotkit init --local --existing --approve-connection --json
+```
+
+The first command prepares the stack and requests connection approval. The second
+uses the saved release and connects the app. It saves the prior settings before
+replacement. Hosted data stays in the hosted service; the local project starts empty.
+
+Add `--json` to new-app local init for one versioned result without terminal prompts.
+Missing inputs return exit code 2 together with a resume command. Failures return
+exit code 1 and recovery guidance. If a new app already exists after interruption,
+enter its directory and resume with `init --local --existing --json`.
+
+Interactive init offers the deployment choice before authentication. Agent-driven
+onboarding offers the same choice and calls the local commands directly. It does
+not invoke full init. Both paths still need validation against published artifacts.
+
+The manifest must identify the published chart, its checksum, image digests,
+and tool downloads for the current platform. `--defer-model` leaves Learning
+model configuration incomplete. To provide your model settings instead, use
+`--model-config /path/to/private-model.json`:
+
+```json
+{
+  "model": "openai/your-model",
+  "provider": "openai",
+  "apiKey": "your-model-key"
+}
+```
+
+Keep that file outside source control. An optional `baseUrl` selects the model
+endpoint. The stack does not include a model or provider credentials.
+
+Interactive init offers app model reuse, a separate Learning model, or deferral.
+For reuse, put the app's model and credentials in the private JSON file.
+The CLI does not read or guess credentials from app source files.
+Both file choices use the same validation as `--model-config`.
+Without `baseUrl`, use an OpenAI or Anthropic model with its API key.
+Custom endpoints must support the OpenAI-compatible API; their API key is optional.
+Configuration belongs to the installation, including all apps that share that stack.
+Saving configuration does not prove model access. A real Learning run provides that proof.
+
+For a model on the Docker host, use a configuration such as:
+
+```json
+{
+  "model": "local/your-model",
+  "provider": "compatible",
+  "baseUrl": "http://localhost:11434/v1"
+}
+```
+
+The CLI replaces loopback addresses and `host.docker.internal` with
+`host.k3d.internal` in the Kubernetes Secret.
+[k3d supplies this host DNS record](https://k3d.io/v5.8.3/usage/k3s/).
+Bind the model server to an interface reachable from Docker and allow that port through the host firewall.
+A server bound only to loopback cannot accept traffic through the Docker bridge.
+With a remote Docker engine, the model must be reachable from that engine's host.
+The CLI does not start the model server or prove endpoint access during setup.
+
+Run `copilotkit local setup` from the app directory for guided model configuration.
+Choose OpenAI, Anthropic, or an OpenAI-compatible endpoint, then supply an API key in
+the masked prompt. Compatible endpoints ask for their base URL first and may omit the key.
+The CLI sends the key only to that provider's model list (`/v1/models`, or `<base URL>/models`)
+and shows the models it can use that Learning supports. Learning resolves OpenAI and Anthropic
+models through the catalog pinned with its runtime, so newer models a provider lists are hidden
+until that catalog is upgraded; the CLI refuses them from prompts and `--model-config` files alike.
+OpenAI-compatible endpoints accept any model ID. Type to filter, use the arrow keys or Tab to pick
+one, or enter an unlisted supported ID. A rejected key returns to key entry. If the list cannot be
+loaded, the prompt shows the supported models instead. Listing models does not prove that a
+Learning run works.
+Esc or Ctrl+C cancels before setup changes the stack. `--defer-model` skips this flow.
+
+For scripts, use `copilotkit local setup --model-config /path/to/private-model.json`
+or `--defer-model`. Fresh setup without a terminal, including `--json`, requires
+one of these flags. Existing unattended setup without model flags keeps saved settings.
+
+After deferral, either method configures Learning. This replaces the saved model configuration.
+On a running, ready stack it updates the model secret and restarts only the Learning agent;
+the dashboard stays up and images, databases, and migrations are not reapplied. A stopped,
+failed, or unfinished stack gets the full installation instead.
+It keeps the saved release, license, ports, and stack credentials.
+If installation fails, run `copilotkit local setup --json` to retry with the saved model configuration.
+To remove model configuration, run `copilotkit local setup --defer-model`.
+
+Setup saves its release, ports, credentials, and recovery inputs before
+installation. After an interrupted install, run `copilotkit local setup --json` from
+the same app directory to reuse all saved inputs without another prompt or another
+license. A different candidate requires an explicit update.
+
+Use `copilotkit local list` to find saved stacks, including stacks whose app
+folders are missing. Use `local status`, `local start`, or `local stop` with
+`--stack <id>` to select one. Stop preserves data. Logout does not remove stacks.
+
+Run `local credentials` to show the generated dashboard login. This command does
+not contact Ops or Docker. Keep its output private.
+
+### First start and later restarts
+
+Run these commands from the app directory. First start does not require an existing evaluation:
+
+```sh
+copilotkit login
+copilotkit local start --defer-model
+```
+
+On first start, the CLI selects and verifies a release, obtains the temporary evaluation
+license, installs its private tools, and creates the stack. First installation needs network
+access. `--defer-model` lets you test sign-in before you configure Learning.
+Use `--model-config /path/to/private-model.json` instead to configure Learning during setup.
+
+For later starts, run the same `local start --defer-model` command. It retains the saved
+release, license, model configuration, credentials, ports, and data. Normal start and stop
+use Docker directly; they do not require Helm or k3d downloads or an Ops session.
+Start waits for App API, the dashboard, and the realtime gateway before returning.
+An interrupted installation resumes through the installer using its saved inputs.
+An explicit unknown `--stack` ID fails without creating replacement storage.
+
+Interactive setup shows the CLI kite spinner, the current phase, and elapsed setup time.
+Repeated image operations share one status line. Piped output uses plain phase lines;
+`--json` emits only its result envelope. A failed setup names the phase that stopped.
+
+The caller never needs to run k3d. Use `local setup` to change an existing
+installation's Learning settings. After startup, follow the CLI sign-in steps below when
+the stack is ready.
+
+### Sample threads and Learning container
+
+A fresh interactive `local setup` asks whether to add sample data after the model prompt.
+Every later interactive `local setup` asks again once the stack is ready, while it has no samples.
+Rerunning setup with the same model choice on a running stack changes nothing and restarts nothing.
+Yes imports 16 sample conversations (support, sales, and coding agents) through the thread
+import API and binds them to a separate Learning container, `samples` ("Sample conversations"),
+so your app's own threads never mix with them. The conversations contain recurring mistakes and
+user corrections for Learning to find. Setup does not start a Learning run; start one from
+Learning in the dashboard once a model is configured.
+
+`--samples` or `--no-samples` answers the question without a prompt. JSON and non-interactive
+setup add samples only with `--samples`. To add them later, or to retry, run
+`copilotkit local samples` from the app folder (or `--stack <id>`). Stable sample IDs make a
+repeat import add no duplicates. If the license does not include Learning, the threads are
+still imported and the CLI reports why the container was not created. A seeding failure never
+fails setup.
+
+### Background CLI sign-in
+
+New local evaluations use the background CLI provider as their only dashboard sign-in method.
+Node.js 22 or newer and macOS or Linux are required.
+Setup and `local start` start the background provider. `local stop` stops it.
+When setup finishes in an interactive terminal, it opens the same one-use sign-in as
+`local login`. No code approval is needed. JSON and non-interactive
+runs never open a browser; they name the `local login` command instead.
+`local status` reports both stack readiness and provider health.
+
+Run `copilotkit local login` from your app folder. It opens the browser and the dashboard
+signs you in without a code or a click. Dashboards released before this change still show
+**Sign In**; choose it. Outside the app folder, add `--stack <id>`.
+The command starts the provider if needed; the stack itself must already be running.
+It needs no hosted session or network access beyond the local stack.
+
+For sign-in started directly in the browser, or if the CLI cannot open a browser:
+
+1. Open the dashboard URL and select **Sign In**.
+2. Run `copilotkit local auth pending --stack <id>`.
+3. Match the terminal code with the browser code.
+4. Run `copilotkit local auth approve CODE --stack <id>` or `deny CODE`.
+
+`local credentials` prints the login command, approval fallback, and dashboard URL. It prints no password.
+The provider continues after the terminal closes. Requests expire after two minutes.
+Terminal login links expire after two minutes and work once. The CLI does not print them.
+After upgrading an already-running provider, stop and start it with `local auth stop`
+and `local auth start` before using `local login`. Neither command removes stack data.
+Only approve a request you initiated. Local processes with access to your private
+CLI files can also approve requests; shell access is part of the trust boundary.
+
+After a provider crash, run `copilotkit local auth start --stack <id>`.
+After a host restart, run `copilotkit local start --stack <id>`.
+Both reuse the saved identity and signing key without an Ops session or internet access.
+An interrupted browser request must start again. Recovery does not restore Keycloak.
+The CLI does not install an OS login service.
+
+The installer writes auth settings into Helm values. Updates retain those settings.
+Browser traffic binds to loopback. On native Linux, the provider also binds the
+verified Docker gateway when it is a host interface. Docker Desktop on macOS uses
+`host.docker.internal`. Approval uses a private Unix socket, not an HTTP endpoint.
+The OIDC client uses an exact callback URL, PKCE, and signed ID tokens.
+App API still enforces organization, project, and license access.
+
+### Operate the local stack
+
+Run Learning and Channels commands from an app connected to the local stack.
+They use that stack's saved project and private service credential, without an Ops session.
+Local Learning reads and configuration calls need no internet connection.
+Learning runs still need the configured model. Slack and Teams still need internet
+access and a public HTTPS address that you supply. A real mention and useful reply
+remain required for Channels proof.
+
+Local commands use the existing CLI telemetry consent settings. Local diagnostic
+logs record step names, elapsed time, and exit status. They exclude command inputs,
+subprocess output, model credentials, and license tokens.
+
+Run `copilotkit local renew --stack <id>` to request a license for the current
+organization plan. Renewal requires internet access and CopilotKit sign-in.
+Non-Enterprise licenses last 30 days. Enterprise licenses follow the recorded paid-term
+end date, or last 30 days when no end date exists. Free organizations qualify without
+payment. Paid organizations must pass the current account-standing checks. The CLI saves
+the new token before applying it. If the stack is stopped, `local start` applies
+the saved renewal. Renewal preserves data and does not restart accepted Learning
+jobs. If application fails, rerun `local renew` to apply the saved token.
+
+Demo licenses require a CLI-managed k3d node inside Docker. During installation,
+the CLI checks the Docker node and writes evidence for the signed organization.
+App API and the Learning scheduler check that evidence before startup. Missing or
+mismatched evidence stops those services with a recovery message; it does not delete data.
+The check does not grant a customer-managed hosting entitlement.
+
+Run `copilotkit local update` from the app folder (or add `--stack <id>`) to move the stack
+to the latest release; it says so when the stack already runs it. `--candidate
+/path/to/release.json` chooses a specific release for testing. The CLI preserves the completed release
+and saves the attempted release before database changes. It stops producers and
+requires active jobs to finish before migrations. It never resets storage or
+rolls back a database automatically.
+
+After interruption, run `copilotkit local status --stack <id>` to inspect the
+saved update state. Run `copilotkit local update --stack <id>` to resume the
+recorded candidate. If migration completion is unknown, `local start` reports
+that recovery command without starting application services. If migrations
+completed, `local start` finishes the recorded update and checks readiness.
+
+Candidates must declare compatibility with the saved schema. Published charts carry
+that declaration in `local-evaluation-release.json`; charts packaged before it existed
+declare none, so update refuses them. A candidate that
+requires Kubernetes replacement cannot use this update path. Candidate and
+update acceptance tests against published artifacts are still required.
+
+For an existing app, connection requires `--approve-connection`. The local project
+starts empty; hosted data is not copied. `local cancel` restores the prior settings
+that still match this setup's writes. It reports conflict names and keeps later
+edits and stack data. Connection refuses to write an API key into a tracked `.env`.
+
+A copied app requires `--share-stack` to share its original stack. Deletion
+lists every associated app path. Before deleting, `local delete` gives every connected app its earlier
+connection settings back, as `local cancel` does; settings it cannot restore (a missing
+folder or later edits) are kept privately under `local-evaluation-recovery/`.
+At a terminal, `copilotkit local delete` asks before it
+deletes anything; "No, keep it" is the default. Scripts and `--json` confirm shared data
+loss with `copilotkit local delete --stack <id> --confirm-delete <id>`. Every local command
+that uses the stack (`setup`, `start`, `stop`, `delete`, `update`, `status`,
+`renew`, `login`, and `auth start`) checks Docker before it prompts, asks for
+confirmation, or downloads anything. It stops with a Docker message when Docker
+is not running or the engine is not supported. The CLI does not start Docker.
+If Docker has no cluster for the stack, delete removes only the saved stack
+settings and app references.
+
+`--json` returns versioned command results. Setup reports missing candidate and
+model-choice inputs together before authentication. Cold installation,
+offline operation, and platform acceptance are not yet validated for a
+published candidate.

package/cli-build-info.json

@@ -2,20 +2,20 @@
   "schemaVersion": 1,
   "package": {
     "name": "copilotkit",
-    "version": "4.21.0"
+    "version": "4.23.0"
   },
   "intelligence": {
-    "commit": "83dc327eb0243ab1d5a74b9fd1496b9f8679d3df"
+    "commit": "9fc4219b274ac05ae24f540bce5c3a338939740d"
   },
   "copilotKit": {
-    "submittedInput": "3dc45f8bdca6665af9b4cc5cecfbcb8ab057e426",
-    "commit": "3dc45f8bdca6665af9b4cc5cecfbcb8ab057e426"
+    "submittedInput": "f835ce816112541654ded07162c2cc8ddf4f3f2c",
+    "commit": "f835ce816112541654ded07162c2cc8ddf4f3f2c"
   },
   "channel": "production",
-  "triggeringActor": "MikeRyanDev",
+  "triggeringActor": "tylerslaton",
   "workflow": {
-    "runId": "36646329163",
-    "runUrl": "https://github.com/CopilotKit/Intelligence/actions/runs/36646329163"
+    "runId": "36949776521",
+    "runUrl": "https://github.com/CopilotKit/Intelligence/actions/runs/36949776521"
   },
   "validationResult": "passed",
   "ag2": {
@@ -24,5 +24,5 @@
     "revision": "main",
     "pinned": false
   },
-  "builtAt": "2026-09-29T23:41:18Z"
+  "builtAt": "2026-10-02T01:13:44Z"
 }