@kici-dev/compiler 0.1.26 → 0.1.27

package/dist/llm-context/llms-cli.txt

@@ -441,7 +441,7 @@ The dashboard is a browser SPA on top of the same `/api/v1/*` surface, so anythi
 
 - **Auth & identity:** `/cli/exchange-token`, `/pats`, `/user`, `/identity-links`, `/github-oauth`, `/invites`, `/invites/pending`, `/invites/:inviteId/{accept,decline}`
 - **Org & membership:** `/orgs`, `/orgs/:customerId`, `/orgs/:customerId/{members,roles,api-keys,orchestrator-keys,service-accounts,billing,trust-policies}`
-- **Workflows & runs:** `/orgs/:customerId/{runs,registrations,workflows,held-runs,environments,secrets,global-workflows}`
+- **Workflows & runs:** `/orgs/:customerId/{runs,registrations,workflows,held-runs,contexts,secrets,global-workflows}`
 - **Webhooks & event log:** `/orgs/:customerId/{sources,webhook-endpoints,event-log}`
 - **Diagnostics & activity:** `/orgs/:customerId/{diagnostics,activity,access-log}`
 
@@ -565,15 +565,6 @@ Compile workflows from `.kici/workflows/` to `kici.lock.json`.
 kici compile [options]
 ```
 
-**Options:**
-
-| Option              | Default | Description                                  |
-| ------------------- | ------- | -------------------------------------------- |
-| `--check`           | `false` | Validate workflows without writing lock file |
-| `--watch`           | `false` | Watch for changes and recompile              |
-| `--kici-dir <path>` | `.kici` | Path to .kici directory                      |
-| `--verbose`         | `false` | Detailed output                              |
-
 **Examples:**
 
 ```bash
@@ -606,69 +597,21 @@ The `--check` flag is useful in CI pipelines and pre-commit hooks. It validates
 
 ### kici run
 
-Execute workflows locally or remotely. The `run` command has two subcommands: `local` for direct execution without infrastructure, and `remote` for fixture-based execution through an orchestrator.
-
-#### kici run local
-
-Execute workflows locally without orchestrator infrastructure. Compiles workflows, matches triggers against the specified event, expands matrices, and runs jobs with DAG-based parallel scheduling.
-
-```bash
-kici run local [event] [options]
-```
-
-**Arguments:**
+Execute workflows locally or remotely. A bare `kici run [event]` performs a real routed run with this machine as the ephemeral agent; the `remote` subcommand runs fixtures through an orchestrator.
 
-| Argument | Required               | Description                                      |
-| -------- | ---------------------- | ------------------------------------------------ |
-| `event`  | when `--pick` is unset | Event type (e.g., `push`, `pr:open`, `schedule`) |
+#### kici run <event> --local
 
-**Options:**
+Run a workflow on this machine as a real routed dispatch. `kici run <event> --local` compiles your workflows, matches triggers against the specified event, expands matrices, and executes the matched jobs — this machine joins as an ephemeral agent through the warm local dev plane. No orchestrator deployment is required.
 
