@kici-dev/compiler 0.1.16 → 0.1.17

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

@@ -26,7 +26,7 @@ Why the lock file must stay in sync with workflow source, how to commit both tog
 
 ### [CLI reference](cli-reference.md)
 
-All CLI commands provided by `@kici-dev/compiler`: `kici compile` (with watch mode and check mode), `kici run` (local and remote execution), `kici test` (event simulation with dry-run, filtering, debug output, and custom payloads), `kici login`/`logout`/`org` (authentication and org management), `kici status`/`cancel` (run management), `kici secrets` (secret listing), `kici types` (type generation), `kici fixture` (generate test payloads), `kici init` (interactive project scaffolding), `kici hook` (pre-commit hook installation), `kici endpoints` (webhook entrypoints), and `kici workflows` (workflow listing). Includes environment variables and exit codes.
+All CLI commands provided by `@kici-dev/compiler`: `kici compile` (with watch mode and check mode), `kici run` (local and remote execution), `kici test` (event simulation with dry-run, filtering, debug output, and custom payloads), `kici login`/`logout`/`org` (authentication and org management), `kici diagnostics` (infrastructure tree) and `kici runs` (`list`/`show`/`logs`/`rerun`/`cancel` — run management), `kici secrets` (secret listing), `kici types` (type generation), `kici fixture` (generate test payloads), `kici init` (interactive project scaffolding), `kici hook` (pre-commit hook installation), `kici endpoints` (webhook entrypoints), and `kici workflows` (workflow listing). Includes environment variables and exit codes.
 
 ### [Workflow patterns](workflow-patterns.md)
 
@@ -215,6 +215,8 @@ This workflow:
 - Runs a `lint` job first
 - Runs a `test` job after lint succeeds (`needs: [lint]`)
 
