@kici-dev/compiler 0.1.25 → 0.1.27

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

@@ -40,7 +40,7 @@ Guide to the KiCI web dashboard. Covers navigation (sidebar, org switcher, mobil
 
 How to run and write tests for KiCI workflows, including remote test execution with `kici run remote`, fixture-based testing, and overlay mode for uncommitted changes.
 
-### [Environments](https://docs.kici.dev/user/environments/)
+### [Contexts](https://docs.kici.dev/user/contexts/)
 
 Configure deployment environments (staging, production, review/\*) with variables, scoped secrets, and protection rules. Covers the SDK API (`environment`, `env`, `concurrencyGroup` on jobs), the 8-layer variable merge precedence, protection rules (branch restrictions, required reviewers, wait timers, concurrency), dashboard management, type generation, and migration from the legacy contexts system.
 
@@ -279,21 +279,13 @@ Decision Summary:
 
 ## Run locally
 
-Execute matched workflows locally with `kici run local`:
+Execute matched workflows locally with `kici run <event> --local`:
 
 ```bash
-npx kici run local pr:open
+npx kici run pr:open --local
 ```
 
-This compiles, matches triggers, and runs all matched jobs with DAG-based parallel scheduling.
-
-If you do not want to remember the event arg, pass `--pick` (or `-p`) and pick from a list of workflows instead:
-
-```bash
-npx kici run local --pick
-```
-
-The picker lists each workflow with a summary of its declared triggers, derives the event arg for the one you choose, and runs it through the same pipeline.
+This compiles, matches triggers, and runs all matched jobs on this machine — which joins as an ephemeral agent through the warm local dev plane — with DAG-based parallel scheduling.
 
 ## Workflow dependencies
 
@@ -418,14 +410,14 @@ Or add the flag to your root `package.json`:
 
 ## Authoring KiCI workflows with LLM coding agents
 
-KiCI is LLM-ready by design. Because workflows are real, typed TypeScript, coding agents reason over the SDK's `.d.ts` signatures instead of guessing a bespoke YAML DSL — and they verify their own pipelines with the same `kici preview` and `kici run local` loop you use, so there's no push-to-find-out round-trip. First-class agent context ships in the box, so an agent is briefed the moment it opens the project.
+KiCI is LLM-ready by design. Because workflows are real, typed TypeScript, coding agents reason over the SDK's `.d.ts` signatures instead of guessing a bespoke YAML DSL — and they verify their own pipelines with the same `kici preview` and `kici run <event> --local` loop you use, so there's no push-to-find-out round-trip. First-class agent context ships in the box, so an agent is briefed the moment it opens the project.
 
 KiCI ships first-class context for LLM coding agents (Claude Code, Cursor, Aider, etc.). When you scaffold a project with `kici init`, the CLI writes `.kici/AGENTS.md`, a one-page briefing that tells the agent:
 
 - where the SDK type declarations live (`node_modules/@kici-dev/sdk/dist/index.d.ts`)
 - the five canonical authoring patterns with runnable examples
 - the anti-patterns that catch agents off-guard (no YAML, no `/dist/...` imports, no top-level `await`)
-- the local commands the agent should drive (`kici compile --check`, `kici preview`, `kici run local`, `kici docs llm`)
+- the local commands the agent should drive (`kici compile --check`, `kici preview`, `kici run <event> --local`, `kici docs llm`)
 
 If you don't want the file, pass `--no-agents-md` to `kici init`, or delete the file afterwards — KiCI never reads it at runtime.
 
@@ -516,7 +508,7 @@ If you're not sure, pick Docker / Podman.
 
 ## Looking for the laptop-only path?
 
-Both quickstarts deploy a real orchestrator + agent. If you only want to write a workflow and dry-run it on your laptop with no infrastructure, [Getting started](https://docs.kici.dev/user/getting-started/) covers `kici preview` and `kici run local` instead.
+Both quickstarts deploy a real orchestrator + agent. If you only want to write a workflow and dry-run it on your laptop with no infrastructure, [Getting started](https://docs.kici.dev/user/getting-started/) covers `kici preview` and `kici run <event> --local` instead.
 
 ---
 
@@ -714,7 +706,7 @@ Sometimes you want a workflow that does **not** fire on pushes, pull requests, t
 
 There are two ways to "explicitly invoke" a `dispatch()` workflow:
 
-1. **Locally from your laptop**, with `kici run local dispatch` — no orchestrator, no agent, no webhook, nothing deployed. This is the only path while you haven't wired the repo to a deployed KiCI orchestrator.
+1. **Locally from your laptop**, with `kici run dispatch --local` — this machine joins as an ephemeral agent through the warm local dev plane, so no orchestrator deployment is required. This is the path to use while you haven't wired the repo to a deployed KiCI orchestrator.
 2. **Remotely**, if the repo is connected to a KiCI orchestrator via a GitHub App, by calling GitHub's repository-dispatch API: `curl -X POST -H "Authorization: token <PAT>" -H "Accept: application/vnd.github+json" https://api.github.com/repos/<owner>/<repo>/dispatches -d '{"event_type":"hello"}'`. GitHub fans the webhook out to the App, the orchestrator normalizes it into a KiCI `dispatch` event (see `packages/orchestrator/src/providers/github/normalizer.ts`), and the matched workflow runs.
 
 Note that GitHub's `workflow_dispatch` event (the "Run workflow" button / `/actions/workflows/.../dispatches` API) is GitHub-Actions-internal and is **not** delivered to KiCI. The SDK has no `workflowDispatch()` trigger. Only `repository_dispatch` reaches KiCI.
@@ -737,36 +729,18 @@ export default workflow('hello-world', {
 });
 ```
 
-Run it locally, without any orchestrator or agent infrastructure:
+Run it locally, without any orchestrator deployment:
 
 ```bash
 npx kici compile           # regenerate .kici/kici.lock.json
-npx kici run local dispatch
-```
-
-`kici run local` compiles the workflow, matches triggers against a simulated `dispatch` event, and executes the matched jobs directly on your machine with DAG-based scheduling. No webhook, no GitHub, no deployed orchestrator involved. See [`kici run local`](https://docs.kici.dev/user/cli-reference/#kici-run-local) for options like `--job`, `--env`, `--json`, and `--junit`.
-
-### Scoping to a single workflow
-
-Because `kici run local dispatch` matches **every** workflow that listens for a `dispatch` event, running it in a repo with several dispatch-triggered workflows will fire all of them. Narrow execution to one with `--workflow <name>`:
-
-```bash
-npx kici run local dispatch --workflow hello-world
-```
-
-`--workflow` is a post-match filter: the workflow still has to have a trigger that matches the event argument. If `hello-world` does not list a `dispatch()` trigger, the command reports `No workflow named "hello-world" matched the event` and exits successfully without running anything.
-
-If you do not want to memorise event args, use the interactive picker instead:
-
-```bash
-npx kici run local --pick
+npx kici run dispatch --local
 ```
 
-`--pick` (aliased as `-p`) lists every workflow alongside a compact summary of its triggers, lets you select one, and derives a matching event arg from the chosen trigger — so the execution still flows through the normal trigger-matching pipeline and "cannot produce an inconsistent run". Multi-trigger workflows show a second prompt for which trigger to simulate. `--pick` is mutually exclusive with `--workflow`; in a non-TTY shell it prints the workflow list and exits without running anything.
+`kici run dispatch --local` compiles the workflow, matches triggers against a simulated `dispatch` event, and executes the matched jobs on this machine — which joins as an ephemeral agent through the warm local dev plane — with DAG-based scheduling. No webhook, no GitHub, no deployed orchestrator involved. See [`kici run <event> --local`](https://docs.kici.dev/user/cli-reference/#kici-run-event---local) for options like `--env`, `--in-place`, and `--offline`.
 
 ### Unfiltered vs typed `dispatch()`
 
-Leave `dispatch()` unfiltered while you drive it from `kici run local`. The CLI currently simulates a dispatch event with no event type (i.e. `action` is undefined), so a trigger defined as `dispatch({ types: ['deploy', 'rollback'] })` will not match `kici run local dispatch` — the typed form is intended for real `repository_dispatch` deliveries from the orchestrator.
+Leave `dispatch()` unfiltered while you drive it from `kici run <event> --local`. The CLI simulates a dispatch event with no event type (i.e. `action` is undefined), so a trigger defined as `dispatch({ types: ['deploy', 'rollback'] })` will not match `kici run dispatch --local` — the typed form is intended for real `repository_dispatch` deliveries from the orchestrator.
 
 ## Conditional execution with rules
 
@@ -2012,8 +1986,8 @@ function workflow(name: string, options: WorkflowOptions): Workflow;
 | `options.rules`       | `Rule[]`                                                               | no       | Conditions that must pass for execution                                                                                                                     |
 | `options.description` | `string`                                                               | no       | Human-readable description                                                                                                                                  |
 | `options.hashFiles`   | `string[]`                                                             | no       | Extra repo-relative paths or globs mixed into the workflow content hash. Changes invalidate the source cache.                                               |
-| `options.registries`  | `Registry[]`                                                           | no       | Private npm registries the agent authenticates against before `npm install`. Each `tokenSecret` uses qualified `<environment>:<secret>` syntax.             |
-| `options.installEnv`  | `string[]`                                                             | no       | Qualified `<environment>:<secret>` refs projected as env vars onto the install subprocess (used with a customer-committed `.kici/.npmrc`).                  |
+| `options.registries`  | `Registry[]`                                                           | no       | Private npm registries the agent authenticates against before `npm install`. Each `tokenSecret` uses qualified `<context>:<secret>` syntax.                 |
+| `options.installEnv`  | `string[]`                                                             | no       | Qualified `<context>:<secret>` refs projected as env vars onto the install subprocess (used with a customer-committed `.kici/.npmrc`).                      |
 | `options.onCancel`    | `HookInput`                                                            | no       | Runs when the workflow is cancelled                                                                                                                         |
 | `options.cleanup`     | `HookInput`                                                            | no       | Always runs after the workflow (success, failure, or cancel)                                                                                                |
 | `options.onSuccess`   | `HookInput`                                                            | no       | Runs on workflow success                                                                                                                                    |
@@ -2564,7 +2538,7 @@ step('fetch-token', {
 - **Timeout is per-attempt.** Each attempt gets the step's full `timeout` budget — a timed-out attempt counts as one failed attempt and is retried while attempts remain. The total wall-clock can therefore approach `maxAttempts * (timeout + delay)`, so keep `maxAttempts` and `maxDelayMs` sane (the job-level `timeout` still bounds the whole job).
 - **Retries exhaust before `continueOnError`.** A step with both retries first; only the _final_ failure is then softened to a warning by `continueOnError`.
 
-`retry` works identically under `kici run local` and on a remote agent, and applies to dynamically-generated job steps too. The `retryIf` predicate is an in-memory function: it is honored at execution time but never serialized into the lock file.
+`retry` works identically under `kici run <event> --local` and on a remote agent, and applies to dynamically-generated job steps too. The `retryIf` predicate is an in-memory function: it is honored at execution time but never serialized into the lock file.
 
 > **Retry vs. wait-until-condition.** `retry` re-runs a step that _throws_. To poll until a condition becomes true (a port listening, a `/health` endpoint returning 200, a unit becoming active), use [`waitForStep`](https://docs.kici.dev/user/sdk/wait-for/) instead — it is purpose-built for declarative wait-for-condition with intervals, a timeout, and on-timeout handling.
 
@@ -2650,7 +2624,7 @@ const deploy = job('deploy', {
 
 **Important:** `needs` must be declared explicitly. Output chaining does not auto-infer dependencies -- you must list job dependencies in `needs` even if you access their outputs via `.result`.
 
-Cross-job output chaining works in both local execution (`kici run local`) and remote pipeline execution. The orchestrator's needs-aware dispatch scheduler guarantees upstream jobs reach a terminal state before downstream jobs dispatch, and upstream outputs are transported to the downstream agent sandbox via the `upstreamJobOutputs` field on `job.dispatch`. See [needs-scheduler](https://docs.kici.dev/architecture/execution/needs-scheduler/) for the full dispatch semantics.
+Cross-job output chaining works in both local execution (`kici run <event> --local`) and remote pipeline execution. The orchestrator's needs-aware dispatch scheduler guarantees upstream jobs reach a terminal state before downstream jobs dispatch, and upstream outputs are transported to the downstream agent sandbox via the `upstreamJobOutputs` field on `job.dispatch`. See [needs-scheduler](https://docs.kici.dev/architecture/execution/needs-scheduler/) for the full dispatch semantics.
 
 ### Job dependencies (`needs`)
 
@@ -3391,7 +3365,7 @@ inside a fan-out job nests its concurrency inside each fan-out child.
 ## Local vs remote execution
 
 Run remotely (the orchestrator + agent), parallel children execute concurrently
-and each surfaces as its own dashboard step. `kici run local` executes the same
+and each surfaces as its own dashboard step. `kici run <event> --local` executes the same
 children in array order in its single-process model — the results are identical,
 only the wall-clock and the live fail-fast cancellation differ. Use a remote run
 to observe the concurrent timeline.
@@ -3531,7 +3505,7 @@ Every variant carries the shared `EventBase` fields — `type`, `action`, `targe
 
 Matrix configurations expand a single job into multiple instances, one per parameter combination. Maximum 256 combinations.
 
-Expansion happens at **dispatch time**: the orchestrator materializes the matrix into N execution jobs — one per combination, each dispatched to its own agent — before any job runs. Each instance receives its combination as `ctx.matrix`. This is identical whether the workflow runs via `kici run local` or remotely through a webhook trigger, and the dashboard groups the N instances under one parent node.
+Expansion happens at **dispatch time**: the orchestrator materializes the matrix into N execution jobs — one per combination, each dispatched to its own agent — before any job runs. Each instance receives its combination as `ctx.matrix`. This is identical whether the workflow runs via `kici run <event> --local` or remotely through a webhook trigger, and the dashboard groups the N instances under one parent node.
 
 ### Static array (single dimension)
 
@@ -3677,7 +3651,7 @@ step('collect', async ({ jobOutputs }) => {
 });
 ```
 
-The downstream job waits for **all** matrix combinations to terminate before it dispatches. A non-matrix upstream keeps the flat outputs shape. The envelope is identical under `kici run local` and the remote path.
+The downstream job waits for **all** matrix combinations to terminate before it dispatches. A non-matrix upstream keeps the flat outputs shape. The envelope is identical under `kici run <event> --local` and the remote path.
 
 ### Matrix type guards
 
@@ -4601,14 +4575,14 @@ verify → view journey, including how to verify a bundle with `kici verify-atte
 
 Workflows access secrets through `ctx.secrets` on `StepContext`. Use `await ctx.secrets.get('KEY')` to retrieve a value (rejects with `SecretNotFoundError` if the key is missing, fail-fast on typos), `ctx.secrets.has('KEY')` for a synchronous existence check, and `await ctx.secrets.expose('KEY')` when you need the value as a `process.env` entry for a child process.
 
-### Declaring the secret environment
+### Declaring the secret context
 
-Each job picks its secret environment via the `environment` option on `job()`. The orchestrator resolves the environment's scoped-secret store at dispatch time, evaluates access rules, and sends the decrypted secrets to the agent:
+Each job picks its secret context via the `context` option on `job()`. The orchestrator resolves the context's scoped-secret store at dispatch time, evaluates access rules, and sends the decrypted secrets to the agent:
 
 ```typescript
 const deploy = job('deploy', {
   runsOn: 'linux',
-  environment: 'production',
+  context: 'production',
   steps: [
     /* ... */
   ],
@@ -4620,11 +4594,11 @@ export default workflow('deploy', {
 });
 ```
 
-`environment` accepts either a static string or an async function `(event) => string | Promise<string>` for dynamic resolution at trigger-evaluation time. The resolved environment's secrets are flattened into `ctx.secrets`.
+`context` accepts either a static string or an async function `(event) => string | Promise<string>` for dynamic resolution at trigger-evaluation time. The resolved context's secrets are flattened into `ctx.secrets`.
 
 ### Accessing secrets (ctx.secrets)
 
-`ctx.secrets` provides flat access to the secrets resolved for the job's environment.
+`ctx.secrets` provides flat access to the secrets resolved for the job's context.
 
 ```typescript
 step('deploy', async ({ secrets }) => {
@@ -6127,7 +6101,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}`
 
@@ -6251,15 +6225,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
@@ -6292,69 +6257,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:**
-
-| Argument | Required               | Description                                      |
-| -------- | ---------------------- | ------------------------------------------------ |
-| `event`  | when `--pick` is unset | Event type (e.g., `push`, `pr:open`, `schedule`) |
+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.
 
-**Options:**
+#### kici run <event> --local
 
-| 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`)                                                                                                                                                   |
+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.
 
-**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.
@@ -6368,7 +6285,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`.
 
@@ -6378,8 +6295,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.
 
@@ -6390,32 +6306,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 workflows matching a push event on this machine
+kici run push --local
 
-# Run only a specific workflow
-kici run local push --workflow ci
+# Run a pull-request-open workflow locally
+kici run pr:open --local
 
-# Run only a specific job (and its dependencies)
-kici run local push --job test
-
-# JSON output for CI scripting
-kici run local push --json
-
-# JUnit XML for CI integration
-kici run local push --junit results.xml
-
-# Quiet mode (summary only, no streaming)
-kici run local push --quiet
+# Reuse the working tree instead of an isolated clone
+kici run push --local --in-place
 
-# 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:**
@@ -6425,20 +6332,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.
 
@@ -6446,39 +6346,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:**
@@ -6600,7 +6467,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)
 
@@ -6653,26 +6520,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
@@ -6699,7 +6546,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
 
@@ -6715,16 +6562,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                                                            |
@@ -6810,12 +6647,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
@@ -6851,14 +6682,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
@@ -6891,20 +6714,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
@@ -6916,16 +6725,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
@@ -6939,12 +6744,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
@@ -6960,10 +6759,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
 ```
@@ -6976,15 +6771,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
@@ -7005,19 +6791,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
@@ -7031,7 +6804,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
 
@@ -7041,20 +6814,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
@@ -7070,7 +6829,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.
 
@@ -7099,18 +6858,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`
@@ -7128,7 +6881,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.
@@ -7147,20 +6900,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
@@ -7189,19 +6930,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
@@ -7261,12 +6989,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
@@ -7293,12 +7015,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:**
@@ -7319,15 +7035,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
@@ -7387,12 +7094,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
@@ -7420,21 +7121,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`.
@@ -7490,194 +7176,816 @@ 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) |
 
-## Workflow discovery
+## Command reference
 
-The CLI discovers workflows by scanning `.kici/workflows/*.ts` (or `.mjs` in MJS mode). Each file should `export default` a single workflow:
+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.
 
-```typescript
-// .kici/workflows/ci.ts
-import { workflow, job, step, pr } from '@kici-dev/sdk';
+<!-- BEGIN GENERATED: kici-commands (do not edit; run the doc generator) -->
 
-export default workflow('ci', {
-  on: pr(),
-  jobs: [
-    /* ... */
-  ],
-});
-```
+### `kici admin`
 
-Multiple workflow files are supported -- each becomes a separate workflow in `kici.lock.json`.
+Operator-facing commands for running instances
 
-## Lock file
+Synopsis: `kici admin`
 
-The `kici compile` command produces `.kici/kici.lock.json` inside the `.kici` directory. This file:
+### `kici admin drain-worker`
 
-- Contains all workflow definitions in a portable JSON format
-- Is used by the orchestrator to evaluate triggers without code checkout
-- Should be committed to version control
-- Is regenerated on every `kici compile` run
+Trigger graceful drain on a worker instance
 
-Use `kici compile --check` in CI to validate that workflows are correct without writing files. For the full story on drift, pre-commit/CI, and agent-side verification, see [Lock file and workflow drift](https://docs.kici.dev/user/lock-file-and-drift/).
+Synopsis: `kici admin drain-worker [options]`
 
-## Exit codes
+**Options**
 
-All commands follow a consistent exit code convention:
+| Option        | Default | Description                                  |
+| ------------- | ------- | -------------------------------------------- |
+| `--url <url>` |         | Worker URL (e.g., http://worker-host:<port>) |
 
-| Code | Meaning              |
-| ---- | -------------------- |
-| 0    | Success              |
-| 1    | Failure (see output) |
+### `kici approve`
 
-## Debug output
+Approve a held approval gate for a run
 
-Use `--debug` (on `kici run local`, `kici run remote`, `kici preview`) or `--verbose` (on `kici compile`) for detailed output:
+Synopsis: `kici approve <run-id> [options]`
 
-```bash
-# Shows trigger matching, rule evaluation, decision traces
-kici run local push --debug
+**Arguments**
 