-| Option                | Default   | Description                                                                                                                                                                                                                            |
-| --------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `-p, --pick`          | `false`   | Interactively pick a workflow + trigger (see below)                                                                                                                                                                                    |
-| `--workflow <name>`   | none      | Run only the specified workflow (mutex with `--pick`)                                                                                                                                                                                  |
-| `--job <name>`        | none      | Run only the specified job (and its dependencies)                                                                                                                                                                                      |
-| `--branch <name>`     | detected  | Override detected git branch                                                                                                                                                                                                           |
-| `--sha <hash>`        | detected  | Override detected git SHA                                                                                                                                                                                                              |
-| `--payload <path>`    | none      | Path to explicit event payload JSON file                                                                                                                                                                                               |
-| `--concurrency <n>`   | CPU cores | Max parallel jobs **within one run** (job-level only). Cross-run [concurrency groups](https://docs.kici.dev/user/concurrency/) declared in `workflow({ concurrency: ... })` are enforced separately — see "Concurrency enforcement" below.                      |
-| `--keep-going`        | `false`   | Continue after job failure                                                                                                                                                                                                             |
-| `--container`         | `false`   | Use Podman container isolation                                                                                                                                                                                                         |
-| `--env <KEY=VALUE>`   | none      | Environment variable override (repeatable)                                                                                                                                                                                             |
-| `--input <KEY=VALUE>` | none      | Typed workflow-dispatch input (repeatable) — coerced + validated against the workflow's `dispatch({ inputs })` schema, exposed as `ctx.dispatchInputs` (see [triggers → typed dispatch inputs](https://docs.kici.dev/user/sdk/triggers/#typed-dispatch-inputs)) |
-| `--files <path>`      | git diff  | Override changed file paths (repeatable, default: git diff)                                                                                                                                                                            |
-| `--quiet`             | `false`   | Suppress streaming output (summary only)                                                                                                                                                                                               |
-| `--json`              | `false`   | Output structured JSON result                                                                                                                                                                                                          |
-| `--junit <path>`      | none      | Output JUnit XML result to file                                                                                                                                                                                                        |
-| `--debug`             | `false`   | Verbose internals                                                                                                                                                                                                                      |
-| `--kici-dir <path>`   | `.kici`   | Path to .kici directory                                                                                                                                                                                                                |
-| `--in-place`          | `false`   | Run against the real working directory instead of an isolated tmp checkout (see "Execution isolation" below)                                                                                                                           |
-| `--keep`              | `false`   | Always retain the isolated tmp checkout (default: keep only on failure)                                                                                                                                                                |
-| `--check`             | `false`   | Run in [check mode](https://docs.kici.dev/user/idempotent-steps/): each step reports drift instead of applying; the run still exits 0                                                                                                                           |
-| `--fail-on-drift`     | `false`   | In check mode, exit non-zero if any step reports drift (no effect without `--check`)                                                                                                                                                   |
-
-**Interactive workflow selection (`--pick` / `-p`):**
-
-When you do not remember the event arg for a workflow, pass `--pick` (or `-p`) to open an interactive picker. It lists every workflow with a compact summary of its triggers, lets you choose one, and (for multi-trigger workflows) prompts again for which trigger to simulate. The selected trigger is converted back into an event arg and fed through the normal pipeline.
+`kici run local` (the old direct-execution subcommand) is retired: every run is now a real routed dispatch. Invoking `kici run local <event>` prints a hint pointing at `kici run <event> --local` and exits without running.
 
 ```bash
-# Open the picker across all triggerable workflows
-kici run local --pick
-
-# Scope the picker to a trigger family (e.g. only workflows that react to pr:*)
-kici run local pr:open --pick
+kici run [event] --local [options]
 ```
 
-Rules:
-
-- `--pick` is mutually exclusive with `--workflow`. Passing both exits with code 2.
-- When `stdin` is not a TTY, `--pick` prints the available workflows and exits without running anything — fall back to `kici run local <event> --workflow <name>` in scripts.
-- Passing an event arg together with `--pick` narrows the picker to workflows that declare at least one trigger in that event family (e.g. `schedule --pick` shows only scheduled workflows).
-
 **Concurrency enforcement:**
 
-When the workflow declares a `concurrency` block, `kici run local` enforces it across concurrent local invocations on the same machine and user account. The behavior mirrors the orchestrator:
+When the workflow declares a `concurrency` block, `kici run <event> --local` enforces it across concurrent local invocations on the same machine and user account. The behavior mirrors the orchestrator:
 
 - The `group` callback is evaluated against the simulated event (same `{ branch, event }` context that the agent sees), and the resulting key is used as the lock identity. Throwing from `group` aborts the workflow run with a clear error — there is no fallback to the workflow name.
 - `cancelInProgress: true` interrupts the holder via `SIGTERM`, then escalates to `SIGKILL` after a grace window if the holder does not exit, and proceeds with the new run.
@@ -682,7 +625,7 @@ The `SIGTERM`-to-`SIGKILL` grace window defaults to 30 000 ms. Override it with
 
 **Execution isolation:**
 
-By default, `kici run local` executes steps inside an **isolated tmp checkout** rather than against your real working directory. Any file a step writes, builds, or deletes — and any `git` mutation a step performs — lands in that throwaway copy, so casual local runs never touch your tree.
+By default, `kici run <event> --local` executes steps inside an **isolated tmp checkout** rather than against your real working directory. Any file a step writes, builds, or deletes — and any `git` mutation a step performs — lands in that throwaway copy, so casual local runs never touch your tree.
 
 What gets materialized into the isolated checkout has full parity with what `kici run remote` reconstructs: your current working tree minus gitignored files, with `.kiciignore` applied to local changes, over a real `.git` directory. Concretely, the checkout is built from a clone pinned to your current `HEAD`, with your local overlay (modified, staged, and untracked-but-not-ignored files) copied on top and locally-deleted files removed. Workflows that read git metadata work because the `.git` directory is present and pinned to your `HEAD`.
 
@@ -692,8 +635,7 @@ Cleanup policy:
 
 - On a fully successful run, the isolated checkout is removed.
 - On failure, it is retained and its path is logged so you can inspect the failed state.
-- `--keep` always retains it, even on success.
-- Retained checkouts are garbage-collected after 72 hours by the next `kici run local` invocation — copy a checkout elsewhere if you need it longer.
+- Retained checkouts are garbage-collected after 72 hours by the next `kici run <event> --local` invocation — copy a checkout elsewhere if you need it longer.
 
 Set the `KICI_RUN_DIR` environment variable to place the isolated checkout under a base directory other than the system temp directory.
 
@@ -704,32 +646,23 @@ Pass `--in-place` to run against the real working directory instead — useful w
 **Examples:**
 
 ```bash
-# Run workflows matching a push event
-kici run local push
-
-# Run only a specific workflow
-kici run local push --workflow ci
+# Run workflows matching a push event on this machine
+kici run push --local
 
-# Run only a specific job (and its dependencies)
-kici run local push --job test
+# Run a pull-request-open workflow locally
+kici run pr:open --local
 
-# JSON output for CI scripting
-kici run local push --json
+# Reuse the working tree instead of an isolated clone
+kici run push --local --in-place
 
-# JUnit XML for CI integration
-kici run local push --junit results.xml
-
-# Quiet mode (summary only, no streaming)
-kici run local push --quiet
-
-# Override branch and SHA
-kici run local push --branch main --sha abc1234
+# Force the throwaway/offline plane
+kici run push --local --offline
 
 # Environment variable overrides
-kici run local push --env NODE_ENV=test --env CI=true
+kici run push --local --env NODE_ENV=test --env CI=true
 
-# Continue running other jobs after one fails
-kici run local push --keep-going
+# Quiet mode (summary only, no streaming)
+kici run push --local --quiet
 ```
 
 **Exit codes:**
@@ -739,20 +672,13 @@ kici run local push --keep-going
 | 0    | All workflows succeeded |
 | 1    | One or more jobs failed |
 
-**Output formats:**
-
-- **Default:** Streaming job output during execution, followed by a tree-format summary with per-step timing
-- **`--json`:** Structured JSON with workflows, jobs, steps, timing, and matrix values
-- **`--junit <path>`:** Standard JUnit XML for CI integration (Jenkins, GitLab, etc.)
-- **`--quiet`:** Summary only, no streaming output during execution
-
 #### kici run remote
 
 Execute fixtures remotely through the full CI pipeline. Fixtures are defined in `.kici/tests/*.ts` using the `fixture()` factory function. Without arguments, lists available fixtures.
 
 Remote runs route through the Platform. Authenticate with a personal access token (`kici login`), then target an organization with `kici org use <org>` or the `--org` flag. The Platform relays the run to the org's orchestrator, while your working-tree overlay uploads directly to object storage — see [How the run is routed](https://docs.kici.dev/user/cli-reference/#how-the-run-is-routed) and [The two planes](https://docs.kici.dev/user/cli-reference/#the-two-planes) below.
 
-Like `kici run local`, `kici run remote` recompiles your workflows (`.kici/workflows` → `kici.lock.json`) before dispatching, so the orchestrator matches and dispatches against your current workflow definitions — a brand-new or edited workflow takes effect without a separate `kici compile`. A compile or validation error aborts the run before anything is uploaded.
+Like `kici run <event> --local`, `kici run remote` recompiles your workflows (`.kici/workflows` → `kici.lock.json`) before dispatching, so the orchestrator matches and dispatches against your current workflow definitions — a brand-new or edited workflow takes effect without a separate `kici compile`. A compile or validation error aborts the run before anything is uploaded.
 
 The orchestrator must have **cache storage configured** (`KICI_STORAGE_TYPE` = `s3` or `filesystem`) with a dev-reachable upload endpoint so the CLI's direct upload succeeds; see the [testing guide](https://docs.kici.dev/user/testing-guide/) and [Storage layout](https://docs.kici.dev/operator/orchestrator/storage-layout/) for setup.
 
@@ -760,39 +686,6 @@ The orchestrator must have **cache storage configured** (`KICI_STORAGE_TYPE` = `
 kici run remote [fixture] [options]
 ```
 
-**Arguments:**
-
-| Argument  | Required | Description                                     |
-| --------- | -------- | ----------------------------------------------- |
-| `fixture` | no       | Fixture name or glob pattern (omit to list all) |
-
-**Options:**
-
-| Option                      | Default | Description                                                                                                                                                                                                                                |
-| --------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `--org <id>`                | active  | Target organization for this run (overrides `kici org use`)                                                                                                                                                                                |
-| `--orchestrator <name>`     | default | Target orchestrator cluster within the org (overrides the per-org default)                                                                                                                                                                 |
-| `--all`                     | `false` | Run all fixtures                                                                                                                                                                                                                           |
-| `-p, --pick`                | `false` | Interactively pick fixtures to run (multi-select; mutex with a fixture arg, `--all`, and `--workflow`)                                                                                                                                     |
-| `--workflow <name>`         | none    | Run a specific workflow directly (bypass triggers)                                                                                                                                                                                         |
-| `--parallel`                | `false` | Run multiple fixtures concurrently                                                                                                                                                                                                         |
-| `--no-wait`                 | -       | Fire and forget (print runIds, don't stream)                                                                                                                                                                                               |
-| `--quiet`                   | `false` | Minimal output (only final result)                                                                                                                                                                                                         |
-| `--json`                    | `false` | Machine-readable JSON output                                                                                                                                                                                                               |
-| `--junit <path>`            | none    | JUnit XML output to file for CI integration                                                                                                                                                                                                |
-| `--history`                 | `false` | Show table of recent test runs                                                                                                                                                                                                             |
-| `--context <ctx.key=value>` | none    | Inject a namespaced context secret, uploaded encrypted (repeatable)                                                                                                                                                                        |
-| `--env <KEY=VALUE>`         | none    | Provide a per-run secret, uploaded encrypted (repeatable) — see [testing guide](https://docs.kici.dev/user/testing-guide/)                                                                                                                                          |
-| `--input <KEY=VALUE>`       | none    | Typed workflow-dispatch input (repeatable) — validated + coerced + defaulted on the orchestrator from the lock descriptor, exposed as `ctx.dispatchInputs` (see [triggers → typed dispatch inputs](https://docs.kici.dev/user/sdk/triggers/#typed-dispatch-inputs)) |
-| `--target <selector>`       | none    | Narrow `runsOnAll` jobs to hosts matching this label selector (repeatable, AND-combined)                                                                                                                                                   |
-| `--target-allow-empty`      | `false` | A `--target` that narrows a `runsOnAll` job to zero hosts skips it instead of failing                                                                                                                                                      |
-| `--debug`                   | `false` | Verbose internals                                                                                                                                                                                                                          |
-| `--kici-dir <path>`         | `.kici` | Path to .kici directory                                                                                                                                                                                                                    |
-| `--routing-key <key>`       | none    | Override the routing key for this run (advanced; selecting the org normally suffices — see [How the run is routed](https://docs.kici.dev/user/cli-reference/#how-the-run-is-routed))                                                                                                |
-| `--check`                   | `false` | Run in [check mode](https://docs.kici.dev/user/idempotent-steps/): each step reports drift instead of applying                                                                                                                                                      |
-| `--fail-on-drift`           | `false` | In check mode, fail the run if any step reports drift (no effect without `--check`)                                                                                                                                                        |
-| `--approve-all, --yes`      | `false` | Auto-approve every [approval gate](https://docs.kici.dev/user/approvals/) this run holds on (run-scoped; eligibility still enforced)                                                                                                                                |
-
 `--approve-all` works in `--json` / `--quiet` mode: the run still auto-approves each gate it holds on, and the auto-approve diagnostics are written to stderr so stdout stays a pure JSON (or summary-only) payload. Without `--approve-all`, a `--json` / `--quiet` run that hits a gate stays held and prints a one-line "run held; approve via the dashboard or `kici approve <run-id>`" notice to stderr per hold.
 
 **Examples:**
@@ -914,7 +807,7 @@ When an org has more than one connected orchestrator cluster, the CLI picks the
 - **Control plane** — run initiation, trigger, status, log retrieval, and cancellation flow from your machine through the Platform, which relays them over a WebSocket connection to the org's orchestrator. Logs are delivered by the CLI polling the Platform for log chunks (tracked by a monotonic line cursor) and run status until the run reaches a terminal state; there is no direct streaming socket to the orchestrator.
 - **Data plane** — your working-tree overlay tarball uploads **directly** from your machine to the orchestrator's object store via a presigned PUT URL. The overlay never passes through the Platform. This is why the orchestrator's object-store upload endpoint must be reachable from your machine; see [Storage layout](https://docs.kici.dev/operator/orchestrator/storage-layout/).
 
-An orchestrator with no Platform connection cannot serve remote runs — the Platform is the service that offers them. For executing workflow steps on your own machine without an orchestrator (no scaler, agents, or environments), use [`kici run local`](https://docs.kici.dev/user/cli-reference/#kici-run-local).
+An orchestrator with no Platform connection cannot serve remote runs — the Platform is the service that offers them. For executing workflow steps on your own machine without an orchestrator (no scaler, agents, or environments), use [`kici run <event> --local`](https://docs.kici.dev/user/cli-reference/#kici-run-event---local).
 
 #### Fresh repos (no GitHub remote)
 
@@ -967,26 +860,6 @@ Preview which workflows match a trigger event (dry-run, no execution). Useful fo
 kici preview [event] [options]
 ```
 
-**Arguments:**
-
-| Argument | Required | Description                                                 |
-| -------- | -------- | ----------------------------------------------------------- |
-| `event`  | no       | Event type to preview (e.g., `push`, `pr:open`, `schedule`) |
-
-**Options:**
-
-| Option                      | Default | Description                                                  |
-| --------------------------- | ------- | ------------------------------------------------------------ |
-| `--workflow <name>`         | none    | Filter to specific workflow                                  |
-| `--job <name>`              | none    | Filter to specific job                                       |
-| `--branch <name>`           | `main`  | Override target branch for trigger matching                  |
-| `--sha <hash>`              | none    | Override commit SHA                                          |
-| `--files <path>`            | none    | Simulate changed file path for trigger matching (repeatable) |
-| `--secret <key=value>`      | none    | Inject flat secret (repeatable)                              |
-| `--context <ctx.key=value>` | none    | Inject context secret (repeatable)                           |
-| `--debug`                   | `false` | Verbose internals                                            |
-| `--kici-dir <path>`         | `.kici` | Path to .kici directory                                      |
-
 **Examples:**
 
 ```bash
@@ -1013,7 +886,7 @@ kici preview push --files src/index.ts --files README.md
 | 0    | Preview completed (including zero matches) |
 | 1    | Error                                      |
 
-**Migration from the old `test` command:** The dry-run preview command was renamed from `test` to `preview`. If you were using the old `test` command with a fixture name for remote fixture execution, use `kici run remote <fixture-name>` instead. For local workflow execution, use `kici run local <event>`.
+**Migration from the old `test` command:** The dry-run preview command was renamed from `test` to `preview`. If you were using the old `test` command with a fixture name for remote fixture execution, use `kici run remote <fixture-name>` instead. For local workflow execution, use `kici run <event> --local`.
 
 ### kici login
 
@@ -1029,16 +902,6 @@ After OAuth, the CLI exchanges the OIDC token for a personal access token (PAT)
 kici login [options]
 ```
 
-**Options:**
-
-| Option                      | Default | Description                                         |
-| --------------------------- | ------- | --------------------------------------------------- |
-| `--token <key>`             | none    | API key for direct authentication (legacy)          |
-| `--device`                  | false   | Force device authorization flow (headless/SSH)      |
-| `--platform-endpoint <url>` | none    | Platform relay URL                                  |
-| `--oidc-issuer <url>`       | none    | OIDC issuer URL (selects a non-default environment) |
-| `--routing-key <key>`       | none    | Routing key for webhook source identification       |
-
 **Environment variables:**
 
 | Variable              | Default                                      | Description                                                            |
@@ -1124,12 +987,6 @@ Switch the active organization by name (case-insensitive) or ID.
 kici org use <name>
 ```
 
-**Arguments:**
-
-| Argument | Required | Description             |
-| -------- | -------- | ----------------------- |
-| `name`   | yes      | Organization name or ID |
-
 **Examples:**
 
 ```bash
@@ -1165,14 +1022,6 @@ concurrency, and heartbeat age.
 kici diagnostics [options]
 ```
 
-**Options:**
-
-| Option                | Default | Description                                         |
-| --------------------- | ------- | --------------------------------------------------- |
-| `--json`              | `false` | Machine-readable JSON output                        |
-| `--verbose`           | `false` | Show extended per-agent fields (host, node, memory) |
-| `--orchestrator <id>` | all     | Scope the tree to one orchestrator connection id    |
-
 **Examples:**
 
 ```bash
@@ -1205,20 +1054,6 @@ branch, trigger, started, duration); pagination is reported at the bottom.
 kici runs list [options]
 ```
 
-**Options:**
-
-| Option                  | Default | Description                                   |
-| ----------------------- | ------- | --------------------------------------------- |
-| `--status <s>`          | all     | Filter by run status                          |
-| `--workflow <w>`        | all     | Filter by workflow name                       |
-| `--branch <b>`          | all     | Filter by branch/ref                          |
-| `--repo <r>`            | all     | Filter by repository                          |
-| `--trigger <t>`         | all     | Filter by trigger type                        |
-| `--source <routingKey>` | all     | Filter by source routing key                  |
-| `--since <ts>`          | none    | Only runs since this ISO-8601 or epoch ms     |
-| `--page <n>`            | `1`     | Page number (server page size is fixed at 20) |
-| `--json`                | `false` | Machine-readable JSON output                  |
-
 ```bash
 kici runs list
 kici runs list --status running
@@ -1230,16 +1065,12 @@ kici runs list --json | jq '.runs[].runId'
 
 Show a run's summary header plus its jobs-and-steps tree (name, status,
 duration, exit code). If the run id is not on the Platform but exists in your
-local run history (from `kici run local`), the local record is shown instead.
+local run history (from `kici run <event> --local`), the local record is shown instead.
 
 ```bash
 kici runs show <run-id> [options]
 ```
 
-| Option   | Default | Description                  |
-| -------- | ------- | ---------------------------- |
-| `--json` | `false` | Machine-readable JSON output |
-
 ```bash
 kici runs show abc123
 kici runs show abc123 --json
@@ -1253,12 +1084,6 @@ Print each job/step's log lines in order, with headers.
 kici runs logs <run-id> [options]
 ```
 
-| Option         | Default | Description                            |
-| -------------- | ------- | -------------------------------------- |
-| `--job <name>` | all     | Only print logs for this job           |
-| `-f, --follow` | `false` | Tail logs for a live run until it ends |
-| `--json`       | `false` | Machine-readable JSON output           |
-
 ```bash
 kici runs logs abc123
 kici runs logs abc123 --job build
@@ -1274,10 +1099,6 @@ cooldown between reruns of the same run.
 kici runs rerun <run-id> [options]
 ```
 
-| Option   | Default | Description                  |
-| -------- | ------- | ---------------------------- |
-| `--json` | `false` | Machine-readable JSON output |
-
 ```bash
 kici runs rerun abc123
 ```
@@ -1290,15 +1111,6 @@ Cancel a single run, or all in-progress runs on a branch.
 kici runs cancel [run-id] [options]
 ```
 
-| Argument | Required | Description      |
-| -------- | -------- | ---------------- |
-| `run-id` | no       | Run ID to cancel |
-
-| Option            | Default | Description                                 |
-| ----------------- | ------- | ------------------------------------------- |
-| `--force`         | `false` | Force cancel (kill immediately, skip hooks) |
-| `--branch <name>` | none    | Cancel all in-progress runs on this branch  |
-
 ```bash
 kici runs cancel abc123
 kici runs cancel abc123 --force
@@ -1319,19 +1131,6 @@ Approve a held [approval gate](https://docs.kici.dev/user/approvals/) so the run
 kici approve <run-id> [options]
 ```
 
-**Arguments:**
-
-| Argument | Required | Description                        |
-| -------- | -------- | ---------------------------------- |
-| `run-id` | yes      | Run ID holding the gate to approve |
-
-**Options:**
-
-| Option           | Default | Description                                          |
-| ---------------- | ------- | ---------------------------------------------------- |
-| `--job <name>`   | none    | Approve a held job (omit for a workflow-level hold)  |
-| `--step <index>` | none    | Approve a held step by its index (used with `--job`) |
-
 **Examples:**
 
 ```bash
@@ -1345,7 +1144,7 @@ kici approve abc123 --job deploy-production
 kici approve abc123 --job migrate-and-deploy --step 1
 ```
 
-You must be eligible for at least one unsatisfied clause (a member of a named team, or a named user) and hold the `environments:write` or `ci_trust:write` permission. The command reports whether the element was released, how many clauses remain, or that it was rejected.
+You must be eligible for at least one unsatisfied clause (a member of a named team, or a named user) and hold the `contexts:write` or `ci_trust:write` permission. The command reports whether the element was released, how many clauses remain, or that it was rejected.
 
 ### kici reject
 
@@ -1355,20 +1154,6 @@ Reject a held [approval gate](https://docs.kici.dev/user/approvals/). A rejectio
 kici reject <run-id> --reason <text> [options]
 ```
 
-**Arguments:**
-
-| Argument | Required | Description                       |
-| -------- | -------- | --------------------------------- |
-| `run-id` | yes      | Run ID holding the gate to reject |
-
-**Options:**
-
-| Option            | Default | Description                                         |
-| ----------------- | ------- | --------------------------------------------------- |
-| `--reason <text>` | none    | Required. Reason recorded with the rejection        |
-| `--job <name>`    | none    | Reject a held job (omit for a workflow-level hold)  |
-| `--step <index>`  | none    | Reject a held step by its index (used with `--job`) |
-
 **Examples:**
 
 ```bash
@@ -1384,7 +1169,7 @@ List secret contexts available for test runs. Shows context names and key names
 kici secrets list
 ```
 
-Each "context" corresponds to an environment configured on the orchestrator. The output lists every environment whose `allowLocalExecution` flag is `true` (the gate that lets CLI-initiated test runs resolve secrets through that environment), along with the secret key names reachable from the environment's bound scopes.
+Each context corresponds to a context configured on the orchestrator. The output lists every context whose `allowLocalExecution` flag is `true` (the gate that lets CLI-initiated test runs resolve secrets through that context), along with the secret key names reachable from the context's bound scopes.
 
 Only key names are shown — secret values are never returned over this endpoint.
 
@@ -1413,18 +1198,12 @@ See [Drive KiCI from your coding agent](https://docs.kici.dev/user/ai-agents/) f
 
 ### kici types
 
-Generate TypeScript declaration files from orchestrator environment metadata. The generated `.d.ts` file augments the SDK's `KnownSecretKeys` and `EnvironmentSecrets` interfaces, providing compile-time autocomplete and type checking for secret key names.
+Generate TypeScript declaration files from orchestrator environment metadata. The generated `.d.ts` file augments the SDK's `KnownSecretKeys` and `ContextSecrets` interfaces, providing compile-time autocomplete and type checking for secret key names.
 
 ```bash
 kici types [options]
 ```
 
-**Options:**
-
-| Option              | Default | Description             |
-| ------------------- | ------- | ----------------------- |
-| `--kici-dir <path>` | `.kici` | Path to .kici directory |
-
 **Prerequisites:** Must be authenticated via `kici login`.
 
 **Output:** `.kici/types/secrets.d.ts`
@@ -1442,7 +1221,7 @@ kici types --kici-dir packages/app/.kici
 **How it works:**
 
 1. Fetches all environment metadata (environment names and secret key names) from the orchestrator
-2. Generates a `.d.ts` file that augments `@kici-dev/sdk`'s `KnownSecretKeys` and `EnvironmentSecrets` interfaces
+2. Generates a `.d.ts` file that augments `@kici-dev/sdk`'s `KnownSecretKeys` and `ContextSecrets` interfaces
 3. Writes the file to `.kici/types/secrets.d.ts`
 
 After generating types, `ctx.secrets.get('MY_KEY')` and `ctx.secrets.expose('DB_HOST')` gain autocomplete and type checking in your IDE.
@@ -1461,20 +1240,8 @@ Generate a fixture template for an event type. Useful for creating custom test p
 kici fixture <event> [options]
 ```
 
-**Arguments:**
-
-| Argument | Required | Description                   |
-| -------- | -------- | ----------------------------- |
-| `event`  | yes      | Event to generate fixture for |
-
 **Valid events:** `pr:open`, `pr:sync`, `pr:close`, `pr:reopen`, `push`, `tag`, `comment`, `review`, `review_comment`, `release`, `dispatch`, `create`, `delete`, `status`, `workflow_run`, `fork`, `star`, `watch`, `kici_event`, `workflow_complete`, `job_complete`, `generic_webhook`, `schedule`, `lifecycle` (many support `:action` suffixes, e.g. `comment:edited`, `release:published`, `lifecycle:workflow_complete`). `webhook:<source>` is a shorthand alias for `generic_webhook:<source>`.
 
-**Options:**
-
-| Option            | Default | Description                     |
-| ----------------- | ------- | ------------------------------- |
-| `--output <path>` | stdout  | Write to file instead of stdout |
-
 **Examples:**
 
 ```bash
@@ -1503,19 +1270,6 @@ Initialize a `.kici/` directory with default workflow templates.
 kici init [options]
 ```
 
-**Options:**
-
-| Option                                | Default                | Description                                                                                             |
-| ------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------- |
-| `--force`                             | `false`                | Overwrite existing `.kici/` directory                                                                   |
-| `--skip-install`                      | `false`                | Create files without installing dependencies                                                            |
-| `--package-manager <npm\|pnpm\|yarn>` | auto-detect            | Force a package manager for the install step (default: detect from your repo)                           |
-| `--mjs`                               | `false`                | JavaScript-only mode (no TypeScript, no deps)                                                           |
-| `--no-agents-md`                      | writes `AGENTS.md`     | Skip writing `.kici/AGENTS.md` (the LLM authoring context file)                                         |
-| `--private-registry <url>`            | none                   | Scaffold a workflow `registries:` entry pointing at `<url>` (e.g. CodeArtifact, GH Packages, Verdaccio) |
-| `--private-registry-scope <scope>`    | none                   | Optional npm package scope (e.g. `@my-org`) for the private registry                                    |
-| `--private-registry-secret <ref>`     | `production:NPM_TOKEN` | Qualified secret reference (`env:NAME`) the private registry token comes from                           |
-
 **Examples:**
 
 ```bash
@@ -1575,12 +1329,6 @@ Install a pre-commit hook that runs `kici compile` before each commit.
 kici hook install [options]
 ```
 
-**Options:**
-
-| Option  | Default | Description                                |
-| ------- | ------- | ------------------------------------------ |
-| `--git` | `false` | Use raw git hook (`.git/hooks/pre-commit`) |
-
 **Examples:**
 
 ```bash
@@ -1607,12 +1355,6 @@ List all webhook entrypoints for the current project. Reads the compiled lock fi
 kici endpoints [options]
 ```
 
-**Options:**
-
-| Option              | Default | Description             |
-| ------------------- | ------- | ----------------------- |
-| `--kici-dir <path>` | `.kici` | Path to .kici directory |
-
 **Prerequisites:** Run `kici compile` first to generate the lock file.
 
 **Examples:**
@@ -1633,15 +1375,6 @@ List permanently registered workflows on the orchestrator.
 kici workflows list [options]
 ```
 
-**Options:**
-
-| Option                  | Default | Description                                    |
-| ----------------------- | ------- | ---------------------------------------------- |
-| `--json`                | `false` | Output as JSON                                 |
-| `--stale <duration>`    | none    | Filter stale registrations (e.g., `30d`, `7d`) |
-| `--trigger-type <type>` | none    | Filter by trigger type                         |
-| `--repo <repo>`         | none    | Filter by repository                           |
-
 **Examples:**
 
 ```bash
@@ -1701,12 +1434,6 @@ Trigger graceful drain on a worker instance. Sends a POST request to the worker'
 kici admin drain-worker [options]
 ```
 
-**Options:**
-
-| Option        | Required | Description                                   |
-| ------------- | -------- | --------------------------------------------- |
-| `--url <url>` | yes      | Worker URL (e.g., `http://worker-host:10143`) |
-
 **Examples:**
 
 ```bash
@@ -1734,21 +1461,6 @@ On success the output prints the **origin org** (the customer's public org id
 kici verify-attestation [artifact] --bundle <path-or-url> [--trust-root <url-or-file>] [options]
 ```
 
-**Arguments:**
-
-| Argument     | Required | Description                                                           |
-| ------------ | -------- | --------------------------------------------------------------------- |
-| `[artifact]` | no       | Artifact path to digest-check against the attestation subject digest. |
-
-**Options:**
-
-| Option                       | Required | Description                                                                                                                     |
-| ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `--bundle <path-or-url>`     | yes      | Path or `http(s)` URL to the attestation bundle JSON.                                                                           |
-| `--trust-root <url-or-file>` | no       | Trusted issuer (see below). Defaults to the hosted KiCI platform. The token issuer is pinned to it, never taken from the token. |
-| `--audience <aud>`           | no       | Expected token audience (defaults to the KiCI provenance audience).                                                             |
-| `--json`                     | no       | Print the structured verification result as JSON instead of human-readable output.                                              |
-
 **Trust root:** `--trust-root` defaults to the hosted KiCI platform's provenance issuer — the same platform you `kici login` against (see [Which trust root do I use?](https://docs.kici.dev/user/provenance/#which-trust-root-do-i-use)), so the common case needs no flag. The verifier never trusts the issuer named inside the token; supplying it out-of-band is what prevents a forged bundle from self-attesting. To override the default, pass `--trust-root` in one of two forms:
 
 - **Online — an HTTPS issuer URL.** The verifier fetches `<url>/.well-known/openid-configuration`, reads its `issuer` and `jwks_uri`, and fetches the JWKS. The token's `iss` is pinned to the discovery document's `issuer`.
@@ -1804,6 +1516,628 @@ the authoritative anchor.
 | 0    | Verified — signature, identity, build context (and digest, if checked) all pass           |
 | 1    | Not verified, or an error (missing `--bundle`, unreadable bundle, unreachable trust root) |
 
+## Command reference
+
+The exhaustive, always-current list of every `kici` command with its arguments and options, generated from the CLI's command tree so it never drifts from the shipped binary. The sections above add concepts and worked examples; the reference below is the authoritative signature list.
+
+<!-- BEGIN GENERATED: kici-commands (do not edit; run the doc generator) -->
+
+### `kici admin`
+
+Operator-facing commands for running instances
+
+Synopsis: `kici admin`
+
+### `kici admin drain-worker`
+
+Trigger graceful drain on a worker instance
+
+Synopsis: `kici admin drain-worker [options]`
+
+**Options**
+
+| Option        | Default | Description                                  |
+| ------------- | ------- | -------------------------------------------- |
+| `--url <url>` |         | Worker URL (e.g., http://worker-host:<port>) |
+
+### `kici approve`
+
+Approve a held approval gate for a run
+
+Synopsis: `kici approve <run-id> [options]`
+
+**Arguments**
+
+| Argument | Required | Variadic | Description                           |
+| -------- | -------- | -------- | ------------------------------------- |
+| `run-id` | yes      | no       | Run ID whose approval gate to approve |
+
+**Options**
+
+| Option           | Default | Description                                 |
+| ---------------- | ------- | ------------------------------------------- |
+| `--job <name>`   |         | Approve the hold for a specific job         |
+| `--step <index>` |         | Approve a step-scoped hold (requires --job) |
+
+### `kici compile`
+
+Compile workflows from .kici/workflows/ to kici.lock.json
+
+Synopsis: `kici compile [options]`
+
+**Options**
+
+| Option              | Default | Description                                  |
+| ------------------- | ------- | -------------------------------------------- |
+| `--check`           | `false` | Validate workflows without writing lock file |
+| `--kici-dir <path>` | `.kici` | Path to .kici directory                      |
+| `--verbose`         | `false` | Detailed output                              |
+| `--watch`           | `false` | Watch for changes and recompile              |
+
+### `kici diagnostics`
+
+Show orchestrators, scalers, and agents (mirrors the dashboard Diagnostics page)
+
+Synopsis: `kici diagnostics [options]`
+
+**Options**
+
+| Option                | Default | Description                         |
+| --------------------- | ------- | ----------------------------------- |
+| `--json`              | `false` | Output raw JSON                     |
+| `--verbose`           | `false` | Show extended per-agent fields      |
+| `--orchestrator <id>` |         | Scope the tree to one connection id |
+
+### `kici docs`
+
+Open the KiCI documentation site in the default browser
+
+Synopsis: `kici docs [options]`
+
+**Options**
+
+| Option      | Default | Description                                     |
+| ----------- | ------- | ----------------------------------------------- |
+| `--no-open` |         | Print the docs URL instead of opening a browser |
+
+### `kici docs llm`
+
+Print KiCI LLM docs bundles. No topic prints the llms.txt index; <topic> prints a task bundle (e.g. sdk, cli, patterns, features, providers, architecture, getting-started); "full" prints the complete bundle.
+
+Synopsis: `kici docs llm [topic] [options]`
+
+**Arguments**
+
+| Argument | Required | Variadic | Description |
+| -------- | -------- | -------- | ----------- |
+| `topic`  | no       | no       |             |
+
+**Options**
+
+| Option         | Default | Description                                  |
+| -------------- | ------- | -------------------------------------------- |
+| `--out <path>` |         | Write the bundle to a file instead of stdout |
+
+### `kici endpoints`
+
+List all webhook entrypoints for the current project
+
+Synopsis: `kici endpoints [options]`
+
+**Options**
+
+| Option              | Default | Description             |
+| ------------------- | ------- | ----------------------- |
+| `--kici-dir <path>` | `.kici` | Path to .kici directory |
+
+### `kici fixture`
+
+Generate fixture template for event type
+
+Synopsis: `kici fixture <event> [options]`
+
+**Arguments**
+
+| Argument | Required | Variadic | Description                                                                                |
+| -------- | -------- | -------- | ------------------------------------------------------------------------------------------ |
+| `event`  | yes      | no       | Event to generate fixture for (e.g., pr:open, push, schedule, lifecycle:workflow_complete) |
+
+**Options**
+
+| Option            | Default | Description                     |
+| ----------------- | ------- | ------------------------------- |
+| `--output <path>` |         | Write to file instead of stdout |
+
+### `kici hook`
+
+Manage pre-commit hooks
+
+Synopsis: `kici hook`
+
+### `kici hook install`
+
+Install kici compile pre-commit hook
+
+Synopsis: `kici hook install [options]`
+
+**Options**
+
+| Option  | Default | Description                              |
+| ------- | ------- | ---------------------------------------- |
+| `--git` | `false` | Use raw git hook (.git/hooks/pre-commit) |
+
+### `kici init`
+
+Initialize .kici/ directory with default workflows
+
+Synopsis: `kici init [options]`
+
+**Options**
+
+| Option                             | Default                | Description                                                                 |
+| ---------------------------------- | ---------------------- | --------------------------------------------------------------------------- | --- | ------------------------------------------------------------------- |
+| `--force`                          | `false`                | Overwrite existing .kici/ directory                                         |
+| `--skip-install`                   | `false`                | Create files without installing dependencies                                |
+| `--package-manager <npm            | pnpm                   | yarn>`                                                                      |     | Force a package manager for the install step (default: auto-detect) |
+| `--mjs`                            | `false`                | JavaScript-only mode (no TypeScript, no dependencies)                       |
+| `--no-agents-md`                   |                        | Skip writing .kici/AGENTS.md (LLM authoring context)                        |
+| `--private-registry <url>`         |                        | Scaffold a workflow registries: entry pointing at <url>                     |
+| `--private-registry-scope <scope>` |                        | Optional npm package scope (e.g. @my-org) for the private registry          |
+| `--private-registry-secret <ref>`  | `production:NPM_TOKEN` | Qualified secret reference (env:NAME) the private registry token comes from |
+| `--use-verdaccio-local`            | `false`                |                                                                             |
+
+### `kici local`
+
+Manage the local dev orchestrator plane
+
+Synopsis: `kici local`
+
+### `kici local attach`
+
+Attach the local dev plane to the Platform (hybrid)
+
+Synopsis: `kici local attach`
+
+### `kici local detach`
+
+Detach the local dev plane from the Platform (offline)
+
+Synopsis: `kici local detach`
+
+### `kici local down`
+
+Stop the local dev plane
+
+Synopsis: `kici local down`
+
+### `kici local logs`
+
+Print the local dev plane orchestrator log path
+
+Synopsis: `kici local logs`
+
+### `kici local status`
+
+Show local dev plane status and control commands
+
+Synopsis: `kici local status`
+
+### `kici local trust-root`
+
+Export the offline dev-signed identity trust root ({ issuer, jwks }) to a file
+
+Synopsis: `kici local trust-root <file>`
+
+**Arguments**
+
+| Argument | Required | Variadic | Description                                          |
+| -------- | -------- | -------- | ---------------------------------------------------- |
+| `file`   | yes      | no       | Output path for the { issuer, jwks } trust-root JSON |
+
+### `kici local up`
+
+Start (or reuse) the local dev plane
+
+Synopsis: `kici local up [options]`
+
+**Options**
+
+| Option        | Default | Description                                                                  |
+| ------------- | ------- | ---------------------------------------------------------------------------- |
+| `--offline`   | `false` | Force the independent (offline) plane (does not clear the attachment record) |
+| `--connected` | `false` | Force the connected/hybrid plane (requires an attached, reachable Platform)  |
+
+### `kici login`
+
+Authenticate with KiCI via browser OAuth (default) or API key (--token)
+
+Synopsis: `kici login [options]`
+
+**Options**
+
+| Option                      | Default | Description                                                                         |
+| --------------------------- | ------- | ----------------------------------------------------------------------------------- |
+| `--token <key>`             |         | API key for direct authentication (legacy)                                          |
+| `--device`                  |         | Force device authorization flow (for headless/SSH environments)                     |
+| `--platform-endpoint <url>` |         | Platform relay URL                                                                  |
+| `--oidc-issuer <url>`       |         | OIDC issuer URL (defaults to the hosted KiCI IdP unless a flag/env selects another) |
+| `--routing-key <key>`       |         | Routing key for webhook source identification                                       |
+| `--no-attach`               |         | Skip the post-login prompt to attach the local dev plane                            |
+
+### `kici logout`
+
+Revoke PAT and clear local credentials
+
+Synopsis: `kici logout`
+
+### `kici orchestrators`
+
+Inspect the org's orchestrator clusters and pick a default for run remote
+
+Synopsis: `kici orchestrators`
+
+### `kici orchestrators list`
+
+List the connected orchestrator clusters for the active org
+
+Synopsis: `kici orchestrators list [options]`
+
+**Options**
+
+| Option       | Default | Description                                    |
+| ------------ | ------- | ---------------------------------------------- |
+| `--org <id>` |         | Target organization (overrides the active org) |
+
+### `kici orchestrators use`
+
+Set the per-org default orchestrator cluster for run remote
+
+Synopsis: `kici orchestrators use <name> [options]`
+
+**Arguments**
+
+| Argument | Required | Variadic | Description               |
+| -------- | -------- | -------- | ------------------------- |
+| `name`   | yes      | no       | Orchestrator cluster name |
+
+**Options**
+
+| Option       | Default | Description                                    |
+| ------------ | ------- | ---------------------------------------------- |
+| `--org <id>` |         | Target organization (overrides the active org) |
+
+### `kici org`
+
+Manage organizations
+
+Synopsis: `kici org`
+
+### `kici org current`
+
+Show current active organization
+
+Synopsis: `kici org current`
+
+### `kici org list`
+
+List organizations you belong to
+
+Synopsis: `kici org list`
+
+### `kici org use`
+
+Switch active organization
+
+Synopsis: `kici org use <name>`
+
+**Arguments**
+
+| Argument | Required | Variadic | Description             |
+| -------- | -------- | -------- | ----------------------- |
+| `name`   | yes      | no       | Organization name or ID |
+
+### `kici pat`
+
+Manage personal access tokens
+
+Synopsis: `kici pat`
+
+### `kici pat create`
+
+Mint a personal access token (use --agent for a coding-agent token)
+
+Synopsis: `kici pat create [options]`
+
+**Options**
+
+| Option                  | Default | Description                                    |
+| ----------------------- | ------- | ---------------------------------------------- |
+| `--name <name>`         |         | Token name (defaults to the agent label)       |
+| `--agent`               | `false` | Mint an agent-kind PAT for the KiCI MCP server |
+| `--expires-in-days <n>` |         | Custom expiry in days                          |
+
+### `kici preview`
+
+Preview which workflows match a trigger event (no execution)
+
+Synopsis: `kici preview [event] [options]`
+
+**Arguments**
+
+| Argument | Required | Variadic | Description                                           |
+| -------- | -------- | -------- | ----------------------------------------------------- |
+| `event`  | no       | no       | Event type to preview (e.g., push, pr:open, schedule) |
+
+**Options**
+
+| Option                      | Default | Description                                                  |
+| --------------------------- | ------- | ------------------------------------------------------------ |
+| `--branch <name>`           |         | Override target branch for trigger matching (default: main)  |
+| `--sha <hash>`              |         | Override commit SHA                                          |
+| `--workflow <name>`         |         | Filter to specific workflow in display                       |
+| `--job <name>`              |         | Filter to specific job in display                            |
+| `--debug`                   | `false` | Verbose internals                                            |
+| `--kici-dir <path>`         | `.kici` | Path to .kici directory                                      |
+| `--files <path>`            |         | Simulate changed file path for trigger matching (repeatable) |
+| `--secret <key=value>`      |         | Inject flat secret (repeatable)                              |
+| `--context <ctx.key=value>` |         | Inject context secret (repeatable)                           |
+
+### `kici reject`
+
+Reject a held approval gate for a run
+
+Synopsis: `kici reject <run-id> [options]`
+
+**Arguments**
+
+| Argument | Required | Variadic | Description                          |
+| -------- | -------- | -------- | ------------------------------------ |
+| `run-id` | yes      | no       | Run ID whose approval gate to reject |
+
+**Options**
+
+| Option            | Default | Description                                |
+| ----------------- | ------- | ------------------------------------------ |
+| `--job <name>`    |         | Reject the hold for a specific job         |
+| `--step <index>`  |         | Reject a step-scoped hold (requires --job) |
+| `--reason <text>` |         | Reason for the rejection                   |
+
+### `kici run`
+
+Execute workflows locally or remotely
+
+Synopsis: `kici run [event] [options]`
+
+**Arguments**
+
+| Argument | Required | Variadic | Description                                            |
+| -------- | -------- | -------- | ------------------------------------------------------ |
+| `event`  | no       | no       | Event type for a routed local run (e.g. push, pr:open) |
+
+**Options**
+
+| Option              | Default | Description                                                                                                              |
+| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `--local`           | `false` | Route the run with this machine as the ephemeral agent                                                                   |
+| `--offline`         | `false` | Force the throwaway/independent plane (offline)                                                                          |
+| `--connected`       | `false` | Force the connected/hybrid plane (requires attachment)                                                                   |
+| `--in-place`        | `false` | Reuse the working tree directly instead of an isolated clone                                                             |
+| `--trusted`         | `false` | Route to the trusted fleet agent profile: steps see the ambient host env (minus the agent identity). Alias: --no-sandbox |
+| `--no-sandbox`      |         | Alias for --trusted (the bwrap sandbox is already off by default)                                                        |
+| `--env <KEY=VALUE>` |         | Per-run secret (repeatable)                                                                                              |
+| `--payload <path>`  |         | Dispatch payload JSON { action?, client_payload? } for a routed dispatch run                                             |
+| `--kici-dir <path>` | `.kici` | Path to .kici directory                                                                                                  |
+| `--quiet`           | `false` | Suppress the banner + streaming output                                                                                   |
+| `--debug`           | `false` | Verbose internals                                                                                                        |
+
+### `kici run remote`
+
+Execute fixtures remotely via orchestrator
+
+Synopsis: `kici run remote [fixture] [options]`
+
+**Arguments**
+
+| Argument  | Required | Variadic | Description                                           |
+| --------- | -------- | -------- | ----------------------------------------------------- |
+| `fixture` | no       | no       | Fixture name or glob pattern (omit to list available) |
+
+**Options**
+
+| Option                      | Default | Description                                                                                 |
+| --------------------------- | ------- | ------------------------------------------------------------------------------------------- |
+| `--workflow <name>`         |         | Run a specific workflow directly (bypass triggers)                                          |
+| `--all`                     | `false` | Run all available fixtures                                                                  |
+| `-p, --pick`                | `false` | Interactively pick fixtures to run                                                          |
+| `--parallel`                | `false` | Run matching fixtures concurrently                                                          |
+| `--no-wait`                 |         | Fire and forget (print runIds, don't stream)                                                |
+| `--quiet`                   | `false` | Suppress output except final result                                                         |
+| `--json`                    | `false` | Output structured JSON result                                                               |
+| `--junit <path>`            |         | Output JUnit XML result                                                                     |
+| `--history`                 | `false` | Show recent run history                                                                     |
+| `--routing-key <key>`       |         | Override routing key for this run                                                           |
+| `--org <id>`                |         | Target organization (overrides the active org)                                              |
+| `--orchestrator <name>`     |         | Target orchestrator cluster (overrides the per-org default)                                 |
+| `--debug`                   | `false` | Verbose internals                                                                           |
+| `--kici-dir <path>`         | `.kici` | Path to .kici directory                                                                     |
+| `--context <ctx.key=value>` |         | Inject a namespaced context secret, uploaded encrypted to the orchestrator (repeatable)     |
+| `--env <KEY=VALUE>`         |         | Provide a per-run secret (repeatable); uploaded encrypted to the orchestrator               |
+| `--check`                   | `false` | Run in check mode: report drift, change nothing                                             |
+| `--fail-on-drift`           | `false` | In check mode, exit non-zero if any step reports drift                                      |
+| `--target <selector>`       |         | Narrow runsOnAll jobs to hosts matching this label selector (repeatable, AND-combined)      |
+| `--target-allow-empty`      | `false` | A --target that narrows a runsOnAll job to zero hosts skips it instead of failing           |
+| `--input <KEY=VALUE>`       |         | Typed workflow-dispatch input (repeatable)                                                  |
+| `--yes, --approve-all`      | `false` | Auto-approve every approval gate this run holds on (run-scoped; eligibility still enforced) |
+
+### `kici runs`
+
+Inspect and manage execution runs
+
+Synopsis: `kici runs`
+
+### `kici runs cancel`
+
+Cancel a run, or all in-progress runs on a branch
+
+Synopsis: `kici runs cancel [run-id] [options]`
+
+**Arguments**
+
+| Argument | Required | Variadic | Description      |
+| -------- | -------- | -------- | ---------------- |
+| `run-id` | no       | no       | Run ID to cancel |
+
+**Options**
+
+| Option            | Default | Description                                 |
+| ----------------- | ------- | ------------------------------------------- |
+| `--force`         | `false` | Force cancel (kill immediately, skip hooks) |
+| `--branch <name>` |         | Cancel all in-progress runs on this branch  |
+
+### `kici runs list`
+
+List execution runs (mirrors the dashboard Runs page)
+
+Synopsis: `kici runs list [options]`
+
+**Options**
+
+| Option                  | Default | Description                            |
+| ----------------------- | ------- | -------------------------------------- |
+| `--status <s>`          |         | Filter by status                       |
+| `--workflow <w>`        |         | Filter by workflow name                |
+| `--branch <b>`          |         | Filter by branch/ref                   |
+| `--repo <r>`            |         | Filter by repository                   |
+| `--trigger <t>`         |         | Filter by trigger type                 |
+| `--source <routingKey>` |         | Filter by source routing key           |
+| `--since <ts>`          |         | Only runs since (ISO-8601 or epoch ms) |
+| `--page <n>`            |         | Page number                            |
+| `--json`                | `false` | Output raw JSON                        |
+
+### `kici runs logs`
+
+Print step logs for a run
+
+Synopsis: `kici runs logs <run-id> [options]`
+
+**Arguments**
+
+| Argument | Required | Variadic | Description |
+| -------- | -------- | -------- | ----------- |
+| `run-id` | yes      | no       | Run ID      |
+
+**Options**
+
+| Option         | Default | Description              |
+| -------------- | ------- | ------------------------ |
+| `--job <name>` |         | Only logs for this job   |
+| `-f, --follow` | `false` | Tail logs for a live run |
+| `--json`       | `false` | Output raw JSON          |
+
+### `kici runs rerun`
+
+Re-trigger a run
+
+Synopsis: `kici runs rerun <run-id> [options]`
+
+**Arguments**
+
+| Argument | Required | Variadic | Description     |
+| -------- | -------- | -------- | --------------- |
+| `run-id` | yes      | no       | Run ID to rerun |
+
+**Options**
+
+| Option   | Default | Description     |
+| -------- | ------- | --------------- |
+| `--json` | `false` | Output raw JSON |
+
+### `kici runs show`
+
+Show a run summary with its jobs and steps
+
+Synopsis: `kici runs show <run-id> [options]`
+
+**Arguments**
+
+| Argument | Required | Variadic | Description       |
+| -------- | -------- | -------- | ----------------- |
+| `run-id` | yes      | no       | Run ID to inspect |
+
+**Options**
+
+| Option   | Default | Description     |
+| -------- | ------- | --------------- |
+| `--json` | `false` | Output raw JSON |
+
+### `kici secrets`
+
+Manage secrets
+
+Synopsis: `kici secrets`
+
+### `kici secrets list`
+
+List test-available secret contexts
+
+Synopsis: `kici secrets list`
+
+### `kici types`
+
+Generate TypeScript declarations for secret contexts
+
+Synopsis: `kici types [options]`
+
+**Options**
+
+| Option              | Default | Description             |
+| ------------------- | ------- | ----------------------- |
+| `--kici-dir <path>` | `.kici` | Path to .kici directory |
+
+### `kici verify-attestation`
+
+Verify a KiCI provenance attestation bundle offline
+
+Synopsis: `kici verify-attestation [artifact] [options]`
+
+**Arguments**
+
+| Argument   | Required | Variadic | Description                                                              |
+| ---------- | -------- | -------- | ------------------------------------------------------------------------ |
+| `artifact` | no       | no       | Artifact path to digest-check against the attestation subject (optional) |
+
+**Options**
+
+| Option                       | Default | Description                                                                                   |
+| ---------------------------- | ------- | --------------------------------------------------------------------------------------------- |
+| `--bundle <path>`            |         | Path or URL to the attestation bundle JSON                                                    |
+| `--trust-root <url-or-file>` |         | Trusted issuer URL, or a self-contained { issuer, jwks } file (default: hosted KiCI platform) |
+| `--audience <aud>`           |         | Expected token audience                                                                       |
+| `--json`                     | `false` | Output structured JSON result                                                                 |
+
+### `kici workflows`
+
+Manage workflow registrations
+
+Synopsis: `kici workflows`
+
+### `kici workflows list`
+
+List permanently registered workflows
+
+Synopsis: `kici workflows list [options]`
+
+**Options**
+
+| Option                  | Default | Description                                |
+| ----------------------- | ------- | ------------------------------------------ |
+| `--json`                | `false` | Output as JSON                             |
+| `--stale <duration>`    |         | Filter stale registrations (e.g., 30d, 7d) |
+| `--trigger-type <type>` |         | Filter by trigger type                     |
+| `--repo <repo>`         |         | Filter by repository                       |
+
+<!-- END GENERATED: kici-commands -->
+
 ## Workflow discovery
 
 The CLI discovers workflows by scanning `.kici/workflows/*.ts` (or `.mjs` in MJS mode). Each file should `export default` a single workflow:
@@ -1844,11 +2178,11 @@ All commands follow a consistent exit code convention:
 
 ## Debug output
 
-Use `--debug` (on `kici run local`, `kici run remote`, `kici preview`) or `--verbose` (on `kici compile`) for detailed output:
+Use `--debug` (on `kici run <event> --local`, `kici run remote`, `kici preview`) or `--verbose` (on `kici compile`) for detailed output:
 
 ```bash
 # Shows trigger matching, rule evaluation, decision traces
-kici run local push --debug
+kici run push --local --debug
 
 # Shows detailed compilation steps
 kici compile --verbose
@@ -2150,14 +2484,14 @@ Each workflow entry includes:
 | `contentHash`          | SHA-256 of the raw workflow source mixed with `compileSchemaVersion` (and an `assetDigest` of declared `hashFiles` when present): `SHA-256(compileSchemaVersion + ":" + rawSource [+ "\0" + assetDigest])`. The orchestrator uses this as the source-tarball cache key and the agent re-computes it against the extracted source to detect drift.                                                                                                               |
 | `compileSchemaVersion` | Compiler schema version used when computing `contentHash` (currently `5`). The hash input is line-ending-normalized (CRLF → LF) so a lock file produced on Linux matches the agent's hash on Windows where Git's `core.autocrlf=true` rewrites checked-out text to CRLF. Bumping the schema version invalidates every existing source cache entry even if source is unchanged, which is the correct behavior when the compile-time or runtime contract changes. |
 | `triggers`             | Trigger definitions extracted from the workflow (used by the orchestrator for event matching).                                                                                                                                                                                                                                                                                                                                                                  |
-| `jobs`                 | Job definitions with scheduling metadata (runsOn, needs, matrix, environment, concurrency, container, checkout, gracePeriod, label routing, dynamic fields, etc.).                                                                                                                                                                                                                                                                                              |
+| `jobs`                 | Job definitions with scheduling metadata (runsOn, needs, matrix, contexts, concurrency, container, checkout, gracePeriod, label routing, dynamic fields, etc.).                                                                                                                                                                                                                                                                                                 |
 | `rules`                | Workflow-level conditional rules (optional). Stored as dynamic references since rule functions cannot be serialized.                                                                                                                                                                                                                                                                                                                                            |
 | `description`          | Optional workflow description.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `hashFiles`            | Declared glob patterns for extra files included in the content hash (optional). See [extra files in the content hash](https://docs.kici.dev/user/lock-file-and-drift/#extra-files-in-the-content-hash-hashfiles).                                                                                                                                                                                                                                                                                              |
 | `resolvedHashFiles`    | Resolved file paths from `hashFiles` at compile time (optional). Recorded so the agent can verify without re-discovering.                                                                                                                                                                                                                                                                                                                                       |
 | `contexts`             | Secret contexts declared by the workflow (optional). The orchestrator validates access to each context before dispatch.                                                                                                                                                                                                                                                                                                                                         |
 | `registries`           | Private npm registry declarations the agent authenticates against before install (optional): `url`, `scope`, `tokenSecret` reference, `alwaysAuth`. Resolved token bytes never appear in the lock file. See [private registries](https://docs.kici.dev/user/private-registries/).                                                                                                                                                                                                        |
-| `installEnv`           | Extra qualified secret refs (`<environment>:<secret-name>`) projected as env vars on the install subprocess for use with a committed `.kici/.npmrc` (optional). See [private registries](https://docs.kici.dev/user/private-registries/).                                                                                                                                                                                                                                                |
+| `installEnv`           | Extra qualified secret refs (`<context>:<secret-name>`) projected as env vars on the install subprocess for use with a committed `.kici/.npmrc` (optional). See [private registries](https://docs.kici.dev/user/private-registries/).                                                                                                                                                                                                                                                    |
 | `concurrency`          | Workflow-level concurrency config: `hasGroup`, `cancelInProgress`, `max` (optional). See [concurrency groups](https://docs.kici.dev/user/concurrency/).                                                                                                                                                                                                                                                                                                                                  |
 | `timeout`              | Whole-run wall-clock timeout in milliseconds (optional). The orchestrator reads this at run creation to set the run deadline.                                                                                                                                                                                                                                                                                                                                   |
 | Hook flags             | Boolean flags (`hasOnCancel`, `hasCleanup`, `hasOnSuccess`, `hasOnFailure`) indicating which lifecycle hooks are defined. Job entries additionally have `hasBeforeStep` and `hasAfterStep`.                                                                                                                                                                                                                                                                     |
@@ -2385,12 +2719,12 @@ export const pushWithSecrets = fixture('push-with-secrets', {
 
 This maps the `db` secret context to the `test-database` context, and `api` to `test-api-keys`.
 
-This mapping is honored by **both** `kici run local` and `kici run remote`:
+This mapping is honored by **both** `kici run <event> --local` and `kici run remote`:
 
-- For **`kici run local`** (see [`kici run local`](https://docs.kici.dev/user/cli-reference/#kici-run-local)), each named context is resolved from your local secret files (`.kici/.secrets`, `.env.local`, `secrets.yaml`, and `--env` flags).
-- For **`kici run remote`**, each named context maps to an orchestrator **environment**, and the orchestrator resolves that environment's secrets for the run. The target environment must be flagged `allowLocalExecution: true` — mapping a context to a missing or non-test environment rejects the run (see [Secret contexts for testing](https://docs.kici.dev/user/testing-guide/#secret-contexts-for-testing) below).
+- For a local **`kici run <event> --local`** (see [`kici run <event> --local`](https://docs.kici.dev/user/cli-reference/#kici-run-event---local)), each named context is resolved from your local secret files (`.kici/.secrets`, `.env.local`, `secrets.yaml`, and `--env` flags).
+- For **`kici run remote`**, each named context maps to an orchestrator **context**, and the orchestrator resolves that context's secrets for the run. The target context must be flagged `allowLocalExecution: true` — mapping a context to a missing or non-test context rejects the run (see [Secret contexts for testing](https://docs.kici.dev/user/testing-guide/#secret-contexts-for-testing) below).
 
-**A fixture `secrets:` mapping is fail-closed; a job's bound `environment:` is not.** The reject above applies only to the fixture `secrets:` mapping — an explicit request for that environment's secrets. A job's own bound `environment:` (`job('deploy', { environment: 'production', … })`) is treated differently on a test run: if it resolves to a non-test or unconfigured environment it is **skipped with a warning**, not rejected, so a job that deploys to production in real runs stays locally testable for its non-secret logic. `kici run remote` prints a warning naming the skipped environment(s), and the dashboard run view shows the same notice. See [Skip-on-test](https://docs.kici.dev/user/environments/#multiple-environments-per-job) in the environments guide.
+**A fixture `secrets:` mapping is fail-closed; a job's bound `context:` is not.** The reject above applies only to the fixture `secrets:` mapping — an explicit request for that context's secrets. A job's own bound `context:` (`job('deploy', { context: 'production', … })`) is treated differently on a test run: if it resolves to a non-test or unconfigured context it is **skipped with a warning**, not rejected, so a job that deploys to production in real runs stays locally testable for its non-secret logic. `kici run remote` prints a warning naming the skipped context(s), and the dashboard run view shows the same notice. See [Skip-on-test](https://docs.kici.dev/user/contexts/#multiple-contexts-per-job) in the contexts guide.
 
 ### Async fixtures
 
@@ -2525,14 +2859,14 @@ The goal of the test-secret model is to let test runs reach **test-only credenti
 
 ### CLI-uploaded local secrets
 
-`kici run remote` collects the same local secret values that `kici run local` reads — `.kici/.secrets`, `.kici/.env.local`, `.kici/secrets.yaml`, and any `--env KEY=VALUE` flags — and uploads them **encrypted** to the orchestrator alongside the run. The orchestrator decrypts them only to inject them into the agent for that run; the control plane never sees the values.
+`kici run remote` collects the same local secret values that `kici run <event> --local` reads — `.kici/.secrets`, `.kici/.env.local`, `.kici/secrets.yaml`, and any `--env KEY=VALUE` flags — and uploads them **encrypted** to the orchestrator alongside the run. The orchestrator decrypts them only to inject them into the agent for that run; the control plane never sees the values.
 
 ```bash
 # Provide an ad-hoc test value for a single remote run
 kici run remote push-main --env KICI_DATABASE_URL=postgresql://localhost/test
 ```
 
-`--env` provides a **flat** per-run override; `--context <ctx>.<KEY>=<value>` is its sibling for a **namespaced** per-run override, placing the value under the named context `ctx`. Both are uploaded **encrypted** and follow the same precedence rule below — a CLI-supplied value wins over the orchestrator test-environment secret on a key collision.
+`--env` provides a **flat** per-run override; `--context <ctx>.<KEY>=<value>` is its sibling for a **namespaced** per-run override, placing the value under the named context `ctx`. Both are uploaded **encrypted** and follow the same precedence rule below — a CLI-supplied value wins over the orchestrator test-context secret on a key collision.
 
 ```bash
 # Provide a namespaced per-run value under the 'db' context
@@ -2541,14 +2875,14 @@ kici run remote push-db --context db.KICI_DATABASE_URL=postgresql://localhost/te
 
 Because these values originate on your machine, they are the natural place to put throwaway test credentials without touching any orchestrator-stored secret.
 
-### Orchestrator test-environment secrets
+### Orchestrator test-context secrets
 
 In addition to your uploaded values, the orchestrator resolves test-scoped secrets from its own store for a remote test run:
 
-- The job's own declared `environment` contributes its resolved secrets (flat). Static strings and **pure dynamic functions** both participate: a pure `environment:` function (see [Dynamic values](https://docs.kici.dev/user/dynamic-values/)) is evaluated against the fixture's simulated event, and the resolved name is gated and resolved like a static one. Impure dynamic functions (those requiring an init job) are not evaluated for test runs — use a fixture `secrets:` mapping (or `--context`) to supply such a job's secrets.
-- Each fixture `secrets: { ctx: envName }` mapping resolves the named environment's secrets under the namespaced context `ctx`.
+- The job's own declared `context` contributes its resolved secrets (flat). Static strings and **pure dynamic functions** both participate: a pure `context:` function (see [Dynamic values](https://docs.kici.dev/user/dynamic-values/)) is evaluated against the fixture's simulated event, and the resolved name is gated and resolved like a static one. Impure dynamic functions (those requiring an init job) are not evaluated for test runs — use a fixture `secrets:` mapping (or `--context`) to supply such a job's secrets.
+- Each fixture `secrets: { ctx: envName }` mapping resolves the named context's secrets under the namespaced context `ctx`.
 
-Both paths are restricted to environments flagged `allowLocalExecution: true`. A production environment left at the default `false` is never resolvable for a test run.
+Both paths are restricted to contexts flagged `allowLocalExecution: true`. A production context left at the default `false` is never resolvable for a test run.
 
 ```typescript
 export const pushWithDb = fixture('push-db', {
@@ -2566,31 +2900,31 @@ step('migrate', async (ctx) => {
 
 ### Precedence: CLI values win
 
-When a key exists in both sources, the **CLI-uploaded local value wins** over the orchestrator test-environment value. This makes a local override a per-run knob: set `--env KICI_DATABASE_URL=...` (or put it in `.kici/.secrets`) to shadow the test environment's value for just that run, without changing anything on the orchestrator.
+When a key exists in both sources, the **CLI-uploaded local value wins** over the orchestrator test-context value. This makes a local override a per-run knob: set `--env KICI_DATABASE_URL=...` (or put it in `.kici/.secrets`) to shadow the test context's value for just that run, without changing anything on the orchestrator.
 
-### Fail-closed on non-test environments
+### Fail-closed on non-test contexts
 
 Test-run secret resolution is fail-closed:
 
-- If a fixture maps a context to an environment that does not exist, the run is **rejected**.
-- If a fixture maps a context to an environment whose `allowLocalExecution` is `false`, the run is **rejected**.
-- The `allowLocalExecution` gate applies to **all** remote test runs: a run whose matched workflow targets an environment with the flag off is rejected, so a test run can never resolve production secrets.
+- If a fixture maps to a context that does not exist, the run is **rejected**.
+- If a fixture maps to a context whose `allowLocalExecution` is `false`, the run is **rejected**.
+- The `allowLocalExecution` gate applies to **all** remote test runs: a run whose matched workflow targets a context with the flag off is rejected, so a test run can never resolve production secrets.
 
-### The `allowLocalExecution` environment flag
+### The `allowLocalExecution` context flag
 
-Each environment carries an `allowLocalExecution` flag (default `false`) that controls test-run access to that environment and to its secrets. Production environments should leave it at `false`; create a dedicated test environment with `allowLocalExecution: true` that binds only test-only secret scopes for the contexts you want test runs to use.
+Each context carries an `allowLocalExecution` flag (default `false`) that controls test-run access to that context and to its secrets. Production contexts should leave it at `false`; create a dedicated test context with `allowLocalExecution: true` that binds only test-only secret scopes for the jobs you want test runs to use.
 
 The flag is set by the orchestrator operator, either via the CLI:
 
 ```bash
-kici-admin environment set-policy --env test-database --allow-local-execution true
+kici-admin context set-policy --env test-database --allow-local-execution true
 ```
 
-or via the dashboard's "Test runs" toggle on the environment detail page. `kici secrets list` only surfaces contexts whose owning environment has `allowLocalExecution: true`, so production environments are never advertised as test-accessible.
+or via the dashboard's "Test runs" toggle on the context detail page. `kici secrets list` only surfaces contexts whose `allowLocalExecution` is `true`, so production contexts are never advertised as test-accessible.
 
 ### Local execution as an alternative
 
-`kici run local` resolves the same local secret files entirely on your machine and honors the fixture `secrets: { ... }` mapping to pick which local context backs each name (see [`kici run local`](https://docs.kici.dev/user/cli-reference/#kici-run-local)). Because the values never leave your machine, it's a good fit when you want to exercise secret-dependent steps without involving the orchestrator at all.
+`kici run <event> --local` resolves the same local secret files entirely on your machine and honors the fixture `secrets: { ... }` mapping to pick which local context backs each name (see [`kici run <event> --local`](https://docs.kici.dev/user/cli-reference/#kici-run-event---local)). Because the values never leave your machine, it's a good fit when you want to exercise secret-dependent steps without involving the orchestrator at all.
 
 ### Discovering available contexts