+`runsOn` selects which agents may run a job. Every agent self-reports `kici:os:<platform>`, `kici:arch:<cpu>`, and `kici:host:<hostname>`, so `runsOn: 'kici:os:linux'` targets any connected Linux agent with zero configuration — `kici init` scaffolds workflows with exactly that. Use a custom label such as `'linux'` or `'gpu'` (defined in your scaler's `labelSet`) to target a specific pool instead. See the [runsOn forms](./sdk/core.md#runson-forms) reference for the full label model.
+
 **Single-step shortcut.** If a job only has one step, pass `run` directly to `job()` instead of building a `steps: [step(...)]` array:
 
 ```typescript
@@ -310,7 +312,7 @@ This updates `.kici/package.json` and generates (or updates) `package-lock.json`
 
 ### Dependency resolution contract
 
-Every `.kici/` dependency must be resolvable from the **single cloned repository**. When a job runs, the agent clones only this repository and installs `.kici/` dependencies with your repo's package manager (npm or pnpm; yarn is not supported — the agent rejects it with an actionable error). A dependency that points outside the cloned repo cannot be resolved.
+Every `.kici/` dependency must be resolvable from the **single cloned repository**. When a job runs, the agent clones only this repository and installs `.kici/` dependencies with your repo's package manager — npm, pnpm, or yarn classic (v1). yarn berry (v2+) is not yet supported. A dependency that points outside the cloned repo cannot be resolved.
 
 In practice:
 
@@ -416,6 +418,8 @@ Or add the flag to your root `package.json`:
 
 ## Authoring KiCI workflows with LLM coding agents
 
+KiCI is LLM-ready by design. Because workflows are real, typed TypeScript, coding agents reason over the SDK's `.d.ts` signatures instead of guessing a bespoke YAML DSL — and they verify their own pipelines with the same `kici test` and `kici run local` loop you use, so there's no push-to-find-out round-trip. First-class agent context ships in the box, so an agent is briefed the moment it opens the project.
+
 KiCI ships first-class context for LLM coding agents (Claude Code, Cursor, Aider, etc.). When you scaffold a project with `kici init`, the CLI writes `.kici/AGENTS.md`, a one-page briefing that tells the agent:
 
 - where the SDK type declarations live (`node_modules/@kici-dev/sdk/dist/index.d.ts`)
@@ -1888,33 +1892,33 @@ function job(options: JobOptions): Job;
 
 **Parameters:**
 
-| Parameter                  | Type                                                            | Required             | Description                                                                                                                                              |
-| -------------------------- | --------------------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `name`                     | `string`                                                        | no                   | Job name (auto-generated UUID if omitted)                                                                                                                |
-| `options.runsOn`           | `RunsOn`                                                        | yes                  | Runner label(s) and optional exclusions (see below)                                                                                                      |
-| `options.steps`            | `StepInput[]`                                                   | yes (or use `run`)   | Steps to execute in order. Mutually exclusive with `run`.                                                                                                |
-| `options.run`              | `(ctx) => Promise<unknown>`                                     | yes (or use `steps`) | Single-step shorthand -- see [Single-step job shorthand](#single-step-job-shorthand). Mutually exclusive with `steps`.                                   |
-| `options.needs`            | `NeedsEntry[]`                                                  | no                   | Job dependencies (must complete first) -- see [Job dependencies (`needs`)](#job-dependencies-needs)                                                      |
-| `options.rules`            | `Rule[]`                                                        | no                   | Conditions for conditional execution                                                                                                                     |
-| `options.description`      | `string`                                                        | no                   | Human-readable description                                                                                                                               |
-| `options.matrix`           | `Matrix`                                                        | no                   | Matrix configuration for job expansion                                                                                                                   |
-| `options.include`          | `MatrixInclude[]`                                               | no                   | Additional matrix combinations                                                                                                                           |
-| `options.exclude`          | `MatrixExclude[]`                                               | no                   | Matrix combinations to remove                                                                                                                            |
-| `options.checkout`         | `boolean`                                                       | no (default: `true`) | When `false`, agent skips git clone. Useful for deploy/notify jobs.                                                                                      |
-| `options.container`        | `string \| ContainerConfig`                                     | no                   | Docker image for job execution. String form is the image name; object form adds `env`. All steps run inside the container.                               |
-| `options.environment`      | `string \| ((event) => string \| Promise<string>)`              | no                   | Deployment environment for this job. Static string or async/dynamic function -- see [Dynamic values](../dynamic-values.md).                              |
-| `options.env`              | `Record<string, string> \| ((event) => Record<string, string>)` | no                   | Environment variables. Static object or async/dynamic function -- see [Dynamic values](../dynamic-values.md).                                            |
-| `options.concurrencyGroup` | `string \| ((event) => string \| Promise<string>)`              | no                   | Concurrency group name (defaults to environment name) -- see [Concurrency](../concurrency.md).                                                           |
-| `options.onCancel`         | `HookInput`                                                     | no                   | Hook that runs when the job is cancelled                                                                                                                 |
-| `options.cleanup`          | `HookInput`                                                     | no                   | Hook that always runs after completion                                                                                                                   |
-| `options.onSuccess`        | `HookInput`                                                     | no                   | Hook that runs when the job succeeds                                                                                                                     |
-| `options.onFailure`        | `HookInput`                                                     | no                   | Hook that runs when the job fails                                                                                                                        |
-| `options.beforeStep`       | `HookInput`                                                     | no                   | Hook that runs before each step                                                                                                                          |
-| `options.afterStep`        | `HookInput`                                                     | no                   | Hook that runs after each step                                                                                                                           |
-| `options.gracePeriod`      | `number`                                                        | no                   | Seconds before SIGKILL after SIGTERM during cancellation -- see [Hooks](../hooks.md#hook-timeout).                                                       |
-| `options.timeout`          | `number`                                                        | no                   | Total job wall-clock timeout in milliseconds (init + all steps + hooks). On breach the job is aborted and reported timed out. See [Timeouts](#timeouts). |
-| `options.resources`        | `ResourceRequest`                                               | no                   | Per-job CPU / memory request and limit. See [Per-job resources](#per-job-resources) below.                                                               |
-| `options.init`             | `GenericInitConfig \| GenericInitConfig[] \| false`             | no                   | Per-job initialization run after clone, before steps -- provisions a toolchain. See [Per-job init](#per-job-init) below.                                 |
+| Parameter                  | Type                                                            | Required             | Description                                                                                                                                                                                              |
+| -------------------------- | --------------------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`                     | `string`                                                        | no                   | Job name (auto-generated UUID if omitted)                                                                                                                                                                |
+| `options.runsOn`           | `RunsOn`                                                        | yes                  | Runner label(s) and optional exclusions (see below)                                                                                                                                                      |
+| `options.steps`            | `StepInput[]`                                                   | yes (or use `run`)   | Steps to execute in order. Mutually exclusive with `run`.                                                                                                                                                |
+| `options.run`              | `(ctx) => Promise<unknown>`                                     | yes (or use `steps`) | Single-step shorthand -- see [Single-step job shorthand](#single-step-job-shorthand). Mutually exclusive with `steps`.                                                                                   |
+| `options.needs`            | `NeedsEntry[]`                                                  | no                   | Job dependencies (must complete first) -- see [Job dependencies (`needs`)](#job-dependencies-needs)                                                                                                      |
+| `options.rules`            | `Rule[]`                                                        | no                   | Conditions for conditional execution                                                                                                                                                                     |
+| `options.description`      | `string`                                                        | no                   | Human-readable description                                                                                                                                                                               |
+| `options.matrix`           | `Matrix`                                                        | no                   | Matrix configuration for job expansion                                                                                                                                                                   |
+| `options.include`          | `MatrixInclude[]`                                               | no                   | Additional matrix combinations                                                                                                                                                                           |
+| `options.exclude`          | `MatrixExclude[]`                                               | no                   | Matrix combinations to remove                                                                                                                                                                            |
+| `options.checkout`         | `boolean`                                                       | no (default: `true`) | When `false`, agent skips git clone. Useful for deploy/notify jobs.                                                                                                                                      |
+| `options.container`        | `string \| ContainerConfig`                                     | no                   | Docker image for job execution. String form is the image name; object form adds `env`. All steps run inside the container.                                                                               |
+| `options.environment`      | `string \| ((event) => string \| Promise<string>)`              | no                   | Deployment environment for this job. Static string or async/dynamic function -- see [Dynamic values](../dynamic-values.md).                                                                              |
+| `options.env`              | `Record<string, string> \| ((event) => Record<string, string>)` | no                   | Environment variables. Static object or async/dynamic function -- see [Dynamic values](../dynamic-values.md).                                                                                            |
+| `options.concurrencyGroup` | `string \| ((event) => string \| Promise<string>)`              | no                   | Concurrency group name (defaults to environment name) -- see [Concurrency](../concurrency.md).                                                                                                           |
+| `options.onCancel`         | `HookInput`                                                     | no                   | Hook that runs when the job is cancelled                                                                                                                                                                 |
+| `options.cleanup`          | `HookInput`                                                     | no                   | Hook that always runs after completion                                                                                                                                                                   |
+| `options.onSuccess`        | `HookInput`                                                     | no                   | Hook that runs when the job succeeds                                                                                                                                                                     |
+| `options.onFailure`        | `HookInput`                                                     | no                   | Hook that runs when the job fails                                                                                                                                                                        |
+| `options.beforeStep`       | `HookInput`                                                     | no                   | Hook that runs before each step                                                                                                                                                                          |
+| `options.afterStep`        | `HookInput`                                                     | no                   | Hook that runs after each step                                                                                                                                                                           |
+| `options.gracePeriod`      | `number`                                                        | no                   | Seconds before SIGKILL after SIGTERM during cancellation -- see [Hooks](../hooks.md#hook-timeout).                                                                                                       |
+| `options.timeout`          | `number`                                                        | no                   | Total job wall-clock timeout in milliseconds (init + all steps + hooks). On breach the job is aborted and reported timed out. See [Timeouts](#timeouts).                                                 |
+| `options.resources`        | `ResourceRequest`                                               | no                   | Per-job CPU / memory request and limit. See [Per-job resources](#per-job-resources) below.                                                                                                               |
+| `options.init`             | `InitConfig`                                                    | no                   | Per-job initialization run after clone, before steps -- provisions a toolchain. A generic config, a typed preset (`'mise'` / `{ mise }`), `'auto'`, or `false`. See [Per-job init](#per-job-init) below. |
 
 **Returns:** `Job` -- an immutable job definition.
 
@@ -1935,20 +1939,27 @@ const build = job({
 
 #### runsOn forms
 
-The `runsOn` parameter accepts three forms for targeting agents:
+A job's `runsOn` selects which agents may run it. Every label listed must be present on the agent (a subset match). It accepts three forms:
 
 ```typescript
 // 1. Simple string -- agent must have this label
-runsOn: 'linux'
+runsOn: 'kici:os:linux'
 
 // 2. Array of required labels -- agent must have ALL labels
-runsOn: ['linux', 'docker']
+runsOn: ['kici:os:linux', 'gpu']
 
 // 3. Object form with exclusions -- agent must have ALL required labels
 //    and NONE of the excluded labels
-runsOn: { labels: ['linux', 'docker'], exclude: ['gpu'] }
+runsOn: { labels: ['kici:os:linux'], exclude: ['kici:host:box-01'] }
 ```
 
+**The label model:**
+
+- Every agent automatically reports `kici:os:<platform>`, `kici:arch:<cpu>`, and `kici:host:<hostname>`, so `runsOn: 'kici:os:linux'` targets any connected Linux agent without configuring labels — a fresh `kici init` matches out of the box.
+- Use **custom labels** (e.g. `'gpu'`, `'prod-pool'`) — defined in your scaler's `labelSet` — to target a specific agent pool.
+- You can also target scaler-assigned labels (`kici:agent:<backend>`, `kici:scaler:<name>`), but those names are deployment-specific, so custom labels are more portable.
+- `runsOn` is a _requirement_ on candidate agents, never a _grant_: targeting a label only narrows the candidate set. Users cannot _set_ `kici:` labels on agents — that namespace is reserved for the scaler and the agent's self-reported platform facts — but they may freely _target_ any label in `runsOn`.
+
 **Semantics:**
 
 - **Required labels:** The agent must have every label in the `labels` array (or the string/array form).
@@ -2108,7 +2119,37 @@ The agent reads both files after the command succeeds, applies the delta, and th
 
 **Arrays run in order.** Passing `GenericInitConfig[]` runs the inits sequentially; each one's `$KICI_ENV` / `$KICI_PATH` delta is applied before the next runs, so a later init sees an earlier init's tools on `PATH`. The first init to fail stops the sequence and fails the job.
 
-**`init: false`** is an explicit opt-out (reserved for a future auto-detect layer); it behaves the same as omitting `init`.
+**`init: false`** is an explicit opt-out; it behaves the same as omitting `init`.
+
+#### Toolchain presets
+
+For the common case, a typed preset removes the hand-written `run` block entirely. The agent expands the preset to the same generic init it would otherwise run.
+
+- **`init: 'mise'`** -- zero-config. Installs mise, trusts and runs `mise install` against the committed mise config (`mise.toml` / `.mise.toml` / `.tool-versions`), hands mise's env + shims dir to subsequent steps, and caches mise's data dir under a key derived from the committed config (so a config change rotates the cache). The committed config is trusted automatically — committing it to your repo is the trust signal.
+- **`init: { mise: { cache, timeout, env, shell } }`** -- the same preset with overrides. These tune the generic fields a hand-written init exposes (minus `run`): `cache: false` disables caching, a `CacheSpec` replaces the default key/paths, and `timeout` / `env` / `shell` map straight through. `init: 'mise'` is exactly `init: { mise: {} }`.
+
+```typescript
+const build = job('build', {
+  runsOn: 'linux',
+  init: 'mise', // committed mise.toml pins the toolchain; jq, node, etc. land on PATH
+  steps: [
+    step('show-jq-version', async (ctx) => {
+      const { stdout } = await ctx.$`jq --version`;
+      ctx.log.info(`jq version: ${stdout.trim()}`);
+    }),
+  ],
+});
+```
+
+#### Auto-detect (`init: 'auto'`)
+
+**`init: 'auto'`** detects the toolchain from committed files instead of naming a preset. The agent scans the clone root and selects a preset when a marker is present: `mise.toml` / `.mise.toml` / `.tool-versions` -> the mise preset. With no markers found, `'auto'` is a logged no-op.
+
+`'auto'` is opt-in: an **unset** `init` does nothing even when the repo carries a `mise.toml` for local development. Use `'auto'` to enable detection and `false` to keep the explicit opt-out.
+
+#### Cross-platform
+
+The mise preset works on Linux, macOS, and Windows. On Linux and macOS mise is installed via its standalone install script; on Windows it is installed from its standalone GitHub release. The resulting toolchain reaches every step the same way on all three. On Windows the standalone mise binary requires the Microsoft Visual C++ runtime (`vc_redist.x64`) to be present on the agent host — install it once when provisioning a Windows agent that uses the mise preset.
 
 ## Step & job authoring patterns
 
@@ -3049,6 +3090,8 @@ Every variant carries the shared `EventBase` fields — `type`, `action`, `targe
 
 Matrix configurations expand a single job into multiple instances, one per parameter combination. Maximum 256 combinations.
 
+Expansion happens at **dispatch time**: the orchestrator materializes the matrix into N execution jobs — one per combination, each dispatched to its own agent — before any job runs. Each instance receives its combination as `ctx.matrix`. This is identical whether the workflow runs via `kici run local` or remotely through a webhook trigger, and the dashboard groups the N instances under one parent node.
+
 ### Static array (single dimension)
 
 ```typescript
@@ -3103,6 +3146,8 @@ The function receives a `DynamicMatrixContext`:
 
 Must return `string[]` (single dimension) or `Record<string, string[]>` (multi-dimensional).
 
+A dynamic matrix is resolved at runtime, then materialized into N instances exactly like a static matrix. Because the combinations are not known until the function runs, the 256-combination cap (and the "zero combinations" guard) is enforced at that point: a dynamic matrix that resolves to more than 256 combinations, or to none, fails the job with a matrix-expansion error rather than dispatching.
+
 ### Include and exclude
 
 Fine-tune matrix combinations on multi-dimensional matrices:
@@ -3141,6 +3186,35 @@ interface MatrixValues {
 }
 ```
 
+### Consuming matrix outputs downstream
+
+A downstream job that lists a matrix job in its `needs` receives a **keyed envelope** instead of a flat outputs object, because the upstream produced N sets of outputs (one per combination). `ctx.jobOutputs(matrixJob)` returns a `MatrixJobOutputs`:
+
+```typescript
+interface MatrixJobOutputs<T = Record<string, unknown>> {
+  /** Keyed by the combination suffix — the text inside `(...)` of the child name. */
+  byMatrix: Record<string, T>;
+  /** Last-write-wins flat merge across children, in child (name) order. */
+  merged: T;
+}
+```
+
+The suffix key matches the child job's display name: `byMatrix['a']` for a single-dimension `['a', 'b']` matrix, `byMatrix['linux, arm64']` for a multi-dimension combination. Use `isMatrixJobOutputs` (or `'byMatrix' in result`) to discriminate:
+
+```typescript
+import { isMatrixJobOutputs } from '@kici-dev/sdk';
+
+step('collect', async ({ jobOutputs }) => {
+  const out = jobOutputs(buildMatrixJob);
+  if (isMatrixJobOutputs(out)) {
+    console.log(out.byMatrix['a']); // outputs of the `a` combination
+    console.log(out.merged); // last-write-wins across all combinations
+  }
+});
+```
+
+The downstream job waits for **all** matrix combinations to terminate before it dispatches. A non-matrix upstream keeps the flat outputs shape. The envelope is identical under `kici run local` and the remote path.
+
 ### Matrix type guards
 
 ```typescript
@@ -3556,6 +3630,68 @@ const deploy = job('deploy', {
 - Maximum 20 secret outputs per job
 - Maximum 64 KB per value
 
+### ctx.kici.oidc.token({ audience })
+
+Request a short-lived OIDC ID token for the current job, bound to an `audience`. The token is a signed JWT whose identity claims (`repository`, `ref`, `sha`, `kici_run_id`, `kici_job_id`) are derived by the build platform from the run context — a step cannot spoof them. Use it to authenticate the build to an external service that trusts the platform's OIDC issuer (for example, when generating build provenance).
+
+```typescript
+const publish = job('publish', {
+  steps: [
+    step('mint', async (ctx) => {
+      const { token, expiresIn } = await ctx.kici.oidc.token({ audience: 'sigstore' });
+      ctx.log.info(`Got an ID token valid for ${expiresIn}s`);
+      // Hand `token` to a tool that exchanges it with the trusting service.
+    }),
+  ],
+});
+```
+
+**Behavior:**
+
+- The token is short-lived (about 10 minutes) and scoped to the current run and job.
+- The returned token value is automatically masked in step logs.
+- The step never holds platform credentials — the request is relayed through the orchestrator, which mints the token on the step's behalf.
+- Only available inside a running job step; calling it outside one (for example, during local execution) rejects with a clear error.
+
+### ctx.attestProvenance({ subject })
+
+Build, sign, and persist a build-provenance attestation for an artifact your step produced. KiCI assembles an in-toto SLSA v1.0 provenance statement whose build identity (`repository`, `ref`, `sha`, run/job ids) comes from the platform — not from the step — so it cannot be spoofed, signs it, and stores a verifiable bundle that the dashboard surfaces and the `kici verify-attestation` CLI checks.
+
+The artifact is **caller-supplied**: give it either a precomputed digest or a path (relative to the step working directory) that KiCI digests with SHA-256. For a container image, pass the manifest digest your build tool emitted.
+
+```typescript
+const publish = job('publish', {
+  steps: [
+    step('build', async (ctx) => {
+      await ctx.$`npm pack`;
+    }),
+    step('attest', async (ctx) => {
+      // Digest a file KiCI hashes for you:
+      const result = await ctx.attestProvenance({
+        subject: { name: 'my-pkg-1.2.3.tgz', path: 'my-pkg-1.2.3.tgz' },
+      });
+      ctx.log.info(`Attestation stored at ${result.storageKey}`);
+
+      // Or supply a precomputed digest (e.g. a container manifest digest):
+      await ctx.attestProvenance({
+        subject: { name: 'ghcr.io/acme/app', digest: { sha256: '<manifest-digest>' } },
+      });
+    }),
+  ],
+});
+```
+
+**Behavior:**
+
+- The attestation is a signed [DSSE](https://github.com/secure-systems-lab/dsse) envelope over an [in-toto](https://in-toto.io) statement carrying the [SLSA v1.0](https://slsa.dev/spec/v1.0/provenance) provenance predicate.
+- It is signed with an ephemeral key bound to a platform-minted identity token, so it is **offline-verifiable** against the platform's published signing keys — no online lookup needed at verify time.
+- The bundle is persisted to object storage and recorded so the dashboard can show it and `kici verify-attestation` can retrieve it.
+- The returned `{ storageKey, subjectDigest, bundleMediaType }` identifies the stored bundle.
+- Only available inside a running job step; calling it outside one (for example, during local execution) rejects with a clear error.
+
+See the [build provenance guide](../provenance.md) for the end-to-end attest →
+verify → view journey, including how to verify a bundle with `kici verify-attestation`.
+
 ## Secrets
 
 Workflows access secrets through `ctx.secrets` on `StepContext`. Use `await ctx.secrets.get('KEY')` to retrieve a value (rejects with `SecretNotFoundError` if the key is missing, fail-fast on typos), `ctx.secrets.has('KEY')` for a synchronous existence check, and `await ctx.secrets.expose('KEY')` when you need the value as a `process.env` entry for a child process.
@@ -4603,7 +4739,7 @@ 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 (endpoint, routing key, connection mode)
+3. Preserves non-auth settings (active org, default clusters, Platform endpoint)
 
 ## Organization management
 
@@ -4623,6 +4759,10 @@ 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
@@ -4633,18 +4773,15 @@ Displays the currently active organization name and ID.
 
 ## Auth status
 
-The `kici status <run-id>` command displays run details including your authentication state:
+`kici org current` shows your current login state and active organization:
 
 ```bash
-kici status <run-id>
+kici org current
 ```
 
-The auth-related output includes:
-
-- Login state (logged in / not logged in)
-- Active organization name
-- PAT expiry date and time remaining
-- Warning if PAT expires within 7 days
+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
 
@@ -4767,7 +4904,8 @@ The CLI stores authentication data in `~/.kici/config` with `0600` permissions (
 - PAT token
 - PAT expiry date
 - Active organization ID
-- Server endpoint URL
+- Per-org default orchestrator clusters
+- Platform endpoint URL
 
 ## Troubleshooting
 
@@ -5026,7 +5164,9 @@ kici run local push --keep-going
 
 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.
 
-Requires `kici login` (an authenticated session) and a target orchestrator that has **cache storage configured** (`KICI_STORAGE_TYPE` = `s3` or `filesystem`) — the command uploads your working-tree overlay to that storage for the agent to fetch. The quickstart orchestrators do not enable storage by default; see the [testing guide](testing-guide.md) for setup (including non-public / self-hosted S3 endpoints).
+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](#how-the-run-is-routed) and [The two planes](#the-two-planes) below.
+
+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](testing-guide.md) and [Storage layout](../operator/orchestrator/storage-layout.md) for setup.
 
 ```bash
 kici run remote [fixture] [options]
@@ -5040,21 +5180,22 @@ kici run remote [fixture] [options]
 
 **Options:**
 
-| Option                      | Default | Description                                                                                                           |
-| --------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
-| `--all`                     | `false` | Run all fixtures                                                                                                      |
-| `--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                                                                                        |
-| `--routing-key <key>`       | none    | Override routing key for this run                                                                                     |
-| `--context <ctx.key=value>` | none    | Inject a namespaced context secret, uploaded encrypted to the orchestrator (repeatable)                               |
-| `--env <KEY=VALUE>`         | none    | Provide a per-run secret, uploaded encrypted to the orchestrator (repeatable) — see [testing guide](testing-guide.md) |
-| `--debug`                   | `false` | Verbose internals                                                                                                     |
-| `--kici-dir <path>`         | `.kici` | Path to .kici directory                                                                                               |
+| 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                                                                                  |
+| `--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](testing-guide.md) |
+| `--debug`                   | `false` | Verbose internals                                                                                 |
+| `--kici-dir <path>`         | `.kici` | Path to .kici directory                                                                           |
 
 **Examples:**
 
@@ -5062,9 +5203,15 @@ kici run remote [fixture] [options]
 # List available fixtures
 kici run remote
 
-# Run a single fixture
+# 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-*
 
@@ -5094,19 +5241,75 @@ kici run remote --history
 | 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](../operator/orchestrator/storage-layout.md).
+
+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`](#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)
-- A synthetic routing key `local:<repo-name>` is used
 - 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](testing-guide.md).
 
+#### 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 test
 
 Preview which workflows match a trigger event (dry-run, no execution). Useful for verifying trigger configurations during development.
@@ -5181,9 +5384,7 @@ kici login [options]
 | --------------------------- | ------- | ---------------------------------------------- |
 | `--token <key>`             | none    | API key for direct authentication (legacy)     |
 | `--device`                  | false   | Force device authorization flow (headless/SSH) |
-| `--endpoint <url>`          | none    | Orchestrator URL for direct connection         |
-| `--platform-endpoint <url>` | none    | Platform relay URL                             |
-| `--routing-key <key>`       | none    | Routing key for webhook source identification  |
+| `--platform-endpoint <url>` | none    | Platform API base URL                          |
 
 **Environment variables:**
 
@@ -5208,11 +5409,8 @@ kici login --device
 # Legacy API key login
 kici login --token kici_sk_abc123...
 
-# Direct connection to orchestrator with API key
-kici login --token kici_sk_abc123... --endpoint https://my-orchestrator.example.com
-
-# Platform relay connection with routing key
-kici login --token kici_sk_abc123... --platform-endpoint https://platform.kici.dev --routing-key github:42
+# Log in against a self-hosted Platform
+kici login --platform-endpoint https://platform.example.com
 
 # Suppress browser opening (print authorize URL to stdout)
 KICI_BROWSER_CMD=none kici login
@@ -5230,7 +5428,7 @@ KICI_CALLBACK_PORT=19876 KICI_CONFIG_DIR=/tmp/kici-test kici login
 
 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 (endpoint, routing key, etc.) are preserved.
+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
@@ -5296,87 +5494,169 @@ Show the current active organization.
 kici org current
 ```
 
-### kici status
+### kici diagnostics
 
-Show details for a specific test run. Fetches from the orchestrator with fallback to local history.
+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 status output includes an **auth section** showing login state, active organization, and PAT expiry. A warning appears when the PAT expires within 7 days.
+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.
 
-For a failed run, the output prints a `Reason:` line with the run's failure reason and shows the failed job's error inline, so you can see why a run failed without opening the dashboard. When provisioning an agent failed before any step ran, this reason is the captured scaler error (for example a missing binary or an unpullable image) rather than a generic "no agents available" message.
+```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
-kici status <run-id> [options]
+# 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
 ```
 
-**Arguments:**
+### 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>`).
 
-| Argument | Required | Description    |
-| -------- | -------- | -------------- |
-| `run-id` | yes      | Run identifier |
+#### 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                                                  |
-| -------------- | ------- | ------------------------------------------------------------ |
-| `--logs`       | `false` | Stream logs (live for active runs, historical for completed) |
-| `--job <name>` | all     | Filter logs to a specific job                                |
-| `--json`       | `false` | Machine-readable JSON output                                 |
+| 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                  |
 
-**Examples:**
+```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
-# Show run summary
-kici status abc123
+kici runs show <run-id> [options]
+```
 
-# Show full logs (historical for completed runs, live streaming for active runs)
-kici status abc123 --logs
+| Option   | Default | Description                  |
+| -------- | ------- | ---------------------------- |
+| `--json` | `false` | Machine-readable JSON output |
 
-# Show logs for a specific job
-kici status abc123 --logs --job build
+```bash
+kici runs show abc123
+kici runs show abc123 --json
+```
 
-# Machine-readable output
-kici status abc123 --json
+#### kici runs logs
+
+Print each job/step's log lines in order, with headers.
+
+```bash
+kici runs logs <run-id> [options]
 ```
 
-When `--json` is set, `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`.
+| 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           |
 
-### kici cancel
+```bash
+kici runs logs abc123
+kici runs logs abc123 --job build
+kici runs logs abc123 --follow
+```
+
+#### kici runs rerun
 
-Cancel a running workflow or all runs on a branch.
+Re-trigger a completed run. Prints the new run id. The server enforces a short
+cooldown between reruns of the same run.
 
 ```bash
-kici cancel [run-id] [options]
+kici runs rerun <run-id> [options]
 ```
 
-**Arguments:**
+| 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 |
 
-**Options:**
-
 | Option            | Default | Description                                 |
 | ----------------- | ------- | ------------------------------------------- |
 | `--force`         | `false` | Force cancel (kill immediately, skip hooks) |
 | `--branch <name>` | none    | Cancel all in-progress runs on this branch  |
 
-**Examples:**
-
 ```bash
-# Cancel a specific run
-kici cancel abc123
-
-# Force cancel (kill immediately)
-kici cancel abc123 --force
-
-# Cancel all runs on a branch
-kici cancel --branch feature/wip
+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](approvals.md) so the run resumes. Identify the held element by run ID, optionally narrowed to a job and step.
@@ -5779,6 +6059,70 @@ kici admin drain-worker --url http://worker-2.internal:10143
 | 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](./provenance.md). 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>` | yes      | Trusted issuer (see below). 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:** the verifier never trusts the issuer named inside the token — you supply the trusted issuer out-of-band via `--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
+# Online: verify a bundle against a deployed 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 flag, 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:
@@ -6110,7 +6454,7 @@ The lock file (`kici.lock.json`) is a JSON file with the following top-level fie
 
 | Field           | Description                                                                                                                                                                                                                                                                                                                                           |
 | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `schemaVersion` | Lock file schema version (currently 15). Incremented on breaking format changes.                                                                                                                                                                                                                                                                      |
+| `schemaVersion` | Lock file schema version (currently 17). 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. |
@@ -6428,7 +6772,7 @@ kici run remote push-main --junit results.xml
 kici run remote push-main --no-wait
 
 # Check status later
-kici status <run-id>
+kici runs show <run-id>
 ```
 
 ### Cancellation
@@ -6596,17 +6940,17 @@ kici run remote --history
 ### Run details
 
 ```bash
-# Show run summary (tries orchestrator first, falls back to local history)
-kici status <run-id>
+# Show run summary (reads the Platform, falls back to local history)
+kici runs show <run-id>
 
 # Show full logs
-kici status <run-id> --logs
+kici runs logs <run-id>
 
 # Show logs for a specific job
-kici status <run-id> --logs --job build
+kici runs logs <run-id> --job build
 
 # Machine-readable output
-kici status <run-id> --json
+kici runs show <run-id> --json
 ```
 
 ## Scaffolding with kici init
@@ -6723,6 +7067,178 @@ To actually change how you sign in, use your account console as described above.
 
 ---
 
+## Approval gates
+
+Source: https://docs.kici.dev/user/approvals/
+
+An **approval gate** pauses execution until an authorized person approves it. Execution resumes from exactly where it paused; a rejection (or an expired hold) fails the run.
+
+You declare a gate in your workflow with `requireApproval`. It is available at three levels of granularity:
+
+- **Step** — pause mid-job, before a specific step runs. The agent holds the live workspace (with all prior-step state intact) for the duration of the wait.
+- **Job** — hold the job before any of its steps run.
+- **Workflow** — hold the whole run before any job is dispatched.
+
+Approvers are named as **teams** and **users**. A team is an operator-defined group of org members; your workflow code may name a team but can never change its membership, which is what makes a team clause a real gate rather than a suggestion. See [Approval gates (operator guide)](../operator/approvals.md) for how operators define teams, the approval queue, and expiry; see [the architecture overview](../architecture/approvals.md) for how a hold is evaluated and resumed.
+
+## Quick start
+
+Hold a deploy job until a member of the `leads` team approves:
+
+```typescript
+import { workflow, job, step, push } from '@kici-dev/sdk';
+
+export default workflow('deploy', {
+  on: [push({ branches: ['main'] })],
+  jobs: [
+    job('deploy-production', {
+      runsOn: 'default',
+      requireApproval: [{ team: 'leads' }],
+      steps: [step('deploy', async (ctx) => ctx.$`deploy --prod`)],
+    }),
+  ],
+});
+```
+
+When the run reaches this job, it is held instead of dispatched. The held run appears in the dashboard approval queue and can be released from there or with the [`kici approve`](#approving-from-the-cli) command. Once a member of `leads` approves, the job dispatches normally.
+
+## The `requireApproval` field
+
+`requireApproval` accepts three forms.
+
+### Shorthand: `true`
+
+```typescript
+job('deploy', {
+  runsOn: 'default',
+  requireApproval: true,
+  steps: [
+    /* ... */
+  ],
+});
+```
+
+`requireApproval: true` holds the element until **any** org member who can act on approvals signs off — anyone with the `environments:write` or `ci_trust:write` permission. Use it when you want a manual gate without restricting who may release it.
+
+### Approver list (AND)
+
+```typescript
+requireApproval: [{ team: 'leads' }, { user: 'cto' }],
+```
+
+A list of approver clauses is an **AND** list: every clause must be satisfied before the element is released.
+
+- `{ team: 'leads' }` is satisfied once **any** member of the `leads` team approves.
+- `{ user: 'cto' }` is satisfied once the user `cto` approves.
+
+A single approver may satisfy more than one clause. If `cto` is also a member of `leads`, one approval from `cto` satisfies both `{ team: 'leads' }` and `{ user: 'cto' }`, releasing the element. A user is named by their KiCI user identifier (their linked identity), and a team by its name as defined by your operator.
+
+There is no OR or nested logic — clauses are always a flat AND list.
+
+### Object form: reason and timeout
+
+```typescript
+requireApproval: {
+  approvers: [{ team: 'security' }, { team: 'leads' }],
+  reason: 'Production deploy requires security + leads sign-off',
+  timeout: 7200, // seconds
+},
+```
+
+| Field       | Type               | Description                                                                                         |
+| ----------- | ------------------ | --------------------------------------------------------------------------------------------------- |
+| `approvers` | `ApproverClause[]` | The AND list of `{ team }` / `{ user }` clauses. An empty list means "any approval-capable member". |
+| `reason`    | `string`           | A human-readable label shown in the dashboard queue and the held-for-approval status check.         |
+| `timeout`   | `number`           | Per-gate expiry in **seconds**, overriding the org default. On expiry the element is rejected.      |
+
+When `timeout` is omitted, the gate uses the org's default approval expiry (set by the operator). On expiry, the held element is rejected and the run fails — see [expiry](../operator/approvals.md#expiry).
+
+## Granularity
+
+The same `requireApproval` field is accepted on a workflow, a job, and a step.
+
+### Workflow-level
+
+A workflow-level gate holds the entire run before any job is dispatched:
+
+```typescript
+export default workflow('release', {
+  on: [push({ branches: ['main'] })],
+  requireApproval: [{ team: 'release-managers' }],
+  jobs: [buildJob, publishJob],
+});
+```
+
+### Job-level
+
+A job-level gate holds just that job; other jobs in the run proceed normally:
+
+```typescript
+job('publish', {
+  runsOn: 'default',
+  requireApproval: [{ team: 'leads' }],
+  steps: [
+    /* ... */
+  ],
+});
+```
+
+### Step-level
+
+A step-level gate pauses mid-job, immediately before the named step. Earlier steps in the job have already run and their workspace state is preserved across the wait:
+
+```typescript
+job('migrate-and-deploy', {
+  runsOn: 'default',
+  steps: [
+    step('build-plan', async (ctx) => ctx.$`./gen-migration-plan.sh`),
+    step('apply-migration', {
+      requireApproval: [{ team: 'dba' }],
+      run: async (ctx) => ctx.$`./apply-migration.sh`,
+    }),
+    step('deploy', async (ctx) => ctx.$`deploy --prod`),
+  ],
+});
+```
+
+Here `build-plan` runs, then the job pauses for a `dba` approval. On approval, `apply-migration` runs against the exact workspace `build-plan` produced, followed by `deploy`. A rejection or expiry fails the job.
+
+Because a step-level hold keeps an agent and its workspace occupied for the whole human wait, prefer job- or workflow-level gates when you do not need prior-step state, and keep step-level timeouts short. See the [operator note on agent occupancy](../operator/approvals.md#agent-occupancy-during-step-level-holds).
+
+## Mandatory vs. explicit gates
+
+`requireApproval` is the **explicit** gate — a deliberate "pause for a human here" written by the workflow author. It composes with the **mandatory** gate an operator can attach to a protected environment via required reviewers (see [Environments](environments.md#required-reviewers)). When both apply to the same job, all clauses from both sources must be satisfied before the job is released. The two funnel into one held-element mechanism, so the dashboard queue and `kici approve` work the same way regardless of which source held the element.
+
+## Approving from the CLI
+
+Approve or reject a held element with the `kici` CLI:
+
+```bash
+# Approve a workflow-level hold
+kici approve <run-id>
+
+# Approve a held job
+kici approve <run-id> --job deploy-production
+
+# Approve a held step
+kici approve <run-id> --job migrate-and-deploy --step apply-migration
+
+# Reject (a reason is required)
+kici reject <run-id> --job deploy-production --reason "Wrong release branch"
+```
+
+You must be eligible for at least one unsatisfied clause — being a member of a named team or being a named user. The orchestrator verifies eligibility against the operator-defined teams, so naming a team in your workflow can never let an ineligible person release the gate. The command reports whether the element was released, how many clauses remain, or that it was rejected. See [`kici approve`](cli-reference.md#kici-approve) for the full command reference.
+
+You can also approve from the dashboard approval queue. See [Dashboard](dashboard.md#approval-queue).
+
+## See also
+
+- [Environments](environments.md) — operator-required reviewers on protected environments.
+- [Approval gates (operator guide)](../operator/approvals.md) — teams, the approval queue, expiry, and self-approval.
+- [Approval gates (architecture)](../architecture/approvals.md) — the unified hold model and the step-level round-trip.
+
+---
+
 ## Concurrency groups
 
 Source: https://docs.kici.dev/user/concurrency/
@@ -7199,7 +7715,7 @@ The page uses a responsive multi-panel layout that adapts to screen width:
 
 - **Wide desktop (>= 1200px)** -- three-panel layout with a resizable job tree (left), content area (center), and metadata sidebar (right). Two draggable dividers between the panels let you resize them. Panel sizes persist to `localStorage`.
 - **Medium desktop (< 1200px)** -- two-panel layout with the job tree and content area. Metadata is accessible via a "Show metadata" drawer button.
-- **Mobile (< 768px)** -- stacked layout with the job tree at the top and content below. Metadata is available as a tab alongside Logs, Payload, Timeline, and Summary.
+- **Mobile (< 768px)** -- stacked layout with the job tree at the top and content below. Metadata is available as a tab alongside Logs, Payload, Timeline, Graph, and Summary.
 
 ### Run header
 
@@ -7265,7 +7781,9 @@ The content area has the following tabs:
 - **Logs** (default) -- shows log output for the selected job or step
 - **Payload** -- webhook payload viewer showing the raw event payload that triggered the run. This tab appears only for runs triggered by a webhook event (and re-runs of those, which copy the original payload); runs started by a schedule, manual schedule, lifecycle event, or another run carry no payload, so the tab is hidden for them
 - **Timeline** -- CSS Gantt chart showing the execution timeline of all jobs, with percentage-based bars and striped animation for running jobs. A **Provisioning** milestones section between the dispatch and execution phases plots scaler lifecycle events for the run — including a **Provisioning failed** marker when the scaler could not bring an agent up
+- **Graph** -- dependency graph (DAG) view of the run's jobs: each job is a node, and arrows point from a job to the jobs that depend on it. Matrix jobs appear as one node per variant. Each node shows the job name, status, and duration; a job's left accent border and the status line are colored by run state (running nodes pulse, failed nodes are red, skipped nodes are dimmed). Click a node to open that job's details (the same selection the Timeline and right panel use); hover a node to highlight what it depends on and what depends on it. Dependency edges flagged to run even when the upstream failed are drawn as dashed orange arrows. The Timeline tab remains the place to see durations and overlap on a time axis
 - **Summary** -- contextual overview scoped to the current selection (run-level trigger/repo/timing info, or job-level execution context with environment variables, runtime info, and sandbox details)
+- **Attestations** -- build-provenance attestations produced by the run's steps (via `ctx.attestProvenance`), one row per attested artifact with a **verified** badge and a bundle download. See [Build provenance and attestations](./provenance.md#viewing-attestations-in-the-dashboard) for what the badge checks and how to verify a bundle against a specific file.
 
 On wide desktop (>= 1200px), Metadata is shown in a dedicated sidebar panel instead of as a tab.
 
@@ -9184,29 +9702,37 @@ registries: [
 
 ## Security model
 
-- **Per-environment scoping.** Every `tokenSecret` and `installEnv` entry is qualified with an environment name. The orchestrator runs the same protection-rule pipeline (branch / trust / concurrency / reviewer / wait-timer) against each named environment **before** resolving any secret, so a workflow that wants a `production` token from a feature branch is rejected exactly like a job that tries to deploy to `production` from a feature branch.
+- **Per-environment scoping.** Every `tokenSecret` and `installEnv` entry is qualified with an environment name. The orchestrator runs the same protection-rule pipeline (branch / trust / concurrency / reviewer / wait-timer) against each named environment **before** resolving any secret, so a workflow that wants a `production` token from a feature branch is rejected exactly like a job that tries to deploy to `production` from a feature branch. A reviewer-gated install environment **pauses** the whole workflow dispatch as a workflow-scoped held run instead of resolving the token — see [Reviewer-gated installs](#reviewer-gated-installs) below.
 - **Untrusted contributors get no tokens.** When a fork PR is dispatched and the contributor-trust resolution returns anything other than `trusted`, the orchestrator strips both `npmRegistries` and `installEnvSecrets` out of the dispatch. The install runs without auth and fails naturally on the first private dep — fork PRs cannot ever observe a registry token, even if a misconfigured environment lacks an explicit `requiredTrustTier`.
 - **Lifecycle scripts disabled.** Whenever a private registry is in scope, the agent runs the install with `--ignore-scripts` (npm or pnpm alike). A malicious `preinstall` / `postinstall` hook in committed `package.json` cannot read the synthesized token env vars, even though they exist in the install subprocess. For a pnpm workspace, the agent builds your in-repo dependency closure as a separate step **after** the install's auth is torn down, so build scripts never see the tokens either.
 - **Stderr is redacted.** If the install fails, the agent masks every token literal out of the surfaced stderr / stdout chunks before logging.
 - **Job-scoped env-var names.** The synthesized auth env var is `KICI_NPM_TOKEN_<jobIdShort>_<i>` where `jobIdShort` is the first 8 chars of the dispatched job id. The name is unguessable from outside the install subprocess and not reused across jobs.
 - **`.npmrc` restored.** Whatever the agent appended for one install is stripped (or the file unlinked) on cleanup, so the workspace is never permanently modified.
 
+## Reviewer-gated installs
+
+When the named install environment carries a protection rule that holds — a required reviewer (`hold`) or a wait timer (`wait`) — the install gate **pauses the whole workflow dispatch** instead of rejecting it. The run is created in the `held` state, no jobs are queued, and a workflow-scoped row appears on the held-runs page with a `Workflow` scope badge.
+
+- **Reviewer hold:** the run waits for an approver. On approval the dispatch resumes from the install gate, resolves the token, and dispatches its jobs as a normal run. On rejection the run transitions to `cancelled` — no jobs ever run.
+- **Wait timer:** the run waits out the timer and resumes automatically when it elapses.
+
+A `reject` protection outcome (for example a disabled environment or a branch the environment forbids) still fails the dispatch loudly with a clear reason, exactly as before — the orchestrator never dispatches a run with an unresolved install token.
+
 ## Limitations
 
 - **`registries:` is workflow-level only in v1.** Per-job overrides aren't supported — there is one shared `.kici/` per workspace, so a per-job `registries:` would be physically nonsensical.
-- **A non-pass protection-rule outcome rejects the whole workflow dispatch.** Today, if the named environment requires reviewer approval (`hold` action) or hits concurrency (`queue` / `wait`) for the install gate, the entire workflow dispatch is rejected with a clear reason. Workflow-scoped held-runs (which would let the install wait for an approver instead of failing outright) are tracked as a follow-up — until then, choose an environment whose protection rules `pass` for the branches that need to install private deps.
 - **Container registries (Docker Hub, ECR, GHCR) are out of scope.** This feature covers **npm** registry auth only. Container image pulls travel through the executor backend's own credential paths.
 
 ## Observability
 
 The orchestrator exposes Prometheus counters and a histogram under the `kici_orch_install_secrets_*` prefix on its `/metrics` endpoint. They populate the **Install secrets resolution** Grafana dashboard and let operators graph install-secrets activity without digging through Loki.
 
-| Metric                                                        | Type      | Labels                         | What it tells you                                                                                                                                                                              |
-| ------------------------------------------------------------- | --------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `kici_orch_install_secrets_decisions_total`                   | Counter   | `decision`, `reason`           | Pass / reject volume. Reject reasons enumerate the failure mode: `malformed_ref`, `invalid_url_scheme`, `env_not_found`, `protection_rule_block`, `missing_token`, `missing_install_env`, etc. |
-| `kici_orch_install_secrets_npm_registry_used_total`           | Counter   | `channel`, `provider`, `scope` | Per-channel + per-scope usage. `channel=registries` is Option A, `channel=install_env` is Option C. `scope=default` marks a no-scope default registry; `scope=-` marks Option C entries.       |
-| `kici_orch_install_secrets_contributor_stripped_total`        | Counter   | `trust_tier`                   | Number of dispatches where registry tokens were stripped because the contributor tier wasn't `trusted` (fork PRs from unknown / known contributors). Expected to be 0 in single-tenant orgs.   |
-| `kici_orch_install_secrets_token_resolution_duration_seconds` | Histogram | `environment`                  | Latency of per-environment secret resolution. Pathological tails (>500ms) usually mean a Vault timeout or a slow Postgres replica.                                                             |
+| Metric                                                        | Type      | Labels                         | What it tells you                                                                                                                                                                                                                                                                                       |
+| ------------------------------------------------------------- | --------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `kici_orch_install_secrets_decisions_total`                   | Counter   | `decision`, `reason`           | Pass / reject / hold volume. `decision=hold` (reason `held`) counts dispatches paused at a reviewer-gated install environment. Reject reasons enumerate the failure mode: `malformed_ref`, `invalid_url_scheme`, `env_not_found`, `protection_rule_block`, `missing_token`, `missing_install_env`, etc. |
+| `kici_orch_install_secrets_npm_registry_used_total`           | Counter   | `channel`, `provider`, `scope` | Per-channel + per-scope usage. `channel=registries` is Option A, `channel=install_env` is Option C. `scope=default` marks a no-scope default registry; `scope=-` marks Option C entries.                                                                                                                |
+| `kici_orch_install_secrets_contributor_stripped_total`        | Counter   | `trust_tier`                   | Number of dispatches where registry tokens were stripped because the contributor tier wasn't `trusted` (fork PRs from unknown / known contributors). Expected to be 0 in single-tenant orgs.                                                                                                            |
+| `kici_orch_install_secrets_token_resolution_duration_seconds` | Histogram | `environment`                  | Latency of per-environment secret resolution. Pathological tails (>500ms) usually mean a Vault timeout or a slow Postgres replica.                                                                                                                                                                      |
 
 The dashboard JSON lives at `infra/terraform/modules/grafana/dashboards/install-secrets.json`; if you maintain your own monitoring stack, you can import it directly.
 
@@ -9218,6 +9744,197 @@ The dashboard JSON lives at `infra/terraform/modules/grafana/dashboards/install-
 
 ---
 
+## Build provenance and attestations
+
+Source: https://docs.kici.dev/user/provenance/
+
+Build provenance is a signed, verifiable statement of **what produced an
+artifact** — the source repository, commit, ref, workflow path, and builder that
+ran. When a workflow step attests an artifact, KiCI records that statement,
+signs it, and makes it retrievable so anyone can later prove the artifact came
+from a specific KiCI run and was not swapped along the way.
+
+This is the same idea behind supply-chain attestation systems like
+[SLSA](https://slsa.dev/spec/v1.0/provenance): a downstream consumer (a release
+gate, a security audit, a `"show me the provenance"` request) can verify the
+artifact's origin without trusting the person who handed it over.
+
+## What an attestation contains
+
+An attestation is a self-contained bundle holding three things:
+
+- An **in-toto SLSA v1.0 statement** describing the build: the subject artifact
+  (name + content digest) and the provenance predicate (source repository,
+  commit, ref, workflow, run/job identifiers, timestamps).
+- A **[DSSE](https://github.com/secure-systems-lab/dsse) signature** over that
+  statement, made with an ephemeral signing key generated for the run.
+- A short-lived **OIDC identity token** issued by the KiCI platform that binds
+  the signature to the build identity. The token's identity claims
+  (`repository`, `ref`, `sha`, run/job ids) are derived by the platform from the
+  run itself — a step cannot forge them.
+
+Because the bundle carries the identity token and the public signing key, it is
+**offline-verifiable**: a verifier checks it against the platform's published
+signing keys with no per-attestation online lookup.
+
+## Attesting an artifact in a workflow
+
+Call `ctx.attestProvenance({ subject })` from a step after you have produced the
+artifact:
+
+```typescript
+import { workflow, job, step } from '@kici-dev/sdk';
+
+export default workflow('release', {
+  on: { push: { branches: ['main'] } },
+  jobs: [
+    job('publish', {
+      steps: [
+        step('build', async (ctx) => {
+          await ctx.$`npm pack`;
+        }),
+        step('attest', async (ctx) => {
+          const result = await ctx.attestProvenance({
+            subject: { name: 'my-pkg-1.2.3.tgz', path: 'my-pkg-1.2.3.tgz' },
+          });
+          ctx.log.info(`Attestation stored at ${result.storageKey}`);
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+The **subject is caller-supplied** — you name the artifact and give KiCI either a
+path or a precomputed digest:
+
+- `{ name, path }` — a path relative to the step working directory. KiCI reads
+  the file and computes its SHA-256 digest.
+- `{ name, digest }` — a precomputed digest. For a container image, pass the OCI
+  manifest digest your build tool emitted:
+
+  ```typescript
+  await ctx.attestProvenance({
+    subject: { name: 'ghcr.io/acme/app', digest: { sha256: '<manifest-digest>' } },
+  });
+  ```
+
+The identity token is fetched and masked in logs automatically — you never
+handle it. The call returns `{ storageKey, subjectDigest, bundleMediaType }`
+identifying the stored bundle.
+
+`ctx.attestProvenance` is only available inside a running job step. Calling it
+during local execution rejects with a clear error.
+
+### Requesting a raw identity token
+
+`ctx.attestProvenance` builds on a lower-level primitive you can call directly
+when you need the identity token for a different tool:
+
+```typescript
+step('mint', async (ctx) => {
+  const { token, expiresIn } = await ctx.kici.oidc.token({ audience: 'sigstore' });
+  ctx.log.info(`Got an ID token valid for ${expiresIn}s`);
+  // Hand `token` to a tool that exchanges it with a service trusting the issuer.
+});
+```
+
+The token is a short-lived (about 10 minutes) signed JWT scoped to the current
+run and job. Its identity claims (`repository`, `ref`, `sha`, `kici_run_id`,
+`kici_job_id`) are derived by the platform from the run context, so a step cannot
+spoof them. The returned token value is automatically masked in step logs, and
+the step never holds platform credentials — the request is relayed through the
+orchestrator, which mints the token on the step's behalf. Like
+`attestProvenance`, it is only available inside a running job step.
+
+## Verifying an attestation
+
+Verify a bundle with the `kici verify-attestation` command. It establishes the
+full chain offline: the identity token verifies against the trusted issuer's
+JWKS, the DSSE signature verifies against the bundled signing key, and the
+statement's build context must match the token's identity claims (a mismatch is
+a hard failure).
+
+```bash
+kici verify-attestation [artifact] --bundle <path-or-url> --trust-root <url-or-file>
+```
+
+You supply the trusted issuer out-of-band via `--trust-root` — the verifier
+never trusts the issuer named inside the token. There are 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, for air-gapped verification:
+
+  ```json
+  {
+    "issuer": "https://platform.example/issuer",
+    "jwks": {
+      "keys": [
+        { "kty": "EC", "crv": "P-256", "x": "...", "y": "...", "alg": "ES256", "kid": "..." }
+      ]
+    }
+  }
+  ```
+
+Pass an optional `[artifact]` to also digest-check the file against the
+attestation subject — this is what binds the attestation to a specific set of
+bytes. Omit it to verify the signatures and identity only. Use `--json` for a
+machine-readable result. The command exits `0` when everything verifies and `1`
+when it does not (or on an error such as a missing flag or unreachable trust
+root).
+
+```bash
+# Verify a bundle against a deployed issuer, digest-checking the artifact:
+kici verify-attestation ./dist/app.tgz \
+  --bundle ./app.tgz.kici.json \
+  --trust-root https://platform.example/issuer
+
+# 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
+```
+
+The full flag reference is in the [CLI reference](./cli-reference.md#kici-verify-attestation).
+
+## Viewing attestations in the dashboard
+
+<!-- help:run-attestations#viewing-attestations-in-the-dashboard -->
+
+The run detail page has an **Attestations** tab listing each artifact a run's
+steps attested (via `ctx.attestProvenance`), one row per artifact.
+
+Each row shows:
+
+- **Status** — a **verified** badge computed in your browser. It checks the
+  attestation's signature, the build identity, and the build context against the
+  trusted provenance issuer. **verified** (green) means all of those pass;
+  **failed** (red) shows why in a tooltip; **unverifiable** means the provenance
+  issuer is not configured.
+- **Job / Artifact / Digest / Created** — the producing job, the artifact name,
+  its content digest, and when it was recorded.
+- **Download** — saves the signed bundle as a `.sigstore.json` file.
+
+The badge does **not** re-hash the artifact bytes — the dashboard does not have
+the artifact. To bind the attestation to a specific file, run
+`kici verify-attestation <artifact> --bundle <bundle>`. A run with no
+attestations shows an empty state.
+
+<!-- /help:run-attestations -->
+
+## See also
+
+- [SDK runtime reference](./sdk/runtime.md) — the `ctx.attestProvenance` and
+  `ctx.kici.oidc.token` step APIs in full.
+- [CLI reference](./cli-reference.md#kici-verify-attestation) — every
+  `kici verify-attestation` flag and exit code.
+
+---
+
 ## Secrets
 
 Source: https://docs.kici.dev/user/secrets/
@@ -9438,6 +10155,45 @@ export default workflow('deploy', {
 });
 ```
 
+### Injecting decrypted sops values into the environment
+
+KiCI does **not** scan your repository for `*.enc.yaml` files and auto-decrypt them into the environment at job init — nothing in a job runs `sops` on your behalf, and resolved secrets are never auto-injected as environment variables (see [Security notes](./sdk/runtime.md#security-notes)). Decryption is always something your workflow does explicitly: provision the age (or other) decryption key as a KiCI secret, expose it for the step, run `sops -d`, and decide what to do with the output.
+
+When you want the decrypted values available as environment variables — not just written to a file — decrypt early and export the values through `$KICI_ENV` (or `ctx.setEnv`). Anything appended to `$KICI_ENV` becomes an environment variable for every later step in the same job, so a single decrypt step can populate the environment for the whole job:
+
+```typescript
+import { workflow, job, step, push } from '@kici-dev/sdk';
+
+export default workflow('deploy', {
+  on: push({ branches: ['main'] }),
+  jobs: [
+    job('decrypt-and-deploy', {
+      runsOn: 'default',
+      environment: 'production',
+      steps: [
+        step('decrypt-to-env', async (ctx) => {
+          await ctx.secrets.exposeFile('SOPS_AGE_KEY_FILE', {
+            sources: ctx.secrets.list().filter((k) => k.startsWith('AGE_KEY_')),
+            divider: '\n',
+          });
+          // Decrypt to dotenv format, then append every KEY=value line to
+          // $KICI_ENV so subsequent steps see them as environment variables.
+          await ctx.$`sops -d --output-type dotenv secrets.enc.yaml >> "$KICI_ENV"`;
+        }),
+        step('deploy', async (ctx) => {
+          // Values decrypted above are now ordinary env vars here.
+          await ctx.$`./deploy.sh`;
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+Decrypted values exported this way follow the same rules as any other `$KICI_ENV` / `ctx.setEnv` export: last-write-wins on a repeated key, and a key that collides with an operator-injected secret is ignored (the operator value wins). See [Exporting env from shell commands](./sdk/runtime.md#exporting-env-from-shell-commands-kici_env--kici_path) for the full `$KICI_ENV` contract.
+
+If you only need the decrypted material as a file on disk (the common `kubectl` / `gcloud` case), skip the env hop and redirect to a file instead — see the [canonical sops example](#canonical-sops-example) above.
+
 ## API reference
 
 | Method       | Signature                                                                | Description                                                                        |
@@ -9800,6 +10556,123 @@ and confirm the App is installed on that repo.
 
 ---
 
+## Local filesystem (file://) source
+
+Source: https://docs.kici.dev/user/providers/local-file/
+
+The **local** provider lets the orchestrator run workflows from a git
+repository that already lives on the agent's filesystem — cloned via a
+`file://` URL rather than fetched from a remote forge. There is no webhook
+from GitHub or GitLab; the operator drives runs explicitly with the
+`kici-admin` CLI or a generated `post-receive` hook.
+
+> **This is an operator-curated source, not daily developer CI.** Use it for
+> globally-registered or policy workflows the operator controls — a vendored
+> repo baked into an agent image, a repo synced onto a host out-of-band, a
+> golden internal pipeline. For ordinary per-developer CI driven by pull
+> requests and pushes, use the [GitHub App provider](./github.md) or the
+> [universal-git provider](./universal-git.md) against a real forge.
+
+## Trust caveat (read first)
+
+A local source uses signature verification `none` — there is no remote forge
+to sign the webhook payload, so the orchestrator cannot authenticate the
+trigger. **Only register repos you trust.** Anyone who can reach the
+orchestrator's webhook route for this source, or push to the repo on disk,
+can drive a run. Treat the repo path as a trusted operator input, the same
+way you treat the orchestrator's own configuration.
+
+## Register a source
+
+```bash
+kici-admin source add local \
+  --org <orgId> \
+  --path /abs/path/to/repo \
+  --name my-local-repo
+```
+
+- `--path` must be an **absolute** directory on the agent filesystem. It is
+  the base path the orchestrator's lock-file fetcher reads
+  (`<path>/.kici/kici.lock.json`) and the base for the `file://` clone the
+  agent performs.
+- `--clone-url-base <url>` is optional. By default the agent clones via
+  `file://<path>`. Supply a `git://` or `http://` base when the agent does
+  **not** share the orchestrator's filesystem and must fetch the repo over a
+  git server instead (see "Per-scaler reachability" below).
+
+Update the path or name later:
+
+```bash
+kici-admin source update-local <id> --path /new/abs/path
+kici-admin source update-local <id> --name new-name
+```
+
+Remove it:
+
+```bash
+kici-admin source remove <routingKey> --local
+```
+
+List and inspect (local sources render their `repoBasePath`):
+
+```bash
+kici-admin source list --org <orgId>
+kici-admin source get <id>
+```
+
+## Trigger runs
+
+A local repo has no forge to send webhooks, so you trigger runs yourself.
+
+**One-shot, by hand:**
+
+```bash
+kici-admin source trigger-local <id>
+```
+
+The command reads the repo's current HEAD ref and commit SHA, builds a
+GitHub-shaped `push` payload, and POSTs it to the orchestrator's generic
+webhook route. Override the ref/sha/event explicitly when needed:
+
+```bash
+kici-admin source trigger-local <id> --event push --ref refs/heads/main --sha <sha>
+```
+
+**On every push, via a hook:**
+
+```bash
+kici-admin source install-hook <id>
+```
+
+This writes a `post-receive` hook into the repo so that every push to it
+triggers a run automatically — the local equivalent of a forge webhook.
+
+## Per-scaler reachability (operator's responsibility)
+
+The orchestrator accepts a local source on **any** scaler backend and does
+**not** verify that the repo is actually reachable inside the agent. Making
+the path reachable is the operator's job. On a container or Firecracker
+scaler the orchestrator logs a reachability warning when it registers the
+source, but it does not reject it.
+
+| Scaler      | How the repo must be reachable in the agent                                                                                                                                                                    |
+| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| bare-metal  | The agent runs on the host, so the `--path` host directory is used directly.                                                                                                                                   |
+| container   | Bake the repo into the agent image, or bind-mount it at the **same absolute path** the source was registered with. Alternatively register `--clone-url-base` pointing at a git server the container can reach. |
+| Firecracker | The repo must be present on the microVM rootfs at the registered path, or reachable via a `--clone-url-base` git server.                                                                                       |
+
+If the path is not reachable inside the agent, the clone fails at run time —
+the run is created and then fails, rather than being silently dropped.
+
+## See also
+
+- [Universal-git provider](./universal-git.md) — for a remote forge (or any
+  `http://` git server) when there is no shared filesystem.
+- [GitHub App provider](./github.md) — the flagship source for pull-request
+  CI with Checks.
+
+---
+
 ## Universal-git provider
 
 Source: https://docs.kici.dev/user/providers/universal-git/
@@ -9826,6 +10699,13 @@ No mirror, no GitHub App, no `checkout: false` escape hatch. The same
 trigger matching, global-workflow policy, and agent execution pipeline
 that back the GitHub App source also serve universal-git sources.
 
+> **No shared filesystem between orchestrator and agent?** Universal-git is
+> the right choice for the **remote-agent** case — point it at an `http://`
+> git server and the agent clones over the network. When the repo instead
+> lives on the agent's own filesystem (a vendored / operator-curated repo),
+> use a [local `file://` source](./local-file.md) and drive it with the
+> `kici-admin` CLI.
+
 ## Which preset do I need?
 
 KiCI ships canonical presets so you don't have to spell out JSONPath for
@@ -10045,7 +10925,7 @@ with the right PEM.
 
 Source: https://docs.kici.dev/architecture/data-flows/
 
-This document describes the key data flows through the KiCI architecture: webhook delivery, job execution, dependency caching, re-run and cancel, trace ID propagation, internal event routing, and generic webhook ingestion.
+This document describes the key data flows through the KiCI architecture: webhook delivery, job execution, developer-initiated remote runs, dependency caching, re-run and cancel, trace ID propagation, internal event routing, and generic webhook ingestion.
 
 > **Lock file schema version:** The lock file uses schema version 15, which adds per-job init config on top of v14's declarative cache specs, v11's `LockInlineValue` for pure function inline evaluation, v10's simplified negative patterns (! prefix in repos/paths arrays), v9's global workflow repos matching, and v8's runsOn polymorphic type support.
 
@@ -10117,6 +10997,41 @@ The agent delegates job execution to an `ExecutionSandbox` (container, bare-meta
 7. **Report** -- Send final `job.status` back to orchestrator with step results and timing
 8. **Cleanup** -- Tear down sandbox and remove work directory
 
+## Remote run flow (`kici run remote`)
+
+A developer running `kici run remote` from a working tree initiates a run through the three-tier relay without a provider webhook. The flow splits into two independent planes: a **control plane** through the Platform relay, and a **data plane** that uploads the working-tree overlay straight to object storage.
+
+```
+Developer machine                Platform relay            Orchestrator           Object store
+      |                               |                         |                      |
+      |-- upload-init (control) ----->|--- WS relay ----------->|                      |
+      |   (org, cluster, overlay      |                         |-- mint presigned     |
+      |    metadata, inline lock)     |                         |   PUT URL ---------->|
+      |<-- presigned PUT URL ---------|<--- WS relay -----------|                      |
+      |                               |                         |                      |
+      |== overlay tarball PUT (data plane) ===========================================>|
+      |                               |                         |                      |
+      |-- trigger (control) --------->|--- WS relay ----------->|-- dispatch jobs       |
+      |                               |                         |   (agents fetch       |
+      |                               |                         |    overlay)           |
+      |-- poll logs + status -------->|--- WS relay ----------->|                      |
+      |<-- log chunks + status -------|<--- WS relay -----------|                      |
+```
+
+### Control plane
+
+Run initiation (`upload-init`), the trigger, status polling, log retrieval, and cancellation all flow from the developer machine to the Platform, which relays them over its WebSocket connection to the org's orchestrator. The developer machine never talks to the orchestrator's HTTP API directly. 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 between the developer machine and the orchestrator.
+
+### Data plane
+
+The working-tree overlay tarball uploads **directly** from the developer machine to the orchestrator's object store via a pre-signed PUT URL minted during `upload-init`. The overlay bytes never pass through the Platform. Because of this split, only the object store needs to be reachable from the developer machine — the orchestrator can sit behind a private network. See [Storage layout](../operator/orchestrator/storage-layout.md) for the upload-endpoint configuration.
+
+### Org anchor
+
+The run is dispatched to the developer's active organization (selected with `kici org use`, or overridden per-run). The orchestrator anchors its bound organization with a system-managed **remote source** (routing key `remote:<orgId>`) that it auto-provisions — no manual webhook source is required, so a zero-source org is immediately routable for remote runs. The Platform forces the run's routing key to `remote:<orgId>` server-side; the developer never sets a routing key. When an org has more than one connected orchestrator cluster, the CLI selects the target cluster explicitly (or relies on the per-org default), and a single connected cluster is auto-selected.
+
+Remote runs are offered by the Platform; an orchestrator with no Platform connection cannot serve them. Executing workflow steps on the developer machine with no orchestrator is the separate `kici run local` path.
+
 ## Source and dependency caching flow
 
 KiCI runs two orchestrator-side caches — the **source tarball cache** (raw `.kici/` directory minus `node_modules/`) and the **dependency tarball cache** (packed `node_modules/`). Both use a build-then-execute pattern: the orchestrator checks the caches before dispatching execution jobs, and if the source cache is cold a build agent populates both in one pass.
@@ -10947,7 +11862,7 @@ Shared business logic used by all three tiers. Single source of truth for cross-
 - Environment allowlist (safe env var filtering)
 - Secrets management (secret context resolution)
 - Environment model (scoped secrets, env merge, protection gates)
-- Label utilities (platform label derivation, runsOn normalization, `kici:*` reserved namespace, role labels)
+- Label utilities (platform label derivation, runsOn normalization, `kici:*` set-only reserved namespace, role labels)
 - Audit policy and retention (per-action access-log sampling, warm-retention windows for cold-store eligibility, federated activity row schema)
 - Scaler backend type enum (`container`, `bare-metal`, `firecracker`, `kubernetes`)
 - Registration trigger type enum (registerable trigger discriminator)