-# Shows detailed compilation steps
-kici compile --verbose
+| Argument | Required | Variadic | Description                           |
+| -------- | -------- | -------- | ------------------------------------- |
+| `run-id` | yes      | no       | Run ID whose approval gate to approve |
 
-# Shows trigger matching preview
-kici preview pr:open --debug
-```
+**Options**
 
-Set `KICI_DEBUG=true` for additional internal debug output across all commands.
+| Option           | Default | Description                                 |
+| ---------------- | ------- | ------------------------------------------- |
+| `--job <name>`   |         | Approve the hold for a specific job         |
+| `--step <index>` |         | Approve a step-scoped hold (requires --job) |
 
-## Environment variables
+### `kici compile`
 
-| Variable     | Description                               |
-| ------------ | ----------------------------------------- |
-| `KICI_DEV`   | Set to `true` for development mode        |
-| `KICI_DEBUG` | Set to `true` for verbose internal output |
-| `CI`         | When `true`, disables interactive prompts |
+Compile workflows from .kici/workflows/ to kici.lock.json
 
-## See also
+Synopsis: `kici compile [options]`
 
-- [Getting started](https://docs.kici.dev/user/getting-started/) -- install the SDK and write your first workflow
-- [Testing guide](https://docs.kici.dev/user/testing-guide/) -- writing fixtures, remote test runs, secret contexts, and repo state transfer
-- [SDK reference](https://docs.kici.dev/user/sdk-reference/) -- complete API for the workflow definitions that the CLI compiles
-- [Workflow patterns](https://docs.kici.dev/user/workflow-patterns/) -- example workflows to compile and test with these commands
+**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              |
 
-## Lifecycle hooks
+### `kici diagnostics`
 
-Source: https://docs.kici.dev/user/hooks/
+Show orchestrators, scalers, and agents (mirrors the dashboard Diagnostics page)
 
-Hooks are callbacks that run at specific points in the execution lifecycle. They let you react to outcomes (cancellation, success, failure) and perform cleanup without affecting the execution flow.
+Synopsis: `kici diagnostics [options]`
 
-## Hook types
+**Options**
 
-KiCI supports six hook types at three levels (step, job, workflow):
+| Option                | Default | Description                         |
+| --------------------- | ------- | ----------------------------------- |
+| `--json`              | `false` | Output raw JSON                     |
+| `--verbose`           | `false` | Show extended per-agent fields      |
+| `--orchestrator <id>` |         | Scope the tree to one connection id |
 
-| Hook         | When it runs                         | Available on        |
-| ------------ | ------------------------------------ | ------------------- |
-| `onCancel`   | After step/job/workflow is cancelled | Step, Job, Workflow |
-| `cleanup`    | Always (success, failure, or cancel) | Step, Job, Workflow |
-| `onSuccess`  | After job/workflow succeeds          | Job, Workflow       |
-| `onFailure`  | After job/workflow fails             | Job, Workflow       |
-| `beforeStep` | Before each step in a job            | Job                 |
-| `afterStep`  | After each step in a job             | Job                 |
+### `kici docs`
 
-## Basic usage
+Open the KiCI documentation site in the default browser
 
-### Job-level hooks
+Synopsis: `kici docs [options]`
 
-```typescript
-import { workflow, job, step, push } from '@kici-dev/sdk';
+**Options**
 
