@kici-dev/compiler 0.1.22 → 0.1.24

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

@@ -0,0 +1,2509 @@
+# KiCI CLI and authoring
+
+This bundle covers: Running the CLI: compile, test, run local/remote, auth, hooks, lock-file drift.
+
+## Drive KiCI from your coding agent
+
+Source: https://docs.kici.dev/user/ai-agents/
+
+KiCI ships a hosted **MCP server** so a coding agent (Claude Code, or any MCP
+client) can drive your CI directly: trigger runs, read a structured result,
+fetch the failing step's logs, cancel, and re-run — all under your own identity,
+org-scoped, and audited. There are no per-tool tokens to configure: point the
+agent at one URL with one credential and it's done.
+
+The MCP exposes only what you can already do yourself through the `kici` CLI and
+the dashboard. It is not a new privileged surface — every tool maps to an
+existing user-facing operation and is gated by the same permissions your role
+grants.
+
+## 1. Mint an agent token
+
+The MCP accepts **only** an agent-kind personal access token (PAT). Mint one with
+the `kici` CLI (log in first with `kici login`):
+
+```bash
+kici pat create --agent --name "claude-code"
+```
+
+The `--name` value is the **agent label**. It is recorded on every action the
+agent takes, so your audit log shows exactly which agent did what (and on whose
+behalf). The token is printed once — save it now; it cannot be retrieved later.
+
+An agent PAT inherits your permissions unchanged — it carries provenance, not
+extra authority. Powerful operator capabilities (secret rotation, agent and peer
+management, draining) are intentionally **not** exposed here.
+
+## 2. Point your coding agent at the MCP server
+
+Configure your MCP client with the KiCI MCP endpoint and the agent PAT as a
+Bearer credential. The endpoint is the hosted Platform URL plus `/api/v1/mcp`.
+
+For Claude Code, add a remote MCP server whose URL is your KiCI Platform's
+`/api/v1/mcp` and whose `Authorization` header is `Bearer <your-agent-pat>`.
+
+That's the entire setup. The agent can now call the tools below.
+
+## 3. What the agent can do
+
+**Read**
+
+- `list_runs` — recent runs in your organization.
+- `get_run` — the structured, provenance-tagged result of a run: the typed job
+  graph, per-step statuses and exit codes, durations, and a derived failure
+  category.
+- `get_step_logs` — the log lines for a specific step.
+- `list_workflows` — your registered workflows.
+
+**Drive**
+
+- `trigger_run` — run a registered workflow ("run now").
+- `rerun_run` — re-run a completed run.
+- `cancel_run` — cancel an in-progress run.
+
+If you belong to a single organization, the org is resolved automatically. If
+you belong to several, pass an `orgId` argument to any tool.
+
+## 4. Why the structured result is agent-safe
+
+`get_run` and `get_step_logs` return a machine-first shape designed for an agent
+to reason over without being misled by repository content. Every field that
+comes from your repo, a contributor, or a process's output — workflow and job
+names, refs, error messages, log lines, job outputs — is wrapped in an
+`{ untrusted: true, value: … }` envelope. KiCI-generated values (ids, statuses,
+exit codes, durations, the derived failure category) are left plain. An agent can
+keep user-controlled content out of its instruction channel by refusing to act
+on anything tagged `untrusted`.
+
+Secret values are never returned — only the names of the secret keys a step
+accessed.
+
+## 5. The audit guarantee
+
+Because the MCP accepts only an agent-kind PAT, **every action that flows through
+it is agent-attributed by construction** — there is no path that produces an
+untagged, human-looking action. Each read and each drive operation is recorded in
+your orchestrator's access log under your identity plus the agent label, so you
+always have a complete trail of what your agent did.
+
+Inspect that trail with `kici-admin access-log list --json` (or
+`kici-admin access-log show <id>` for one entry). An agent-attributed row keeps
+`actor_type` as `user` and `actor_id` as your own identity — the agent provenance
+rides in the row's actor metadata as `agentLabel` (the `--name` you minted the
+PAT with) and `agentPatId` (the token that acted). The label is also stored in a
+dedicated `agent_label` column on every such row.
+
+---
+
+## CLI authentication
+
+Source: https://docs.kici.dev/user/cli-auth/
+
+The KiCI CLI supports three authentication methods: browser-based OAuth (default), device authorization flow (for headless environments), and API key paste (for CI/CD pipelines).
+
+## Authentication methods
+
+### Browser OAuth (default)
+
+The default `kici login` flow:
+
+1. Opens your default browser to the KiCI identity provider
+2. You authenticate in the browser
+3. The CLI receives a token via localhost callback
+4. A personal access token (PAT) is created and stored locally
+
+```bash
+kici login
+```
+
+The CLI auto-detects headless environments (SSH sessions, CI runners) and switches to device flow automatically.
+
+### Device flow (headless)
+
+For environments without a browser (SSH, remote servers):
+
+```bash
+kici login --device
+```
+
+This displays a URL and a code. Open the URL on any device, enter the code, and authenticate. The CLI polls for completion.
+
+### API key paste
+
+For CI/CD pipelines and automated environments, paste an API key directly:
+
+```bash
+kici login --token kici_sk_abc123...
+```
+
+The API key (starts with `kici_sk_`) is passed directly as the flag value and stored in your local config file.
+
+## kici logout
+
+Revoke your PAT and clear local authentication:
+
+```bash
+kici logout
+```
+
+This:
+
+1. Revokes the PAT on the server (preventing further use)
+2. Clears auth fields from the local config file
+3. Preserves non-auth settings (active org, default clusters, Platform endpoint)
+
+## Organization management
+
+### List organizations
+
+```bash
+kici org list
+```
+
+Shows all organizations you belong to, with your role in each. The active organization is marked with an asterisk.
+
+### Switch active organization
+
+```bash
+kici org use <name-or-id>
+```
+
+Name matching is case-insensitive. You can also use the organization ID directly.
+
+The active organization is both the scope for org-scoped commands (`kici runs list`, `kici diagnostics`, `kici secrets list`, …) **and** the default target for `kici run remote`. After `kici login` and `kici org use <org>`, `kici run remote` dispatches to that org through the Platform — that is the complete path to a remote run. Override the target for a single run with `kici run remote --org <id>`.
+
+If an organization has more than one connected orchestrator cluster, set its default cluster once with `kici orchestrators use <name>` (list them with `kici orchestrators list`). `kici run remote` then targets that cluster unless you pass `--orchestrator <name>`. With a single connected orchestrator the cluster is selected automatically.
+
+### Show current organization
+
+```bash
+kici org current
+```
+
+Displays the currently active organization name and ID.
+
+## Auth status
+
+`kici org current` shows your current login state and active organization:
+
+```bash
+kici org current
+```
+
+It reports whether you are logged in and which organization is active. PAT
+expiry and the full list of your tokens are managed from the dashboard (see
+"Dashboard management" below).
+
+## Personal access tokens
+
+Personal access tokens (PATs) are created automatically when you log in via OAuth. You can also create and manage PATs through the dashboard.
+
+### How PATs work
+
+- **User-scoped**: PATs work across all organizations you belong to
+- **120-day default expiry**: Configurable when creating from the dashboard
+- **Named per machine**: Each login creates a PAT named after the machine hostname
+- **Permission inheritance**: PATs inherit your effective role permissions in each org
+
+### PATs vs API keys
+
+|            | Personal access tokens | API keys        |
+| ---------- | ---------------------- | --------------- |
+| Scope      | User (cross-org)       | Organization    |
+| Prefix     | `kici_pat_`            | `kici_sk_`      |
+| Created by | CLI login or dashboard | Dashboard       |
+| Expiry     | 120 days (default)     | No expiry       |
+| Use case   | Developer CLI access   | CI/CD pipelines |
+
+### Dashboard management
+
+Create, view, and revoke PATs from the dashboard:
+
+1. Click your avatar in the sidebar
+2. Select **Account settings**
+3. Navigate to the **Personal access tokens** tab
+
+From here you can:
+
+- Create PATs with custom names and expiry periods
+- View active PATs with their prefixes and expiry dates
+- Revoke PATs that are no longer needed
+
+## Reaching the Platform API directly
+
+The Platform exposes a versioned REST API under `/api/v1/*`. The same endpoints back the dashboard SPA, the `kici` CLI, and any third-party automation. There is no separate "public" surface — the dashboard's API is the API.
+
+### Base URL
+
+| Deployment  | Base URL pattern                                                          |
+| ----------- | ------------------------------------------------------------------------- |
+| KiCI Cloud  | `https://<your-platform-host>/api/v1/`                                    |
+| Self-hosted | `https://<orchestrator-host>/<deployment-slug>/api/v1/` (slug is optional |
+|             | — `KICI_BASE_PATH` may add a prefix when the Platform is reverse-proxied) |
+
+`/api/v1/*` requires authentication (see below). `/health`, `/metrics`, and `/ws` (WebSocket) sit outside that prefix and have their own access posture (`/metrics` is meant for Prometheus scrape, not public exposure).
+
+### Authentication
+
+Every request to `/api/v1/*` carries an `Authorization: Bearer <token>` header. The Platform routes on the prefix:
+
+| Prefix      | Token type                    | Created via                             | Scope            |
+| ----------- | ----------------------------- | --------------------------------------- | ---------------- |
+| `kici_pat_` | Personal access token         | `kici login` or dashboard               | User (cross-org) |
+| `kici_sk_`  | User API key                  | Dashboard → Settings → API keys         | Org              |
+| `kici_sa_`  | Service account key           | Dashboard → Settings → Service accounts | Org              |
+| (other)     | OIDC JWT or opaque OIDC token | OIDC login (browser SPA)                | User (cross-org) |
+
+JWT and opaque OIDC tokens are validated against the configured OIDC issuer (JWKS for JWTs, the issuer's UserInfo endpoint for opaque ones). All `kici_*` tokens are validated by SHA-256 hash lookup against the Platform DB. See [RBAC: authentication methods](https://docs.kici.dev/architecture/security/rbac/#authentication-methods) for the full model.
+
+> **Note:** `kici_ok_` keys are **not** for the HTTP API — they authenticate orchestrator-to-Platform WebSocket connections only. Use `kici_sk_` (or `kici_pat_`) for HTTP calls.
+
+### Permissions
+
+Tokens authenticate; RBAC authorizes. Every org-scoped route runs `orgContextMiddleware` (verifies you are a member of the target org) followed by `requirePermission(resource, level)`. The 17 resources and 5 levels are documented in [RBAC](https://docs.kici.dev/architecture/security/rbac/#permission-model). User API keys carry their own permission matrix bounded above by the creator's effective permissions; PATs inherit the user's role permissions (or are capped further by their `scopes` field).
+
+### Configurable surfaces
+
+The dashboard is a browser SPA on top of the same `/api/v1/*` surface, so anything you can configure in the dashboard you can configure over HTTP. The mounted route groups include:
+
+- **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}`
+- **Webhooks & event log:** `/orgs/:customerId/{sources,webhook-endpoints,event-log}`
+- **Diagnostics & activity:** `/orgs/:customerId/{diagnostics,activity,access-log}`
+
+The full route tree is the source of truth — every method, request schema, and response schema is enumerated server-side. There is currently no auto-generated OpenAPI spec; the typed `DashboardApiType` export is the canonical contract for TypeScript clients.
+
+### Calling the API
+
+Two short examples — adapt the base URL and token to your deployment.
+
+**curl (PAT or API key):**
+
+```bash
+TOKEN="$(grep -E '^pat=' ~/.kici/config | cut -d= -f2)"   # or paste a kici_sk_…
+ORG="<your-org-id>"
+curl -sS \
+  -H "Authorization: Bearer $TOKEN" \
+  "https://<orchestrator-host>/<deployment-slug>/api/v1/orgs/$ORG/runs?limit=5" | jq
+```
+
+**Browser console (after dashboard login):**
+
+```js
+const ns = Object.keys(localStorage).find((k) => k.startsWith('oidc.user:'));
+const { access_token } = JSON.parse(localStorage.getItem(ns));
+const res = await fetch('/<deployment-slug>/api/v1/orgs/<your-org-id>/runs?limit=5', {
+  headers: { Authorization: `Bearer ${access_token}` },
+});
+console.log(await res.json());
+```
+
+### Rate limits and body size
+
+There is currently no per-token rate limit on `/api/v1/*`. A single global body-size cap applies to webhook ingress and dashboard API requests alike.
+
+### Audit trail
+
+Every `/api/v1/*` mutation that touches tenant-plane data is recorded in the upstream tenant-plane audit log, stamped with the actor (user, API key, service account, or upstream operator on a break-glass support read). Reads on customer data go through the orchestrator over the WebSocket proxy and land in the orchestrator's `access_log` table. See [Audit log](https://docs.kici.dev/operator/security/audit-log/) for the orchestrator schema and the dashboard's "Activity" page for the federated view.
+
+## Token storage
+
+The CLI stores authentication data in `~/.kici/config` with `0600` permissions (owner read/write only). The config file contains:
+
+- PAT token
+- PAT expiry date
+- Active organization ID
+- Per-org default orchestrator clusters
+- Platform endpoint URL
+
+## Troubleshooting
+
+### Browser doesn't open
+
+If `kici login` can't open a browser:
+
+- Use `kici login --device` for the device flow
+- Or set the `KICI_BROWSER_CMD` environment variable to your browser command (e.g., `KICI_BROWSER_CMD='firefox {url}'`)
+
+### Device flow timeout
+
+The device flow has a 5-minute timeout. If it expires:
+
+- Run `kici login --device` again to get a new code
+- Ensure you're using the correct URL displayed by the CLI
+
+### Expired PAT
+
+If you see "Personal access token has expired":
+
+- Run `kici login` to create a new PAT
+- The old expired PAT is automatically superseded
+
+### "Not a member" errors
+
+If authenticated commands return 403:
+
+- Check your active org: `kici org current`
+- List available orgs: `kici org list`
+- Switch to the correct org: `kici org use <name>`
+
+### Connection refused
+
+If the CLI can't reach the server:
+
+- Verify the endpoint: check `~/.kici/config` for the correct URL
+- Test connectivity: `curl <your-platform-url>/health`
+
+---
+
+## CLI reference
+
+Source: https://docs.kici.dev/user/cli-reference/
+
+The `@kici-dev/compiler` package provides the `kici` CLI for compiling, testing, and managing workflows.
+
+## Installation
+
+```bash
+pnpm add -D @kici-dev/compiler
+```
+
+The examples use pnpm, but npm and yarn work too — `npm install -D @kici-dev/compiler` or `yarn add -D @kici-dev/compiler`.
+
+Run commands with `npx kici` or add scripts to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "kici:compile": "kici compile",
+    "kici:preview": "kici preview"
+  }
+}
+```
+
+## Commands
+
+### kici compile
+
+Compile workflows from `.kici/workflows/` to `kici.lock.json`.
+
+```bash
+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
+# Compile all workflows
+kici compile
+
+# Validate only (CI-friendly, no file writes)
+kici compile --check
+
+# Watch mode for development
+kici compile --watch
+
+# Custom .kici directory location
+kici compile --kici-dir packages/app/.kici
+
+# Verbose output for debugging
+kici compile --verbose
+```
+
+**Exit codes:**
+
+| Code | Meaning                     |
+| ---- | --------------------------- |
+| 0    | Compilation successful      |
+| 1    | Compilation failed (errors) |
+
+The `--check` flag is useful in CI pipelines and pre-commit hooks. It validates that workflows are syntactically and semantically correct without writing the lock file or any other files.
+
+**Auto-type regeneration:** When authenticated (via `kici login`), `kici compile` automatically refreshes `.kici/types/secrets.d.ts` after each successful compilation. This keeps type declarations in sync with your orchestrator's secret contexts. The type regeneration is non-blocking -- if the orchestrator is unreachable, compilation still succeeds with a warning. The `--check` flag skips type regeneration since no files are written.
+
+### 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`) |
+
+**Options:**
+
+| Option                | Default   | Description                                                                                                                                                                                                                            |
+| --------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `-p, --pick`          | `false`   | Interactively pick a workflow + trigger (see below)                                                                                                                                                                                    |
+| `--workflow <name>`   | none      | Run only the specified workflow (mutex with `--pick`)                                                                                                                                                                                  |
+| `--job <name>`        | none      | Run only the specified job (and its dependencies)                                                                                                                                                                                      |
+| `--branch <name>`     | detected  | Override detected git branch                                                                                                                                                                                                           |
+| `--sha <hash>`        | detected  | Override detected git SHA                                                                                                                                                                                                              |
+| `--payload <path>`    | none      | Path to explicit event payload JSON file                                                                                                                                                                                               |
+| `--concurrency <n>`   | CPU cores | Max parallel jobs **within one run** (job-level only). Cross-run [concurrency groups](https://docs.kici.dev/user/concurrency/) declared in `workflow({ concurrency: ... })` are enforced separately — see "Concurrency enforcement" below.                      |
+| `--keep-going`        | `false`   | Continue after job failure                                                                                                                                                                                                             |
+| `--container`         | `false`   | Use Podman container isolation                                                                                                                                                                                                         |
+| `--env <KEY=VALUE>`   | none      | Environment variable override (repeatable)                                                                                                                                                                                             |
+| `--input <KEY=VALUE>` | none      | Typed workflow-dispatch input (repeatable) — coerced + validated against the workflow's `dispatch({ inputs })` schema, exposed as `ctx.dispatchInputs` (see [triggers → typed dispatch inputs](https://docs.kici.dev/user/sdk/triggers/#typed-dispatch-inputs)) |
+| `--files <path>`      | git diff  | Override changed file paths (repeatable, default: git diff)                                                                                                                                                                            |
+| `--quiet`             | `false`   | Suppress streaming output (summary only)                                                                                                                                                                                               |
+| `--json`              | `false`   | Output structured JSON result                                                                                                                                                                                                          |
+| `--junit <path>`      | none      | Output JUnit XML result to file                                                                                                                                                                                                        |
+| `--debug`             | `false`   | Verbose internals                                                                                                                                                                                                                      |
+| `--kici-dir <path>`   | `.kici`   | Path to .kici directory                                                                                                                                                                                                                |
+| `--in-place`          | `false`   | Run against the real working directory instead of an isolated tmp checkout (see "Execution isolation" below)                                                                                                                           |
+| `--keep`              | `false`   | Always retain the isolated tmp checkout (default: keep only on failure)                                                                                                                                                                |
+| `--check`             | `false`   | Run in [check mode](https://docs.kici.dev/user/idempotent-steps/): each step reports drift instead of applying; the run still exits 0                                                                                                                           |
+| `--fail-on-drift`     | `false`   | In check mode, exit non-zero if any step reports drift (no effect without `--check`)                                                                                                                                                   |
+
+**Interactive workflow selection (`--pick` / `-p`):**
+
+When you do not remember the event arg for a workflow, pass `--pick` (or `-p`) to open an interactive picker. It lists every workflow with a compact summary of its triggers, lets you choose one, and (for multi-trigger workflows) prompts again for which trigger to simulate. The selected trigger is converted back into an event arg and fed through the normal pipeline.
+
+```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
+```
+
+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:
+
+- 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.
+- Otherwise the new invocation waits in FIFO order. A status line is printed when the wait starts and roughly every five seconds thereafter.
+- Locks live under `$XDG_RUNTIME_DIR/kici-local-locks/` on Linux, falling back to `os.tmpdir()/kici-local-locks-<uid>/` on platforms without a per-user runtime dir. Each lock file records the holder PID, hostname, workflow name, group key, and start timestamp so concurrent invocations can describe what they are waiting for.
+- Stale locks (the recorded holder PID is gone, per `process.kill(pid, 0)`) are reclaimed automatically.
+
+Coordination is local only — running the same workflow on two different machines does not serialize across them. That requires the orchestrator.
+
+The `SIGTERM`-to-`SIGKILL` grace window defaults to 30 000 ms. Override it with the `KICI_LOCAL_LOCK_KILL_GRACE_MS` environment variable (positive integer, milliseconds) when iterating on workflows that need longer to clean up on cancellation.
+
+**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.
+
+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`.
+
+The path is logged at run start (for example, `running in /tmp/kici-run-ab12cd`) so you can inspect it.
+
+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.
+
+Set the `KICI_RUN_DIR` environment variable to place the isolated checkout under a base directory other than the system temp directory.
+
+Secrets are always sourced from your real `.kici/` directory, not from the isolated checkout. Gitignored secret files (such as `.kici/.env.local` and `.kici/secrets.yaml`) are never copied into the checkout, so a step that reads a secret still gets it from the original location.
+
+Pass `--in-place` to run against the real working directory instead — useful when you explicitly want in-tree execution. `--in-place` requires no git repository; the default isolated mode does, and fails with an actionable error pointing at `--in-place` when the directory is not a git repository.
+
+**Examples:**
+
+```bash
+# Run workflows matching a push event
+kici run local push
+
+# Run only a specific workflow
+kici run local push --workflow ci
+
+# 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
+
+# Override branch and SHA
+kici run local push --branch main --sha abc1234
+
+# Environment variable overrides
+kici run local push --env NODE_ENV=test --env CI=true
+
+# Continue running other jobs after one fails
+kici run local push --keep-going
+```
+
+**Exit codes:**
+
+| Code | Meaning                 |
+| ---- | ----------------------- |
+| 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.
+
+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.
+
+```bash
+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)                                                                                                                                |
+
+**Examples:**
+
+```bash
+# List available fixtures
+kici run remote
+
+# Run a single fixture against the active org
+kici run remote push-main
+
+# Target a specific org for this run
+kici run remote push-main --org xyz789ghi012
+
+# Target a specific orchestrator cluster within the org
+kici run remote push-main --orchestrator us-east
+
+# Run all push-related fixtures
+kici run remote 'push-*'
+
+# Run everything
+kici run remote --all
+
+# Run a specific workflow directly (bypass trigger matching)
+kici run remote --workflow ci
+
+# Quiet mode -- just pass/fail
+kici run remote push-main --quiet
+
+# JSON output for scripting
+kici run remote push-main --json
+
+# Fire and forget
+kici run remote push-main --no-wait
+
+# View recent test run history
+kici run remote --history
+
+# Interactively pick which fixtures to run (multi-select)
+kici run remote --pick
+
+# Narrow runsOnAll jobs to a subset of the host roster
+kici run remote deploy --target role:web
+
+# AND-combine repeated --target values (hosts must match every selector)
+kici run remote deploy --target role:web --target dc:eu
+
+# Skip a runsOnAll job instead of failing it when the target matches no host
+kici run remote deploy --target role:gpu --target-allow-empty
+```
+
+**Interactive fixture selection (`--pick` / `-p`):**
+
+Pass `--pick` (or `-p`) to open an interactive checkbox menu of the available
+fixtures. Toggle one or more with space, confirm with enter, and the selected
+fixtures run through the normal remote pipeline (honoring `--parallel`,
+`--no-wait`, and the other run flags). Notes:
+
+- `--pick` is mutually exclusive with a fixture argument, `--all`, and
+  `--workflow`. Passing any together exits with code 2.
+- When `stdin` is not a TTY, `--pick` prints the available fixtures and exits
+  without running anything — pass a fixture name (or `--all`) in scripts.
+
+#### Host narrowing with `--target`
+
+`--target <selector>` is a runtime narrowing for `runsOnAll` jobs, analogous to
+Ansible's `--limit`. A `runsOnAll` job normally fans out to **every** roster host
+matching its predicate, one pinned execution per host. `--target` intersects that
+matched roster with a label selector, so the effective host set is
+`runsOnAll ∩ target`:
+
+- **Narrow-only.** `--target` can only _remove_ hosts from the matched set, never
+  add them. The widening dimension (OR across host groups) lives in the workflow's
+  `runsOnAll`; `--target` only subtracts.
+- **Run-global, `runsOnAll`-only.** A single `--target` applies to every
+  `runsOnAll` job in the run. Jobs pinned to a single host with `runsOn` are
+  untouched.
+- **Repeatable and AND-combined.** Each `--target` value is its own selector; a
+  host must satisfy **all** of them to survive the narrowing. Use a single value
+  for an OR-style match within one selector and repeated values for AND.
+- **Selector syntax** matches `runsOn`: an exact label (`role:web`), a glob
+  (`role:*`), or a regex (`/^box-0[1-3]$/`).
+
+When `--target` narrows a `runsOnAll` job to zero hosts, the default is to **fail**
+the run (fail-loud — a typo in the selector shouldn't silently skip work). Pass
+`--target-allow-empty` to **skip** the zeroed job instead; the job records a
+`skipped` status, and any downstream job that needs it with `when: 'on-skip'` (or
+`when: 'always'`) still runs. See [Job dependencies](https://docs.kici.dev/user/sdk/core/#job-dependencies-needs)
+for the `when` gating model.
+
+**Exit codes:**
+
+| Code | Meaning                      |
+| ---- | ---------------------------- |
+| 0    | All matched workflows passed |
+| 1    | One or more workflows failed |
+
+#### How the run is routed
+
+A remote run is dispatched to your **active organization** — the one set with `kici org use <org>`, or overridden per-run with `--org <id>`. The org is resolved in this order:
+
+1. The `--org <id>` flag, if provided.
+2. Otherwise the active org saved in your global config by `kici org use <org>`.
+3. If neither is set, the command errors and asks you to select an org with `kici org use` or pass `--org`.
+
+The orchestrator anchors the org without any manual webhook source: it auto-provisions a system-managed **remote source** (routing key `remote:<orgId>`) that maps to its bound organization, so even a zero-source org is immediately routable for remote runs. You never set a routing key for a remote run — selecting the org is enough.
+
+When an org has more than one connected orchestrator cluster, the CLI picks the target cluster in this order:
+
+1. The `--orchestrator <name>` flag, if provided.
+2. Otherwise the per-org default cluster, set with `kici orchestrators use <name>`.
+3. If the org has exactly **one** connected orchestrator, it is auto-selected.
+4. Otherwise the run errors with the list of connected clusters, and you pass `--orchestrator <name>` to choose one. Run `kici orchestrators list` to see the available cluster names.
+
+#### The two planes
+
+`kici run remote` uses two independent paths:
+
+- **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).
+
+#### Fresh repos (no GitHub remote)
+
+`kici run remote` works even if the repo has never been pushed to GitHub. When no remote is detected:
+
+- The entire repo content is uploaded (not just a diff overlay)
+- The lock file is sent inline (no GitHub API fetch)
+- Steps that use git commands will fail (no `.git` directory in the remote workspace)
+- Build cache (`__build__` jobs) is skipped for local repos
+- Environments must have `allowLocalExecution: true` to be accessible from local runs (default is `false`)
+
+Destination routing is unchanged for fresh repos: the run still goes to your active org through the Platform.
+
+For a detailed guide on writing fixtures, configuring secrets, and understanding the upload flow, see [Testing guide](https://docs.kici.dev/user/testing-guide/).
+
+#### kici orchestrators
+
+List the orchestrator clusters connected to an organization, and set the per-org default cluster used by `kici run remote`. Requires `kici login` and an active org (or pass `--org`).
+
+```bash
+kici orchestrators list [--org <id>]
+kici orchestrators use <clusterName> [--org <id>]
+```
+
+**`kici orchestrators list`** prints the org's connected orchestrator clusters, so you know what to pass to `--orchestrator` (or to `kici orchestrators use`).
+
+**`kici orchestrators use <clusterName>`** sets the default orchestrator cluster for the org, stored per-org in your global config. Subsequent `kici run remote` invocations target that cluster unless overridden with `--orchestrator`.
+
+**Examples:**
+
+```bash
+# List the active org's connected clusters
+kici orchestrators list
+
+# List a specific org's clusters
+kici orchestrators list --org xyz789ghi012
+
+# Set the default cluster for the active org
+kici orchestrators use us-east
+
+# Set the default cluster for a specific org
+kici orchestrators use us-east --org xyz789ghi012
+```
+
+### kici preview
+
+Preview which workflows match a trigger event (dry-run, no execution). Useful for verifying trigger configurations during development.
+
+```bash
+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
+# Preview which workflows match a push event
+kici preview push
+
+# Preview PR trigger matching
+kici preview pr:open
+
+# Preview with branch override
+kici preview push --branch develop
+
+# Filter to specific workflow
+kici preview push --workflow ci
+
+# Simulate changed files for path-filtered triggers
+kici preview push --files src/index.ts --files README.md
+```
+
+**Exit codes:**
+
+| Code | Meaning                                    |
+| ---- | ------------------------------------------ |
+| 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>`.
+
+### kici login
+
+Authenticate with KiCI via browser-based OAuth (default) or API key (`--token`).
+
+By default, `kici login` opens your browser for OIDC authentication using PKCE. In headless environments (SSH, CI, containers), it automatically switches to the RFC 8628 device authorization flow where you visit a URL and enter a code.
+
+After OAuth, the CLI exchanges the OIDC token for a personal access token (PAT) stored in the config directory (`~/.kici/config` by default, overridable with `KICI_CONFIG_DIR`).
+
+`kici login` targets the hosted KiCI Platform by default. To authenticate against another environment (a self-hosted Platform, for example), pass `--platform-endpoint` / `--oidc-issuer` or set `KICI_PLATFORM_URL` / `KICI_OIDC_ISSUER`. Login persists the platform endpoint and OIDC issuer it authenticated against alongside the PAT, so a saved PAT always matches its endpoint. Because the config describes one environment at a time, **switching the endpoint resets the active organization and default clusters** — re-run `kici org use <name>` after switching environments.
+
+```bash
+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                                                            |
+| --------------------- | -------------------------------------------- | ---------------------------------------------------------------------- |
+| `KICI_PLATFORM_URL`   | `https://api.kici.dev`                       | Platform API base URL (override for a self-hosted Platform)            |
+| `KICI_OIDC_ISSUER`    | `https://auth.kici.dev/realms/kici-internal` | OIDC issuer URL (override for a self-hosted Platform)                  |
+| `KICI_OIDC_CLIENT_ID` | `kici-cli`                                   | OIDC client ID (override for a self-hosted Platform)                   |
+| `KICI_BROWSER_CMD`    | uses `open` package                          | Custom browser command with `{url}` placeholder, or `none` to suppress |
+| `KICI_CALLBACK_PORT`  | random                                       | Fixed port for OAuth PKCE callback server                              |
+| `KICI_CONFIG_DIR`     | `~/.kici`                                    | Override config directory                                              |
+
+**Examples:**
+
+```bash
+# Browser-based OAuth login (default)
+kici login
+
+# Force device flow (for SSH/headless)
+kici login --device
+
+# Legacy API key login
+kici login --token kici_sk_abc123...
+
+# Log in against a self-hosted Platform
+kici login --platform-endpoint https://platform.example.com \
+  --oidc-issuer https://auth.example.com/realms/kici-internal
+
+# Suppress browser opening (print authorize URL to stdout)
+KICI_BROWSER_CMD=none kici login
+
+# Use custom browser command
+KICI_BROWSER_CMD='firefox {url}' kici login
+
+# Fixed callback port and custom config directory
+KICI_CALLBACK_PORT=19876 KICI_CONFIG_DIR=/tmp/kici-test kici login
+```
+
+**Headless detection:** The CLI automatically detects headless environments by checking for `SSH_CLIENT`, `SSH_TTY`, `CI`, `GITHUB_ACTIONS`, `GITLAB_CI`, `container`, or `DOCKER_CONTAINER` env vars, and on Linux, the absence of `DISPLAY` and `WAYLAND_DISPLAY`.
+
+### kici logout
+
+Revoke your personal access token on the server and clear local credentials.
+
+If the server is unreachable, local credentials are still cleared (the PAT will expire automatically). Non-auth config fields (active org, default clusters, etc.) are preserved.
+
+```bash
+kici logout
+```
+
+**Examples:**
+
+```bash
+# Log out and revoke PAT
+kici logout
+```
+
+### kici org
+
+Manage organization context. Requires a PAT (run `kici login` first).
+
+#### kici org list
+
+List organizations you belong to. The active org is marked with a star (`*`).
+
+```bash
+kici org list
+```
+
+**Example output:**
+
+```
+Organizations:
+
+  * Personal          (owner)  abc123def456
+    My team           (admin)  xyz789ghi012
+```
+
+#### kici org use
+
+Switch the active organization by name (case-insensitive) or ID.
+
+```bash
+kici org use <name>
+```
+
+**Arguments:**
+
+| Argument | Required | Description             |
+| -------- | -------- | ----------------------- |
+| `name`   | yes      | Organization name or ID |
+
+**Examples:**
+
+```bash
+# Switch by name
+kici org use "My team"
+
+# Switch by ID
+kici org use xyz789ghi012
+```
+
+#### kici org current
+
+Show the current active organization.
+
+```bash
+kici org current
+```
+
+### kici diagnostics
+
+Show the orchestrators, scalers, and agents serving your organization — the
+terminal equivalent of the dashboard Diagnostics page. Reads the same
+org-scoped data the dashboard does, so it needs `kici login` and an active org
+(`kici org use <name>`).
+
+The output has three parts: a one-line header (runs in the last 24h, success
+rate, average duration, queued/running job counts), any infrastructure alerts
+(only shown when present), and a tree of each orchestrator with its scalers and
+agents. Each agent line shows its labels, platform/architecture, active/maximum
+concurrency, and heartbeat age.
+
+```bash
+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
+# Show the full infrastructure tree
+kici diagnostics
+
+# Extended per-agent detail
+kici diagnostics --verbose
+
+# Only one orchestrator's scalers and agents
+kici diagnostics --orchestrator conn-abc123
+
+# Machine-readable output
+kici diagnostics --json
+```
+
+### kici runs
+
+Inspect and manage execution runs from the terminal — the equivalent of the
+dashboard Runs page. All `kici runs` subcommands read/write the same org-scoped
+data as the dashboard, so they require `kici login` and an active org
+(`kici org use <name>`).
+
+#### kici runs list
+
+List runs with optional filters. Output is a table (run id, workflow, status,
+branch, trigger, started, duration); pagination is reported at the bottom.
+
+```bash
+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
+kici runs list --workflow ci --branch main
+kici runs list --json | jq '.runs[].runId'
+```
+
+#### kici runs show
+
+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.
+
+```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
+```
+
+#### kici runs logs
+
+Print each job/step's log lines in order, with headers.
+
+```bash
+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
+kici runs logs abc123 --follow
+```
+
+#### kici runs rerun
+
+Re-trigger a completed run. Prints the new run id. The server enforces a short
+cooldown between reruns of the same run.
+
+```bash
+kici runs rerun <run-id> [options]
+```
+
+| Option   | Default | Description                  |
+| -------- | ------- | ---------------------------- |
+| `--json` | `false` | Machine-readable JSON output |
+
+```bash
+kici runs rerun abc123
+```
+
+#### kici runs cancel
+
+Cancel a single run, or all in-progress runs on a branch.
+
+```bash
+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
+kici runs cancel --branch feature/wip
+```
+
+When `--json` is set on any of these commands, `kici` emits only the JSON
+document on stdout — the `kici v<version>` banner is suppressed — so the output
+is safe to pipe into `jq` or `JSON.parse`. The same holds for the other
+`--json` commands (`kici run remote --json`, `kici workflows list --json`) and
+for `--quiet`.
+
+### kici approve
+
+Approve a held [approval gate](https://docs.kici.dev/user/approvals/) so the run resumes. Identify the held element by run ID, optionally narrowed to a job and step.
+
+```bash
+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
+# Approve a workflow-level hold
+kici approve abc123
+
+# Approve a held job
+kici approve abc123 --job deploy-production
+
+# Approve a held step (steps are addressed by index)
+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.
+
+### kici reject
+
+Reject a held [approval gate](https://docs.kici.dev/user/approvals/). A rejection fails the held element and the run. A reason is required.
+
+```bash
+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
+# Reject a held job with a reason
+kici reject abc123 --job deploy-production --reason "Wrong release branch"
+```
+
+### kici secrets list
+
+List secret contexts available for test runs. Shows context names and key names (not values).
+
+```bash
+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.
+
+Only key names are shown — secret values are never returned over this endpoint.
+
+**Prerequisites:** authenticate via `kici login` and select an active organization with `kici org use <name>`.
+
+### kici pat create
+
+Mint a personal access token under your own identity. Pass `--agent` to mint an
+**agent-kind** PAT — the credential a coding agent points the KiCI MCP server at.
+
+```bash
+kici pat create --agent --name "claude-code"
+```
+
+- `--agent` marks the token as agent-kind. An agent PAT inherits your
+  permissions unchanged (it carries provenance, not extra authority) and is the
+  **only** credential the MCP server accepts.
+- `--name <label>` sets the token name. For an agent PAT this is the **agent
+  label** recorded on every action the agent takes — required with `--agent`.
+- `--expires-in-days <n>` overrides the default expiry.
+
+The token is printed once — save it immediately; it cannot be retrieved later.
+See [Drive KiCI from your coding agent](https://docs.kici.dev/user/ai-agents/) for the full setup.
+
+**Prerequisites:** authenticate via `kici login` first.
+
+### 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.
+
+```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`
+
+**Examples:**
+
+```bash
+# Generate types from orchestrator
+kici types
+
+# Use custom .kici directory
+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
+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.
+
+**Git workflow:** Commit the generated `.kici/types/secrets.d.ts` so team members get type checking without needing orchestrator access. Run `kici types` to refresh when environments change.
+
+**Auto-regeneration:** `kici compile` automatically runs `kici types` after successful compilation when authenticated. See the [kici compile](https://docs.kici.dev/user/cli-reference/#kici-compile) section for details.
+
+**Escape hatch:** For dynamic keys not in the generated types, use a cast: `(ctx.secrets as any).DYNAMIC_KEY`.
+
+### kici fixture
+
+Generate a fixture template for an event type. Useful for creating custom test payloads.
+
+```bash
+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
+# Print fixture to stdout
+kici fixture pr:open
+
+# Write fixture to file
+kici fixture pr:open --output fixtures/pr-open.json
+
+# Generate push fixture
+kici fixture push --output fixtures/push.json
+```
+
+Use generated fixtures as reference when writing test fixture files in `.kici/tests/`:
+
+```bash
+kici fixture pr:open --output fixtures/pr-open-reference.json
+# Use the generated JSON as reference when writing .kici/tests/pr-open.ts
+```
+
+### kici init
+
+Initialize a `.kici/` directory with default workflow templates.
+
+```bash
+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
+# Interactive initialization
+kici init
+
+# Overwrite existing setup
+kici init --force
+
+# Skip dependency install (faster, install manually later)
+kici init --skip-install
+
+# Force a specific package manager (default: detect from your repo)
+kici init --package-manager pnpm
+
+# JavaScript mode (no TypeScript)
+kici init --mjs
+
+# Skip writing the AGENTS.md LLM authoring context file
+kici init --no-agents-md
+
+# Scaffold a workflow registries entry for a private npm registry
+kici init --private-registry https://npm.pkg.github.com/ \
+          --private-registry-scope @my-org \
+          --private-registry-secret production:GITHUB_PACKAGES_TOKEN
+```
+
+**What it creates:**
+
+```
+.kici/
+  workflows/
+    hello-world.ts    # Minimal push workflow
+    pr-checks.ts      # Comprehensive PR workflow
+  tests/
+    push-test.ts      # Sample test fixture
+  types/              # Directory for generated type declarations (kici types)
+  package.json        # Dependencies (@kici-dev/sdk)
+  tsconfig.json       # TypeScript configuration (includes types/**/*.d.ts)
+.kiciignore           # Default exclusion patterns for test uploads
+```
+
+In interactive mode (TTY), `kici init` prompts you to:
+
+1. Select which workflow templates to include
+2. Optionally install a pre-commit hook
+
+**Package manager:** the dependency install step uses the package manager detected for your repo — the `packageManager` field in the nearest `package.json` (Corepack convention), then a lockfile in the project root (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `package-lock.json` → npm), then the package manager that invoked `kici` (`pnpm dlx` / `yarn dlx` / `npx`), defaulting to npm. Pass `--package-manager <npm|pnpm|yarn>` to override detection, or `--skip-install` to set up the files and install later yourself.
+
+**Development mode:** When `KICI_DEV=true` or `package.json` has `"kici": { "development": true }`, the generated `package.json` uses prerelease-compatible version ranges (`>=0.0.1-0`) so npm resolves Verdaccio's prerelease builds.
+
+### kici hook install
+
+Install a pre-commit hook that runs `kici compile` before each commit.
+
+```bash
+kici hook install [options]
+```
+
+**Options:**
+
+| Option  | Default | Description                                |
+| ------- | ------- | ------------------------------------------ |
+| `--git` | `false` | Use raw git hook (`.git/hooks/pre-commit`) |
+
+**Examples:**
+
+```bash
+# Auto-detect hook tool (husky, lint-staged, etc.)
+kici hook install
+
+# Force raw git hook
+kici hook install --git
+```
+
+The command auto-detects existing hook tools in your project:
+
+- **Husky**: Adds to `.husky/pre-commit`
+- **lint-staged**: Adds to lint-staged configuration
+- **Raw git**: Writes `.git/hooks/pre-commit`
+
+If multiple tools are detected, you are prompted to choose.
+
+### kici endpoints
+
+List all webhook entrypoints for the current project. Reads the compiled lock file and displays webhook URLs grouped by type (git provider, generic webhooks, scheduled, event-driven).
+
+```bash
+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:**
+
+```bash
+# List all webhook entrypoints
+kici endpoints
+
+# Custom .kici directory
+kici endpoints --kici-dir packages/app/.kici
+```
+
+### kici workflows list
+
+List permanently registered workflows on the orchestrator.
+
+```bash
+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
+# List all registered workflows
+kici workflows list
+
+# JSON output for scripting
+kici workflows list --json
+
+# Show workflows not updated in 30 days
+kici workflows list --stale 30d
+
+# Filter by trigger type
+kici workflows list --trigger-type push
+
+# Filter by repository
+kici workflows list --repo my-org/my-repo
+```
+
+### kici docs
+
+Open the KiCI documentation site in the default browser. With the `llm` subcommand, print the LLM-friendly documentation bundle that ships with `@kici-dev/compiler` — pipe it into a coding agent's context buffer to brief the agent on authoring conventions without an internet round-trip.
+
+```bash
+kici docs               # open https://kici.dev/docs/
+kici docs --no-open     # print the URL instead of opening a browser
+kici docs llm           # print the llms.txt index (a router over the task bundles)
+kici docs llm sdk       # print the SDK task bundle
+kici docs llm full      # print llms-full.txt (every page in one file)
+kici docs llm sdk --out sdk-context.md   # write a bundle to a file
+```
+
+**Examples:**
+
+```bash
+# Open the docs site in your browser
+kici docs
+
+# Pipe just the SDK bundle into a coding agent (small, task-scoped context)
+kici docs llm sdk | claude -- "Read this and help me author a deploy workflow"
+
+# Save the router index for offline reference
+kici docs llm --out kici-llms-index.txt
+```
+
+Bundles are regenerated from `docs/` every time `@kici-dev/compiler` is built, so they always match your installed CLI version. The index lists each task bundle — `getting-started`, `sdk`, `cli`, `patterns`, `features`, `providers`, `architecture` — with its size and a one-line purpose; pass the bundle id as the topic. Every cross-reference link inside a bundle is an absolute `docs.kici.dev` URL. The same files are published online following the [llms.txt convention](https://llmstxt.org/).
+
+### kici admin
+
+Operator-facing commands for running instances.
+
+#### kici admin drain-worker
+
+Trigger graceful drain on a worker instance. Sends a POST request to the worker's `/drain` endpoint.
+
+```bash
+kici admin drain-worker [options]
+```
+
+**Options:**
+
+| Option        | Required | Description                                   |
+| ------------- | -------- | --------------------------------------------- |
+| `--url <url>` | yes      | Worker URL (e.g., `http://worker-host:10143`) |
+
+**Examples:**
+
+```bash
+# Drain a local worker
+kici admin drain-worker --url http://localhost:10143
+
+# Drain a remote worker
+kici admin drain-worker --url http://worker-2.internal:10143
+```
+
+**Exit codes:**
+
+| Code | Meaning                             |
+| ---- | ----------------------------------- |
+| 0    | Drain request accepted              |
+| 1    | Error (unreachable or request fail) |
+
+### kici verify-attestation
+
+Verify a KiCI build-provenance attestation bundle offline. A bundle is the signed package a workflow step produces via `ctx.attestProvenance(...)`: a DSSE-wrapped SLSA in-toto statement, the ephemeral public key that signed it, and the KiCI identity token that anchors the build context. For the end-to-end attest → verify → view journey, see the [build provenance guide](https://docs.kici.dev/user/provenance/). Verification establishes the full chain — the identity token verifies against the trusted issuer's JWKS, the DSSE signature verifies against the bundled key, and the statement's build context must match the token's claims (a mismatch is a hard failure). When an `[artifact]` is given, its SHA-256 digest is also matched against the attestation subject.
+
+```bash
+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`.
+- **Offline — a self-contained trust-root file.** A local JSON file with the issuer and JWKS inlined, so no network access is needed (air-gapped verification):
+
+  ```json
+  {
+    "issuer": "https://platform.example/issuer",
+    "jwks": {
+      "keys": [
+        { "kty": "EC", "crv": "P-256", "x": "...", "y": "...", "alg": "ES256", "kid": "..." }
+      ]
+    }
+  }
+  ```
+
+**Examples:**
+
+```bash
+# Default: verify against the hosted KiCI platform (no --trust-root needed)
+kici verify-attestation ./dist/app.tgz --bundle ./app.tgz.kici.json
+
+# Override: verify a bundle against a specific issuer, digest-checking the artifact
+kici verify-attestation ./dist/app.tgz \
+  --bundle ./app.tgz.kici.json \
+  --trust-root https://platform.example/issuer
+
+# Offline / air-gapped: verify against a self-contained trust-root file
+kici verify-attestation ./dist/app.tgz \
+  --bundle ./app.tgz.kici.json \
+  --trust-root ./kici-trust-root.json
+
+# Machine-readable result for scripting
+kici verify-attestation --bundle ./app.tgz.kici.json \
+  --trust-root https://platform.example/issuer --json
+```
+
+**Exit codes:**
+
+| Code | Meaning                                                                                   |
+| ---- | ----------------------------------------------------------------------------------------- |
+| 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
+
+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 local`, `kici run remote`, `kici preview`) or `--verbose` (on `kici compile`) for detailed output:
+
+```bash
+# Shows trigger matching, rule evaluation, decision traces
+kici run local push --debug
+
+# 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()`
+- Access previous step outputs via `ctx.outputsOf()` and `ctx.jobOutputs()`
+- Publish encrypted secret outputs via `ctx.setSecretOutput()`
+- Log via `log.info()`, `log.error()`, etc.
+
+## Hook timeout
+
+Each hook has a timeout (default: 5 minutes). You can customize it per-hook:
+
+```typescript
+job('deploy', {
+  runsOn: 'linux',
+  steps: [
+    /* ... */
+  ],
+  cleanup: {
+    run: async (ctx) => {
+      await ctx.$`./lengthy-cleanup.sh`;
+    },
+    timeout: 10 * 60 * 1000, // 10 minutes in ms
+  },
+});
+```
+
+## Hook execution order
+
+Hooks execute inside-out on cancellation (like stack unwinding):
+
+1. **Step-level** cleanup (on the cancelled step)
+2. **Job-level** onCancel, then cleanup
+3. **Workflow-level** onCancel, then cleanup
+
+On success: step afterStep (after each step), then job onSuccess + cleanup, then workflow onSuccess + cleanup.
+
+On failure: job onFailure + cleanup, then workflow onFailure + cleanup.
+
+**cleanup always runs** -- regardless of whether the outcome was success, failure, or cancel.
+
+## Hooks are observers
+
+Hooks follow the "one mechanism per concern" principle:
+
+- **Rules** control whether a step/job executes (conditional logic)
+- **Hooks** react to execution outcomes (lifecycle callbacks)
+
+Hooks cannot short-circuit step execution or change the execution flow. They observe and respond.
+
+## beforeStep and afterStep
+
+These job-level hooks run around every step in the job:
+
+```typescript
+job('test', {
+  runsOn: 'linux',
+  beforeStep: async (ctx) => {
+    console.log(`Starting step at ${new Date().toISOString()}`);
+  },
+  afterStep: async (ctx) => {
+    console.log(`Step completed with status: ${ctx.outcome.status}`);
+  },
+  steps: [
+    step('lint', async ({ $ }) => {
+      await $`pnpm lint`;
+    }),
+    step('test', async ({ $ }) => {
+      await $`pnpm test`;
+    }),
+  ],
+});
+```
+
+`afterStep` runs immediately after its step, before the next step starts (not deferred to the end of the job).
+
+## Step-level rules
+
+Step-level rules control whether a step executes, evaluated at runtime by the agent:
+
+```typescript
+import { step, rule, skip, isEventType } from '@kici-dev/sdk';
+
+step('deploy', {
+  run: async ({ $ }) => {
+    await $`kubectl apply -f manifests/`;
+  },
+  rules: [
+    rule('only on main pushes', (ctx) => {
+      if (!isEventType(ctx.event, 'push')) return false;
+      return ctx.event.payload.ref === 'refs/heads/main';
+    }),
+  ],
+});
+
+// Or use skip() for explicit skip with a reason
+step('optional-check', {
+  run: async ({ $ }) => {
+    await $`./optional-check.sh`;
+  },
+  rules: [skip('not needed in CI', () => true)],
+});
+```
+
+When a rule returns `false`, the step is reported as `skipped` and subsequent steps continue normally. Skipped steps don't cause the job to fail.
+
+Step rules have access to runtime context via `RuleContext`: `event` (typed discriminated union), `changedFiles`, `env`, and `$`. They evaluate agent-side (unlike job-level rules which evaluate at the orchestrator during trigger matching).
+
+## Hook failure behavior
+
+If a hook throws an error or times out:
+
+- The job status changes to `failed` with a compound reason (e.g., "cancelled (onCancel hook failed: Connection timeout)")
+- Remaining hooks for that level are skipped
+- The failure is visible in the dashboard as a failed hook step
+- Force cancel kills running hooks immediately via SIGKILL
+
+This behavior is consistent across all hook types.
+
+---
+
+_Source: `packages/sdk/src/hooks/`, `packages/sdk/src/types.ts`_
+
+---
+
+## Lock file and workflow drift
+
+Source: https://docs.kici.dev/user/lock-file-and-drift/
+
+KiCI uses a **two-artifact model**: TypeScript workflows are the source of truth; the lock file (`kici.lock.json`) is the execution contract. The orchestrator reads only the lock file to match triggers and decide cache vs build. Keeping these in sync is important.
+
+## Why the lock file matters
+
+- **Orchestrator** fetches the lock file at the commit SHA and uses it to evaluate triggers and to look up the cached `.kici/` source tarball + `node_modules` tarball. It never runs your TypeScript.
+- **Agents** download the cached source tarball (or, on cold cache, the build agent clones + packs it), register the shared TypeScript loader hook, and dynamic-`import()` the workflow `.ts` directly. The lock file's per-workflow `contentHash` identifies the expected raw-source bytes and is verified against the extracted source before any step runs.
+
+If you change a workflow file (`.ts`) but do **not** regenerate and commit the lock file, the repo at that commit has **drift**: the lock file no longer matches the source. Triggers and cache keys can be wrong, and runs can fail with a clear “stale lock file” error once the agent verifies the hash.
+
+## Lock file structure
+
+The lock file (`kici.lock.json`) is a JSON file with the following top-level fields:
+
+| Field           | Description                                                                                                                                                                                                                                                                                                                                           |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `schemaVersion` | Lock file schema version (currently 29). Incremented on breaking format changes.                                                                                                                                                                                                                                                                      |
+| `source`        | Reference to the source file and export (e.g., `{ file: “.kici/workflows/ci.ts”, export: “#default” }`).                                                                                                                                                                                                                                              |
+| `contentHash`   | SHA-256 of the serialized lock file content (excluding itself). Changes when any workflow, trigger, or job changes.                                                                                                                                                                                                                                   |
+| `lockfileHash`  | SHA-256 of the detected package manager's lockfile, used as the dependency cache key. The lockfile is `.kici/package-lock.json` for npm, or the repo-root `pnpm-lock.yaml` / `yarn.lock` for a pnpm/yarn workspace; the hash input is prefixed with the manager name so a manager change is a guaranteed cache miss. Omitted when no lockfile exists. |
+| `workflows`     | Array of workflow entries, each with its own `contentHash`, `compileSchemaVersion`, triggers, and jobs.                                                                                                                                                                                                                                               |
+
+Each workflow entry includes:
+
+| Field                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`                 | Workflow name.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `source`               | Per-workflow source file and export reference.                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `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.).                                                                                                                                                                                                                                                                                              |
+| `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/).                                                                                                                                                                                                                                                |
+| `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`.                                                                                                                                                                                                                                                                     |
+
+## Rule: commit both together
+
+**Always commit `.kici/kici.lock.json` in the same commit as the workflow source files it was generated from.**
+
+1. After editing `.kici/workflows/*.ts`, run:
+   ```bash
+   npx kici compile
+   ```
+2. Stage both the workflow file(s) and `.kici/kici.lock.json`.
+3. Commit them together.
+
+That way the lock file at every commit SHA matches the workflow source at that SHA.
+
+## Catch drift early: pre-commit and CI
+
+Use automation so drift is caught before it reaches the repo.
+
+### Pre-commit hook
+
+Install a hook that compiles and stages the lock file before each commit:
+
+```bash
+npx kici hook install
+```
+
+This runs `kici compile && git add .kici/kici.lock.json` before each commit: if compilation fails the commit is blocked; if it succeeds the updated lock file is automatically staged. See [CLI Reference — kici hook](https://docs.kici.dev/user/cli-reference/#kici-hook) for options (husky, lefthook, pre-commit, prek, raw git).
+
+### CI check
+
+In your CI pipeline, verify that the workflow source compiles without errors:
+
+```bash
+kici compile --check
+```
+
+This validates all workflows and generates the lock file in memory without writing it. If any workflow has syntax errors or invalid configuration, the command exits non-zero. Pair this with the agent-side hash verification (below) for full drift detection -- `--check` catches broken source, while the agent catches source-lock-file mismatches at run time.
+
+## Extra files in the content hash (`hashFiles`)
+
+By default, the per-workflow content hash is `SHA-256(compileSchemaVersion + ":" + rawSource)` where `rawSource` is the TypeScript text of the workflow entry file. If your workflow depends on files outside `.kici/workflows/` -- configuration files, scripts, Dockerfiles, etc. -- changes to those files will **not** invalidate the cache unless you declare them.
+
+Use the `hashFiles` option on a workflow to include additional paths or glob patterns (relative to the repo root) in the content hash:
+
+```typescript
+export default workflow('deploy', {
+  hashFiles: ['config.json', 'scripts/*.sh'],
+  jobs: [
+    /* ... */
+  ],
+});
+```
+
+When any of the matched files change, the content hash formula becomes `SHA-256(compileSchemaVersion + ":" + rawSource + "\0" + assetDigest)` where `assetDigest` is a deterministic encoding of the resolved file paths and their contents. This busts the source-tarball cache and forces the build agent to pack and upload a fresh `source/{contentHash}.tar.gz`. The resolved file paths are recorded in the lock file under `resolvedHashFiles` so the agent can verify without re-discovering the workflow.
+
+## Agent-side safety net
+
+If drift still occurs (e.g. someone committed only the `.ts` change), the agent detects it at run time before any step runs:
+
+- After extracting the `.kici/` source tarball (or loading source from a `git clone` on the build path), the agent reads the workflow entry file and re-computes `contentHash = SHA-256(compileSchemaVersion + ":" + rawSource [+ "\0" + assetDigest])` using the same formula as the compiler.
+- If the orchestrator sent a `contentHash` (from the lock file) and the computed hash does **not** match, the agent fails the run with an error like: **lock file is out of date** (workflow source changed without regenerating the lock file). The error includes the baked agent `@kici-dev/sdk` version + bundle hash so operators can debug cross-host compile mismatches.
+
+So even without a pre-commit or CI check, a stale lock file will cause the run to fail with a clear message instead of running with the wrong workflow.
+
+## Summary
+
+| Goal                         | What to do                                                                                 |
+| ---------------------------- | ------------------------------------------------------------------------------------------ |
+| Keep lock file in sync       | Commit `kici.lock.json` with the workflow `.ts` changes; run `kici compile` before commit. |
+| Catch drift before commit    | Install a pre-commit hook with `kici hook install`.                                        |
+| Catch broken source in CI    | Run `kici compile --check` in CI.                                                          |
+| Bust cache on external files | Add `hashFiles: [‘config.json’]` to include non-workflow files in the content hash.        |
+| Fail fast when drift remains | Rely on the agent’s hash verification when it compiles from source.                        |
+
+## See also
+
+- [Getting Started](https://docs.kici.dev/user/getting-started/) — compile and commit the lock file
+- [CLI Reference](https://docs.kici.dev/user/cli-reference/) — `kici compile`, `kici compile --check`, `kici hook`
+- [Architecture — Data flows](https://docs.kici.dev/architecture/data-flows/) — how the lock file is used in the pipeline
+
+---
+
+## Testing guide
+
+Source: https://docs.kici.dev/user/testing-guide/
+
+Test your workflows remotely against the full CI pipeline from your local machine. `kici run remote` uploads your current repo state (including uncommitted changes), triggers the pipeline, and streams execution logs back in real time.
+
+## Overview
+
+`kici run remote` connects your local development environment to the remote orchestrator/agent pipeline. Instead of pushing a commit and waiting for CI, you can:
+
+- Run any workflow against your current working tree (including unstaged changes)
+- Get real-time log output streamed back to your terminal
+- Give test runs test-scoped secrets — your local secret files and `--env` values (uploaded encrypted) plus any environment flagged `allowLocalExecution: true` — while production environments stay unreachable
+- Detect test mode in workflow code via `ctx.isTestRun`
+
+The command is remote-only -- all execution happens on the orchestrator and agent. For local-only trigger matching previews, use `kici preview <event>`.
+
+:::note[Orchestrator prerequisite: cache storage]
+`kici run remote` uploads your working-tree overlay to the orchestrator's **cache storage** via a pre-signed URL, and the agent fetches it from there (see [Repo state transfer](https://docs.kici.dev/user/testing-guide/#repo-state-transfer)). The target orchestrator must therefore have cache storage enabled (`KICI_STORAGE_TYPE` = `s3` or `filesystem`).
+
+- **Both quickstarts wire this up for you** — the [Docker / Podman quickstart](https://docs.kici.dev/user/quickstart/compose/) and the [bare-metal quickstart](https://docs.kici.dev/user/quickstart/bare-metal/) each ship a SeaweedFS object store and pre-fill the orchestrator's `KICI_STORAGE_*` block, so `kici run remote` works out of the box (see each guide's "run a workflow without pushing" step).
+- **A hand-rolled orchestrator deploy does not configure storage by default** — enable a backend before using `kici run remote`:
+  - **`filesystem`** — simplest for a single-host orchestrator: set `KICI_STORAGE_TYPE=filesystem` and `KICI_STORAGE_FS_PATH=/var/lib/kici/cache`. No external service needed; blobs are served through the orchestrator's own HMAC-signed HTTP route.
+  - **`s3`** — any S3-compatible bucket. **A non-public / self-hosted endpoint works**: set `KICI_STORAGE_TYPE=s3`, `KICI_STORAGE_BUCKET`, `KICI_STORAGE_ENDPOINT=https://your-endpoint` and (for most self-hosted services) `KICI_STORAGE_FORCE_PATH_STYLE=true`. If the developer machine running `kici run remote` reaches the bucket at a different address than the orchestrator, set `KICI_STORAGE_UPLOAD_ENDPOINT` to the developer-reachable address; if agents reach it at yet another address (e.g. agents in containers), set `KICI_STORAGE_EXTERNAL_ENDPOINT` to the agent-routable URL.
+
+See [Storage layout](https://docs.kici.dev/operator/orchestrator/storage-layout/) for the full env-var reference.
+:::
+
+## Getting started
+
+### 1. Authenticate
+
+```bash
+kici login
+```
+
+This opens your browser for OAuth authentication and stores a personal access token in `~/.kici/config`. For CI/CD pipelines or headless environments, use `kici login --token <your-api-key>` or `kici login --device` instead. See [CLI authentication](https://docs.kici.dev/user/cli-auth/) for details.
+
+### 2. Write a test fixture
+
+Fixtures define the events you want to simulate. They live in `.kici/tests/*.ts` and use the same SDK trigger functions as workflows.
+
+```typescript
+// .kici/tests/push-tests.ts
+import { fixture, push } from '@kici-dev/sdk';
+
+export const pushMain = fixture('push-main', {
+  event: push({ branches: ['main'] }),
+});
+
+export const pushDevelop = fixture('push-develop', {
+  event: push({ branches: ['develop'] }),
+});
+```
+
+Each file can export multiple fixtures. The `fixture()` factory takes an ID (used on the command line) and options including the event to simulate.
+
+### 3. Run a fixture
+
+```bash
+# List available fixtures
+kici run remote
+
+# Run a specific fixture
+kici run remote push-main
+
+# Run all fixtures matching a glob
+kici run remote 'push-*'
+
+# Run everything
+kici run remote --all
+```
+
+The single quotes keep your shell from expanding `push-*` against local files, so the pattern reaches KiCI intact for its own fixture-glob matching.
+
+## Fixture reference
+
+### Event types
+
+Fixtures accept any SDK trigger function as their event:
+
+```typescript
+import { fixture, push, pr, comment, tag, release } from '@kici-dev/sdk';
+
+// Push event
+export const pushMain = fixture('push-main', {
+  event: push({ branches: ['main'] }),
+});
+
+// PR event
+export const prOpen = fixture('pr-open', {
+  event: pr({ branches: ['main'], actions: ['opened'] }),
+});
+
+// Comment event
+export const prComment = fixture('pr-comment', {
+  event: comment({ actions: ['created'] }),
+});
+
+// Tag event
+export const tagRelease = fixture('tag-release', {
+  event: tag({ tags: ['v*'] }),
+});
+
+// Release event
+export const published = fixture('release-published', {
+  event: release({ actions: ['published'] }),
+});
+```
+
+### Overrides
+
+Override default payload values per fixture:
+
+```typescript
+export const pushFeature = fixture('push-feature', {
+  event: push({ branches: ['feature/*'] }),
+  branch: 'feature/auth', // Override branch name
+  sha: 'abc123def456', // Override commit SHA
+  repo: 'myorg/myrepo', // Override repository
+  pr: 42, // Override PR number (for PR events)
+});
+```
+
+When not specified, these default to values detected from your local git repo (current branch, HEAD SHA, remote URL).
+
+### Secret context mappings
+
+Map secret contexts to your fixture:
+
+```typescript
+export const pushWithSecrets = fixture('push-with-secrets', {
+  event: push({ branches: ['main'] }),
+  secrets: {
+    db: 'test-database',
+    api: 'test-api-keys',
+  },
+});
+```
+
+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`:
+
+- 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).
+
+### Async fixtures
+
+For dynamic fixture configuration, export an async function:
+
+```typescript
+export const dynamicFixture = fixture('dynamic', async () => ({
+  event: push({ branches: ['main'] }),
+  sha: await getCurrentSha(),
+}));
+```
+
+## Running tests
+
+### Basic commands
+
+```bash
+# List all available fixtures (discovers .kici/tests/*.ts)
+kici run remote
+
+# Run a single fixture by ID
+kici run remote push-main
+
+# Glob matching -- run all push-related fixtures
+kici run remote 'push-*'
+
+# Run all fixtures sequentially
+kici run remote --all
+
+# Run all fixtures in parallel
+kici run remote --all --parallel
+```
+
+### Direct workflow run
+
+Bypass trigger matching and run a specific workflow directly:
+
+```bash
+kici run remote --workflow ci
+```
+
+This skips the trigger evaluation step and runs all jobs in the named workflow.
+
+### Output modes
+
+```bash
+# Default: full log streaming with colored job prefixes
+kici run remote push-main
+
+# Quiet: minimal output (just pass/fail result)
+kici run remote push-main --quiet
+
+# JSON: machine-readable structured output
+kici run remote push-main --json
+
+# JUnit XML: for CI integration
+kici run remote push-main --junit results.xml
+```
+
+### Non-blocking execution
+
+```bash
+# Fire and forget -- returns immediately with run ID
+kici run remote push-main --no-wait
+
+# Check status later
+kici runs show <run-id>
+```
+
+### Cancellation
+
+Press Ctrl+C during a running test to send a cancel signal to the orchestrator. The agent job will be terminated gracefully.
+
+## Repo state transfer
+
+When you run `kici run remote`, the CLI:
+
+1. Detects all files differing from HEAD (staged, unstaged, and untracked)
+2. Creates a compressed tarball of changed files
+3. Encrypts the tarball using X25519 ECDH key exchange
+4. Uploads the encrypted tarball to storage via a signed URL
+5. Triggers the pipeline with a reference to the upload
+
+The agent clones your repo at HEAD, then applies the overlay tarball on top -- giving you the exact same file state as your local working tree.
+
+### What gets included
+
+- Modified tracked files (staged and unstaged)
+- New untracked files (not in `.gitignore`)
+- File deletions (tracked files you deleted locally)
+
+### What gets excluded
+
+- Files matching `.gitignore` patterns
+- Files matching `.kiciignore` patterns (additional exclusions)
+- The `.git` directory itself
+
+### `.kiciignore`
+
+Create a `.kiciignore` file in your repo root to exclude additional files from the upload:
+
+```
+# Large binaries
+*.bin
+*.iso
+data/fixtures/large-dataset.csv
+
+# Local-only configs
+.env.local
+docker-compose.override.yml
+```
+
+The format is the same as `.gitignore` -- one glob pattern per line, `#` for comments.
+
+### Size limits
+
+| Threshold | Behavior                                                                          |
+| --------- | --------------------------------------------------------------------------------- |
+| < 50 MB   | Normal upload                                                                     |
+| 50-500 MB | Warning displayed, upload proceeds                                                |
+| > 500 MB  | Error -- reduce bundle size via `.kiciignore` or check for unintended large files |
+
+The CLI always shows a pre-upload summary before transferring:
+
+```
+12 files changed, 3 new, 1 deleted (2.3 MB compressed)
+```
+
+## Secret contexts for testing
+
+The goal of the test-secret model is to let test runs reach **test-only credentials** while keeping production credentials out of reach. `kici run remote` combines two sources of secrets for a test run, then merges them with a clear precedence and a fail-closed gate.
+
+### 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.
+
+```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.
+
+```bash
+# Provide a namespaced per-run value under the 'db' context
+kici run remote push-db --context db.KICI_DATABASE_URL=postgresql://localhost/test
+```
+
+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
+
+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`.
+
+Both paths are restricted to environments flagged `allowLocalExecution: true`. A production environment left at the default `false` is never resolvable for a test run.
+
+```typescript
+export const pushWithDb = fixture('push-db', {
+  event: push({ branches: ['main'] }),
+  secrets: { db: 'test-database' }, // 'test-database' must be allowLocalExecution: true
+});
+```
+
+```typescript
+step('migrate', async (ctx) => {
+  const dbUrl = await ctx.secrets.get('KICI_DATABASE_URL');
+  await ctx.$`npx prisma migrate deploy`;
+});
+```
+
+### 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.
+
+### Fail-closed on non-test environments
+
+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.
+
+### The `allowLocalExecution` environment 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.
+
+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
+```
+
+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.
+
+### 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.
+
+### Discovering available contexts
+
+```bash
+# List test-accessible secret contexts and their key names (not values)
+kici secrets list
+```
+
+## Detecting test mode in workflows
+
+Use `ctx.isTestRun` to conditionally skip destructive operations:
+
+```typescript
+step('deploy', async (ctx) => {
+  if (ctx.isTestRun) {
+    ctx.log.info('Skipping deployment in test mode');
+    return;
+  }
+  await ctx.$`kubectl apply -f k8s/`;
+});
+```
+
+## Run history
+
+### Viewing history
+
+```bash
+# Show recent test runs (from local history)
+kici run remote --history
+```
+
+### Run details
+
+```bash
+# Show run summary (reads the Platform, falls back to local history)
+kici runs show <run-id>
+
+# Show full logs
+kici runs logs <run-id>
+
+# Show logs for a specific job
+kici runs logs <run-id> --job build
+
+# Machine-readable output
+kici runs show <run-id> --json
+```
+
+## Scaffolding with kici init
+
+Running `kici init` in a new project scaffolds a sample test fixture alongside the workflow templates:
+
+```
+.kici/
+  workflows/
+    hello-world.ts     # Sample workflow
+    pr-checks.ts       # Sample PR workflow
+  tests/
+    push-test.ts       # Sample push fixture
+  package.json
+  tsconfig.json
+.kiciignore            # Default exclusion patterns
+```
+
+The generated fixture uses the detected default branch:
+
+```typescript
+// .kici/tests/push-test.ts
+import { fixture, push } from '@kici-dev/sdk';
+
+export const pushMain = fixture('push-main', {
+  event: push({ branches: ['main'] }),
+});
+```
+
+## See also
+
+- [CLI reference](https://docs.kici.dev/user/cli-reference/) -- complete command reference for all `kici` commands
+- [SDK reference](https://docs.kici.dev/user/sdk-reference/) -- trigger functions, step context, and workflow API
+- [Workflow patterns](https://docs.kici.dev/user/workflow-patterns/) -- example workflows to test against
+
+---
+
+## Workflow patterns
+
+Source: https://docs.kici.dev/user/workflow-patterns/
+
+Practical patterns for building real-world KiCI workflows in TypeScript. The patterns are organised across five pages -- start with [Basic CI](https://docs.kici.dev/user/patterns/basic/) if you're new, or jump to [Integrations](https://docs.kici.dev/user/patterns/integrations/) if you're wiring up a non-GitHub forge or a generic webhook.
+
+| Page                                                       | Covers                                                                                                                                             |
+| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Basic CI](https://docs.kici.dev/user/patterns/basic/)                            | Single-job CI, PR-only / push-only filters, multiple triggers on one workflow, manual-only workflows.                                              |
+| [Conditionals & matrix](https://docs.kici.dev/user/patterns/conditionals-matrix/) | Conditional execution with rules, matrix builds (static + dynamic), and dynamic job generation.                                                    |
+| [Integrations](https://docs.kici.dev/user/patterns/integrations/)                 | Workflow chaining, generic webhooks, Stripe handlers, self-hosted git forges (Forgejo / Gitea / Gogs), plain GitHub repo webhooks (no GitHub App). |
+| [Scheduling & events](https://docs.kici.dev/user/patterns/scheduling-and-events/) | Nightly cron, workflow-complete-triggered deploys, custom event chaining.                                                                          |
+| [Pattern reference](https://docs.kici.dev/user/patterns/reference/)               | Step context, the examples repository, and GitHub check run output -- cross-cutting reference shared by every pattern above.                       |
+
+## See also
+
+- [Event system](https://docs.kici.dev/user/events/) -- event model concepts, registration model, circuit breaker
+- [SDK reference](https://docs.kici.dev/user/sdk-reference/) -- complete API reference for all functions used in these patterns
+- [CLI reference](https://docs.kici.dev/user/cli-reference/) -- how to compile and test these workflows locally
+- [Getting started](https://docs.kici.dev/user/getting-started/) -- installation and first workflow setup
+- [Job execution lifecycle](https://docs.kici.dev/architecture/execution/job-execution/) -- how agents execute the jobs defined in these patterns
+- [GitHub checks architecture](https://docs.kici.dev/architecture/webhooks/github-checks/) -- deep dive into the check run system
+
+---