@kodycodes/cli 1.26.3 → 1.27.1

package/README.md

@@ -1,13 +1,13 @@
 # @kodycodes/cli
 
-Install [Kody](https://kody.codes) as a remote MCP server in local agents.
-Talks MCP `2026-07-28` (Kody's stateless `/mcp` lane) and logs in with Client
-ID Metadata Documents (SEP-991).
+Install [Kody](https://kody.codes) as a remote MCP server in local agents, and
+call Kody's Open API from the terminal. `kody login` uses Client ID Metadata
+Documents (SEP-991) once, then stores a `kody_at_…` device token.
 
-**Long term, use Kody through the host MCP connection** — `search` and
-`execute` in Cursor, Claude Code, or another client. This CLI writes that
-config. Keep `kody login` / `kody search` / `kody execute` for bootstrap,
-scripts, or hosts that cannot run MCP.
+**Long term, use Kody through the host MCP connection** — `search` and `execute`
+in Cursor, Claude Code, or another client. This CLI writes that config. Keep
+`kody login` / `kody search` / `kody execute` for bootstrap, scripts, or hosts
+that cannot run MCP.
 
 ```bash
 npx @kodycodes/cli install
@@ -25,8 +25,9 @@ npx @kodycodes/cli install
 `kody install` lists **running local** agents (Cursor, Claude Desktop, VS Code,
 Goose, Claude Code, Codex, Windsurf, Zed, and similar) and writes each host's
 remote MCP entry for `https://kody.codes/mcp`. Common host formats go through
-[`add-mcp`](https://www.npmjs.com/package/add-mcp). It does not list web clients.
-For ChatGPT, Claude.ai, and Grok, use [kody.codes/onboarding](https://kody.codes/onboarding).
+[`add-mcp`](https://www.npmjs.com/package/add-mcp). It does not list web
+clients. For ChatGPT, Claude.ai, and Grok, use
+[kody.codes/onboarding](https://kody.codes/onboarding).
 
 After install, the CLI prints a prompt you can paste into the configured agent
 to continue onboarding. Host OAuth stays in that client — `kody login` is only
@@ -43,8 +44,8 @@ also tells the agent to prefer the MCP server over the CLI.
 
 ## CLI as a local client
 
-Optional. Use when you need a scripted or headless client instead of a host
-MCP connection.
+Optional. Use when you need a scripted or headless client instead of a host MCP
+connection.
 
 ```bash
 npm install -g @kodycodes/cli
@@ -57,38 +58,38 @@ kody execute --org acme …  # one-shot org override (also: KODY_ORG=acme)
 
 Or run via `npx @kodycodes/cli` without a global install.
 
-Each `kody login` adds an org (chosen in the browser, or via `--org`). Re-logging
-into an org that is already stored replaces only that org's credential. Org-scoped
-commands (`execute`, `search`, `whoami`, `api`, …) take `--org <slug>` or
-`KODY_ORG` (flag wins, then env, then the active org). `kody logout` removes the
-active org; `kody logout --org <slug>` removes one org. Git auth stays user-wide
-(`kody auth setup-git` once covers every repo across orgs). Existing single-org
-keychain credentials migrate silently into the multi-org store as the active org
-(no re-login).
+Each `kody login` adds an org (chosen in the browser, or via `--org`).
+Re-logging into an org that is already stored replaces only that org's
+credential. Org-scoped commands (`execute`, `search`, `whoami`, `api`, …) take
+`--org <slug>` or `KODY_ORG` (flag wins, then env, then the active org).
+`kody logout` removes the active org; `kody logout --org <slug>` removes one
+org. Git auth stays user-wide (`kody auth setup-git` once covers every repo
+across orgs). Existing single-org keychain credentials migrate silently into the
+multi-org store as the active org (no re-login).
 
 ## Commands
 
-| Command | Purpose |
-| --- | --- |
-| `kody install` | Detect running local MCP clients, write their config, and start host OAuth. **Recommended long-term path.** |
-| `kody skill install` | Copies the getting-started skill into Claude Code / Cursor / Agents. |
-| `kody login` | Browser OAuth (CIMD + PKCE) for the CLI itself. Adds/replaces one org login (browser picker, or `kody login --org acme`) and keeps other org logins. |
-| `kody org list` | Lists logged-in orgs and marks the active one. `--json` for agents. |
-| `kody org use [<slug>]` | Switches the active org. With a slug (agents) switches directly; with no slug on a TTY opens a chooser; without a TTY pass a slug. |
-| `kody logout` | Removes the active org login (or `--org <slug>` for one org) and clears a stored bootstrap/API token when appropriate. |
-| `kody status` | Shows CLI login / stored API token state without printing secrets. |
-| `kody auth bootstrap --code` | Redeems a one-shot `kody_bc_…` from MCP `cliCredentialBootstrap` and stores the resulting `kody_at_…` for `execute --local` (never prints the token). |
-| `kody auth bootstrap --scopes` | Opt-in extra scopes: mints the code itself by passing `scopes` to `cliCredentialBootstrap` (with `--token`, else the `kody login` session, else a stored token), then redeems and stores it. See [Opt-in scopes](#opt-in-scopes). |
-| `kody auth setup-git` | Installs a Git credential helper for `https://kody.codes/@owner/name.git` (persistent `kody_at_…`, user-owned token with `package:read`/`package:write`). See [Git HTTPS](#git-https-setup-git). |
-| `kody auth remove-git` | Inverse of `setup-git`: clears Kody HTTPS git helpers, revokes the stored API token, deletes it from the keychain. Leaves `kody login` alone. |
-| `kody git-credential` | Credential helper invoked by Git after `setup-git` (`get` / `store` / `erase`). |
-| `kody whoami` | Confirms the CLI MCP connection and lists tools. With a scoped API token (and no login), shows token identity via the Open API. |
-| `kody search [query]` | Calls Kody `search` from the CLI (prefer the host MCP tool). Token-only auth uses Open API `GET /v1/search`. |
-| `kody api <operationId>` | Thin Open API wrapper matching the MCP `api` tool: `operationId` + flat `--params` JSON. Auth: `--token` / `KODY_API_TOKEN` / stored `auth bootstrap` token. The parsed `/openapi.json` route map is cached under the Kody cache dir keyed by the document's `ETag` and revalidated with `If-None-Match` on each run. |
-| `kody package publish` | Thin wrapper for `packagePublishExternalPush`. Optional positional `@owner/leaf`, bare leaf name, or package UUID (names are resolved to the package UUID via `packageList`); extra fields via `--params`. Same auth as `kody api`. |
-| `kody package collaborators` / `grant` / `revoke` | Who can use one package, and add or remove teams and members of the org (`--org`). `<package>` is `@owner/leaf`, the kody id, or the package id. `grant <package> --team <slug>\|--user <username> [--preset use\|contribute\|manage]` (default `use`) adds or changes a collaborator via `packageCollaboratorSet`; people outside the org are refused. `revoke <package> --team\|--user\|--grant <grant_id>` removes one via `packageCollaboratorRemove`. Needs Manage on the package and a token with `package:manage_access` (`auth bootstrap --scopes …,package:manage_access`). Prints a summary, or JSON with `--json`. |
-| `kody execute` | Calls Kody `execute` from the CLI (`--invoke`, `--code`, `--file`, or stdin via `--file -`). With a scoped API token and no login (or with `--token`), cloud execute goes through CapabilityProxy → `kody.execute` — no `kody login`. Add `--local` to run the module (and static `kody:@…` package modules) on this machine instead. `--credential key=name` (repeatable; `org:name` / `personal:name` / empty `=` for none) picks ADR 0068 credentials for `--local` or a `kody login` MCP session. `--allow-private-network` opts local execution into private and local network access. `--target prod\|mock` (default `prod`) sends CapabilityProxy / search hops to prod or the built-in CLI mock; `--target mock` implies local workerd. |
-| `kody dev` | Local testing for unpublished packages. Serves `kody.app.entry` on localhost via workerd with hot reload. Subcommands: `fetch`, `job`, `webhook`, `emit`, `check`. Default `--target mock` (scratch storage, fake credentials). Covers exports, webhooks, schedules (run-once), and subscriptions. See [Local package testing](#local-package-testing-kody-dev). |
+| Command                                           | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `kody install`                                    | Detect running local MCP clients, write their config, and start host OAuth. **Recommended long-term path.**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `kody skill install`                              | Copies the getting-started skill into Claude Code / Cursor / Agents.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `kody login`                                      | Browser OAuth (CIMD + PKCE) for the CLI itself. Adds/replaces one org login (browser picker, or `kody login --org acme`) and keeps other org logins.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `kody org list`                                   | Lists logged-in orgs and marks the active one. `--json` for agents.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `kody org use [<slug>]`                           | Switches the active org. With a slug (agents) switches directly; with no slug on a TTY opens a chooser; without a TTY pass a slug.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `kody logout`                                     | Removes the active org login (or `--org <slug>` for one org) and clears a stored bootstrap/API token when appropriate.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `kody status`                                     | Shows CLI login / stored API token state without printing secrets.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `kody auth bootstrap --code`                      | Redeems a one-shot `kody_bc_…` from MCP `cliCredentialBootstrap` and stores the resulting `kody_at_…` for `execute --local` (never prints the token).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `kody auth bootstrap --scopes`                    | Opt-in extra scopes: mints the code itself by passing `scopes` to `cliCredentialBootstrap` (with `--token`, else the `kody login` session, else a stored token), then redeems and stores it. See [Opt-in scopes](#opt-in-scopes).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `kody auth setup-git`                             | Installs a Git credential helper for `https://kody.codes/@owner/name.git` (persistent `kody_at_…`, user-owned token with `package:read`/`package:write`). See [Git HTTPS](#git-https-setup-git).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `kody auth remove-git`                            | Inverse of `setup-git`: clears Kody HTTPS git helpers, revokes the stored API token, deletes it from the keychain. Leaves `kody login` alone.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `kody git-credential`                             | Credential helper invoked by Git after `setup-git` (`get` / `store` / `erase`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `kody whoami`                                     | Confirms the CLI MCP connection and lists tools. With a scoped API token (and no login), shows token identity via the Open API.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `kody search [query]`                             | Calls Kody `search` from the CLI (prefer the host MCP tool). Token-only auth uses Open API `GET /v1/search`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `kody api <operationId>`                          | Thin Open API wrapper matching the MCP `api` tool: `operationId` + flat `--params` JSON. Auth: `--token` / `KODY_API_TOKEN` / stored `auth bootstrap` token. The parsed `/openapi.json` route map is cached under the Kody cache dir keyed by the document's `ETag` and revalidated with `If-None-Match` on each run.                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `kody package publish`                            | Thin wrapper for `packagePublishExternalPush`. Optional positional `@owner/leaf`, bare leaf name, or package UUID (names are resolved to the package UUID via `packageList`); extra fields via `--params`. Same auth as `kody api`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `kody package collaborators` / `grant` / `revoke` | Who can use one package, and add or remove teams and members of the org (`--org`). `<package>` is `@owner/leaf`, the kody id, or the package id. `grant <package> --team <slug>\|--user <username> [--preset use\|contribute\|manage]` (default `use`) adds or changes a collaborator via `packageCollaboratorSet`; people outside the org are refused. `revoke <package> --team\|--user\|--grant <grant_id>` removes one via `packageCollaboratorRemove`. Needs Manage on the package and a token with `package:manage_access` (`auth bootstrap --scopes …,package:manage_access`). Prints a summary, or JSON with `--json`.                                                                                                                   |
+| `kody execute`                                    | Calls Kody `execute` from the CLI (`--invoke`, `--code`, `--file`, or stdin via `--file -`). With a scoped API token and no login (or with `--token`), cloud execute goes through CapabilityProxy → `kody.execute` — no `kody login`. Add `--local` to run the module (and static `kody:@…` package modules) on this machine instead. `--credential key=name` (repeatable; `org:name` / `personal:name` / empty `=` for none) picks ADR 0068 credentials for `--local` or a `kody login` MCP session. `--allow-private-network` opts local execution into private and local network access. `--target prod\|mock` (default `prod`) sends CapabilityProxy / search hops to prod or the built-in CLI mock; `--target mock` implies local workerd. |
+| `kody dev`                                        | Local testing for unpublished packages. Serves `kody.app.entry` on localhost via workerd with hot reload. Subcommands: `fetch`, `job`, `webhook`, `emit`, `check`. Default `--target mock` (scratch storage, fake credentials). Covers exports, webhooks, schedules (run-once), and subscriptions. See [Local package testing](#local-package-testing-kody-dev).                                                                                                                                                                                                                                                                                                                                                                                |
 
 `--json` prints structured MCP results.
 
@@ -99,9 +100,9 @@ Agents already on Kody MCP should prefer `cliCredentialBootstrap` →
 CLI store without pasting `kody_at_…` into chat. Interactive humans can use
 `kody login`. Scoped API tokens (`kody_at_…`, from bootstrap redeem,
 `tokenCreate`, or `POST /v1/tokens`) authenticate the Open API and
-CapabilityProxy. They never replace MCP OAuth on `/mcp`. The CLI uses that
-token path when you pass `--token` / `KODY_API_TOKEN` and are not logged in
-(or when you pass `--token` explicitly):
+CapabilityProxy. They never replace MCP OAuth on `/mcp`. The CLI uses that token
+path when you pass `--token` / `KODY_API_TOKEN` and are not logged in (or when
+you pass `--token` explicitly):
 
 ```bash
 # Preferred for agents on MCP (no tokenCreate, no second OAuth):
@@ -123,22 +124,22 @@ npx @kodycodes/cli api usageGet --params '{}'
   `cliCredentialBootstrap` → `auth bootstrap`, then `kody login`, then
   `tokenCreate` for CI/headless (`--token` / `KODY_API_TOKEN`).
 - For `execute --local` specifically: `--token` / `KODY_API_TOKEN` wins when
-  set; else a stored bootstrap/API token from `auth bootstrap`; else the
-  stored `kody login` OAuth access token as Bearer only when the API and MCP
-  URLs are paired (no under-the-hood `tokenCreate`). The default pair is
+  set; else a stored bootstrap/API token from `auth bootstrap`; else the stored
+  `kody login` OAuth access token as Bearer only when the API and MCP URLs are
+  paired (no under-the-hood `tokenCreate`). The default pair is
   `https://api.kody.codes` and `https://kody.codes/mcp`; preview workers pair
-  when the API worker name adds `-api`, and loopback hosts pair at any port.
-  For a different API origin, use `auth bootstrap --api-url <origin>` or set
+  when the API worker name adds `-api`, and loopback hosts pair at any port. For
+  a different API origin, use `auth bootstrap --api-url <origin>` or set
   `KODY_API_TOKEN`. The Open API must accept that OAuth bearer on
   CapabilityProxy / package-graph
   ([kentcdodds/kody#2812](https://github.com/kentcdodds/kody/issues/2812));
   until then use bootstrap or a scoped `kody_at_…` token.
 - Wrong/expired token → 401 with a mint-fresh-token message (or the OAuth
   platform-gap message when the bearer is login OAuth).
-- Wrong scopes → the error names the missing scope and the exact command to
-  mint a token that adds it (see [Opt-in scopes](#opt-in-scopes)). When your
-  org role lacks the permission, it says so instead: a new token cannot add
-  it, and an org Owner has to grant it.
+- Wrong scopes → the error names the missing scope and the exact command to mint
+  a token that adds it (see [Opt-in scopes](#opt-in-scopes)). When your org role
+  lacks the permission, it says so instead: a new token cannot add it, and an
+  org Owner has to grant it.
 - Account flag off → the error includes `feature_disabled` and the
   `local-execute` feature flag. Another token does not bypass that flag.
 - Prefer the env var so the token stays out of shell history and `ps`.
@@ -164,10 +165,9 @@ npx @kodycodes/cli auth bootstrap --code 'kody_bc_…' --lifetime short
   `--token` when given, else the `kody login` session, else `KODY_API_TOKEN` /
   the stored token. A token can only mint scopes it already holds.
 - A bootstrap code's scopes are fixed when it is minted, so `--code` with
-  `--scopes` is an error that prints the matching `cliCredentialBootstrap`
-  call.
-- `insufficient_scope` errors print both commands with the full scope list
-  (your current scopes plus the missing one), so you can copy one and retry.
+  `--scopes` is an error that prints the matching `cliCredentialBootstrap` call.
+- `insufficient_scope` errors print both commands with the full scope list (your
+  current scopes plus the missing one), so you can copy one and retry.
 
 ## Git HTTPS (`setup-git`)
 
@@ -185,15 +185,15 @@ git clone https://kody.codes/@owner/name.git
 user-owned `kody_at_…` with `package:read` and `package:write` (default
 `--lifetime long`; reuses a suitable stored token). That one credential
 authorizes every `@owner/name.git` you can access across all orgs — login
-`--org` only scopes the MCP mint session, not git. When an API token is
-already stored it probes `org_binding` on `GET /v1/tokens/current`; after a
-fresh login with no API token yet, it mints via the login session and checks
-`org_binding` on the minted token. Configures a **stable** credential helper
-(global `kody` only when that install's version supports `git-credential`,
-otherwise `npx -y @kodycodes/cli@<exact-version> …` — never a major-only
-`@1` range that can reuse a stale npx cache, and never an ephemeral
-`~/.npm/_npx/…` path). Re-running `setup-git` rewrites stale helper entries;
-every CLI command also refreshes an outdated pin silently.
+`--org` only scopes the MCP mint session, not git. When an API token is already
+stored it probes `org_binding` on `GET /v1/tokens/current`; after a fresh login
+with no API token yet, it mints via the login session and checks `org_binding`
+on the minted token. Configures a **stable** credential helper (global `kody`
+only when that install's version supports `git-credential`, otherwise
+`npx -y @kodycodes/cli@<exact-version> …` — never a major-only `@1` range that
+can reuse a stale npx cache, and never an ephemeral `~/.npm/_npx/…` path).
+Re-running `setup-git` rewrites stale helper entries; every CLI command also
+refreshes an outdated pin silently.
 
 ```bash
 git config --global credential.https://kody.codes.helper '!… git-credential'
@@ -209,14 +209,14 @@ Push moves live HEAD only (packages do not auto-publish). Existing `kody login`
 
 ## Local package testing (`kody dev`)
 
-Test an unpublished package (app, exports, jobs, webhooks, subscriptions)
-before publish. Bundling reuses the same esbuild path as `execute --file` /
-publish (`local-bundle.ts`). One shared flag:
+Test an unpublished package (app, exports, jobs, webhooks, subscriptions) before
+publish. Bundling reuses the same esbuild path as `execute --file` / publish
+(`local-bundle.ts`). One shared flag:
 
-| Command | `--target prod` (default for execute/search) | `--target mock` (default for `kody dev`) |
-| --- | --- | --- |
-| `kody dev` | Local app against real Kody | Local app against the CLI mock |
-| `execute` / `search` | Real capabilities, storage, secrets | Mock catalog / scratch storage / fake credentials |
+| Command              | `--target prod` (default for execute/search) | `--target mock` (default for `kody dev`)          |
+| -------------------- | -------------------------------------------- | ------------------------------------------------- |
+| `kody dev`           | Local app against real Kody                  | Local app against the CLI mock                    |
+| `execute` / `search` | Real capabilities, storage, secrets          | Mock catalog / scratch storage / fake credentials |
 
 The mock is built into the CLI (no kody-celld). It refuses unimplemented routes
 with `not_implemented_in_mock` rather than faking success. `--reset-storage`
@@ -256,55 +256,62 @@ kody search --target mock local
   The last good build does not keep answering `200`.
 - **Runtime errors**: an uncaught throw from the fetch handler returns a
   dev-only `500` page with the stack mapped back to your `.ts` sources
-  (`x-kody-dev-error: runtime`). Runtime wrapper and native frames are
-  dropped. The terminal prints the same stack.
+  (`x-kody-dev-error: runtime`). Runtime wrapper and native frames are dropped.
+  The terminal prints the same stack.
 - **Logs**: app `console.*` output streams to the terminal tagged with the
   request, e.g. `[GET /scores #12] saved 3 rows`. `warn` and `error` go to
   stderr.
 - **Live reload** (on by default; `--no-live-reload` turns it off): HTML
-  responses get a small `<script>` that listens on
-  `/__kody/dev/events` (server-sent events). The page reloads after each swap
-  to a new build. Build errors, and runtime errors from the page's own
-  `fetch` calls, show an overlay; the page reloads on the next good build.
-  There is no HMR. Only requests that accept `text/html` (browser page loads)
-  get the script; compressed HTML, agent requests, and `kody dev fetch`
-  responses are left untouched.
-- **Fast rebuilds.** File events are debounced for 30ms, and esbuild reuses
-  an incremental context, so a save usually serves the new code in about
-  60ms on a small app.
-- **Ports.** Each package gets a stable default port in 4100–4999 (derived
-  from `kody.id`), so URLs survive restarts. If it is taken, `kody dev` moves
-  to the next free port. An explicit `--port <n>` is used exactly and fails
-  with a fix when the port is busy (`--port 0` picks any free port). Starting
-  a second `kody dev` for the same package and target without `--port` fails
-  and names the running server's URL and pid.
-- **Client bundle and assets**, same URLs as a published app:
-  `kody.app.client` is bundled for the browser and served at
+  responses get a small `<script>` that listens on `/__kody/dev/events`
+  (server-sent events). The page reloads after each swap to a new build. Build
+  errors, and runtime errors from the page's own `fetch` calls, show an overlay;
+  the page reloads on the next good build. There is no HMR. Only requests that
+  accept `text/html` (browser page loads) get the script; compressed HTML, agent
+  requests, and `kody dev fetch` responses are left untouched.
+- **Fast rebuilds.** File events are debounced for 30ms, and esbuild reuses an
+  incremental context, so a save usually serves the new code in about 60ms on a
+  small app.
+- **Ports.** Each package gets a stable default port in 4100–4999 (derived from
+  `kody.id`), so URLs survive restarts. If it is taken, `kody dev` moves to the
+  next free port. An explicit `--port <n>` is used exactly and fails with a fix
+  when the port is busy (`--port 0` picks any free port). Starting a second
+  `kody dev` for the same package and target without `--port` fails and names
+  the running server's URL and pid.
+- **Client bundle and assets**, same URLs as a published app: `kody.app.client`
+  is bundled for the browser and served at
   `<appBasePath>/_assets/client.<hash>.js` (inline source map;
-  `client.externals` stay bare imports). `packageContext.clientModuleUrl`
-  points at it, and `/_assets/__version.json` reports it. Files in
-  `kody.app.assets` are served under `/_assets/`. Both are `no-store` and
-  rebuild on save; editing an asset reloads open pages.
-- **Prebuild**: `kody.dev.prebuild` runs a shell command from the package
-  root before every build (with `KODY_DEV=1`), for generated CSS, icons, or
-  data files. Its output is tagged `[prebuild]`. A non-zero exit is shown as a
-  build error. File changes made while it runs do not trigger another build.
+  `client.externals` stay bare imports). `packageContext.clientModuleUrl` points
+  at it, and `/_assets/__version.json` reports it. Files in `kody.app.assets`
+  are served under `/_assets/`. Both are `no-store` and rebuild on save; editing
+  an asset reloads open pages.
+- **Prebuild**: `kody.dev.prebuild` runs a shell command from the package root
+  before every build (with `KODY_DEV=1`), for generated CSS, icons, or data
+  files. Its output is tagged `[prebuild]`. A non-zero exit is shown as a build
+  error. File changes made while it runs do not trigger another build.
   `kody.dev.ignore` lists root-relative path prefixes the watcher skips:
 
   ```json
   {
-    "kody": {
-      "app": { "entry": "./app/router.ts", "client": "./app/client.ts", "assets": "./public" },
-      "dev": { "prebuild": "node scripts/build-css.mjs", "ignore": ["public/generated"] }
-    }
+  	"kody": {
+  		"app": {
+  			"entry": "./app/router.ts",
+  			"client": "./app/client.ts",
+  			"assets": "./public"
+  		},
+  		"dev": {
+  			"prebuild": "node scripts/build-css.mjs",
+  			"ignore": ["public/generated"]
+  		}
+  	}
   }
   ```
 
   `kody.dev` only affects `kody dev`; publish ignores it.
+
 - **Cleanup**: Ctrl-C, `SIGTERM`, and `SIGHUP` stop workerd and remove the
   `kody-dev-*` temp dir. If the CLI is killed outright, a small reaper process
-  does the same. Each start also sweeps dirs and orphaned workerd processes
-  left behind by dead CLI runs, including older CLI versions.
+  does the same. Each start also sweeps dirs and orphaned workerd processes left
+  behind by dead CLI runs, including older CLI versions.
 
 ### Driving `kody dev` from an agent
 
@@ -314,8 +321,8 @@ curl -s http://127.0.0.1:<port>/__kody/dev/status
 kody dev fetch /scores                          # reuses the running server
 ```
 
-- `--json` prints one JSON object per line on stdout, each with a `type` and
-  an ISO `ts`:
+- `--json` prints one JSON object per line on stdout, each with a `type` and an
+  ISO `ts`:
   - `ready`: `url`, `port`, `basePath`, `pid`, `statusUrl`, `buildId`
   - `rebuild_start`: `files`
   - `rebuild_ok`: `ms`, `buildId`, `restarted`
@@ -324,10 +331,11 @@ kody dev fetch /scores                          # reuses the running server
   - `log`: `source`, `level`, `message`, `request`
 
   Status lines stay on stderr.
-- `GET /__kody/dev/status` returns `{ ok, state, buildId, url, port,
-  basePath, target, package, pid, lastRebuild, lastError }`. `state` is one of
-  `starting`, `building`, `ready`, or `build_error`. `lastError` holds the
-  current build error or the most recent runtime error.
+
+- `GET /__kody/dev/status` returns
+  `{ ok, state, buildId, url, port, basePath, target, package, pid, lastRebuild, lastError }`.
+  `state` is one of `starting`, `building`, `ready`, or `build_error`.
+  `lastError` holds the current build error or the most recent runtime error.
 - `--ready-file <path>` writes `{ url, port, basePath, pid, statusUrl }` once
   the first build settles, and deletes the file on exit.
 - `kody dev fetch` attaches to a running `kody dev` for the same package and
@@ -338,10 +346,10 @@ kody dev fetch /scores                          # reuses the running server
 
 ## Local execute
 
-`kody execute --local` runs the same execute module (default export called
-with `--params`) on this machine instead of in Kody's cloud sandbox. Local CPU
-is free; every `kody:runtime` call (`kody.*`, `kody.mcp.*`, `workflows.create`)
-is proxied to Kody's CapabilityProxy and metered like a cloud hop. Static
+`kody execute --local` runs the same execute module (default export called with
+`--params`) on this machine instead of in Kody's cloud sandbox. Local CPU is
+free; every `kody:runtime` call (`kody.*`, `kody.mcp.*`, `workflows.create`) is
+proxied to Kody's CapabilityProxy and metered like a cloud hop. Static
 `kody:@scope/package/export` imports are **resolved into the local workerd
 bundle** via `POST /v1/local-execute/package-graph` (same Bearer as
 CapabilityProxy — never hosted MCP `execute`, and never a whole-module
@@ -371,67 +379,65 @@ npx @kodycodes/cli execute --local --invoke kody:@scope/pkg/export --params '{"n
 
 - **Auth:** `--token` / `KODY_API_TOKEN` when set; else stored `auth bootstrap`
   API token; else a valid `kody login` session (OAuth access token as Bearer —
-  never printed, never exchanged via `tokenCreate`). Prefer the env var for
-  API tokens so they stay out of shell history and `ps`. The bearer stays in
-  the CLI process; the sandbox only talks to a loopback bridge. Host MCP OAuth
-  from other clients is never read. Until
-  [kentcdodds/kody#2812](https://github.com/kentcdodds/kody/issues/2812)
-  ships, login-only Bearer is rejected by the Open API — use bootstrap or a
-  `kody_at_…` token in that case.
+  never printed, never exchanged via `tokenCreate`). Prefer the env var for API
+  tokens so they stay out of shell history and `ps`. The bearer stays in the CLI
+  process; the sandbox only talks to a loopback bridge. Host MCP OAuth from
+  other clients is never read. Until
+  [kentcdodds/kody#2812](https://github.com/kentcdodds/kody/issues/2812) ships,
+  login-only Bearer is rejected by the Open API — use bootstrap or a `kody_at_…`
+  token in that case.
 - **Node.js:** 22 or newer (`package.json` `engines` is `>=22`). Older Node
   fails immediately with that requirement, before workerd is downloaded or
   started.
-- **Bundling:** `--file` entries are bundled with esbuild before workerd
-  loads `main.js` (relative local imports and bare npm packages from
-  `node_modules`; `kody:*` stays external for package-graph / runtime). That
-  matches hosted execute and publish. Unresolvable imports fail with a clear
-  bundle error before any network call. `--code` and stdin (`--file -`) are
-  left as written (no filesystem graph to follow).
+- **Bundling:** `--file` entries are bundled with esbuild before workerd loads
+  `main.js` (relative local imports and bare npm packages from `node_modules`;
+  `kody:*` stays external for package-graph / runtime). That matches hosted
+  execute and publish. Unresolvable imports fail with a clear bundle error
+  before any network call. `--code` and stdin (`--file -`) are left as written
+  (no filesystem graph to follow).
 - **Runtime:** a pinned [workerd](https://github.com/cloudflare/workerd)
   release, downloaded once from GitHub, sha256-verified, and cached under
-  `~/.cache/kody` (Linux, or `$XDG_CACHE_HOME/kody`) or
-  `~/Library/Caches/kody` (macOS). Override with `KODY_CACHE_DIR`, or point
-  `KODY_WORKERD_PATH` at your own binary. No Docker required. Linux and macOS
-  (x64/arm64) only for now.
-- **API:** `https://api.kody.codes` by default (`--api-url` or `KODY_API_URL`
-  to override). The CLI calls `POST /v1/local-execute/package-graph` before
+  `~/.cache/kody` (Linux, or `$XDG_CACHE_HOME/kody`) or `~/Library/Caches/kody`
+  (macOS). Override with `KODY_CACHE_DIR`, or point `KODY_WORKERD_PATH` at your
+  own binary. No Docker required. Linux and macOS (x64/arm64) only for now.
+- **API:** `https://api.kody.codes` by default (`--api-url` or `KODY_API_URL` to
+  override). The CLI calls `POST /v1/local-execute/package-graph` before
   starting workerd (it authenticates the bearer and, when the module imports
   `kody:@…`, downloads stamped package modules for local embedding,
   [platform issue](https://github.com/kentcdodds/kody/issues/2808)) and
   `POST /v1/capability-proxy/call` with `{ path, args, conversationId? }` for
-  each runtime call.
-  CapabilityProxy requests go through Node's own `node:http(s)` client with
-  one keep-alive connection and a 7-minute idle limit for headers and body
-  chunks. Origin's 5-minute deadline for a `fetch` with `{{secret:…}}`
-  placeholders ends that call first, with its own error. Node's default
-  300-second fetch limit no longer cuts it short. With `NODE_USE_ENV_PROXY=1`
-  or `--use-env-proxy`, these requests honor `HTTP_PROXY` / `HTTPS_PROXY` /
-  `NO_PROXY` like Node's own fetch (Node 22.21 / 24.5 or later; older Node
-  fails with a clear error instead of silently bypassing the proxy).
-  A PR preview's API host is `https://kody-pr-<n>-api.<subdomain>.workers.dev`;
-  the app origin (`kody-pr-<n>`) answers `/v1/*` with an HTML 404.
-- **Errors:** an expired/revoked token or an account without the
-  `local-execute` flag fails fast with a clear message before any code runs.
-  The token is only sent over https (plain http is allowed for localhost).
-  A non-JSON error body, such as an HTML page from the wrong `--api-url`, is
-  shortened to its title or a 200-character excerpt plus its size.
-  Missing package-graph API, unresolved imports, or missing artifacts fail
-  clearly — there is **no silent fallback** to cloud `kody.execute`.
+  each runtime call. CapabilityProxy requests go through Node's own
+  `node:http(s)` client with one keep-alive connection and a 7-minute idle limit
+  for headers and body chunks. Origin's 5-minute deadline for a `fetch` with
+  `{{secret:…}}` placeholders ends that call first, with its own error. Node's
+  default 300-second fetch limit no longer cuts it short. With
+  `NODE_USE_ENV_PROXY=1` or `--use-env-proxy`, these requests honor `HTTP_PROXY`
+  / `HTTPS_PROXY` / `NO_PROXY` like Node's own fetch (Node 22.21 / 24.5 or
+  later; older Node fails with a clear error instead of silently bypassing the
+  proxy). A PR preview's API host is
+  `https://kody-pr-<n>-api.<subdomain>.workers.dev`; the app origin
+  (`kody-pr-<n>`) answers `/v1/*` with an HTML 404.
+- **Errors:** an expired/revoked token or an account without the `local-execute`
+  flag fails fast with a clear message before any code runs. The token is only
+  sent over https (plain http is allowed for localhost). A non-JSON error body,
+  such as an HTML page from the wrong `--api-url`, is shortened to its title or
+  a 200-character excerpt plus its size. Missing package-graph API, unresolved
+  imports, or missing artifacts fail clearly — there is **no silent fallback**
+  to cloud `kody.execute`.
 - **Lifetime:** no execution time limit locally; Ctrl-C (or SIGTERM) stops
   workerd and removes the temporary module.
 - **Saved packages:** `import { … } from 'kody:@owner/name/export'` under
   `--local` keeps the user module + package graph in local workerd. Local
-  package CPU is not billed as a full cloud execute of the user module;
-  per-call CapabilityProxy hops (and whatever the package-graph prep call
-  meters once shipped) may still meter. Prefer keeping `--local` in agent
-  workflows — do not switch to hosted MCP `execute`. `--invoke` without
-  `--local` is the thin passthrough for a single export (still cloud).
-  `packageStorage()`, `packageSecrets`, `email`, and `events` stay unbound on
-  the ad hoc entry like cloud execute unless the downloaded package modules
-  carry stamps. Outbound `fetch` is public-network-only by default. Pass
-  `--allow-private-network` with `execute --local` to also allow private and
-  local addresses; the loopback bridge used for CapabilityProxy calls remains
-  available either way.
+  package CPU is not billed as a full cloud execute of the user module; per-call
+  CapabilityProxy hops (and whatever the package-graph prep call meters once
+  shipped) may still meter. Prefer keeping `--local` in agent workflows — do not
+  switch to hosted MCP `execute`. `--invoke` without `--local` is the thin
+  passthrough for a single export (still cloud). `packageStorage()`,
+  `packageSecrets`, `email`, and `events` stay unbound on the ad hoc entry like
+  cloud execute unless the downloaded package modules carry stamps. Outbound
+  `fetch` is public-network-only by default. Pass `--allow-private-network` with
+  `execute --local` to also allow private and local addresses; the loopback
+  bridge used for CapabilityProxy calls remains available either way.
 
 ## Token storage
 
@@ -462,10 +468,12 @@ same run).
 
 ## Releases
 
-This repo uses [semantic-release](https://github.com/semantic-release/semantic-release)
-the same way [match-sorter](https://github.com/kentcdodds/match-sorter) does:
+This repo uses
+[semantic-release](https://github.com/semantic-release/semantic-release) the
+same way [match-sorter](https://github.com/kentcdodds/match-sorter) does:
 conventional commits on `main` publish `@kodycodes/cli` with npm provenance
-(`id-token: write`). Version in `package.json` stays `0.0.0-semantically-released`.
+(`id-token: write`). Version in `package.json` stays
+`0.0.0-semantically-released`.
 
 Trusted publishing for `@kodycodes/cli` is attached to this GitHub repository.
 

package/dist/add-mcp-install.d.ts

@@ -1,5 +1,5 @@
 import { type AgentType, type InstallResult, type McpServerConfig } from 'add-mcp';
-import type { HostId } from './host-catalog.js';
+import { type HostId } from './host-catalog.js';
 /**
  * Hosts whose on-disk MCP config `add-mcp` already knows how to merge.
  * Claude Desktop is intentionally omitted: remote MCP lives in Connectors, not

package/dist/api-token.d.ts

@@ -1,5 +1,5 @@
 import { loadStoredApiToken, type StoredApiToken } from './api-token-store.js';
-import type { SecretBackend, StoreResolution } from './store.js';
+import { type SecretBackend, type StoreResolution } from './store.js';
 /** Mirrors `cliTokenLifetimeAliases` in auth-bootstrap (keep in sync; avoid import cycle). */
 export type CliTokenLifetimeAlias = 'short' | 'long';
 /** Platform tracking for login OAuth as CapabilityProxy / package-graph Bearer. */

package/dist/{auth-4FW6GCLG.js → auth-6ZE6QQXA.js}

@@ -2,25 +2,30 @@ import { createRequire as __createRequire } from 'node:module'; const require =
 import {
   credentialsFromTokens,
   ensureFreshCredentials,
+  ensureOpenApiCredentials,
   isAccessTokenExpired,
   login,
   refreshStoredCredentials,
   resolvePendingOrgSlug
-} from "./chunk-4D6ORNXY.js";
-import "./chunk-JWEFKKAD.js";
+} from "./chunk-5ZBJAP6G.js";
+import "./chunk-ZILB2HWE.js";
 import "./chunk-CASGRYOF.js";
+import "./chunk-W2SAFAT4.js";
+import "./chunk-46IJPEID.js";
+import "./chunk-DW5UTJ6T.js";
+import "./chunk-5JIRHJQP.js";
+import "./chunk-4GIFJVGT.js";
 import "./chunk-CWWHR4FH.js";
-import "./chunk-G6LJWROP.js";
-import "./chunk-RTWUNV76.js";
-import "./chunk-RM34N3KI.js";
-import "./chunk-IHP6PV6X.js";
-import "./chunk-QHBCP4OB.js";
+import "./chunk-3H72XY5R.js";
+import "./chunk-BTL3PJ2H.js";
+import "./chunk-UW6AWLXX.js";
 export {
   credentialsFromTokens,
   ensureFreshCredentials,
+  ensureOpenApiCredentials,
   isAccessTokenExpired,
   login,
   refreshStoredCredentials,
   resolvePendingOrgSlug
 };
-//# sourceMappingURL=auth-4FW6GCLG.js.map
+//# sourceMappingURL=auth-6ZE6QQXA.js.map

package/dist/auth-bootstrap.d.ts

@@ -1,5 +1,5 @@
 import { type StoredApiToken } from './api-token-store.js';
-import type { SecretBackend, StoreResolution } from './store.js';
+import { type SecretBackend, type StoreResolution } from './store.js';
 /** ADR 0056 one-shot bootstrap code prefix (`kody_bc_…`). */
 export declare const cliBootstrapCodePrefix = "kody_bc_";
 export declare const bootstrapRedeemPath = "v1/tokens/bootstrap/redeem";