-export default workflow('deploy', {
-  on: push({ branches: ['main'] }),
-  jobs: [
-    job('deploy-prod', {
-      runsOn: 'linux',
-      steps: [
-        step('deploy', async ({ $ }) => {
-          await $`kubectl apply -f manifests/`;
-        }),
-      ],
-      onCancel: async (ctx) => {
-        console.log(`Deploy cancelled: ${ctx.outcome.reason}`);
-        await ctx.$`kubectl rollout undo deployment/app`;
-      },
-      cleanup: async (ctx) => {
-        // Always runs -- release lock, notify team, etc.
-        await ctx.$`curl -X POST https://slack.com/webhook -d '{"text": "Deploy ${ctx.outcome.status}"}'`;
-      },
-      onSuccess: async (ctx) => {
-        console.log(`Deploy succeeded in ${ctx.outcome.duration}ms`);
-      },
-      onFailure: async (ctx) => {
-        console.log(`Deploy failed at step: ${ctx.outcome.failedStep}`);
-      },
-      gracePeriod: 60, // 60 seconds before SIGKILL on cancel
-    }),
-  ],
-});
-```
+| Option      | Default | Description                                     |
+| ----------- | ------- | ----------------------------------------------- |
+| `--no-open` |         | Print the docs URL instead of opening a browser |
 
-### Step-level hooks
+### `kici docs llm`
 
-```typescript
-step('download-artifacts', {
-  run: async ({ $ }) => {
-    await $`wget https://artifacts.example.com/build.tar.gz`;
-  },
-  onCancel: async (ctx) => {
-    // Clean up partial downloads
-    await ctx.$`rm -f build.tar.gz`;
-  },
-  cleanup: async (ctx) => {
-    await ctx.$`rm -rf /tmp/staging`;
-  },
-});
-```
+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.
 
-### Workflow-level hooks
+Synopsis: `kici docs llm [topic] [options]`
 
-```typescript
-workflow('ci', {
-  on: push({ branches: ['main'] }),
-  jobs: [
-    /* ... */
-  ],
-  onCancel: async (ctx) => {
-    // Notify when any job in the workflow is cancelled
-    console.log('CI workflow cancelled');
-  },
-  cleanup: async (ctx) => {
-    // Always runs after all jobs complete
-    console.log(`CI workflow finished with status: ${ctx.outcome.status}`);
-  },
-});
-```
+**Arguments**
 
-## Hook context
+| Argument | Required | Variadic | Description |
+| -------- | -------- | -------- | ----------- |
+| `topic`  | no       | no       |             |
 
-Hook functions receive the same `StepContext` as regular steps (`$`, `ctx`, `log`, `env`), plus an `outcome` object with metadata about the execution result.
+**Options**
 
-### ctx.outcome
+| Option         | Default | Description                                  |
+| -------------- | ------- | -------------------------------------------- |
+| `--out <path>` |         | Write the bundle to a file instead of stdout |
 
-```typescript
-interface OutcomeMetadata {
-  /** Final status of the job/workflow. */
-  status: 'cancelled' | 'success' | 'failed';
-  /** Reason for cancellation (e.g., "User requested", "Superseded by run #42"). */
-  reason?: string;
-  /** Name of the step that caused failure (for onFailure hooks). */
-  failedStep?: string;
-  /** Outputs from all completed steps. */
-  stepOutputs: Record<string, unknown>;
-  /** Total execution duration in milliseconds. */
-  duration: number;
-}
-```
+### `kici endpoints`
 
-### Capabilities
+List all webhook entrypoints for the current project
 
-Hooks can do everything regular steps can:
+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:
+
+```typescript
+// .kici/workflows/ci.ts
+import { workflow, job, step, pr } from '@kici-dev/sdk';
+
+export default workflow('ci', {
+  on: pr(),
+  jobs: [
+    /* ... */
+  ],
+});
+```
+
+Multiple workflow files are supported -- each becomes a separate workflow in `kici.lock.json`.
+
+## Lock file
+
+The `kici compile` command produces `.kici/kici.lock.json` inside the `.kici` directory. This file:
+
+- Contains all workflow definitions in a portable JSON format
+- Is used by the orchestrator to evaluate triggers without code checkout
+- Should be committed to version control
+- Is regenerated on every `kici compile` run
+
+Use `kici compile --check` in CI to validate that workflows are correct without writing files. For the full story on drift, pre-commit/CI, and agent-side verification, see [Lock file and workflow drift](https://docs.kici.dev/user/lock-file-and-drift/).
+
+## Exit codes
+
+All commands follow a consistent exit code convention:
+
+| Code | Meaning              |
+| ---- | -------------------- |
+| 0    | Success              |
+| 1    | Failure (see output) |
+
+## Debug 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 push --local --debug
+
+# Shows detailed compilation steps
+kici compile --verbose
+
+# Shows trigger matching preview
+kici preview pr:open --debug
+```
+
+Set `KICI_DEBUG=true` for additional internal debug output across all commands.
+
+## Environment variables
+
+| Variable     | Description                               |
+| ------------ | ----------------------------------------- |
+| `KICI_DEV`   | Set to `true` for development mode        |
+| `KICI_DEBUG` | Set to `true` for verbose internal output |
+| `CI`         | When `true`, disables interactive prompts |
+
+## See also
+
+- [Getting started](https://docs.kici.dev/user/getting-started/) -- install the SDK and write your first workflow
+- [Testing guide](https://docs.kici.dev/user/testing-guide/) -- writing fixtures, remote test runs, secret contexts, and repo state transfer
+- [SDK reference](https://docs.kici.dev/user/sdk-reference/) -- complete API for the workflow definitions that the CLI compiles
+- [Workflow patterns](https://docs.kici.dev/user/workflow-patterns/) -- example workflows to compile and test with these commands
+
+---
+
+## Lifecycle hooks
+
+Source: https://docs.kici.dev/user/hooks/
+
+Hooks are callbacks that run at specific points in the execution lifecycle. They let you react to outcomes (cancellation, success, failure) and perform cleanup without affecting the execution flow.
+
+## Hook types
+
+KiCI supports six hook types at three levels (step, job, workflow):
+
+| Hook         | When it runs                         | Available on        |
+| ------------ | ------------------------------------ | ------------------- |
+| `onCancel`   | After step/job/workflow is cancelled | Step, Job, Workflow |
+| `cleanup`    | Always (success, failure, or cancel) | Step, Job, Workflow |
+| `onSuccess`  | After job/workflow succeeds          | Job, Workflow       |
+| `onFailure`  | After job/workflow fails             | Job, Workflow       |
+| `beforeStep` | Before each step in a job            | Job                 |
+| `afterStep`  | After each step in a job             | Job                 |
+
+## Basic usage
+
+### Job-level hooks
+
+```typescript
+import { workflow, job, step, push } from '@kici-dev/sdk';
+
+export default workflow('deploy', {
+  on: push({ branches: ['main'] }),
+  jobs: [
+    job('deploy-prod', {
+      runsOn: 'linux',
+      steps: [
+        step('deploy', async ({ $ }) => {
+          await $`kubectl apply -f manifests/`;
+        }),
+      ],
+      onCancel: async (ctx) => {
+        console.log(`Deploy cancelled: ${ctx.outcome.reason}`);
+        await ctx.$`kubectl rollout undo deployment/app`;
+      },
+      cleanup: async (ctx) => {
+        // Always runs -- release lock, notify team, etc.
+        await ctx.$`curl -X POST https://slack.com/webhook -d '{"text": "Deploy ${ctx.outcome.status}"}'`;
+      },
+      onSuccess: async (ctx) => {
+        console.log(`Deploy succeeded in ${ctx.outcome.duration}ms`);
+      },
+      onFailure: async (ctx) => {
+        console.log(`Deploy failed at step: ${ctx.outcome.failedStep}`);
+      },
+      gracePeriod: 60, // 60 seconds before SIGKILL on cancel
+    }),
+  ],
+});
+```
+
+### Step-level hooks
+
+```typescript
+step('download-artifacts', {
+  run: async ({ $ }) => {
+    await $`wget https://artifacts.example.com/build.tar.gz`;
+  },
+  onCancel: async (ctx) => {
+    // Clean up partial downloads
+    await ctx.$`rm -f build.tar.gz`;
+  },
+  cleanup: async (ctx) => {
+    await ctx.$`rm -rf /tmp/staging`;
+  },
+});
+```
+
+### Workflow-level hooks
+
+```typescript
+workflow('ci', {
+  on: push({ branches: ['main'] }),
+  jobs: [
+    /* ... */
+  ],
+  onCancel: async (ctx) => {
+    // Notify when any job in the workflow is cancelled
+    console.log('CI workflow cancelled');
+  },
+  cleanup: async (ctx) => {
+    // Always runs after all jobs complete
+    console.log(`CI workflow finished with status: ${ctx.outcome.status}`);
+  },
+});
+```
+
+## Hook context
+
+Hook functions receive the same `StepContext` as regular steps (`$`, `ctx`, `log`, `env`), plus an `outcome` object with metadata about the execution result.
+
+### ctx.outcome
+
+```typescript
+interface OutcomeMetadata {
+  /** Final status of the job/workflow. */
+  status: 'cancelled' | 'success' | 'failed';
+  /** Reason for cancellation (e.g., "User requested", "Superseded by run #42"). */
+  reason?: string;
+  /** Name of the step that caused failure (for onFailure hooks). */
+  failedStep?: string;
+  /** Outputs from all completed steps. */
+  stepOutputs: Record<string, unknown>;
+  /** Total execution duration in milliseconds. */
+  duration: number;
+}
+```
+
+### Capabilities
+
+Hooks can do everything regular steps can:
 
 - Run shell commands via `$`
 - Set environment variables via `ctx.setEnv()` and prepend to `PATH` via `ctx.addPath()`
@@ -7836,14 +8144,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`.                                                                                                                                                                                                                                                                     |
@@ -8071,12 +8379,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
 
@@ -8211,14 +8519,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
@@ -8227,14 +8535,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', {
@@ -8252,31 +8560,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
 
@@ -8491,7 +8799,7 @@ job('deploy', {
 });
 ```
 
-`approval: true` holds the element until **any** org member who can act on approvals signs off — anyone with the `environments:write` or `ci_trust:write` permission. Use it when you want a manual gate without restricting who may release it.
+`approval: true` holds the element until **any** org member who can act on approvals signs off — anyone with the `contexts:write` or `ci_trust:write` permission. Use it when you want a manual gate without restricting who may release it.
 
 ### Approver list (AND)
 
@@ -8612,7 +8920,7 @@ A `when: 'drift'` gate on a step without a `check` facet, or at job/workflow sco
 
 ## Mandatory vs. explicit gates
 
-`approval` is the **explicit** gate — a deliberate "pause for a human here" written by the workflow author. It composes with the **mandatory** gate an operator can attach to a protected environment via required reviewers (see [Environments](https://docs.kici.dev/user/environments/#required-reviewers)). When both apply to the same job, all clauses from both sources must be satisfied before the job is released. The two funnel into one held-element mechanism, so the dashboard queue and `kici approve` work the same way regardless of which source held the element.
+`approval` is the **explicit** gate — a deliberate "pause for a human here" written by the workflow author. It composes with the **mandatory** gate an operator can attach to a protected context via required reviewers (see [Contexts](https://docs.kici.dev/user/contexts/#required-reviewers)). When both apply to the same job, all clauses from both sources must be satisfied before the job is released. The two funnel into one held-element mechanism, so the dashboard queue and `kici approve` work the same way regardless of which source held the element.
 
 ## Approving from the CLI
 
@@ -8646,12 +8954,14 @@ kici run remote deploy-prod --approve-all
 
 `--approve-all` is **run-scoped** — it only auto-approves holds belonging to the run this invocation dispatched; there is no fleet-wide or account-wide auto-approve. Eligibility is still enforced per hold: if you are not eligible for a gate, that gate still blocks. Each auto-approved gate prints its payload before resolving and is recorded distinctly in the audit trail (`held_run.auto_approve`).
 
-You can also approve from the dashboard approval queue. See [Dashboard](https://docs.kici.dev/user/dashboard/environments-and-secrets/#approval-queue).
+`--approve-all` is honored in non-interactive runs too: with `--json` or `--quiet` (no TTY), the flag still auto-approves each eligible gate as it appears instead of hanging or printing out-of-band instructions. Hold notices are routed to stderr so `--json` stdout stays pure machine-readable output.
+
+You can also approve from the dashboard approval queue. See [Dashboard](https://docs.kici.dev/user/dashboard/contexts-and-secrets/#approval-queue).
 
 ## See also
 
 - [Idempotent steps](https://docs.kici.dev/user/idempotent-steps/) — the check/apply step facet that drift gates build on.
-- [Environments](https://docs.kici.dev/user/environments/) — operator-required reviewers on protected environments.
+- [Contexts](https://docs.kici.dev/user/contexts/) — operator-required reviewers on protected contexts.
 - [Approval gates (operator guide)](https://docs.kici.dev/operator/approvals/) — teams, the approval queue, expiry, and self-approval.
 - [Approval gates (architecture)](https://docs.kici.dev/architecture/approvals/) — the unified hold model and the step-level round-trip.
 
@@ -8713,7 +9023,7 @@ group: () => 'deploy';
 group: (ctx) => `deploy-${ctx.event.targetBranch ?? 'default'}`;
 ```
 
-The workflow-level group function is always evaluated **agent-side** at runtime -- the lock file records only that a group function exists (`hasGroup: true`), not the function itself. The agent loads the workflow source, calls the group function with `{ branch, event }`, and reports the evaluated key back to the orchestrator before step execution begins. This differs from job-level `concurrencyGroup` (see [Environments](https://docs.kici.dev/user/environments/#concurrency-groups)), where the compiler performs purity analysis and can inline pure functions for orchestrator-side evaluation.
+The workflow-level group function is always evaluated **agent-side** at runtime -- the lock file records only that a group function exists (`hasGroup: true`), not the function itself. The agent loads the workflow source, calls the group function with `{ branch, event }`, and reports the evaluated key back to the orchestrator before step execution begins. This differs from job-level `concurrencyGroup` (see [Contexts](https://docs.kici.dev/user/contexts/#concurrency-groups)), where the compiler performs purity analysis and can inline pure functions for orchestrator-side evaluation.
 
 ## cancelInProgress mode
 
@@ -8806,7 +9116,7 @@ workflow('deploy', {
   jobs: [
     job('deploy-staging', {
       runsOn: 'linux',
-      environment: 'staging',
+      context: 'staging',
       steps: [
         /* ... */
       ],
@@ -8837,284 +9147,62 @@ workflow('migrate', {
 workflow('deploy', {
   concurrency: {
     group: (ctx) => {
-      const env = ctx.branch === 'main' ? 'production' : 'staging';
-      return `deploy-${env}`;
-    },
-    cancelInProgress: true,
-  },
-  jobs: [
-    /* ... */
-  ],
-});
-```
-
-## Interaction with environment protection
-
-When a workflow has both `concurrency` and `environment` protection rules:
-
-1. Environment protection gates (required reviewers, wait timer) apply first
-2. Concurrency group check happens after protection gates pass
-3. If the run is queued by concurrency, it keeps its protection approval
-
-This means a run that passed approval won't need re-approval if it gets queued by concurrency.
-
-## Cancelling queued runs
-
-Queued runs can be cancelled before they start executing. The cancel request removes them from the queue immediately -- they don't go through the grace period since no step is running.
-
-## Job-level concurrency groups
-
-In addition to workflow-level concurrency, individual jobs can define their own concurrency group via the `concurrencyGroup` property. This controls concurrent execution at the job level rather than the workflow level. See [Environments — concurrency groups](https://docs.kici.dev/user/environments/#concurrency-groups) for details.
-
-## Local execution
-
-`kici run local` honors workflow-level `concurrency` per-machine, per-user. The `group` callback is evaluated against the simulated event identically to the remote orchestrator path; `cancelInProgress` carries the same semantics — `true` interrupts the holder via `SIGTERM` (escalating to `SIGKILL` after a grace window) and proceeds with the new run, while `false` queues the new invocation in FIFO order until the holder finishes.
-
-Coordination is local only. Running the same workflow on two different machines does not serialize across them — that requires the orchestrator. For full cross-host enforcement (queueing across agents, dashboard visibility, `max > 1`), use `kici run remote` against a deployed orchestrator.
-
-Lock files live under `$XDG_RUNTIME_DIR/kici-local-locks/` on Linux, falling back to `os.tmpdir()/kici-local-locks-<uid>/`. A workflow whose `group` callback throws aborts the run with a clear error rather than running unprotected. See [`kici run local` — Concurrency enforcement](https://docs.kici.dev/user/cli-reference/#concurrency-enforcement) for the `KICI_LOCAL_LOCK_KILL_GRACE_MS` override and the diagnostic output emitted while contending on a busy lock.
-
-The `kici run local --concurrency <n>` flag is a separate concept — it caps **job-level** parallelism within a single run (how many jobs from one workflow run at once), not cross-run serialization.
-
----
-
-_Source: `packages/sdk/src/types.ts` (WorkflowOptions.concurrency, JobOptions.concurrencyGroup)_
-
----
-
-## Dashboard
-
-Source: https://docs.kici.dev/user/dashboard/
-
-The KiCI dashboard is the browser interface for monitoring workflow runs, inspecting jobs and logs, and managing your organization. It signs in via OIDC and talks to KiCI over its API.
-
-This guide is split across the following pages:
-
-| Page                                                                                  | Covers                                                                  |
-| ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
-| [Getting started](https://docs.kici.dev/user/dashboard/getting-started/)                                     | Onboarding checklist and your organizations list                        |
-| [Navigation and layout](https://docs.kici.dev/user/dashboard/navigation/)                                    | Sidebar, mobile nav, theme, time display, shortcuts, error pages        |
-| [Runs and logs](https://docs.kici.dev/user/dashboard/runs/)                                                  | Run list, run detail, the log viewer                                    |
-| [Settings](https://docs.kici.dev/user/dashboard/settings/)                                                   | Members, roles, teams, keys, sources, billing, security, support access |
-| [Workflows, diagnostics, and orchestrators](https://docs.kici.dev/user/dashboard/workflows-and-diagnostics/) | Registered workflows, infra health, per-cluster views                   |
-| [Environments, secrets, and approvals](https://docs.kici.dev/user/dashboard/environments-and-secrets/)       | Environments, secret scopes, approval queue                             |
-| [Activity and DLQ](https://docs.kici.dev/user/dashboard/activity-and-dlq/)                                   | Forensic activity log and dead-letter queue                             |
-| [Account](https://docs.kici.dev/user/dashboard/account/)                                                     | Personal account settings                                               |
-
----
-
-## Dynamic values
-
-Source: https://docs.kici.dev/user/dynamic-values/
-
-Dynamic values let you compute `environment`, `env`, and `concurrencyGroup` at runtime based on the incoming event. Instead of hardcoding static strings, you pass a function that receives the normalized event envelope and returns the resolved value.
-
-```typescript
-job('deploy', {
-  runsOn: ['default'],
-  environment: (event) => event.targetBranch,
-  env: (event) => ({ BRANCH: event.targetBranch }),
-  concurrencyGroup: (event) => `deploy-${event.targetBranch}`,
-  steps: [
-    /* ... */
-  ],
-});
-```
-
-```typescript
-job('deploy', {
-  runsOn: 'default',
-  // One shape everywhere: branch on the normalized event type.
-  environment: (event) => (event.type === 'pull_request' ? 'preview' : 'production'),
-  steps: [
-    /* ... */
-  ],
-});
-```
-
-## How it works
-
-When you define a dynamic value as a function, the compiler analyzes it at compile time to determine whether it is **pure** (can be evaluated without cloning the repo or running an init job).
-
-### Pure functions (inline evaluation)
-
-A pure function is one that:
-
-- Is synchronous (no `async`/`await`)
-- Only references its parameters and local variables
-- Does not import or require external modules
-- Does not access globals like `process`, `fetch`, `console`, `setTimeout`, etc.
-- Uses only safe built-in constructors: `String`, `Number`, `Boolean`, `Array`, `Object`, `JSON`, `Math`, `parseInt`, `parseFloat`, `isNaN`, `isFinite`, `encodeURIComponent`, `decodeURIComponent`, `encodeURI`, `decodeURI`
-- Does not use `this`, `new`, `class`, `throw`, `try`/`catch`, `delete`, `var`, `yield`, or mutation operators (`++`, `--`, `+=`, etc.)
-
-When the compiler detects a pure function, it serializes the function source directly into the lock file as an inline expression. At dispatch time, the orchestrator evaluates the expression in a sandboxed VM context (~0ms overhead) instead of dispatching an init job.
-
-**Examples of pure functions:**
-
-```typescript
-// Simple branch extraction
-environment: (event) => event.targetBranch;
-
-// Object literal with string operations
-env: (event) => ({ BRANCH: event.targetBranch });
-
-// Concatenation with event data
-concurrencyGroup: (event) => `deploy-${event.targetBranch}`;
-
-// Using safe globals
-env: (event) => ({ UPPER: String(event.targetBranch).toUpperCase() });
-
-// Local variables are fine
-environment: (event) => {
-  const parts = event.targetBranch.split('/');
-  return parts[parts.length - 1];
-};
-```
-
-### Impure functions (init-job evaluation)
-
-If the compiler determines a function is impure, it emits a warning during compilation and falls back to the two-phase init model. This means:
-
-1. The orchestrator dispatches a special `__init__` job to a builder agent
-2. The builder agent clones the repository and evaluates the function
-3. The resolved values are sent back to the orchestrator
-4. The orchestrator dispatches the real execution job with the resolved values
-
-This adds approximately 5-10 seconds of overhead for cloning and evaluation.
-
-**Examples of impure functions (will use init job):**
-
-```typescript
-// Async functions cannot be inlined
-environment: async (event) => await lookupEnv(event.targetBranch);
-
-// External module references
-env: (event) => {
-  const config = require('./config');
-  return config.env;
-};
-
-// Process/global access
-environment: (event) => process.env.DEFAULT_ENV || 'staging';
-
-// Dynamic imports
-env: async (event) => {
-  const m = await import('./config.js');
-  return m.default;
-};
-```
-
-## Performance comparison
-
-| Evaluation path                      | Overhead | When used                                                           |
-| ------------------------------------ | -------- | ------------------------------------------------------------------- |
-| Static value (string/object literal) | ~0ms     | `environment: 'staging'`                                            |
-| Inline expression (pure function)    | ~0ms     | `environment: (event) => event.targetBranch`                        |
-| Init job (impure function)           | ~5-10s   | `environment: async (event) => await lookupEnv(event.targetBranch)` |
-
-## Tips
-
-- **Write pure functions whenever possible** to avoid the init-job delay. Most environment and env computations only need the event payload data.
-- **Check compiler warnings** -- the compiler tells you when a function is classified as impure and explains why.
-- **Runtime errors in inline expressions cause immediate job failure.** There is no fallback to the init-job path. If your pure function throws at runtime (e.g., accessing a property on `undefined`), the job fails immediately.
-- **The event parameter is the normalized event envelope** — the same shape rules receive as `ctx.event`: `{ type, action, targetBranch, sourceBranch, changedFiles, payload, … }` (see the [event payload reference](https://docs.kici.dev/user/sdk/event-payloads/) for the complete schema). Narrow on `event.type` (`'push'`, `'pull_request'`, `'tag'`, …) to branch per trigger kind. The raw provider webhook body is nested at `event.payload` (for GitHub pushes: `payload.ref`, `payload.after`, `payload.repository`, …).
-
----
-
-## Environment variables
-
-Source: https://docs.kici.dev/user/env-vars/
-
-The KiCI CLI reads the following environment variables to customize its behavior. OAuth login (`kici login` without `--token`) defaults `KICI_PLATFORM_URL`, `KICI_OIDC_ISSUER`, and `KICI_OIDC_CLIENT_ID` to the hosted KiCI Platform, so `kici login` works with no configuration. Set them only to target another KiCI environment (e.g. a testing instance) or a custom OIDC provider.
-
-## Authentication
-
-| Variable              | Description                            | Default                                      |
-| --------------------- | -------------------------------------- | -------------------------------------------- |
-| `KICI_OIDC_ISSUER`    | OIDC issuer URL for authentication     | `https://auth.kici.dev/realms/kici-internal` |
-| `KICI_OIDC_CLIENT_ID` | OIDC client ID for the CLI application | `kici-cli`                                   |
-| `KICI_PLATFORM_URL`   | Platform API base URL                  | `https://api.kici.dev`                       |
-| `KICI_CONFIG_DIR`     | Override the KiCI config directory     | `~/.kici`                                    |
-
-## Browser behavior
-
-| Variable             | Description                                                                                                                                          | Default                                                |
-| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
-| `KICI_BROWSER_CMD`   | Custom browser command for OAuth login. Supports `{url}` placeholder. Set to `none` to suppress browser opening and print the URL to stdout instead. | Uses the system default browser via the `open` package |
-| `KICI_CALLBACK_PORT` | Fixed port for the OAuth PKCE callback server. Useful when firewall rules require a known port.                                                      | Random available port                                  |
-
-## Development
-
-| Variable     | Description                                                                                                                                                                | Default |
-| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| `KICI_DEV`   | Enable development mode. When `true`, uses prerelease-compatible version ranges (`>=0.0.1-0`) for dev dependencies and skips npm version resolution.                       | unset   |
-| `KICI_DEBUG` | Enable debug logging. When `true`, prints verbose diagnostics (SDK alias resolution, step-level debug logs, stack traces on errors). Equivalent to the `--debug` CLI flag. | unset   |
-
-## Usage examples
-
-### CI/CD environment
-
-Authenticate with a pre-existing API key (no browser needed):
-
-```bash
-kici login --token <<< "$KICI_API_KEY"
+      const env = ctx.branch === 'main' ? 'production' : 'staging';
+      return `deploy-${env}`;
+    },
+    cancelInProgress: true,
+  },
+  jobs: [
+    /* ... */
+  ],
+});
 ```
 
-### Targeting another environment or custom OIDC provider
+## Interaction with context protection
 
-`kici login` targets the hosted KiCI Platform by default. To point the CLI at another KiCI environment (e.g. a testing instance) or a custom OIDC provider, override the defaults:
+When a workflow has both `concurrency` and `context` protection rules:
 
-```bash
-export KICI_OIDC_ISSUER=https://your-idp.example.com
-export KICI_OIDC_CLIENT_ID=your-client-id
-export KICI_PLATFORM_URL=https://your-platform.example.com
-kici login
-```
+1. Context protection gates (required reviewers, wait timer) apply first
+2. Concurrency group check happens after protection gates pass
+3. If the run is queued by concurrency, it keeps its protection approval
 
-### Headless SSH session
+This means a run that passed approval won't need re-approval if it gets queued by concurrency.
 
-The CLI auto-detects headless environments and uses the device flow. To force PKCE with URL output instead:
+## Cancelling queued runs
 
-```bash
-export KICI_BROWSER_CMD=none
-kici login
-```
+Queued runs can be cancelled before they start executing. The cancel request removes them from the queue immediately -- they don't go through the grace period since no step is running.
 
-This prints the authorization URL to stdout as `KICI_AUTH_URL=<url>`. Open the URL in any browser to complete authentication.
+## Job-level concurrency groups
 
-### Fixed callback port
+In addition to workflow-level concurrency, individual jobs can define their own concurrency group via the `concurrencyGroup` property. This controls concurrent execution at the job level rather than the workflow level. See [Contexts — concurrency groups](https://docs.kici.dev/user/contexts/#concurrency-groups) for details.
 
-When behind a firewall or using port forwarding:
+## Local execution
 
-```bash
-export KICI_CALLBACK_PORT=19876
-kici login
-```
+`kici run <event> --local` honors workflow-level `concurrency` per-machine, per-user. The `group` callback is evaluated against the simulated event identically to the remote orchestrator path; `cancelInProgress` carries the same semantics — `true` interrupts the holder via `SIGTERM` (escalating to `SIGKILL` after a grace window) and proceeds with the new run, while `false` queues the new invocation in FIFO order until the holder finishes.
 
-### Custom config location
+Coordination is local only. Running the same workflow on two different machines does not serialize across them — that requires the orchestrator. For full cross-host enforcement (queueing across agents, dashboard visibility, `max > 1`), use `kici run remote` against a deployed orchestrator.
 
-Store the KiCI config in a non-default location:
+Lock files live under `$XDG_RUNTIME_DIR/kici-local-locks/` on Linux, falling back to `os.tmpdir()/kici-local-locks-<uid>/`. A workflow whose `group` callback throws aborts the run with a clear error rather than running unprotected. See [`kici run <event> --local` — Concurrency enforcement](https://docs.kici.dev/user/cli-reference/#concurrency-enforcement) for the `KICI_LOCAL_LOCK_KILL_GRACE_MS` override and the diagnostic output emitted while contending on a busy lock.
 
-```bash
-export KICI_CONFIG_DIR=/tmp/kici-test
-kici login
-```
+---
+
+_Source: `packages/sdk/src/types.ts` (WorkflowOptions.concurrency, JobOptions.concurrencyGroup)_
 
 ---
 
-## Environments
+## Contexts
 
-Source: https://docs.kici.dev/user/environments/
+Source: https://docs.kici.dev/user/contexts/
 
-<!-- help:environments-list#overview -->
+<!-- help:contexts-list#overview -->
 
-Environments are named deployment targets (like staging or production) that control where your workflow jobs run. Each environment can have its own variables, secrets, and protection rules to gate deployments.
+Contexts are named deployment targets (like staging or production) that control where your workflow jobs run. Each context can have its own variables, secrets, and protection rules to gate deployments.
 
-<!-- /help:environments-list -->
+<!-- /help:contexts-list -->
 
-<!-- help:environments-protection#protection-rules -->
+<!-- help:contexts-protection#protection-rules -->
 
-Protection rules control when jobs targeting an environment can execute.
+Protection rules control when jobs targeting a context can execute.
 
 Available rules:
 
@@ -9123,24 +9211,24 @@ Available rules:
 - **Wait timers** — delay execution for a fixed period.
 - **Concurrency limits** — prevent collisions between parallel deployments.
 
-<!-- /help:environments-protection -->
+<!-- /help:contexts-protection -->
 
-Environments represent deployment targets like `staging`, `production`, or `review/PR-*`. Each environment can have its own variables, bound secrets, and protection rules that control when and how jobs targeting that environment can execute.
+Contexts represent deployment targets like `staging`, `production`, or `review/PR-*`. Each context can have its own variables, bound secrets, and protection rules that control when and how jobs targeting that context can execute.
 
 ## Overview
 
-An environment in KiCI provides:
+A context in KiCI provides:
 
 - **Variables** -- non-secret key-value configuration (e.g., `API_URL`, `CLUSTER_NAME`)
-- **Scoped secrets** -- encrypted values bound to the environment via scope bindings
+- **Scoped secrets** -- encrypted values bound to the context via scope bindings
 - **Protection rules** -- branch restrictions, required reviewers, wait timers, and concurrency limits
 - **Per-source overrides** -- repositories can override unlocked variables for their own deployments
 
 ## SDK API
 
-### Job-level environment property
+### Job-level context property
 
-The `environment` property is set on a job, not a workflow or step:
+The `context` property is set on a job, not a workflow or step:
 
 ```typescript
 import { workflow, job, step, push } from '@kici-dev/sdk';
@@ -9150,16 +9238,16 @@ export default workflow('deploy', {
   jobs: [
     job('deploy-staging', {
       runsOn: 'default',
-      environment: 'staging',
+      context: 'staging',
       steps: [
         step('deploy', async (ctx) => {
-          // ctx.environment is the resolved environment name
-          console.log(`Deploying to ${ctx.environment}`);
-          // ctx.secrets provides async get/expose/has methods for environment-bound secrets
+          // ctx.context is the resolved context name
+          console.log(`Deploying to ${ctx.context}`);
+          // ctx.secrets provides async get/expose/has methods for context-bound secrets
           const dbPassword = await ctx.secrets.get('DB_PASSWORD');
           // Environment variables are in ctx.env
           const apiUrl = ctx.env.API_URL;
-          await ctx.$`deploy --target ${ctx.environment}`;
+          await ctx.$`deploy --target ${ctx.context}`;
         }),
       ],
     }),
@@ -9167,54 +9255,54 @@ export default workflow('deploy', {
 });
 ```
 
-### Dynamic environments
+### Dynamic contexts
 
-The environment name can be a string or a function (sync or async) for dynamic environments (e.g., per-PR review environments). The function receives the normalized event envelope, with the raw provider body nested at `event.payload`:
+The context name can be a string or a function (sync or async) for dynamic contexts (e.g., per-PR review contexts). The function receives the normalized event envelope, with the raw provider body nested at `event.payload`:
 
 ```typescript
 job('deploy-review', {
   runsOn: 'default',
-  environment: (event) => `review/PR-${event.payload.pull_request.number}`,
+  context: (event) => `review/PR-${event.payload.pull_request.number}`,
   steps: [
     step('deploy', async (ctx) => {
-      // ctx.environment is 'review/PR-123' (resolved at runtime)
-      await ctx.$`deploy-preview --env ${ctx.environment}`;
+      // ctx.context is 'review/PR-123' (resolved at runtime)
+      await ctx.$`deploy-preview --env ${ctx.context}`;
     }),
   ],
 });
 ```
 
-A pure function like the one above (see [Dynamic values](https://docs.kici.dev/user/dynamic-values/)) is evaluated inline at dispatch with no init-job overhead. Dynamic environments that match a glob pattern (e.g., `review/*`) inherit the pattern's configuration, variables, and protection rules.
+A pure function like the one above (see [Dynamic values](https://docs.kici.dev/user/dynamic-values/)) is evaluated inline at dispatch with no init-job overhead. Dynamic contexts that match a glob pattern (e.g., `review/*`) inherit the pattern's configuration, variables, and protection rules.
 
-### Multiple environments per job
+### Multiple contexts per job
 
-A job can bind more than one environment with `environments`, an ordered array. This lets a single job draw secrets and variables from several environments at once — for example a shared `staging` environment plus a `my-testing` environment that carries test-only variables:
+A job can bind more than one context with `contexts`, an ordered array. This lets a single job draw secrets and variables from several contexts at once — for example a shared `staging` context plus a `my-testing` context that carries test-only variables:
 
 ```typescript
 job('deploy', {
   runsOn: 'default',
-  environments: ['staging', 'my-testing'],
+  contexts: ['staging', 'my-testing'],
   steps: [
     step('deploy', async (ctx) => {
-      // ctx.secrets and ctx.env carry the merged set from both environments
+      // ctx.secrets and ctx.env carry the merged set from both contexts
       const dbUrl = await ctx.secrets.get('DB_URL');
     }),
   ],
 });
 ```
 
-- `environment` (singular) and `environments` (array) are mutually exclusive — setting both is a compile error. `environment: 'staging'` is exactly equivalent to `environments: ['staging']`.
-- Each array entry is a static name or a function of the event, resolved per element exactly like a single dynamic environment.
+- `context` (singular) and `contexts` (array) are mutually exclusive — setting both is a compile error. `context: 'staging'` is exactly equivalent to `contexts: ['staging']`.
+- Each array entry is a static name or a function of the event, resolved per element exactly like a single dynamic context.
 
-**Merge order — last wins.** All bound environments are resolved on every dispatch (webhook, scheduled, and test runs alike) and merged in array order. When the same secret or variable key is defined in more than one environment, the later entry in the array wins. With `environments: ['staging', 'my-testing']`, a key defined in both resolves to `my-testing`'s value; keys defined in only one are preserved. The longest-scope-path-wins rule still applies _within_ each environment.
+**Merge order — last wins.** All bound contexts are resolved on every dispatch (webhook, scheduled, and test runs alike) and merged in array order. When the same secret or variable key is defined in more than one context, the later entry in the array wins. With `contexts: ['staging', 'my-testing']`, a key defined in both resolves to `my-testing`'s value; keys defined in only one are preserved. The longest-scope-path-wins rule still applies _within_ each context.
 
-**Protection rules combine all-must-pass.** A job must satisfy **every** bound environment's gates — adding an environment can never loosen access. Branch restrictions, trigger-type filters, and repo patterns must pass for all environments; the minimum trust tier is the most restrictive across them; required reviewers are the union of all environments' reviewers; the wait timer is the longest; and the hold expiry is the shortest. If a run is gated out, the rejection names which environment and which rule rejected it (visible via `kici runs show <run-id>` and the run's rejection reason), so a mutually-exclusive set of rules surfaces as a clear failure rather than a silent perpetual rejection.
+**Protection rules combine all-must-pass.** A job must satisfy **every** bound context's gates — adding a context can never loosen access. Branch restrictions, trigger-type filters, and repo patterns must pass for all contexts; the minimum trust tier is the most restrictive across them; required reviewers are the union of all contexts' reviewers; the wait timer is the longest; and the hold expiry is the shortest. If a run is gated out, the rejection names which context and which rule rejected it (visible via `kici runs show <run-id>` and the run's rejection reason), so a mutually-exclusive set of rules surfaces as a clear failure rather than a silent perpetual rejection.
 
-**Skip-on-test (allow-and-warn).** On a test or local run (`kici run remote`, `kici run local`), a bound environment never rejects the run. Any bound environment that disallows local execution (`allowLocalExecution: false`) — or that is not configured — is **skipped**: its variables and secrets are omitted from the merge and its gates are not evaluated. The run proceeds, and a user-visible warning naming the skipped environment(s) is shown both on the `kici run remote` CLI output and on the dashboard run view. This makes the test-only-variables pattern work: with `environments: ['staging', 'my-testing']` where only `my-testing` allows local execution, a test run resolves just `my-testing`'s variables and warns that `staging` was skipped. If every bound environment is skipped, the job runs with no environment variables. This is intentionally different from a fixture `secrets:` mapping, which is fail-closed — see the [testing guide](https://docs.kici.dev/user/testing-guide/).
+**Skip-on-test (allow-and-warn).** On a test or local run (`kici run remote`, `kici run <event> --local`), a bound context never rejects the run. Any bound context that disallows local execution (`allowLocalExecution: false`) — or that is not configured — is **skipped**: its variables and secrets are omitted from the merge and its gates are not evaluated. The run proceeds, and a user-visible warning naming the skipped context(s) is shown both on the `kici run remote` CLI output and on the dashboard run view. This makes the test-only-variables pattern work: with `contexts: ['staging', 'my-testing']` where only `my-testing` allows local execution, a test run resolves just `my-testing`'s variables and warns that `staging` was skipped. If every bound context is skipped, the job runs with no environment variables. This is intentionally different from a fixture `secrets:` mapping, which is fail-closed — see the [testing guide](https://docs.kici.dev/user/testing-guide/).
 
-**Unconfigured environments contribute nothing at dispatch.** At dispatch time a bound environment name with no matching configured environment (and no matching glob environment) simply adds no variables, secrets, or protection rules — the job still runs, exactly as a single dynamic environment resolving to an as-yet-unconfigured name does today.
+**Unconfigured contexts contribute nothing at dispatch.** At dispatch time a bound context name with no matching configured context (and no matching glob context) simply adds no variables, secrets, or protection rules — the job still runs, exactly as a single dynamic context resolving to an as-yet-unconfigured name does today.
 
-**Registration rejects a provably-unsatisfiable binding.** When a workflow is registered, KiCI statically checks every multi-environment binding: a bound environment that does not exist, a disabled one, or two environments with mutually-exclusive fixed branch / trigger-type / repository restrictions (no value can satisfy both) makes the binding provably unsatisfiable, and the registration is rejected with a precise message naming the job, the environments, and the rule — for example `unsatisfiable environment binding: job 'deploy' binds environments [staging, my-testing] with mutually exclusive branch restrictions (no value satisfies all bound environments)`. Bindings whose restrictions use globs are undecidable at registration and fall through to the dispatch-time gate check instead.
+**Registration rejects a provably-unsatisfiable binding.** When a workflow is registered, KiCI statically checks every multi-context binding: a bound context that does not exist, a disabled one, or two contexts with mutually-exclusive fixed branch / trigger-type / repository restrictions (no value can satisfy both) makes the binding provably unsatisfiable, and the registration is rejected with a precise message naming the job, the contexts, and the rule — for example `unsatisfiable context binding: job 'deploy' binds contexts [staging, my-testing] with mutually exclusive branch restrictions (no value satisfies all bound contexts)`. Bindings whose restrictions use globs are undecidable at registration and fall through to the dispatch-time gate check instead.
 
 ### Job-level environment variables
 
@@ -9223,7 +9311,7 @@ The `env` property on a job provides static or dynamic environment variables:
 ```typescript
 job('deploy', {
   runsOn: 'default',
-  environment: 'production',
+  context: 'production',
   env: { DEPLOY_TARGET: 'us-east-1' },
   // Or dynamic:
   // env: (event) => ({ DEPLOY_SHA: event.payload.after?.slice(0, 7) }),
@@ -9238,14 +9326,14 @@ job('deploy', {
 
 ### Concurrency groups
 
-Jobs can define their own concurrency groups to control concurrent execution within an environment. For workflow-level concurrency (which applies to all jobs in a workflow), see [Concurrency groups](https://docs.kici.dev/user/concurrency/).
+Jobs can define their own concurrency groups to control concurrent execution within a context. For workflow-level concurrency (which applies to all jobs in a workflow), see [Concurrency groups](https://docs.kici.dev/user/concurrency/).
 
-Control concurrent deployments to the same environment:
+Control concurrent deployments to the same context:
 
 ```typescript
 job('deploy', {
   runsOn: 'default',
-  environment: 'production',
+  context: 'production',
   concurrencyGroup: 'production-api',
   // Or dynamic:
   // concurrencyGroup: (event) => `review-${event.payload.pull_request.number}`,
@@ -9255,17 +9343,17 @@ job('deploy', {
 });
 ```
 
-If no `concurrencyGroup` is specified, the environment name is used as the default concurrency group. For a job bound to multiple environments, the default is the **first** bound environment's name.
+If no `concurrencyGroup` is specified, the context name is used as the default concurrency group. For a job bound to multiple contexts, the default is the **first** bound context's name.
 
 ### Step context
 
 Inside a step, the `ctx` object provides:
 
-| Property          | Type                                  | Description                                                                               |
-| ----------------- | ------------------------------------- | ----------------------------------------------------------------------------------------- |
-| `ctx.environment` | `string \| undefined`                 | Resolved environment name (undefined for jobs without environment)                        |
-| `ctx.env`         | `Record<string, string \| undefined>` | Environment variables (merged from system, org, source, and job-level `env`)              |
-| `ctx.secrets`     | `StepSecretsTyped`                    | Async accessor for bound secrets (get, expose, has, getMeta, list, mountFile, exposeFile) |
+| Property      | Type                                  | Description                                                                               |
+| ------------- | ------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `ctx.context` | `string \| undefined`                 | Resolved context name (undefined for jobs without context)                                |
+| `ctx.env`     | `Record<string, string \| undefined>` | Environment variables (merged from system, org, source, and job-level `env`)              |
+| `ctx.secrets` | `StepSecretsTyped`                    | Async accessor for bound secrets (get, expose, has, getMeta, list, mountFile, exposeFile) |
 
 | Method                                       | Returns                   | Description                                                                                                                                                        |
 | -------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -9282,25 +9370,25 @@ The full secrets API — including `SecretFileOptions`, log masking, and the can
 
 ## Environment variable merge precedence
 
-When a job targets an environment, variables are merged in this order (last wins):
+When a job targets a context, variables are merged in this order (last wins):
 
 1. **Allowed system vars** -- `PATH`, `HOME`, etc. from the agent process
 2. **Sandbox defaults** -- `FORCE_COLOR=1`
 3. **KICI\_\* system vars** -- orchestrator-generated metadata
-4. **Org-level environment vars** -- from the dashboard, managed per-environment
+4. **Org-level context vars** -- from the dashboard, managed per-context
 5. **Source-level overrides** -- per-repository overrides (skips locked vars)
 6. **Job env** -- from the `env` property in the SDK
 7. **`setEnv()` calls** -- runtime modifications within steps
 
-> **Note:** Secrets are NOT part of the environment variable merge. They are delivered to the step context via IPC and accessed through `ctx.secrets`, not through `process.env`. See the [step context](https://docs.kici.dev/user/environments/#step-context) section above.
+> **Note:** Secrets are NOT part of the environment variable merge. They are delivered to the step context via IPC and accessed through `ctx.secrets`, not through `process.env`. See the [step context](https://docs.kici.dev/user/contexts/#step-context) section above.
 
 ## Protection rules
 
-Environments can have protection rules that gate job execution:
+Contexts can have protection rules that gate job execution:
 
 ### Branch restrictions
 
-Limit which branches can deploy to an environment:
+Limit which branches can deploy to a context:
 
 ```
 Allowed branches: main, release/*
@@ -9357,7 +9445,7 @@ See the [CI security architecture docs](https://docs.kici.dev/architecture/secur
 
 ### Security approval queue
 
-When a PR is held for security review (unknown contributor, workflow modification, or trust policy violation), it enters the security approval queue. This is separate from environment-level approval queues.
+When a PR is held for security review (unknown contributor, workflow modification, or trust policy violation), it enters the security approval queue. This is separate from context-level approval queues.
 
 Held runs can be approved:
 
@@ -9368,7 +9456,7 @@ Security holds expire after a configurable timeout (default 1 hour).
 
 ### Concurrency limits
 
-Control how many jobs can run simultaneously in an environment:
+Control how many jobs can run simultaneously in a context:
 
 ```
 Concurrency limit: 1
@@ -9380,18 +9468,18 @@ Strategy: queue (or cancel-pending)
 
 ## Dashboard management
 
-### Creating environments
+### Creating contexts
 
-Navigate to **Settings > Environments** in the dashboard. Click **New environment** to choose the environment name and type (Fixed or Glob).
+Navigate to **Settings > Contexts** in the dashboard. Click **New context** to choose the context name and type (Fixed or Glob).
 
-- **Fixed** -- applies to jobs that declare exactly this environment name, like `staging` or `production`
-- **Glob** -- applies to any environment name a job declares that matches the pattern, e.g. `review/*` matches a job with `environment: 'review/PR-123'`
+- **Fixed** -- applies to jobs that declare exactly this context name, like `staging` or `production`
+- **Glob** -- applies to any context name a job declares that matches the pattern, e.g. `review/*` matches a job with `context: 'review/PR-123'`
 
-The environments list shows each environment's type, whether test runs may use it (the `allowLocalExecution` flag -- see the [testing guide](https://docs.kici.dev/user/testing-guide/)), and whether it is enabled.
+The contexts list shows each context's type, whether test runs may use it (the `allowLocalExecution` flag -- see the [testing guide](https://docs.kici.dev/user/testing-guide/)), and whether it is enabled.
 
-### Environment detail page
+### Context detail page
 
-Each environment has four tabs:
+Each context has four tabs:
 
 1. **Variables** -- manage key-value pairs with lock toggles. Locked variables cannot be overridden by source-level overrides. Source overrides are managed in a sub-tab.
 
@@ -9399,26 +9487,26 @@ Each environment has four tabs:
 
 3. **Protection** -- configure branch restrictions, required reviewers, wait timers, and concurrency limits with enable toggles for each section.
 
-4. **History** -- view filtered runs targeting this environment.
+4. **History** -- view filtered runs targeting this context.
 
-### Bound environments on runs
+### Bound contexts on runs
 
-A job's bound deployment environments are shown as chips on the run detail page (in the job metadata panel) in the order the job declared them, and the distinct set across a run's jobs appears as compact chips on the run list. For a multi-environment job the chips read left-to-right in merge order — later environments override earlier ones on key collisions. A `(dynamic)` chip marks an environment whose name is computed at runtime; it resolves to the real name once the run starts. A job that binds a single environment shows one chip; a job that binds none shows no chip.
+A job's bound deployment contexts are shown as chips on the run detail page (in the job metadata panel) in the order the job declared them, and the distinct set across a run's jobs appears as compact chips on the run list. For a multi-context job the chips read left-to-right in merge order — later contexts override earlier ones on key collisions. A `(dynamic)` chip marks a context whose name is computed at runtime; it resolves to the real name once the run starts. A job that binds a single context shows one chip; a job that binds none shows no chip.
 
-If a multi-environment binding is gated out, the run's failure banner names which environment and which rule rejected it (the same all-must-pass detail surfaced by `kici runs show <run-id>`).
+If a multi-context binding is gated out, the run's failure banner names which context and which rule rejected it (the same all-must-pass detail surfaced by `kici runs show <run-id>`).
 
 ### Secrets management
 
-Secrets are individual encrypted values organized by scope paths (e.g., `aws/prod`, `databases/postgres`). Scopes are bound to environments via bindings:
+Secrets are individual encrypted values organized by scope paths (e.g., `aws/prod`, `databases/postgres`). Scopes are bound to contexts via bindings:
 
-- **Scope-centric view** (Secrets page): tree view of scopes with per-scope environment binding checkboxes
-- **Environment-centric view** (inside environment detail): bound scopes, resolved secrets, add binding
+- **Scope-centric view** (Secrets page): tree view of scopes with per-scope context binding checkboxes
+- **Context-centric view** (inside context detail): bound scopes, resolved secrets, add binding
 
 When scope paths collide on the same key name, the longer (more specific) path wins.
 
 ## Type generation
 
-Running `kici types` generates two augmented interfaces: `KnownSecretKeys` (union of all secret keys across all environments) and `EnvironmentSecrets` (per-environment key unions):
+Running `kici types` generates two augmented interfaces: `KnownSecretKeys` (union of all secret keys across all contexts) and `ContextSecrets` (per-context key unions):
 
 ```typescript
 interface KnownSecretKeys {
@@ -9426,13 +9514,233 @@ interface KnownSecretKeys {
   API_KEY: string;
 }
 
-interface EnvironmentSecrets {
+interface ContextSecrets {
   production: 'DB_PASSWORD' | 'API_KEY';
   staging: 'DB_PASSWORD';
 }
 ```
 
-`KnownSecretKeys` narrows `ctx.secrets.get()` and `ctx.secrets.expose()` key parameters to valid key names. `EnvironmentSecrets` maps each environment to its available secret key names as a string union. Dynamic environments fall back to the full `KnownSecretKeys` union.
+`KnownSecretKeys` narrows `ctx.secrets.get()` and `ctx.secrets.expose()` key parameters to valid key names. `ContextSecrets` maps each context to its available secret key names as a string union. Dynamic contexts fall back to the full `KnownSecretKeys` union.
+
+---
+
+## Dashboard
+
+Source: https://docs.kici.dev/user/dashboard/
+
+The KiCI dashboard is the browser interface for monitoring workflow runs, inspecting jobs and logs, and managing your organization. It signs in via OIDC and talks to KiCI over its API.
+
+This guide is split across the following pages:
+
+| Page                                                                                  | Covers                                                                  |
+| ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| [Getting started](https://docs.kici.dev/user/dashboard/getting-started/)                                     | Onboarding checklist and your organizations list                        |
+| [Navigation and layout](https://docs.kici.dev/user/dashboard/navigation/)                                    | Sidebar, mobile nav, theme, time display, shortcuts, error pages        |
+| [Runs and logs](https://docs.kici.dev/user/dashboard/runs/)                                                  | Run list, run detail, the log viewer                                    |
+| [Settings](https://docs.kici.dev/user/dashboard/settings/)                                                   | Members, roles, teams, keys, sources, billing, security, support access |
+| [Workflows, diagnostics, and orchestrators](https://docs.kici.dev/user/dashboard/workflows-and-diagnostics/) | Registered workflows, infra health, per-cluster views                   |
+| [Contexts, secrets, and approvals](https://docs.kici.dev/user/dashboard/contexts-and-secrets/)               | Contexts, secret scopes, approval queue                                 |
+| [Activity and DLQ](https://docs.kici.dev/user/dashboard/activity-and-dlq/)                                   | Forensic activity log and dead-letter queue                             |
+| [Account](https://docs.kici.dev/user/dashboard/account/)                                                     | Personal account settings                                               |
+
+---
+
+## Dynamic values
+
+Source: https://docs.kici.dev/user/dynamic-values/
+
+Dynamic values let you compute `context`, `env`, and `concurrencyGroup` at runtime based on the incoming event. Instead of hardcoding static strings, you pass a function that receives the normalized event envelope and returns the resolved value.
+
+```typescript
+job('deploy', {
+  runsOn: ['default'],
+  context: (event) => event.targetBranch,
+  env: (event) => ({ BRANCH: event.targetBranch }),
+  concurrencyGroup: (event) => `deploy-${event.targetBranch}`,
+  steps: [
+    /* ... */
+  ],
+});
+```
+
+```typescript
+job('deploy', {
+  runsOn: 'default',
+  // One shape everywhere: branch on the normalized event type.
+  context: (event) => (event.type === 'pull_request' ? 'preview' : 'production'),
+  steps: [
+    /* ... */
+  ],
+});
+```
+
+## How it works
+
+When you define a dynamic value as a function, the compiler analyzes it at compile time to determine whether it is **pure** (can be evaluated without cloning the repo or running an init job).
+
+### Pure functions (inline evaluation)
+
+A pure function is one that:
+
+- Is synchronous (no `async`/`await`)
+- Only references its parameters and local variables
+- Does not import or require external modules
+- Does not access globals like `process`, `fetch`, `console`, `setTimeout`, etc.
+- Uses only safe built-in constructors: `String`, `Number`, `Boolean`, `Array`, `Object`, `JSON`, `Math`, `parseInt`, `parseFloat`, `isNaN`, `isFinite`, `encodeURIComponent`, `decodeURIComponent`, `encodeURI`, `decodeURI`
+- Does not use `this`, `new`, `class`, `throw`, `try`/`catch`, `delete`, `var`, `yield`, or mutation operators (`++`, `--`, `+=`, etc.)
+
+When the compiler detects a pure function, it serializes the function source directly into the lock file as an inline expression. At dispatch time, the orchestrator evaluates the expression in a sandboxed VM context (~0ms overhead) instead of dispatching an init job.
+
+**Examples of pure functions:**
+
+```typescript
+// Simple branch extraction
+context: (event) => event.targetBranch;
+
+// Object literal with string operations
+env: (event) => ({ BRANCH: event.targetBranch });
+
+// Concatenation with event data
+concurrencyGroup: (event) => `deploy-${event.targetBranch}`;
+
+// Using safe globals
+env: (event) => ({ UPPER: String(event.targetBranch).toUpperCase() });
+
+// Local variables are fine
+context: (event) => {
+  const parts = event.targetBranch.split('/');
+  return parts[parts.length - 1];
+};
+```
+
+### Impure functions (init-job evaluation)
+
+If the compiler determines a function is impure, it emits a warning during compilation and falls back to the two-phase init model. This means:
+
+1. The orchestrator dispatches a special `__init__` job to a builder agent
+2. The builder agent clones the repository and evaluates the function
+3. The resolved values are sent back to the orchestrator
+4. The orchestrator dispatches the real execution job with the resolved values
+
+This adds approximately 5-10 seconds of overhead for cloning and evaluation.
+
+**Examples of impure functions (will use init job):**
+
+```typescript
+// Async functions cannot be inlined
+context: async (event) => await lookupEnv(event.targetBranch);
+
+// External module references
+env: (event) => {
+  const config = require('./config');
+  return config.env;
+};
+
+// Process/global access
+context: (event) => process.env.DEFAULT_ENV || 'staging';
+
+// Dynamic imports
+env: async (event) => {
+  const m = await import('./config.js');
+  return m.default;
+};
+```
+
+## Performance comparison
+
+| Evaluation path                      | Overhead | When used                                                       |
+| ------------------------------------ | -------- | --------------------------------------------------------------- |
+| Static value (string/object literal) | ~0ms     | `context: 'staging'`                                            |
+| Inline expression (pure function)    | ~0ms     | `context: (event) => event.targetBranch`                        |
+| Init job (impure function)           | ~5-10s   | `context: async (event) => await lookupEnv(event.targetBranch)` |
+
+## Tips
+
+- **Write pure functions whenever possible** to avoid the init-job delay. Most context and env computations only need the event payload data.
+- **Check compiler warnings** -- the compiler tells you when a function is classified as impure and explains why.
+- **Runtime errors in inline expressions cause immediate job failure.** There is no fallback to the init-job path. If your pure function throws at runtime (e.g., accessing a property on `undefined`), the job fails immediately.
+- **The event parameter is the normalized event envelope** — the same shape rules receive as `ctx.event`: `{ type, action, targetBranch, sourceBranch, changedFiles, payload, … }` (see the [event payload reference](https://docs.kici.dev/user/sdk/event-payloads/) for the complete schema). Narrow on `event.type` (`'push'`, `'pull_request'`, `'tag'`, …) to branch per trigger kind. The raw provider webhook body is nested at `event.payload` (for GitHub pushes: `payload.ref`, `payload.after`, `payload.repository`, …).
+
+---
+
+## Environment variables
+
+Source: https://docs.kici.dev/user/env-vars/
+
+The KiCI CLI reads the following environment variables to customize its behavior. OAuth login (`kici login` without `--token`) defaults `KICI_PLATFORM_URL`, `KICI_OIDC_ISSUER`, and `KICI_OIDC_CLIENT_ID` to the hosted KiCI Platform, so `kici login` works with no configuration. Set them only to target another KiCI environment (e.g. a testing instance) or a custom OIDC provider.
+
+## Authentication
+
+| Variable              | Description                            | Default                                      |
+| --------------------- | -------------------------------------- | -------------------------------------------- |
+| `KICI_OIDC_ISSUER`    | OIDC issuer URL for authentication     | `https://auth.kici.dev/realms/kici-internal` |
+| `KICI_OIDC_CLIENT_ID` | OIDC client ID for the CLI application | `kici-cli`                                   |
+| `KICI_PLATFORM_URL`   | Platform API base URL                  | `https://api.kici.dev`                       |
+| `KICI_CONFIG_DIR`     | Override the KiCI config directory     | `~/.kici`                                    |
+
+## Browser behavior
+
+| Variable             | Description                                                                                                                                          | Default                                                |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| `KICI_BROWSER_CMD`   | Custom browser command for OAuth login. Supports `{url}` placeholder. Set to `none` to suppress browser opening and print the URL to stdout instead. | Uses the system default browser via the `open` package |
+| `KICI_CALLBACK_PORT` | Fixed port for the OAuth PKCE callback server. Useful when firewall rules require a known port.                                                      | Random available port                                  |
+
+## Development
+
+| Variable     | Description                                                                                                                                                                | Default |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| `KICI_DEV`   | Enable development mode. When `true`, uses prerelease-compatible version ranges (`>=0.0.1-0`) for dev dependencies and skips npm version resolution.                       | unset   |
+| `KICI_DEBUG` | Enable debug logging. When `true`, prints verbose diagnostics (SDK alias resolution, step-level debug logs, stack traces on errors). Equivalent to the `--debug` CLI flag. | unset   |
+
+## Usage examples
+
+### CI/CD environment
+
+Authenticate with a pre-existing API key (no browser needed):
+
+```bash
+kici login --token <<< "$KICI_API_KEY"
+```
+
+### Targeting another environment or custom OIDC provider
+
+`kici login` targets the hosted KiCI Platform by default. To point the CLI at another KiCI environment (e.g. a testing instance) or a custom OIDC provider, override the defaults:
+
+```bash
+export KICI_OIDC_ISSUER=https://your-idp.example.com
+export KICI_OIDC_CLIENT_ID=your-client-id
+export KICI_PLATFORM_URL=https://your-platform.example.com
+kici login
+```
+
+### Headless SSH session
+
+The CLI auto-detects headless environments and uses the device flow. To force PKCE with URL output instead:
+
+```bash
+export KICI_BROWSER_CMD=none
+kici login
+```
+
+This prints the authorization URL to stdout as `KICI_AUTH_URL=<url>`. Open the URL in any browser to complete authentication.
+
+### Fixed callback port
+
+When behind a firewall or using port forwarding:
+
+```bash
+export KICI_CALLBACK_PORT=19876
+kici login
+```
+
+### Custom config location
+
+Store the KiCI config in a non-default location:
+
+```bash
+export KICI_CONFIG_DIR=/tmp/kici-test
+kici login
+```
 
 ---
 
@@ -10027,21 +10335,19 @@ guaranteed side-effect-free.
 
 ## Running in check mode
 
-`--check` and `--fail-on-drift` work on both local and remote runs:
+`--check` and `--fail-on-drift` control drift reporting on `kici run remote`:
 
 ```bash
 # Apply (default): converge the workflow.
-kici run local push
+kici run push --local
 kici run remote my-fixture
 
 # Check: report drift, change nothing. Always exits 0.
-kici run local push --check
 kici run remote my-fixture --check
 
-# Check + fail on drift: exit non-zero (2) locally, or fail the run remotely,
-# when any step reports drift. Use this as a CI gate ("fail the build if prod
-# has drifted").
-kici run local push --check --fail-on-drift
+# Check + fail on drift: fail the run when any step reports drift. Use this as a
+# CI gate ("fail the build if prod has drifted").
+kici run remote my-fixture --check --fail-on-drift
 ```
 
 `--fail-on-drift` only modifies check mode — passing it without `--check` is an
@@ -10080,7 +10386,7 @@ The two channels (Option A and Option C) compose. If you declare both, the agent
 
 ## Option A — `registries:` block
 
-Declare the registry in your workflow file and point its `tokenSecret` at a scoped secret using the qualified `<environment>:<secret-name>` syntax. The orchestrator resolves the token at dispatch time and the agent applies it for one `npm install` only.
+Declare the registry in your workflow file and point its `tokenSecret` at a scoped secret using the qualified `<context>:<secret-name>` syntax. The orchestrator resolves the token at dispatch time and the agent applies it for one `npm install` only.
 
 ```typescript
 import { workflow, job, step, push } from '@kici-dev/sdk';
@@ -10097,7 +10403,7 @@ export default workflow('build', {
   jobs: [
     job('build', {
       runsOn: 'default',
-      environment: 'production',
+      context: 'production',
       steps: [
         step('install-and-build', async (ctx) => {
           // .kici/package.json can now reference @my-org/* packages
@@ -10113,7 +10419,7 @@ Per-field rules:
 
 - **`url`** — Must be HTTPS. HTTP is permitted only for `localhost` / `127.0.0.0/8` / `::1` / `*.local` hosts, or when an operator has flipped the org-level `allow_http_npm_registries` toggle (see [`kici-admin org-settings allow-http-npm`](https://docs.kici.dev/operator/kici-admin-cli#allow-http-npm--permit-non-https-private-npm-registries)).
 - **`scope`** — Optional. When present, the registry serves only that scope (`@my-org`). When absent, this entry becomes the **default** registry — at most one entry may omit `scope`.
-- **`tokenSecret`** — Mandatory `<environment>:<secret-name>`. The orchestrator looks up the secret in the named environment via the per-environment secret resolver. The bare name **must not** contain a colon.
+- **`tokenSecret`** — Mandatory `<context>:<secret-name>`. The orchestrator looks up the secret in the named context via the per-context secret resolver. The bare name **must not** contain a colon.
 - **`alwaysAuth`** — Defaults to `true`. Forces npm to send the token on every request (even GETs), which is what most managed-registry providers require.
 
 ### How tokens reach `npm install`
@@ -10143,14 +10449,14 @@ export default workflow('build', {
   jobs: [
     job('build', {
       runsOn: 'default',
-      environment: 'production',
+      context: 'production',
       steps: [step('build', async (ctx) => ctx.$`npm run build`)],
     }),
   ],
 });
 ```
 
-The orchestrator resolves `MY_NPM_TOKEN` from the `production` environment's secret store and seeds it as `MY_NPM_TOKEN` (bare name) in the install subprocess. Your committed `.npmrc` reads it through `${MY_NPM_TOKEN}`.
+The orchestrator resolves `MY_NPM_TOKEN` from the `production` context's secret store and seeds it as `MY_NPM_TOKEN` (bare name) in the install subprocess. Your committed `.npmrc` reads it through `${MY_NPM_TOKEN}`.
 
 This path is the right answer when:
 
@@ -10172,7 +10478,7 @@ export default workflow('build', {
   jobs: [
     job('mint-codeartifact-token', {
       runsOn: 'default',
-      environment: 'production',
+      context: 'production',
       steps: [
         step('mint', async (ctx) => {
           const awsKey = await ctx.secrets.get('AWS_ACCESS_KEY_ID');
@@ -10197,7 +10503,7 @@ export default workflow('build', {
     }),
     job('build', {
       runsOn: 'default',
-      environment: 'production',
+      context: 'production',
       needs: ['mint-codeartifact-token'],
       steps: [step('build', async (ctx) => ctx.$`npm run build`)],
     }),
@@ -10221,7 +10527,7 @@ registries: [
 ],
 ```
 
-Mint the token from a fine-grained PAT with `read:packages` scope, store it as a scoped secret in the `production` environment.
+Mint the token from a fine-grained PAT with `read:packages` scope, store it as a scoped secret in the `production` context.
 
 ### GitLab Packages
 
@@ -10276,8 +10582,8 @@ registries: [
 
 ## Security model
 
-- **Per-environment scoping.** Every `tokenSecret` and `installEnv` entry is qualified with an environment name. The orchestrator runs the same protection-rule pipeline (branch / trust / concurrency / reviewer / wait-timer) against each named environment **before** resolving any secret, so a workflow that wants a `production` token from a feature branch is rejected exactly like a job that tries to deploy to `production` from a feature branch. A reviewer-gated install environment **pauses** the whole workflow dispatch as a workflow-scoped held run instead of resolving the token — see [Reviewer-gated installs](https://docs.kici.dev/user/private-registries/#reviewer-gated-installs) below.
-- **Untrusted contributors get no tokens.** When a fork PR is dispatched and the contributor-trust resolution returns anything other than `trusted`, the orchestrator strips both `npmRegistries` and `installEnvSecrets` out of the dispatch. The install runs without auth and fails naturally on the first private dep — fork PRs cannot ever observe a registry token, even if a misconfigured environment lacks an explicit `requiredTrustTier`.
+- **Per-context scoping.** Every `tokenSecret` and `installEnv` entry is qualified with a context name. The orchestrator runs the same protection-rule pipeline (branch / trust / concurrency / reviewer / wait-timer) against each named context **before** resolving any secret, so a workflow that wants a `production` token from a feature branch is rejected exactly like a job that tries to deploy to `production` from a feature branch. A reviewer-gated install context **pauses** the whole workflow dispatch as a workflow-scoped held run instead of resolving the token — see [Reviewer-gated installs](https://docs.kici.dev/user/private-registries/#reviewer-gated-installs) below.
+- **Untrusted contributors get no tokens.** When a fork PR is dispatched and the contributor-trust resolution returns anything other than `trusted`, the orchestrator strips both `npmRegistries` and `installEnvSecrets` out of the dispatch. The install runs without auth and fails naturally on the first private dep — fork PRs cannot ever observe a registry token, even if a misconfigured context lacks an explicit `requiredTrustTier`.
 - **Lifecycle scripts disabled.** Whenever a private registry is in scope, the agent runs the install with `--ignore-scripts` (npm or pnpm alike). A malicious `preinstall` / `postinstall` hook in committed `package.json` cannot read the synthesized token env vars, even though they exist in the install subprocess. For a pnpm workspace, the agent builds your in-repo dependency closure as a separate step **after** the install's auth is torn down, so build scripts never see the tokens either.
 - **Stderr is redacted.** If the install fails, the agent masks every token literal out of the surfaced stderr / stdout chunks before logging.
 - **Job-scoped env-var names.** The synthesized auth env var is `KICI_NPM_TOKEN_<jobIdShort>_<i>` where `jobIdShort` is the first 8 chars of the dispatched job id. The name is unguessable from outside the install subprocess and not reused across jobs.
@@ -10285,12 +10591,12 @@ registries: [
 
 ## Reviewer-gated installs
 
-When the named install environment carries a protection rule that holds — a required reviewer (`hold`) or a wait timer (`wait`) — the install gate **pauses the whole workflow dispatch** instead of rejecting it. The run is created in the `held` state, no jobs are queued, and a workflow-scoped row appears on the held-runs page with a `Workflow` scope badge.
+When the named install context carries a protection rule that holds — a required reviewer (`hold`) or a wait timer (`wait`) — the install gate **pauses the whole workflow dispatch** instead of rejecting it. The run is created in the `held` state, no jobs are queued, and a workflow-scoped row appears on the held-runs page with a `Workflow` scope badge.
 
 - **Reviewer hold:** the run waits for an approver. On approval the dispatch resumes from the install gate, resolves the token, and dispatches its jobs as a normal run. On rejection the run transitions to `cancelled` — no jobs ever run.
 - **Wait timer:** the run waits out the timer and resumes automatically when it elapses.
 
-A `reject` protection outcome (for example a disabled environment or a branch the environment forbids) still fails the dispatch loudly with a clear reason, exactly as before — the orchestrator never dispatches a run with an unresolved install token.
+A `reject` protection outcome (for example a disabled context or a branch the context forbids) still fails the dispatch loudly with a clear reason, exactly as before — the orchestrator never dispatches a run with an unresolved install token.
 
 ## Limitations
 
@@ -10301,19 +10607,19 @@ A `reject` protection outcome (for example a disabled environment or a branch th
 
 The orchestrator exposes Prometheus counters and a histogram under the `kici_orch_install_secrets_*` prefix on its `/metrics` endpoint. They populate the **Install secrets resolution** Grafana dashboard and let operators graph install-secrets activity without digging through Loki.
 
-| Metric                                                        | Type      | Labels                         | What it tells you                                                                                                                                                                                                                                                                                       |
-| ------------------------------------------------------------- | --------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `kici_orch_install_secrets_decisions_total`                   | Counter   | `decision`, `reason`           | Pass / reject / hold volume. `decision=hold` (reason `held`) counts dispatches paused at a reviewer-gated install environment. Reject reasons enumerate the failure mode: `malformed_ref`, `invalid_url_scheme`, `env_not_found`, `protection_rule_block`, `missing_token`, `missing_install_env`, etc. |
-| `kici_orch_install_secrets_npm_registry_used_total`           | Counter   | `channel`, `provider`, `scope` | Per-channel + per-scope usage. `channel=registries` is Option A, `channel=install_env` is Option C. `scope=default` marks a no-scope default registry; `scope=-` marks Option C entries.                                                                                                                |
-| `kici_orch_install_secrets_contributor_stripped_total`        | Counter   | `trust_tier`                   | Number of dispatches where registry tokens were stripped because the contributor tier wasn't `trusted` (fork PRs from unknown / known contributors). Expected to be 0 in single-tenant orgs.                                                                                                            |
-| `kici_orch_install_secrets_token_resolution_duration_seconds` | Histogram | `environment`                  | Latency of per-environment secret resolution. Pathological tails (>500ms) usually mean a Vault timeout or a slow Postgres replica.                                                                                                                                                                      |
+| Metric                                                        | Type      | Labels                         | What it tells you                                                                                                                                                                                                                                                                                   |
+| ------------------------------------------------------------- | --------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `kici_orch_install_secrets_decisions_total`                   | Counter   | `decision`, `reason`           | Pass / reject / hold volume. `decision=hold` (reason `held`) counts dispatches paused at a reviewer-gated install context. Reject reasons enumerate the failure mode: `malformed_ref`, `invalid_url_scheme`, `env_not_found`, `protection_rule_block`, `missing_token`, `missing_install_env`, etc. |
+| `kici_orch_install_secrets_npm_registry_used_total`           | Counter   | `channel`, `provider`, `scope` | Per-channel + per-scope usage. `channel=registries` is Option A, `channel=install_env` is Option C. `scope=default` marks a no-scope default registry; `scope=-` marks Option C entries.                                                                                                            |
+| `kici_orch_install_secrets_contributor_stripped_total`        | Counter   | `trust_tier`                   | Number of dispatches where registry tokens were stripped because the contributor tier wasn't `trusted` (fork PRs from unknown / known contributors). Expected to be 0 in single-tenant orgs.                                                                                                        |
+| `kici_orch_install_secrets_token_resolution_duration_seconds` | Histogram | `environment`                  | Latency of per-environment secret resolution. Pathological tails (>500ms) usually mean a Vault timeout or a slow Postgres replica.                                                                                                                                                                  |
 
 The dashboard JSON lives at `infra/terraform/modules/grafana/dashboards/install-secrets.json`; if you maintain your own monitoring stack, you can import it directly.
 
 ## See also
 
-- [Secrets](https://docs.kici.dev/user/secrets/) — how to seed the `<environment>:<secret-name>` values referenced by `tokenSecret` / `installEnv`.
-- [Environments](https://docs.kici.dev/user/environments/) — protection rules (`branch_restrictions`, `requires_review`, `minimum_trust`) that the install gate inherits.
+- [Secrets](https://docs.kici.dev/user/secrets/) — how to seed the `<context>:<secret-name>` values referenced by `tokenSecret` / `installEnv`.
+- [Contexts](https://docs.kici.dev/user/contexts/) — protection rules (`branch_restrictions`, `requires_review`, `minimum_trust`) that the install gate inherits.
 - [Operator: `kici-admin org-settings`](https://docs.kici.dev/operator/kici-admin-cli#org-settings----org-level-security-policy) — the `allow_http_npm_registries` toggle and other org-scoped knobs.
 
 ---
@@ -10582,11 +10888,11 @@ KiCI provides an explicit secrets API that gives workflow steps controlled acces
 
 ## Overview
 
-Secrets are managed per-environment in the orchestrator (see [operator docs](https://docs.kici.dev/operator/orchestrator/configuration) for setup). When a job runs with an `environment` binding, the agent receives the secret keys available for that environment but does **not** inject their values into the step's process environment. Instead, steps access secrets through the `ctx.secrets` API.
+Secrets are managed per-context in the orchestrator (see [operator docs](https://docs.kici.dev/operator/orchestrator/configuration) for setup). When a job runs with a `context` binding, the agent receives the secret keys available for that context but does **not** inject their values into the step's process environment. Instead, steps access secrets through the `ctx.secrets` API.
 
 This design prevents accidental secret leakage through child processes, log output, or error messages. Only secrets you explicitly request are loaded into memory.
 
-A job can bind several environments with `environments: ['staging', 'my-testing']`; the secret keys from all bound environments are merged in array order, with a later environment's value winning on a key collision. See [Multiple environments per job](https://docs.kici.dev/user/environments/#multiple-environments-per-job).
+A job can bind several contexts with `contexts: ['staging', 'my-testing']`; the secret keys from all bound contexts are merged in array order, with a later context's value winning on a key collision. See [Multiple contexts per job](https://docs.kici.dev/user/contexts/#multiple-contexts-per-job).
 
 ## Where secret values come from
 
@@ -10654,7 +10960,7 @@ export default workflow('deploy', {
   jobs: [
     job('deploy', {
       runsOn: 'default',
-      environment: 'production',
+      context: 'production',
       steps: [
         step('deploy', async (ctx) => {
           const token = await ctx.secrets.get('DEPLOY_TOKEN');
@@ -10778,7 +11084,7 @@ export default workflow('deploy', {
   jobs: [
     job('decrypt-and-deploy', {
       runsOn: 'default',
-      environment: 'production',
+      context: 'production',
       steps: [
         step('decrypt', async (ctx) => {
           const ageKeys = ctx.secrets.list().filter((k) => k.startsWith('AGE_KEY_'));
@@ -10810,7 +11116,7 @@ export default workflow('deploy', {
   jobs: [
     job('decrypt-and-deploy', {
       runsOn: 'default',
-      environment: 'production',
+      context: 'production',
       steps: [
         step('decrypt-to-env', async (ctx) => {
           await ctx.secrets.exposeFile('SOPS_AGE_KEY_FILE', {
@@ -10889,7 +11195,9 @@ The **GitHub App** is KiCI's flagship source. A single App:
 
 1. receives `push`, `pull_request`, and related events from every repo it's installed on,
 2. clones repos with a short-lived installation token (no deploy key to manage),
-3. posts workflow / job / step Check runs back to the pull request (see
+3. posts workflow / job / step Check runs back to the commit — visible on
+   the commit view for a plain `push` and on the **Checks** tab of any pull
+   request that contains it (see
    [GitHub checks architecture](https://docs.kici.dev/architecture/webhooks/github-checks/)).
 
 You don't need an App for every scenario — if you only care about `push`
@@ -11226,6 +11534,13 @@ driven by the orchestrator's reporting module; no workflow
 configuration is required beyond installing the App with the
 `checks: write` permission.
 
+Check runs are keyed to the head commit SHA, so they surface whether or
+not a pull request exists: after a `push` you see the pass/fail directly
+on the commit (a red ✗ / green ✓ next to the SHA in GitHub's commit list
+and on the commit page), and the same checks roll up into the **Checks**
+tab of any pull request that later includes the commit. A failing run is
+therefore visible in GitHub itself without opening the KiCI dashboard.
+
 For architecture details see
 [GitHub checks architecture](https://docs.kici.dev/architecture/webhooks/github-checks/).
 
@@ -12162,7 +12477,7 @@ The working-tree overlay tarball uploads **directly** from the developer machine
 
 The run is dispatched to the developer's active organization (selected with `kici org use`, or overridden per-run). The orchestrator anchors its bound organization with a system-managed **remote source** (routing key `remote:<orgId>`) that it auto-provisions — no manual webhook source is required, so a zero-source org is immediately routable for remote runs. The Platform forces the run's routing key to `remote:<orgId>` server-side; the developer never sets a routing key. When an org has more than one connected orchestrator cluster, the CLI selects the target cluster explicitly (or relies on the per-org default), and a single connected cluster is auto-selected.
 
-Remote runs are offered by the Platform; an orchestrator with no Platform connection cannot serve them. Executing workflow steps on the developer machine with no orchestrator is the separate `kici run local` path.
+Remote runs are offered by the Platform; an orchestrator with no Platform connection cannot serve them. Executing workflow steps on the developer machine with no orchestrator is the separate `kici run <event> --local` path.
 
 ## Source and dependency caching flow
 
@@ -12833,7 +13148,7 @@ The compiler processes the workflow definition:
 
 ### Execution time (local test runner)
 
-When `kici run local` runs a workflow:
+When `kici run <event> --local` runs a workflow:
 
 1. **SDK module resolution:** The runner resolves `setStepOutputsMap` / `setJobOutputsMap` from the same `@kici-dev/sdk` module instance that the workflow uses (ensures the proxy reads from the same map)
 2. **Map injection:** Fresh `OutputsMap` and `StepRefMap` are created and injected via `setStepOutputsMap()` / `setStepRefMap()` before each job