@kici-dev/compiler 0.1.16 → 0.1.18

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,14 +312,14 @@ 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, yarn classic (v1), and yarn berry (v2+). A dependency that points outside the cloned repo cannot be resolved.
 
 In practice:
 
 - **From a registry** — the common case. Pin a published version (a private registry works — see [Private registries](./private-registries.md)). Available for any package manager.
-- **From an in-repo workspace sibling** — if your `.kici/` is a member of a **pnpm workspace**, it can depend on a sibling package in the same repo via `workspace:*`. The whole repo is cloned, so the sibling is present and resolves; the agent also builds your `.kici/` dependency closure after install, so a sibling's build output exists before the workflow that imports it loads. A `file:`/`link:`/`portal:` path is allowed only when it stays inside the repository.
+- **From an in-repo workspace sibling** — if your `.kici/` is a member of a **pnpm workspace** or a **yarn berry workspace** (a `workspaces` array in the repo-root `package.json`), it can depend on a sibling package in the same repo via `workspace:*` (yarn berry also accepts `portal:`). The whole repo is cloned, so the sibling is present and resolves; the agent also builds your `.kici/` dependency closure after install, so a sibling's build output exists before the workflow that imports it loads. A `file:`/`link:`/`portal:` path is allowed only when it stays inside the repository.
 
-What fails fast (with an actionable error naming the dependency, not a raw package-manager error): a `workspace:` dependency in an **npm** project (npm has no workspace protocol — pin a published version or switch to pnpm), and any `file:`/`link:`/`portal:` path that points outside the cloned repo.
+What fails fast (with an actionable error naming the dependency, not a raw package-manager error): a `workspace:` dependency in an **npm** project (npm has no workspace protocol — pin a published version or switch to pnpm), a `workspace:`/`portal:` dependency in a **yarn classic** project (v1 has neither — use a version range, pnpm, or yarn berry), a `workspace:` dependency in a **yarn berry** project whose repo-root `package.json` has no `workspaces` array, and any `file:`/`link:`/`portal:` path that points outside the cloned repo.
 
 Then use the package in your workflow:
 
@@ -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`)
@@ -1146,6 +1150,46 @@ export const postDeploy = workflow('post-deploy', {
 });
 ```
 
+`workflowComplete()` / `jobComplete()` start a **separate** workflow run that reacts to the prior one finishing, gated on its status. They are the right tool when a _different_ workflow should respond. When you instead need to add more jobs to the **same** run based on what a job just produced — fanning out follow-up work from a prior job's outputs — use a result-aware generator (next section), not a completion-event chain.
+
+### Same-run discovery → fan-out
+
+A result-aware [`dynamicJob(group, { needs, generate })`](../sdk/rules-matrix-dynamic.md#dynamicjob--result-aware-generation) is deferred until its declared upstreams complete, then runs with their frozen outputs as `ctx.needs` — so a discovery job can emit a list at runtime and the generator fans out one follow-up job per item, all in the same run:
+
+```typescript
+import { workflow, job, step, push, dynamicJob, z } from '@kici-dev/sdk';
+
+const discover = job('discover', {
+  runsOn: 'linux',
+  steps: [
+    step('list-services', {
+      outputs: { services: z.array(z.string()) },
+      run: async ({ $ }) => {
+        const out = await $`ls services/`;
+        return { services: out.stdout.trim().split('\n') };
+      },
+    }),
+  ],
+});
+
+const deployEach = dynamicJob('deploys', {
+  needs: ['discover'],
+  generate: async ({ ctx }) =>
+    ctx.needs.discover.result.services.map((svc) =>
+      job(`deploy-${svc}`, {
+        runsOn: 'linux',
+        run: async ({ $ }) => {
+          await $`./scripts/deploy.sh ${svc}`;
+        },
+      }),
+    ),
+});
+
+export default workflow('deploy-discovered-services', { on: push(), jobs: [discover, deployEach] });
+```
+
+Contrast: this keeps everything in one run with results flowing job→job. A cross-workflow `jobComplete()` chain (above) reacts to a job finishing but only sees its _status_, in a new run — use that when the reacting logic belongs to a different workflow.
+
 ### Using custom events
 
 For richer payload data, emit custom events from steps using `ctx.emit()`:
@@ -1888,33 +1932,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 +1979,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, and each label can be an exact string, a glob, or a regular expression (see [Targeting by pattern](#targeting-by-pattern) below):
 
 ```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).
@@ -1970,6 +2021,48 @@ const deploy = job('deploy', {
 });
 ```
 
+#### Targeting by pattern
+
+Every selector element — in `runsOn`, in `runsOnAll`, on both the include and the exclude side — can be a plain string, a glob pattern, or a regular expression. KiCI picks the matching mode from the value itself:
+
+- **Plain string → exact match.** `'kici:os:linux'` matches the label `kici:os:linux` and nothing else.
+- **String with glob metacharacters (`*`, `?`, `[]`, `{}`) → glob.** `'kici:host:web-*'` matches every host label starting with `kici:host:web-`. `'kici:host:box-0[1-3]'` matches `box-01`, `box-02`, `box-03`.
+- **`RegExp` literal → regular expression.** `/kici:host:box-0[1-3]/` matches any label the expression matches.
+
+Both the required (include) side and the excluded side accept all three forms:
+
+```typescript
+// Glob include + regex exclude, single-agent targeting.
+const build = job('build', {
+  runsOn: { labels: ['kici:os:linux', 'kici:host:web-*'], exclude: [/.*-canary$/] },
+  steps: [compile],
+});
+
+// A bare regex picks any agent whose label the expression matches.
+const probe = job('probe', {
+  runsOn: /kici:host:box-0[1-3]/,
+  steps: [smoke],
+});
+```
+
+In the `runsOnAll` array form, a leading `!` still routes an entry to the exclude side. The `!` is stripped **before** the matching mode is decided, so `'!kici:host:box-*'` is an exclude **glob** and `'!box-01'` an exclude **exact** match. Regular-expression exclusions use the structured `exclude: [/…/]` form (a `RegExp` cannot carry a `!` prefix). The structured `runsOnAll` form below targets every Linux host in the `db` or `replica` role except those whose hostname ends in `-canary`:
+
+```typescript
+const fanout = job('deploy', {
+  runsOnAll: {
+    include: [{ all: ['kici:os:linux', 'kici:host:web-*'] }],
+    exclude: [/.*-canary$/],
+  },
+  run: async (ctx) => {
+    /* runs once per matched host */
+  },
+});
+```
+
+**Edge case — custom labels that contain glob metacharacters.** Because the matching mode is inferred from the value, a custom label that literally contains `*`, `?`, `[]`, or `{}` is always treated as a glob and can no longer be matched exactly. Avoid glob metacharacters in label names you intend to target by exact string.
+
+**ReDoS protection.** Glob patterns are linear by construction. A regular expression you supply is validated for catastrophic-backtracking (ReDoS) when you run `kici compile` — a pattern that could hang on a crafted input is rejected with an error, so it never reaches the orchestrator. The orchestrator re-validates every pattern when it loads the lock file.
+
 ### step(name, run) / step(name, options)
 
 Create a step with a run function or with typed outputs.
@@ -2108,7 +2201,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 +3172,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 +3228,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 +3268,58 @@ interface MatrixValues {
 }
 ```
 
+### Bounding matrix concurrency (maxParallel / failFast)
+
+A matrix fan-out runs every combination at once by default. The fan-out-generic
+`maxParallel` and `failFast` job options bound it the same way they bound a
+[`runsOnAll`](./runs-on-all.md#rolling-rollout-maxparallel--failfast) host fan-out:
+
+```typescript
+const test = job('test', {
+  runsOn: 'linux',
+  matrix: { os: ['ubuntu', 'macos', 'windows'] },
+  maxParallel: 1, // run one combination at a time (sliding window)
+  failFast: true, // stop launching combinations after the first failure
+  run: async (ctx) => {
+    /* ctx.matrix.os */
+  },
+});
+```
+
+`maxParallel` is a sliding window (each combination that finishes releases the next;
+`1` = serial; must be `>= 1`); `failFast` halts the fan-out on the first failure and
+skips the held remainder (default `false`). They are ignored on a job with no `matrix`
+or `runsOnAll`.
+
+### 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
@@ -3201,6 +3380,53 @@ export default workflow('ci', {
 });
 ```
 
+### dynamicJob — result-aware generation
+
+`dynamicJob(group, fnOrConfig)` tags a generator with a group name (so static jobs can depend on it via `needs: [dynamicGroup('group')]`). It is polymorphic:
+
+- **Function form** — event-only, dispatched at webhook time: `dynamicJob('shards', async ({ ctx }) => [...])`.
+- **Options-object form** — result-aware, deferred until its declared `needs` complete, then run with the upstreams' frozen outputs as `ctx.needs`: `dynamicJob('reports', { needs, generate })`.
+
+```typescript
+import { workflow, job, step, dynamicJob, dynamicGroup, z } from '@kici-dev/sdk';
+
+// Upstream job A discovers a list of targets at runtime.
+const discover = job('discover', {
+  runsOn: 'linux',
+  steps: [
+    step('emit', {
+      outputs: { targets: z.array(z.string()) },
+      run: async () => ({ targets: ['api', 'web'] }),
+    }),
+  ],
+});
+
+// Result-aware generator fans out one report job per discovered target.
+const reports = dynamicJob('reports', {
+  needs: ['discover'],
+  generate: async ({ ctx }) => {
+    const targets = ctx.needs.discover.result.targets; // OutputProxy over discover's outputs
+    return targets.map((target) =>
+      job(`report-${target}`, {
+        runsOn: 'linux',
+        run: async ({ log }) => log.info(`reporting on ${target}`),
+      }),
+    );
+  },
+});
+
+export default workflow('discovery-fan-out', { jobs: [discover, reports] });
+```
+
+`ctx.needs` shape:
+
+| Need form                                               | `ctx.needs[...]` value                                                                                                                                    |
+| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `'jobName'` / `{ name, ifFailed }`                      | `{ result }` — `result` is an `OutputProxy` (`ctx.needs.<job>.result.<step>.<field>`; single-step `run` jobs flatten to `ctx.needs.<job>.result.<field>`) |
+| `dynamicGroup('g')` / `dynamicGroup('g', { ifFailed })` | ordered array of `{ name, result }`, one per group member                                                                                                 |
+
+`ctx.needs` is deterministic — a snapshot of upstream outputs frozen at first eval and replayed unchanged on re-eval, like `ctx.event`. Use result-aware generation for same-run fan-out from a prior job's result; use [`jobComplete()`](./triggers.md) for cross-workflow reactions to a job finishing. See the architecture deep-dive in [dynamic jobs](../../architecture/execution/dynamic-jobs.md#result-aware-generation).
+
 ### JobOrFactory
 
 The `jobs` array in `WorkflowOptions` accepts both static jobs and dynamic generators:
@@ -3229,6 +3455,218 @@ for (const item of workflow.jobs) {
 
 ---
 
+## SDK reference: runsOnAll host fan-out
+
+Source: https://docs.kici.dev/user/sdk/runs-on-all/
+
+## runsOnAll
+
+`runsOnAll` fans a single job out to **every** host in the orchestrator's declared
+roster that matches a label predicate — one pinned execution per host. Use it for
+fleet-wide operations: patch every web tier, smoke-test every node, collect uptime
+from the fleet.
+
+`runsOnAll` is mutually exclusive with [`runsOn`](/user/sdk/core/): a job declares one
+or the other. Where `runsOn` picks a **single** agent that satisfies the labels,
+`runsOnAll` targets **all** matching hosts and runs the job once on each, pinned to
+that specific host.
+
+```typescript
+import { job } from '@kici-dev/sdk';
+
+// Run on every host labelled role:web.
+const patch = job('patch', {
+  runsOnAll: 'role:web',
+  run: async (ctx) => {
+    await ctx.$`sudo apt-get update && sudo apt-get upgrade -y`;
+    ctx.log.info(`patched ${ctx.host}`);
+  },
+});
+```
+
+### Input forms
+
+`runsOnAll` accepts three shapes:
+
+- **Bare string** — one required label.
+
+  ```typescript
+  runsOnAll: 'role:web';
+  ```
+
+- **Array** — every positive entry is required (AND); a `!`-prefixed entry excludes a host.
+
+  ```typescript
+  runsOnAll: ['kici:os:linux', 'role:db', '!kici:host:db-01'];
+  ```
+
+- **Structured** — explicit OR-of-AND include groups plus excludes.
+
+  ```typescript
+  runsOnAll: {
+    include: [{ all: ['kici:os:linux', 'role:db'] }, { all: ['role:replica'] }],
+    exclude: ['kici:host:db-01'],
+  };
+  ```
+
+  A host matches when it satisfies **any** include group (all labels in that group)
+  and carries **none** of the exclude labels.
+
+#### Targeting by pattern
+
+Every entry in any of these forms — include or exclude — can be an exact string, a
+glob, or a regular expression, exactly like [`runsOn`](./core.md#targeting-by-pattern):
+
+- **Plain string → exact match** (`'role:web'`).
+- **String with glob metacharacters (`*`, `?`, `[]`, `{}`) → glob** (`'kici:host:web-*'`).
+- **`RegExp` literal → regular expression** (`/.*-canary$/`).
+
+In the array form, a leading `!` routes an entry to the exclude side and is stripped
+**before** the matching mode is decided, so `'!kici:host:box-*'` is an exclude **glob**
+and `'!box-01'` an exclude **exact** match. A regular-expression exclusion uses the
+structured `exclude: [/…/]` form (a `RegExp` cannot carry a `!` prefix):
+
+```typescript
+const fanout = job('deploy', {
+  runsOnAll: {
+    include: [{ all: ['kici:os:linux', 'kici:host:web-*'] }],
+    exclude: [/.*-canary$/],
+  },
+  run: async (ctx) => {
+    /* runs once per matched host */
+  },
+});
+```
+
+A custom label that literally contains glob metacharacters is always treated as a glob
+and can no longer be matched exactly. A regular expression you supply is validated for
+catastrophic-backtracking (ReDoS) when you run `kici compile` and rejected if it could
+hang on a crafted input.
+
+### Per-host execution model
+
+Each matching host runs the job as its own pinned child, named `<job> (<hostname>)`
+(e.g. `patch (web-01)`). The children fan in for downstream `needs:` exactly like a
+matrix job — a downstream that needs the base job waits for every host child.
+
+The job runs once per host with concurrency `unlimited` (all hosts in parallel).
+
+### ctx.host and ctx.agent
+
+Inside a `runsOnAll` step, two extra context fields identify the host the child is
+running on:
+
+- `ctx.host` — the hostname (string).
+- `ctx.agent` — the resolved agent facts: `{ host, labels, platform?, arch? }`.
+
+```typescript
+run: async (ctx) => {
+  ctx.log.info(`running on ${ctx.host} (${ctx.agent?.platform}/${ctx.agent?.arch})`);
+};
+```
+
+Both are `undefined` for jobs that do not use `runsOnAll`.
+
+### byHost outputs
+
+A downstream that `needs:` a `runsOnAll` job receives a **byHost** envelope instead
+of a flat outputs object — keyed by hostname, with a per-host summary:
+
+```typescript
+import { isHostJobOutputs } from '@kici-dev/sdk';
+
+const report = job('report', {
+  runsOn: 'role:control',
+  needs: [patch],
+  run: async (ctx) => {
+    const outputs = ctx.jobOutputs(patch);
+    if (isHostJobOutputs(outputs)) {
+      ctx.log.info(`succeeded: ${outputs.summary.succeededHosts.join(', ')}`);
+      ctx.log.info(`failed: ${outputs.summary.failedHosts.join(', ')}`);
+      // Per-host outputs, keyed by hostname:
+      const version = outputs.byHost['web-01']?.version;
+      // Array view of one output key across every host:
+      const allVersions = outputs.summary.outputs.version;
+    }
+  },
+});
+```
+
+Unlike the matrix envelope's last-write-wins `merged`, the host summary never collapses
+to a single scalar: `summary.outputs[key]` is an array of every host's value, and
+`succeededHosts` / `failedHosts` record each host's terminal outcome.
+
+### onUnreachable: skip | fail | hold
+
+Resolution is backed by the **declared host roster** (see the operator
+[host roster](/operator/orchestrator/host-roster/) doc), not just the live registry.
+This lets KiCI surface an expected-but-absent host instead of silently fanning out to a
+partial fleet. The `onUnreachable` policy controls what happens when a **durable**
+(static) host in the roster is matched but not currently connected:
+
+- **`hold`** (default) — queue a pinned child for the absent host and wait for it to
+  reconnect. The fan-out is honest: a 5-host fleet with 1 host rebooting reports
+  `4 ran, 1 held`, not a silent 4-of-5 success.
+- **`skip`** — omit the absent durable host and run only on the reachable hosts.
+- **`fail`** — fail the run init if any expected durable host is unreachable.
+
+```typescript
+const patch = job('patch', {
+  runsOnAll: 'role:web',
+  onUnreachable: 'skip',
+  run: async (ctx) => {
+    /* ... */
+  },
+});
+```
+
+Ephemeral (scaled-down) hosts that are no longer connected are **always** skipped,
+independent of `onUnreachable` — a scaled-down node may never return. A `runsOnAll`
+that matches zero usable hosts fails the run rather than reporting a silent zero-child
+success.
+
+### Rolling rollout: maxParallel + failFast
+
+By default a `runsOnAll` fan-out dispatches to every matched host at once — fine for
+collecting state across the fleet, dangerous for a deploy that takes the whole tier
+down simultaneously. Two job options bound the rollout:
+
+- **`maxParallel`** — the fan-out width: at most this many hosts run at once. It is a
+  sliding window — each host that finishes (success or failure) releases the next held
+  host. `maxParallel: 1` is a strictly serial, one-host-at-a-time rolling deploy. Must
+  be `>= 1`.
+- **`failFast`** — when `true`, the first host failure halts the rollout: no further
+  held hosts are started, and the remaining ones are marked skipped. Default `false`
+  (every host runs regardless of sibling outcomes — the same as the unbounded fan-out).
+
+```typescript
+const deploy = job('deploy', {
+  runsOnAll: 'role:web',
+  onUnreachable: 'skip', // see the caveat below
+  maxParallel: 1, // strictly one host at a time
+  failFast: true, // stop the roll on the first failure
+  run: async (ctx) => {
+    /* patch ctx.host */
+  },
+});
+```
+
+Both options are **fan-out-generic** — they bound a `matrix` fan-out exactly the same
+way (the children are matrix combinations instead of hosts). They are ignored on a job
+with neither `matrix` nor `runsOnAll` (there is no fan-out to bound).
+
+**Caveat — use `onUnreachable: 'skip'` or `'fail'` for rolling deploys, not `'hold'`.**
+A held host occupies a wave slot indefinitely while it waits to reconnect, stalling the
+roll behind an absent box. `skip` (run only reachable hosts) or `fail` (refuse the roll
+if any expected host is down) keep the window moving.
+
+### Limits (v0)
+
+- Per-host secret scoping is not yet available — all hosts receive the job's resolved
+  secrets.
+
+---
+
 ## SDK reference: runtime
 
 Source: https://docs.kici.dev/user/sdk/runtime/
@@ -3239,25 +3677,26 @@ All types are exported from `@kici-dev/sdk` as type-only imports.
 
 ### Core types
 
-| Type              | Description                                                                           |
-| ----------------- | ------------------------------------------------------------------------------------- |
-| `Workflow`        | Workflow definition returned by `workflow()`                                          |
-| `WorkflowOptions` | Options for `workflow()` factory                                                      |
-| `Job`             | Job definition returned by `job()`                                                    |
-| `JobOptions`      | Options for `job()` factory                                                           |
-| `Step<TOutputs>`  | Step definition returned by `step()`                                                  |
-| `StepOptions<T>`  | Options for `step()` factory (full form with outputs)                                 |
-| `StepRunFn`       | Simple step function type: `(ctx) => Promise<void>`                                   |
-| `BareStepFn`      | Bare step function (no options, just `(ctx) => ...`)                                  |
-| `StepInput`       | Union of step input forms accepted by `job()`                                         |
-| `OutputSchema`    | Record of Zod types for step outputs                                                  |
-| `InferOutputs<T>` | Infer output type from output schema                                                  |
-| `ContainerConfig` | Container config for job execution (`image`, `env?`)                                  |
-| `RunsOn`          | Union of `runsOn` forms: `string \| string[] \| RunsOnSelector`                       |
-| `RunsOnSelector`  | Object form for `runsOn` with `labels` (required) and `exclude` (optional) properties |
-| `Fixture`         | Test fixture definition returned by `fixture()`                                       |
-| `FixtureOptions`  | Options for `fixture()` factory                                                       |
-| `Registry`        | Private npm registry declaration used in `WorkflowOptions.registries`                 |
+| Type              | Description                                                                                                                                                                                                                                                                        |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Workflow`        | Workflow definition returned by `workflow()`                                                                                                                                                                                                                                       |
+| `WorkflowOptions` | Options for `workflow()` factory                                                                                                                                                                                                                                                   |
+| `Job`             | Job definition returned by `job()`                                                                                                                                                                                                                                                 |
+| `JobOptions`      | Options for `job()` factory                                                                                                                                                                                                                                                        |
+| `Step<TOutputs>`  | Step definition returned by `step()`                                                                                                                                                                                                                                               |
+| `StepOptions<T>`  | Options for `step()` factory (full form with outputs)                                                                                                                                                                                                                              |
+| `StepRunFn`       | Simple step function type: `(ctx) => Promise<void>`                                                                                                                                                                                                                                |
+| `BareStepFn`      | Bare step function (no options, just `(ctx) => ...`)                                                                                                                                                                                                                               |
+| `StepInput`       | Union of step input forms accepted by `job()`                                                                                                                                                                                                                                      |
+| `OutputSchema`    | Record of Zod types for step outputs                                                                                                                                                                                                                                               |
+| `InferOutputs<T>` | Infer output type from output schema                                                                                                                                                                                                                                               |
+| `ContainerConfig` | Container config for job execution (`image`, `env?`)                                                                                                                                                                                                                               |
+| `RunsOn`          | Union of `runsOn` forms: `string \| RegExp \| (string \| RegExp)[] \| RunsOnSelector`. A plain string matches exactly, a string with glob metacharacters (`*?[]{}`) is a glob, and a `RegExp` is a regular expression. See [Targeting by pattern](./core.md#targeting-by-pattern). |
+| `RunsOnSelector`  | Object form for `runsOn` with `labels` (required) and `exclude` (optional) properties. Each element accepts the exact / glob / regex forms on both sides.                                                                                                                          |
+| `RunsOnAllInput`  | Union of `runsOnAll` host fan-out forms: `string \| RegExp \| (string \| RegExp)[] \| { include: { all: (string \| RegExp)[] }[]; exclude?: (string \| RegExp)[] }`. Same exact / glob / regex semantics per element. See [runsOnAll](./runs-on-all.md#targeting-by-pattern).      |
+| `Fixture`         | Test fixture definition returned by `fixture()`                                                                                                                                                                                                                                    |
+| `FixtureOptions`  | Options for `fixture()` factory                                                                                                                                                                                                                                                    |
+| `Registry`        | Private npm registry declaration used in `WorkflowOptions.registries`                                                                                                                                                                                                              |
 
 ### Trigger types
 
@@ -3556,6 +3995,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.
@@ -4126,6 +4627,8 @@ jobComplete({ workflow: 'CI', job: 'build', status: ['success'] }); // Success o
 jobComplete({ workflow: 'CI', job: 'build', source: 'org/repo' }); // Cross-repo
 ```
 
+`jobComplete()` starts a **new** workflow run that reacts to another job finishing (gated on the prior job's status). For same-run fan-out — generating follow-up jobs from a prior job's _outputs_ within the same run — use a result-aware [`dynamicJob(group, { needs, generate })`](./rules-matrix-dynamic.md#dynamicjob--result-aware-generation) instead.
+
 ### genericWebhook()
 
 Create a generic webhook trigger. Fires when a non-GitHub webhook is received from an external source configured via the admin API. Returns a frozen `GenericWebhookTriggerConfig`.
@@ -4603,7 +5106,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 +5126,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 +5140,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
 
@@ -4723,7 +5227,6 @@ The dashboard is a browser SPA on top of the same `/api/v1/*` surface, so anythi
 - **Workflows & runs:** `/orgs/:customerId/{runs,registrations,workflows,held-runs,environments,secrets,global-workflows}`
 - **Webhooks & event log:** `/orgs/:customerId/{sources,webhook-endpoints,event-log}`
 - **Diagnostics & activity:** `/orgs/:customerId/{diagnostics,activity,access-log}`
-- **Admin (kici-admin org only):** `/admin/{orgs,connections,audit-log,grafana/*}`
 
 The full route tree is the source of truth — every method, request schema, and response schema is enumerated server-side. There is currently no auto-generated OpenAPI spec; the typed `DashboardApiType` export is the canonical contract for TypeScript clients.
 
@@ -4767,7 +5270,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 +5530,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 +5546,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 +5569,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 +5607,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 +5750,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 +5775,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 +5794,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 +5860,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.
-
-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.
+The output has three parts: a one-line header (runs in the last 24h, success
+rate, average duration, queued/running job counts), any infrastructure alerts
+(only shown when present), and a tree of each orchestrator with its scalers and
+agents. Each agent line shows its labels, platform/architecture, active/maximum
+concurrency, and heartbeat age.
 
 ```bash
-kici status <run-id> [options]
+kici diagnostics [options]
 ```
 
-**Arguments:**
-
-| Argument | Required | Description    |
-| -------- | -------- | -------------- |
-| `run-id` | yes      | Run identifier |
-
 **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                                         |
+| --------------------- | ------- | --------------------------------------------------- |
+| `--json`              | `false` | Machine-readable JSON output                        |
+| `--verbose`           | `false` | Show extended per-agent fields (host, node, memory) |
+| `--orchestrator <id>` | all     | Scope the tree to one orchestrator connection id    |
 
 **Examples:**
 
 ```bash
-# Show run summary
-kici status abc123
+# Show the full infrastructure tree
+kici diagnostics
 
-# Show full logs (historical for completed runs, live streaming for active runs)
-kici status abc123 --logs
+# Extended per-agent detail
+kici diagnostics --verbose
 
-# Show logs for a specific job
-kici status abc123 --logs --job build
+# Only one orchestrator's scalers and agents
+kici diagnostics --orchestrator conn-abc123
 
 # Machine-readable output
-kici status abc123 --json
+kici diagnostics --json
 ```
 
-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`.
+### kici runs
+
+Inspect and manage execution runs from the terminal — the equivalent of the
+dashboard Runs page. All `kici runs` subcommands read/write the same org-scoped
+data as the dashboard, so they require `kici login` and an active org
+(`kici org use <name>`).
 
-### kici cancel
+#### kici runs list
 
-Cancel a running workflow or all runs on a branch.
+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 cancel [run-id] [options]
+kici runs list [options]
 ```
 
-**Arguments:**
+**Options:**
+
+| Option                  | Default | Description                                   |
+| ----------------------- | ------- | --------------------------------------------- |
+| `--status <s>`          | all     | Filter by run status                          |
+| `--workflow <w>`        | all     | Filter by workflow name                       |
+| `--branch <b>`          | all     | Filter by branch/ref                          |
+| `--repo <r>`            | all     | Filter by repository                          |
+| `--trigger <t>`         | all     | Filter by trigger type                        |
+| `--source <routingKey>` | all     | Filter by source routing key                  |
+| `--since <ts>`          | none    | Only runs since this ISO-8601 or epoch ms     |
+| `--page <n>`            | `1`     | Page number (server page size is fixed at 20) |
+| `--json`                | `false` | Machine-readable JSON output                  |
+
+```bash
+kici runs list
+kici runs list --status running
+kici runs list --workflow ci --branch main
+kici runs list --json | jq '.runs[].runId'
+```
+
+#### kici runs show
+
+Show a run's summary header plus its jobs-and-steps tree (name, status,
+duration, exit code). If the run id is not on the Platform but exists in your
+local run history (from `kici run local`), the local record is shown instead.
+
+```bash
+kici runs show <run-id> [options]
+```
+
+| Option   | Default | Description                  |
+| -------- | ------- | ---------------------------- |
+| `--json` | `false` | Machine-readable JSON output |
+
+```bash
+kici runs show abc123
+kici runs show abc123 --json
+```
+
+#### kici runs logs
+
+Print each job/step's log lines in order, with headers.
+
+```bash
+kici runs logs <run-id> [options]
+```
+
+| Option         | Default | Description                            |
+| -------------- | ------- | -------------------------------------- |
+| `--job <name>` | all     | Only print logs for this job           |
+| `-f, --follow` | `false` | Tail logs for a live run until it ends |
+| `--json`       | `false` | Machine-readable JSON output           |
+
+```bash
+kici runs logs abc123
+kici runs logs abc123 --job build
+kici runs logs abc123 --follow
+```
+
+#### kici runs rerun
+
+Re-trigger a completed run. Prints the new run id. The server enforces a short
+cooldown between reruns of the same run.
+
+```bash
+kici runs rerun <run-id> [options]
+```
+
+| Option   | Default | Description                  |
+| -------- | ------- | ---------------------------- |
+| `--json` | `false` | Machine-readable JSON output |
+
+```bash
+kici runs rerun abc123
+```
+
+#### kici runs cancel
+
+Cancel a single run, or all in-progress runs on a branch.
+
+```bash
+kici runs cancel [run-id] [options]
+```
 
 | Argument | Required | Description      |
 | -------- | -------- | ---------------- |
 | `run-id` | no       | Run ID to cancel |
 
-**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 +6425,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 +6820,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. |
@@ -6238,8 +6948,8 @@ The command is remote-only -- all execution happens on the orchestrator and agen
 :::note[Orchestrator prerequisite: cache storage]
 `kici run remote` uploads your working-tree overlay to the orchestrator's **cache storage** via a pre-signed URL, and the agent fetches it from there (see [Repo state transfer](#repo-state-transfer)). The target orchestrator must therefore have cache storage enabled (`KICI_STORAGE_TYPE` = `s3` or `filesystem`).
 
-- **The [Docker / Podman quickstart](quickstart/compose.md) wires this up for you** — it ships a SeaweedFS service, so `kici run remote` works there out of the box (see its "run a workflow without pushing" step).
-- **The [bare-metal quickstart](quickstart/bare-metal.md) does not configure storage by default** — enable a backend before using `kici run remote`:
+- **Both quickstarts wire this up for you** — the [Docker / Podman quickstart](quickstart/compose.md) and the [bare-metal quickstart](quickstart/bare-metal.md) each ship a SeaweedFS object store and pre-fill the orchestrator's `KICI_STORAGE_*` block, so `kici run remote` works out of the box (see each guide's "run a workflow without pushing" step).
+- **A hand-rolled orchestrator deploy does not configure storage by default** — enable a backend before using `kici run remote`:
   - **`filesystem`** — simplest for a single-host orchestrator: set `KICI_STORAGE_TYPE=filesystem` and `KICI_STORAGE_FS_PATH=/var/lib/kici/cache`. No external service needed; blobs are served through the orchestrator's own HMAC-signed HTTP route.
   - **`s3`** — any S3-compatible bucket. **A non-public / self-hosted endpoint works**: set `KICI_STORAGE_TYPE=s3`, `KICI_STORAGE_BUCKET`, `KICI_STORAGE_ENDPOINT=https://your-endpoint` and (for most self-hosted services) `KICI_STORAGE_FORCE_PATH_STYLE=true`. If the developer machine running `kici run remote` reaches the bucket at a different address than the orchestrator, set `KICI_STORAGE_UPLOAD_ENDPOINT` to the developer-reachable address; if agents reach it at yet another address (e.g. agents in containers), set `KICI_STORAGE_EXTERNAL_ENDPOINT` to the agent-routable URL.
 
@@ -6428,7 +7138,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 +7306,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 +7433,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/environments-and-secrets.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/
@@ -6820,1164 +7702,152 @@ Run #1 starts deploying                -> running
 Run #2 arrives for same group          -> queued ("Waiting for deploy-main (1 ahead)")
 Run #1 completes                       -> success
 Run #2 starts                          -> running
-```
-
-In queue mode, the agent that picked up the queued run **stays connected** to the orchestrator and parks on a long-poll wait. When the holder finishes (success, failure, or cancel), the orchestrator dequeues the FIFO-next entry and pushes a `proceed` notification over the same WebSocket; the queued agent then continues with normal step execution against the workspace it already has. The agent's slot is therefore held for the duration of the queue wait — bound by `KICI_CONCURRENCY_WAIT_TIMEOUT_MS` (default 1 hour).
-
-```typescript
-workflow('migrate-db', {
-  concurrency: {
-    group: () => 'migrations',
-    cancelInProgress: false,
-    max: 1,
-  },
-  jobs: [
-    /* ... */
-  ],
-});
-```
-
-The dashboard will show a "Queued" badge with the reason: "Waiting for deploy-main (1 ahead)".
-
-## Max concurrent runs
-
-The `max` field controls how many runs can execute simultaneously in the same group:
-
-```typescript
-// Allow up to 3 parallel test runs per branch
-workflow('test', {
-  concurrency: {
-    group: (ctx) => `test-${ctx.branch}`,
-    cancelInProgress: false,
-    max: 3,
-  },
-  jobs: [
-    /* ... */
-  ],
-});
-```
-
-When `max: 1` (default), runs are fully serialized within the group.
-
-## Group key examples
-
-### Deploy per environment
-
-```typescript
-workflow('deploy', {
-  concurrency: {
-    group: (ctx) => `deploy-${ctx.branch}`,
-    cancelInProgress: true,
-  },
-  jobs: [
-    job('deploy-staging', {
-      runsOn: 'linux',
-      environment: 'staging',
-      steps: [
-        /* ... */
-      ],
-    }),
-  ],
-});
-```
-
-### Global singleton
-
-```typescript
-// Only one migration can run at a time, regardless of branch
-workflow('migrate', {
-  concurrency: {
-    group: () => 'db-migration',
-    cancelInProgress: false,
-  },
-  jobs: [
-    /* ... */
-  ],
-});
-```
-
-### Environment-aware groups
-
-```typescript
-// Serialize deploys per environment
-workflow('deploy', {
-  concurrency: {
-    group: (ctx) => {
-      const env = ctx.branch === 'main' ? 'production' : 'staging';
-      return `deploy-${env}`;
-    },
-    cancelInProgress: true,
-  },
-  jobs: [
-    /* ... */
-  ],
-});
-```
-
-## Interaction with environment protection
-
-When a workflow has both `concurrency` and `environment` protection rules:
-
-1. Environment protection gates (required reviewers, wait timer) apply first
-2. Concurrency group check happens after protection gates pass
-3. If the run is queued by concurrency, it keeps its protection approval
-
-This means a run that passed approval won't need re-approval if it gets queued by concurrency.
-
-## Cancelling queued runs
-
-Queued runs can be cancelled before they start executing. The cancel request removes them from the queue immediately -- they don't go through the grace period since no step is running.
-
-## Job-level concurrency groups
-
-In addition to workflow-level concurrency, individual jobs can define their own concurrency group via the `concurrencyGroup` property. This controls concurrent execution at the job level rather than the workflow level. See [Environments — concurrency groups](environments.md#concurrency-groups) for details.
-
-## Local execution
-
-`kici run local` honors workflow-level `concurrency` per-machine, per-user. The `group` callback is evaluated against the simulated event identically to the remote orchestrator path; `cancelInProgress` carries the same semantics — `true` interrupts the holder via `SIGTERM` (escalating to `SIGKILL` after a grace window) and proceeds with the new run, while `false` queues the new invocation in FIFO order until the holder finishes.
-
-Coordination is local only. Running the same workflow on two different machines does not serialize across them — that requires the orchestrator. For full cross-host enforcement (queueing across agents, dashboard visibility, `max > 1`), use `kici run remote` against a deployed orchestrator.
-
-Lock files live under `$XDG_RUNTIME_DIR/kici-local-locks/` on Linux, falling back to `os.tmpdir()/kici-local-locks-<uid>/`. A workflow whose `group` callback throws aborts the run with a clear error rather than running unprotected. See [`kici run local` — Concurrency enforcement](cli-reference.md#concurrency-enforcement) for the `KICI_LOCAL_LOCK_KILL_GRACE_MS` override and the diagnostic output emitted while contending on a busy lock.
-
-The `kici run local --concurrency <n>` flag is a separate concept — it caps **job-level** parallelism within a single run (how many jobs from one workflow run at once), not cross-run serialization.
-
----
-
-_Source: `packages/sdk/src/types.ts` (WorkflowOptions.concurrency, JobOptions.concurrencyGroup)_
-
----
-
-## Dashboard
-
-Source: https://docs.kici.dev/user/dashboard/
-
-The KiCI dashboard is a web-based interface for monitoring workflow runs, inspecting job and step details, and reading log output. It is a browser single-page application that authenticates via OIDC and communicates with the Platform tier through REST API endpoints.
-
-## Getting started
-
-<!-- help:getting-started-overview#getting-started -->
-
-The getting-started page is a six-step checklist that takes you from zero to your first workflow run.
-
-- **Self-checked steps** -- install the CLI, scaffold a workflow, and run it locally. These run on your own machine, so you tick them off yourself; the dashboard remembers your choices in the browser.
-- **Auto-detected steps** -- connect an orchestrator, add a webhook source, and trigger your first run. These tick automatically as the dashboard observes the matching activity in your organization.
-
-Each step links to the relevant settings page or documentation. A progress bar tracks overall completion, and the sidebar entry shows a `done/total` badge until you finish or dismiss reminders.
-
-<!-- /help:getting-started-overview -->
-
-When you first sign in to a brand-new organization with no orchestrator, no webhook source, and no runs, the dashboard opens this page automatically. Once your organization has any activity, the run list becomes your landing page instead. The **Getting started** sidebar entry stays available so you can return to the checklist at any time.
-
-The six steps are:
-
-1. **Install the kici CLI** -- `npm install -g kici`.
-2. **Create a workflow** -- `kici init` scaffolds a `.kici/` directory in your repository.
-3. **Run a workflow locally** -- `kici run local pr:open` executes a workflow on your machine with no orchestrator required.
-4. **Connect an orchestrator** -- deploy an orchestrator and connect it with a join token from **Settings → Orchestrator keys**.
-5. **Add a webhook source** -- register a source under **Settings → Sources** so pushes and pull requests trigger runs.
-6. **Trigger your first run** -- push to your repository to produce your first run through the relay.
-
-## Navigation
-
-### Sidebar
-
-The left sidebar provides persistent navigation across all org-scoped pages:
-
-- **Org switcher** -- dropdown at the top to switch between organizations
-- **Getting started** -- onboarding checklist (shows a `done/total` badge until complete or dismissed)
-- **Runs** -- the default landing page, showing your workflow run history
-- **Workflows** -- permanently registered workflows listening for events
-- **Diagnostics** -- infrastructure health, execution metrics, and recent errors
-- **Metrics** -- time-series charts of orchestrator health (dispatch & agents, execution, webhooks, caching, logs, errors), scoped to this org
-- **Environments** -- deployment environments with protection rules
-- **Secrets** -- secret scope management with environment bindings
-- **Approval queue** -- held runs pending approval (shows a badge with pending count)
-- **Activity** -- federated forensic log merging upstream tenant-plane mutations and orchestrator reads (`access_log`) into one chronological stream
-- **DLQ** -- dead-letter queue of internal events whose dispatch retries were exhausted (shows a badge with the current depth)
-- **Settings** -- organization settings with tabbed sub-pages
-
-The sidebar footer shows the WebSocket connection indicator, your user profile, UTC/local time toggle, theme toggle, and a collapse button.
-
-<!-- help:sidebar-build-info#sidebar -->
-
-Below the KiCI logo, the sidebar shows build information for both the dashboard UI and the Platform API backend:
-
-- Git commit hash.
-- Relative build timestamp (e.g. "2h ago").
-
-This makes it easy to confirm which version is currently deployed.
-
-<!-- /help:sidebar-build-info -->
-
-### Mobile navigation
-
-On screens narrower than 768px (the `sm` breakpoint), the sidebar collapses and is replaced by a bottom tab bar with six navigation items: Runs, Workflows, Envs (environments), Secrets, Health (diagnostics), and Settings. Note that the mobile tab bar shows a subset of the full sidebar navigation -- activity and approval queue are only available in the full desktop sidebar.
-
-<!-- help:run-list-overview#run-list -->
-
-The run list is your organization's default landing page, showing all workflow runs with status, trigger, branch, and timing. Use filters and sorting to find specific runs, or enable commit grouping to see all runs triggered by a single push.
-
-<!-- /help:run-list-overview -->
-
-<!-- help:run-list-commit-grouping#commit-grouped-view -->
-
-Commit grouping collapses runs that share the same commit SHA under a single header. This is useful when a push triggers multiple workflows -- you can see their aggregate status at a glance instead of scanning individual rows.
-
-<!-- /help:run-list-commit-grouping -->
-
-## Run list
-
-The run list is the default page when entering an organization (`/orgs/:customerId/runs`).
-
-### Columns
-
-Each run is displayed in a table row (desktop) or card (mobile) with:
-
-- **Status** -- colored badge (green = success, red = failed/error/timed out, amber = running/cancelling, yellow = queued/pending, gray = cancelled/skipped)
-- **Trigger** -- icon indicating the event type (push, pull request, tag, dispatch, etc.)
-- **Workflow** -- the workflow name from your `.kici/workflows/` directory
-- **Branch** -- the git ref that triggered the run
-- **Commit** -- the first 7 characters of the commit SHA, linked to the provider (GitHub)
-- **Duration** -- how long the run took (e.g. "2m 30s")
-- **Time** -- relative timestamp (e.g. "5 minutes ago")
-
-### Filters
-
-Dropdown filters appear above the table:
-
-- **Status** -- filter by success, failed, running, or cancelled
-- **Workflow** -- filter by workflow name
-- **Branch** -- filter by git branch
-- **Repository** -- filter by repository
-
-A "More filters" button reveals additional filters:
-
-- **Trigger type** -- filter by push, pull_request, tag, dispatch, etc.
-
-Filters persist in URL query parameters (e.g. `/runs?status=failed&branch=main`), making filtered views shareable and bookmark-friendly. A "Clear filters" button appears when any filter is active.
-
-### Sorting
-
-Click any column header to sort the table by that column. Clicking the same header toggles between ascending and descending order. The current sort is reflected in the URL (e.g. `?sort=workflowName&dir=desc`), so sorted views are shareable.
-
-Sorting is server-side -- the API returns results in the requested order.
-
-### Column visibility
-
-A gear icon button (labeled "Toggle columns") next to the filter bar opens a menu of toggleable columns. Uncheck a column to hide it from the table. Column visibility preferences are saved per organization in `localStorage`.
-
-### Commit grouped view
-
-A "Group by commit" toggle switch groups runs by their commit SHA. When enabled, runs sharing the same commit are collapsed under a group header showing the commit SHA (first 7 characters), commit message, and aggregate status dots. This is useful for seeing all workflow runs triggered by a single push.
-
-### Compile indicator
-
-Runs where the lock file was recompiled during execution show a hammer icon next to the workflow name. Hover over the icon to see the tooltip "Lock file recompiled".
-
-### Pagination
-
-The run list shows 20 runs per page with numbered pagination controls. A footer displays the current range and total count (e.g. "Showing 1-20 of 237 runs").
-
-### Empty states
-
-- **No runs, WS disconnected** -- "No orchestrator connected" with guidance to check orchestrator configuration and a link to settings.
-- **No runs, WS connected** -- "No runs yet" with guidance to push code to trigger a workflow run.
-- **No filter matches** -- "No matching runs" with guidance to adjust filters.
-
-<!-- help:run-detail-job-tree#job-tree -->
-
-The job tree shows the hierarchical structure of your run's jobs and steps. Click a job to see combined logs from all its steps, or expand a job to select an individual step.
-
-Failed runs auto-expand the first failed job for quick diagnosis.
-
-<!-- /help:run-detail-job-tree -->
-
-<!-- help:run-detail-metadata#metadata -->
-
-The metadata panel displays detailed context about the selected run, job, or step:
-
-- IDs, status, duration.
-- Orchestrator and agent assignment.
-- Matrix values (when present).
-- Provider links — commit SHA, trigger event, workflow source file on GitHub.
-
-Use it as the quick-reference card when you need to jump from the dashboard to the underlying VCS or infrastructure.
-
-<!-- /help:run-detail-metadata -->
-
-<!-- help:run-detail-source#metadata -->
-
-The source row identifies which webhook source produced this run. Orchestrators register sources at startup with a friendly name and a fine-grained subtype — GitHub App, generic webhook, universal Git, or internal.
-
-The dimmed routing key under the name (e.g. `github:12345` or `generic:org:src-id`) is the unique identifier Platform uses to route the webhook back to your orchestrator.
-
-Two repos with the same path served by different sources are distinguished here, so you can tell at a glance which deployment a run came from.
-
-<!-- /help:run-detail-source -->
-
-<!-- help:run-detail-job-labels#metadata -->
-
-Labels show the routing constraints used to match this job to an agent.
-
-Label categories:
-
-- **Platform labels:** `kici:os:linux`, `kici:arch:x64`, etc.
-- **Scaler labels:** added by the scaler that provisioned the agent.
-- **Role labels:** e.g. `kici:role:builder`.
-- **Custom labels:** anything you set via `runsOn` in your workflow definition.
-
-<!-- /help:run-detail-job-labels -->
-
-<!-- help:run-detail-trust-context#metadata -->
-
-The trust context shows the security evaluation for PR-triggered runs:
-
-- **Trust tier:** trusted, known, or unknown contributor.
-- **Lock file source:** head branch or base branch.
-- **Secrets access level:** what the run was permitted to read.
-
-Use this to understand why a run was held for approval or ran with restricted permissions.
-
-<!-- /help:run-detail-trust-context -->
-
-<!-- help:summary-job-contexts#tabs -->
-
-The job contexts section in the run summary shows execution context per job:
-
-- **Sandbox type** — container, Firecracker, bare-metal.
-- **Runtime environment** — image, OS, arch.
-- **Dependency cache status** — hit, miss, or skipped.
-- **Available secret keys** — which scopes the job could read.
-
-This gives a quick overview of every job's execution environment without needing to select each job individually.
-
-<!-- /help:summary-job-contexts -->
-
-<!-- help:summary-scaler-context#tabs -->
-
-The scaler configuration section shows the execution mode and backend-specific settings used to provision the agent that ran this job. The execution mode describes how steps run — for example, "bare-metal" means direct processes, even inside containers where the container is the isolation layer.
-
-Backend-specific fields:
-
-- **Container backends:** image name, runtime (Docker/Podman), resource limits, and network isolation settings.
-- **Firecracker backends:** rootfs and kernel paths, vCPU/memory allocation, and the VM's IP address.
-- **Bare-metal backends:** binary path and resource hints.
-
-Hover over the execution mode badge for a contextual explanation.
-
-<!-- /help:summary-scaler-context -->
-
-<!-- help:summary-job-outputs#tabs -->
-
-Shows plain outputs and secret output keys produced by this job.
-
-- **Plain outputs:** values returned by step functions, grouped by step name.
-- **Secret outputs:** set via `ctx.setSecretOutput()`, shown here as masked key names — the values are encrypted and never sent to the dashboard.
-
-Downstream jobs that declare this job in their `needs` array can read these outputs.
-
-<!-- /help:summary-job-outputs -->
-
-<!-- help:summary-step-secrets#tabs -->
-
-When a step is selected, the secrets-accessed section shows which secret keys the step read via `ctx.secrets.get()` or `ctx.secrets.expose()` during execution.
-
-Only key names are shown, never values — use this to audit which steps access sensitive credentials.
-
-Available for runs executed after this feature was deployed; older runs show no data.
-
-<!-- /help:summary-step-secrets -->
-
-## Run detail
-
-Click any run in the list to open its detail page (`/orgs/:customerId/runs/:runId`).
-
-### Layout
-
-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.
-
-### Run header
-
-A summary bar above the two panels shows:
-
-- **Breadcrumbs** -- Runs > github > owner/repo > commit SHA > #runId > workflow name (each segment is clickable and filters the run list by that dimension)
-- **Status badge** -- the current run status
-- **Trigger icon** -- visual indicator of the event type
-- **Branch** -- the git ref with a branch icon
-- **Commit SHA** -- linked to the provider's commit page
-- **Duration** -- total run time
-- **Timestamp** -- relative time since the run started (hover for absolute time)
-- **Re-run button** -- available for terminal-state runs (success, failed, cancelled, error, timed out) triggered by webhooks. Opens a confirmation dialog before re-running on the same commit. After confirmation, navigates to the new run.
-- **Cancel button** -- available for pending, running, cancelling, or queued runs. For running runs, sends a graceful cancel; for already-cancelling runs, a "Force cancel" button appears to immediately kill without cleanup.
-- **Lineage badge** -- if the run is a re-run, a badge shows the parent/child relationship with a link to the original run.
-
-### Job tree
-
-The left panel shows a tree of jobs and their steps:
-
-- Each job shows a **status dot**, **name**, and **duration** (live timer while running)
-- Click a job row to select the job and view its combined logs (all steps merged with sticky headers)
-- Click the expand chevron on a job to expand/collapse its steps
-- Each step shows a **status dot**, **name**, and **duration**
-- Click a step to select it and view its individual logs
-
-**Job-level selection** -- clicking a job row selects it and shows combined logs from all of its steps, with sticky step headers separating each step's output. This provides a unified view of the entire job's execution without needing to click through steps individually.
-
-**Matrix jobs** are grouped under a parent node. For example, a matrix with 3 Node.js versions appears as "Test (3 variants)" with expandable sub-entries like "Test (node:18)", "Test (node:20)", "Test (node:22)".
-
-**Hook steps** -- lifecycle hook steps (e.g. `onCancel`, `cleanup`, `onSuccess`) are displayed with a distinct badge to differentiate them from regular steps.
-
-<!-- help:run-detail-setup-jobs#job-tree -->
-
-**Setup jobs** are rows prefixed with `__init__`, `__build__`, or `__dynamic__`. They run before (or alongside) your workflow jobs.
-
-In the tree they appear with:
-
-- A pretty display name — `Init: foo`, `Build: foo`, `Evaluate: foo`.
-- A muted "setup" visual variant that distinguishes them from regular jobs without hiding them.
-- A single synthetic step-0 log that captures everything the workflow source and dynamic functions write — explicit `log.*` calls, `console.*` output, and subprocess stdout from `await $` inside a `DynamicJobFn`.
-
-Their elapsed time is intentionally visible: clone, dependency install, and dynamic evaluation can consume real user-observable time, and hiding it would obscure where the run is actually spending itself.
-
-<!-- /help:run-detail-setup-jobs -->
-
-**Auto-expand on failure** -- when viewing a failed run, the first failed job is automatically expanded and the failed step is selected.
-
-**URL sync** -- selecting a job updates the URL to `/runs/:runId/jobs/:jobId`, and selecting a step updates it to `/runs/:runId/jobs/:jobId/steps/:stepIndex`, making selections bookmarkable and shareable.
-
-### Keyboard navigation
-
-The job tree supports keyboard navigation:
-
-- **Arrow Up/Down** -- move focus through tree items
-- **Enter** -- select a job (show combined logs) or select a step (show step logs)
-- **Escape** -- deselect the current selection and navigate to the first job
-
-### Tabs
-
-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
-- **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)
-
-On wide desktop (>= 1200px), Metadata is shown in a dedicated sidebar panel instead of as a tab.
-
-### Metadata
-
-The metadata panel shows detailed information organized into sections:
-
-- **Run metadata** -- run ID, status, trigger event, branch, commit SHA (linked to provider), workflow name (linked to source file on provider), duration, and timestamps
-- **Job metadata** -- job name, status, agent ID, matrix values (if present), duration
-- **Step metadata** -- step name, step index, status, duration
-- **Trust context** (PR-triggered runs only) -- shows the contributor's trust tier (trusted, known, or unknown), lock file source (head or base branch), and secrets access level
-
-Provider-specific links (e.g., GitHub commit URL, branch URL, PR link, workflow source file link) are automatically generated based on the repository context. The workflow name in the metadata panel is a clickable link to the `.kici/workflows/<name>.ts` source file on the provider (e.g. GitHub blob view).
-
-### WebSocket connection indicator
-
-A small indicator in the sidebar footer shows the real-time WebSocket connection status:
-
-- **Green dot** -- connected and receiving live updates
-- **Red dot (pulsing)** -- disconnected
-
-## Log viewer
-
-The log viewer renders step output with full terminal color support.
-
-### ANSI color rendering
-
-Log lines containing ANSI escape codes are rendered with color. Supported sequences include:
-
-- Standard 16 colors (red, green, blue, etc.) and bright variants
-- 256-color palette
-- Truecolor (24-bit RGB)
-- Bold, faint, italic, underline, and inverse text
-
-Colors use CSS classes with a dark background (similar to a terminal), regardless of the dashboard's light/dark theme setting.
-
-### Timestamps
-
-A clock icon button next to the search bar toggles per-line timestamps in the log viewer. When enabled, each log line shows the timestamp in the gutter alongside the line number. The timestamp format respects the UTC/local time preference. The setting persists to `localStorage`.
-
-### Search
-
-A search bar at the top of the log viewer provides:
-
-- **Debounced search** -- type a query and matches are highlighted after 300ms
-- **Match count** -- shows "N of M" with the current and total match count
-- **Navigation** -- up/down arrows to jump between matches (also Enter/Shift+Enter)
-- **Clear** -- press Escape or click the X button to clear the search
-- **Wraparound** -- navigation wraps from the last match back to the first
-
-### Permalink
-
-Click any line number in the gutter to:
-
-1. Highlight that line with a blue tint
-2. Update the URL hash to `#L42` (for line 42)
-
-Sharing the URL scrolls the recipient directly to the highlighted line.
-
-### Copy to clipboard
-
-Hover over any line to reveal a copy button on the right. Clicking it copies the line's **plain text** (ANSI escape codes are stripped) to the clipboard. A "Copied!" tooltip confirms the action.
-
-### Live log streaming
-
-When viewing a running job, logs appear in real time as the agent executes steps. The dashboard maintains a WebSocket connection to the Platform tier and subscribes to log updates for the currently selected step.
-
-**Auto-scroll** -- new lines automatically scroll into view as they arrive. If you scroll up to review earlier output, auto-scroll pauses and a **"Jump to bottom"** button appears. Clicking it resumes auto-scroll.
-
-**Streaming indicator** -- a pulsing "Streaming" badge appears next to the Logs tab header while a step is actively running.
-
-**Completion banner** -- when a step finishes, a banner appears at the bottom of the log viewer showing the final status (success or failed) and total line count.
-
-**Status updates** -- the run list and run detail pages update live as jobs and steps change state. You do not need to refresh the page to see a run complete.
-
-**Known limitations**:
-
-- Live streaming requires an active WebSocket connection. Some corporate proxies may block WebSocket upgrades.
-- If the WS connection drops, the dashboard reconnects automatically and refetches all cached data to catch up on missed updates.
-- Log lines received during streaming are held in memory. For very long-running steps with massive output, the REST endpoint is the authoritative source for complete logs.
-
-### Provisioning logs
-
-Above the step logs, a collapsible **Provisioning logs** section shows the orchestrator-side lifecycle of the agent that ran the job — the scaler lifecycle events emitted while bringing an agent up. It starts expanded while provisioning is in progress (no step logs yet) and collapses once steps begin producing output.
-
-When the scaler **fails** to provision an agent (for example a missing binary, an unpullable container image, or a microVM that fails to boot), the failure appears here along with a bounded tail of the agent process's own stdout/stderr captured by the scaler. This is the surface to check for a run that fails with no step logs at all — the agent never started, so the cause lives in the provisioning lifecycle rather than in any step's output.
-
-### Performance
-
-The log viewer uses virtualized scrolling to handle large outputs. Only the visible lines plus a small buffer are rendered in the DOM, keeping performance smooth even for logs with 10,000+ lines.
-
-<!-- help:settings-general#settings -->
-
-General settings show your organization's basic information, including the org name (editable by owners) and the unique organization ID. Use this to rename your org or reference the ID for API calls and configuration.
-
-<!-- /help:settings-general -->
-
-<!-- help:settings-members#settings -->
-
-The members tab lets you manage your team:
-
-- Invite new members by email.
-- Assign roles.
-- Suspend or remove members.
-- Configure per-user CI trust levels.
-
-Each member's linked provider accounts (e.g. GitHub) are also visible here.
-
-<!-- /help:settings-members -->
-
-<!-- help:settings-roles#settings -->
-
-Roles define granular permissions across 15 resource categories (runs, secrets, members, etc.) with 5 access levels: `none`, `read`, `read_payload`, `write`, `admin`.
-
-Create custom roles to restrict what team members can do, or use the built-in **Owner** role for full access.
-
-<!-- /help:settings-roles -->
-
-<!-- help:settings-teams#settings -->
-
-Teams are named groups of organization members. A role granted to a team is inherited by every member, so you can manage permissions for a whole group in one place.
-
-Team names can also be referenced in workflow approval gates (`requireApproval: [{ team: 'leads' }]`) — any member of the named team can satisfy that gate.
-
-Managing teams (create / rename / delete, membership, role grants) requires the **Teams** permission at `admin`; `read` shows a view-only list.
-
-<!-- /help:settings-teams -->
-
-<!-- help:settings-api-keys#settings -->
-
-API keys allow programmatic access to the KiCI API for automation, scripts, and CI integrations.
-
-Each key is scoped to this organization with a custom permission matrix and an optional expiry date. Keys can be revoked individually.
-
-Use a key's clone button to open the creation modal prefilled with that key's name, expiry, and permissions — handy for recreating an expired key or deriving a new key from an existing one.
-
-<!-- /help:settings-api-keys -->
-
-<!-- help:settings-orchestrator-keys#orchestrator-keys -->
-
-Orchestrator keys authenticate the WebSocket connection between your orchestrator and the KiCI Platform relay.
-
-Create a key here and set it as the `KICI_PLATFORM_TOKEN` environment variable in your orchestrator configuration. Keys can optionally be restricted to specific routing patterns.
-
-Use a key's clone button to open the creation modal prefilled with that key's name and description.
-
-<!-- /help:settings-orchestrator-keys -->
-
-<!-- help:settings-sources#sources -->
-
-Webhook sources are registered automatically when an orchestrator connects to the Platform and sends a `source.register` message.
-
-Each source shows its routing key and full webhook URL — configure this URL in your provider's webhook settings (e.g. GitHub App).
-
-To retrieve the webhook secret for signature verification, use the `kici-admin source get-webhook-secret <routingKey>` command shown below each source.
-
-<!-- /help:settings-sources -->
-
-<!-- help:settings-billing#settings -->
-
-The billing tab shows your current plan (Free, Pro, or Team), resource usage meters, and lets you upgrade to a paid tier.
-
-Choose Monthly or Annual billing, click "Upgrade to Pro" or "Upgrade to Team" to start a Stripe Checkout, or use "Manage payment" to switch tiers and update payment methods via the Stripe Billing Portal.
-
-The usage meters track:
-
-- **Members:** invited users in this org.
-- **Orchestrator connections:** direct WebSocket connections from your orchestrators to the Platform. Only coordinators (and standalone orchestrators) open a connection; peer/worker nodes in a Raft cluster share their coordinator's connection and don't count separately.
-- **Relayed webhooks (this month):** webhooks delivered through the Platform relay during the current billing window.
-- **Live log minutes (today):** log streaming time consumed in the current UTC day.
-- **Retention period:** how long execution history is kept.
-
-The diagnostics page may show a higher orchestrator count than this tab — diagnostics counts cluster nodes, billing counts billable connections.
-
-<!-- /help:settings-billing -->
-
-<!-- help:settings-billing-orch-connections#settings -->
-
-The orchestrator-connections counter measures the number of **direct WebSocket connections** that your orchestrator processes hold open against the KiCI Platform — one count per live connection.
-
-**What counts as one connection:**
-
-- One standalone orchestrator (single process, no cluster) → **1 connection**.
-- One Raft cluster (1 coordinator + N peers) → **1 connection** — only the coordinator opens a Platform WebSocket. The peers gossip through the coordinator and never connect to Platform directly, so they do **not** count toward your billing limit.
-- N independent orchestrator deployments (e.g., one per environment, one per region) → **N connections**.
-
-This is why the diagnostics page can show more orchestrator **nodes** than the billing page shows **connections**: diagnostics counts every node in your topology (coordinator + peers), while billing only counts the WebSocket connections you pay for. A 4-connection org running two 3-node clusters and two standalones will show 4 on the billing meter and 8 on the diagnostics page — both numbers are correct, they measure different things.
-
-When you hit the cap, the next coordinator that tries to connect is rejected with WebSocket close code 4020 (`WS_CLOSE_PLAN_LIMIT`). Existing connections are never disconnected. Upgrade your plan to lift the cap; the meter updates immediately.
-
-<!-- /help:settings-billing-orch-connections -->
-
-<!-- help:settings-billing-relayed-webhooks#settings -->
-
-The relayed-webhooks counter only includes webhooks delivered through the KiCI Platform relay — the route at `kici.dev` that signature-verifies an inbound webhook and forwards it over WebSocket to your orchestrator.
-
-Webhooks pointed directly at your orchestrator's public ingest endpoint never reach the Platform, so they're invisible to this counter and uncapped on every Hosted tier. If you have a public orchestrator ingress, you can mix-and-match: use the relay for sources you can't expose publicly, and point GitHub (or any provider / generic webhook) straight at your orchestrator for the rest.
-
-Every webhook the relay forwards counts — **including ones your workflows ultimately ignore**. Trigger matching runs on your orchestrator, not on the Platform, so the relay forwards each signature-verified webhook before any trigger is evaluated. A source that sends many events you filter down to a handful of runs still consumes one relayed webhook per event. If a high-volume source mostly produces no run, point it directly at your orchestrator (see above) to keep it off this counter entirely.
-
-When you hit the cap, new relayed webhooks are rejected with `429 Plan limit reached`. Upgrade in the Stripe Billing Portal to lift the cap immediately; usage resets monthly on your billing anniversary.
-
-<!-- /help:settings-billing-relayed-webhooks -->
-
-<!-- help:settings-billing-currency#settings -->
-
-Switch the prices shown on the tier cards between US dollars and euros. The choice you pick here is also the currency Stripe charges in when you click "Upgrade".
-
-The default is detected from your browser language. EU, EFTA, and UK locales default to euros; everywhere else defaults to dollars.
-
-Your choice persists in a 90-day cookie (`kici_pricing_currency`), so it survives across reloads and applies on every billing page.
-
-<!-- /help:settings-billing-currency -->
-
-<!-- help:billing-payment-failure#settings -->
-
-This banner appears when your organization's latest payment to Stripe has failed. Your subscription remains active during the retry period, but you should update your payment method promptly to avoid service interruption.
-
-<!-- /help:billing-payment-failure -->
-
-<!-- help:activity-overview#activity -->
-
-Activity is your forensic log — every Platform mutation (invites, role changes, sources, plans) and every orchestrator action (reads, run cancels, secret reveals, environment edits) merged into one chronological stream.
-
-Each row shows the actor, the action, the target, and the outcome.
-
-- **Audit rows:** expand for field-level change tracking.
-- **Access rows:** expand for the request ID, origin, and any error message.
-
-<!-- /help:activity-overview -->
-
-<!-- help:activity-filters#activity -->
-
-Filters live entirely in the URL — bookmark or share a filtered view to replay it.
-
-- **Search:** full-text match against access-log error messages and the JSON body of audit entries.
-- **Run ID:** combine with another filter to scope all activity touching a specific run.
-
-Click a row's run target to jump straight to the run detail page.
-
-<!-- /help:activity-filters -->
-
-## DLQ
-
-The DLQ (dead-letter queue) page lists internal events whose dispatch attempts were exhausted (or that hit a non-retryable error). Each row shows when the event landed in the DLQ, the event name, the attempt count, the failure reason, and the last error message.
-
-<!-- help:dlq#dlq -->
-
-The DLQ holds events your org emitted that could not be dispatched within the retry budget. The sidebar badge shows the current depth so you can spot a building backlog without opening the page.
-
-Per-row actions (visible when you have `event_dlq:write`):
-
-- **Retry:** clears the DLQ flag and re-publishes the event. A healthy orchestrator picks it up immediately.
-- **Discard:** permanently deletes the row. Use when the payload is corrupt or the routing target no longer exists.
-
-Members with only `event_dlq:read` see the list but cannot retry or discard. Org owners have both actions by default.
-
-<!-- /help:dlq -->
-
-<!-- help:settings-ci-trust#settings -->
-
-CI trust policy controls how your organization handles PR-triggered runs from different contributor types. Configure the default trust level for unknown contributors and set per-member overrides to control who can run workflows with full secrets access.
-
-<!-- /help:settings-ci-trust -->
-
-<!-- help:settings-global-workflows#settings -->
-
-Global workflows let a single "workflow repo" define jobs that run when events happen in other repos in the same org.
-
-This tab exposes the security knobs as independent axes:
-
-- **Master enable toggle:** turn the whole feature on or off.
-- **Authoring allow-list:** which repos may **define** global workflows.
-- **Source deny-list:** **source** repos whose events never trigger globals (forks, public-contrib).
-- **Elevated-access list:** authoring repos that need source-repo secrets during execution.
-
-See the [user guide](global-workflows.md) and the [architecture reference](../architecture/global-workflows.md) for the full model.
-
-<!-- /help:settings-global-workflows -->
-
-<!-- help:settings-global-workflows-enable#settings -->
-
-Master kill-switch for global workflows in this org.
-
-- **OFF:** the orchestrator will **not register** any workflow that declares `repos:` patterns, and will **not dispatch** cross-repo triggers — effectively rolling the org back to per-repo-only semantics. All other settings on this page are ignored.
-- **ON:** the other toggles become your safety rails. Turn ON to opt in.
-
-<!-- /help:settings-global-workflows-enable -->
-
-<!-- help:settings-global-workflows-authors#settings -->
-
-Restricts which repos in this org may **define** global workflows (the "authoring axis").
-
-- **OFF:** any repo in the org may declare a workflow with `repos:` patterns and have it registered.
-- **ON:** only repos whose identifier matches one of the entries below may author globals. Non-matching repos have their global workflows dropped at registration time, with a warning in the orchestrator log.
-- **ON + empty list:** **no repo** may author globals — use as a temporary lock-down.
-
-Each entry has two parts:
-
-- **Source:** pick a configured source (a specific GitHub App or universal-git source) to pin the entry to that source only, or leave it as **Any source** to match across every source in the org.
-- **Pattern:** a glob matched against the authoring repo identifier (e.g. `myorg/ci-*`, `myorg/platform-*`).
-
-Pinning by source is useful when the same `owner/repo` could legitimately exist on more than one configured source and you only want to trust one of them as an author.
-
-<!-- /help:settings-global-workflows-authors -->
-
-<!-- help:settings-global-workflows-blocked-sources#settings -->
-
-Deny-list for **source** repos whose events must never trigger a global workflow (the "source axis").
-
-Use this for untrusted territory — forks, public-contrib mirrors, sandboxes — where a single push shouldn't be able to fan out org-wide automation.
-
-Evaluated at dispatch time against the repo that emitted the event, independently of the authoring allow-list: a global workflow whose author is allowed will still be skipped if the _source_ repo is denied. Both lists can be active simultaneously.
-
-Each entry has two parts:
-
-- **Source:** pick a configured source to deny only events delivered on that source, or leave it as **Any source** to deny across the org.
-- **Pattern:** a glob matched against the source repo identifier (e.g. `myorg/fork-*`, `myorg/public-*`).
-
-Pinning by source is the right move when the same `owner/repo` is reachable through more than one configured source (e.g. a public forge and a trusted mirror) and you want to drop deliveries from only one of them.
-
-<!-- /help:settings-global-workflows-blocked-sources -->
-
-<!-- help:settings-global-workflows-elevated#settings -->
-
-Authoring repos listed here receive **elevated access to source-repo secrets** during global workflow execution.
-
-- **Without elevation:** a global workflow job runs with only the workflow repo's own credentials — it can clone both repos but can't read the source repo's scoped secrets.
-- **With elevation:** the job gets the source repo's secret context injected, so deploy / release / cross-repo automation flows work.
-
-Treat elevated repos as effective owners of every source repo's CI secrets — only add repos you fully trust.
-
-Each entry has two parts:
-
-- **Source:** pick a configured source to elevate only when the authoring repo lives on that source, or leave it as **Any source** to elevate across the org.
-- **Pattern:** a glob matched against the **workflow-authoring** repo, not the source repo (e.g. `myorg/ci-deploy`, `myorg/release-automation`).
-
-Pinning by source narrows the trust window: if the same `owner/repo` is configured on more than one source, only the source you pick will grant elevation.
-
-<!-- /help:settings-global-workflows-elevated -->
-
-<!-- help:settings-webhooks#settings -->
-
-Configure outbound webhook endpoints to receive notifications when runs and jobs change status. Each endpoint receives HMAC-SHA256 signed payloads with event details.
-
-For each endpoint you can:
-
-- **Subscribe to event types:** `run.started`, `run.completed`, `run.failed`, `job.started`, `job.completed`, `job.failed`.
-- **View delivery logs:** HTTP response codes and retry counts.
-- **Send a test ping:** verify connectivity before going live.
-
-<!-- /help:settings-webhooks -->
-
-<!-- help:settings-security-dashboard-policy#settings -->
-
-Read-only view of the orchestrator's dashboard-write policy.
-
-Each row toggles one mutating dashboard action — setting a secret, approving a held run, retrying a dead-lettered webhook, and so on. The orchestrator operator decides which actions stay on the dashboard and which become **CLI-only**. The dashboard cannot change the policy itself — that's the point: disabled actions stay out of the SaaS Platform's trust path.
-
-Manage the policy with:
-
-- **Show the full policy:** `kici-admin org-settings dashboard-writes show`
-- **Disable an operation:** `kici-admin org-settings dashboard-writes set --op <name>=false`
-- **Reset to permissive defaults:** `kici-admin org-settings dashboard-writes reset`
-
-The summary strip at the top shows total / enabled / disabled counts plus whether your orchestrator is currently connected. A disconnected orchestrator means the page falls back to the cached policy from the most recent connection.
-
-<!-- /help:settings-security-dashboard-policy -->
-
-<!-- help:settings-support-access#settings -->
-
-Controls whether KiCI support staff may open read-only support sessions against your organization. Sessions are **off by default** — nobody outside your org can read your data until you opt in here.
-
-When enabled:
-
-- KiCI staff can open time-boxed, read-only sessions to investigate an issue.
-- Every read they perform is recorded in your audit trail with the support reason.
-- No writes are ever possible during a session.
-
-Disabling the toggle immediately ends any in-progress support session. Only users with the `support:admin` permission (owners by default) can change this setting.
-
-<!-- /help:settings-support-access -->
-
-<!-- help:settings-webhooks-delivery-log#settings -->
-
-The delivery log shows recent webhook deliveries for an endpoint, including the HTTP status code, number of retry attempts, and the event payload.
-
-Retry behavior:
-
-- Deliveries are retried up to 3 times with exponential backoff.
-- After 10 consecutive failures, the endpoint is automatically disabled — you can re-enable it from this view.
-
-<!-- /help:settings-webhooks-delivery-log -->
-
-<!-- help:settings-event-log#event-log -->
-
-The event log shows every inbound webhook this organization has received, regardless of whether it came in via the Platform relay or directly to an orchestrator.
-
-Each row joins two records:
-
-- **Platform side:** event metadata and a SHA-256 hash of the body (no payload stored).
-- **Orchestrator side:** full payload and processing outcome.
-
-Filter by routing key, event type, status, or delivery ID. Click a row for the full per-tier breakdown.
-
-<!-- /help:settings-event-log -->
-
-<!-- help:settings-event-log-detail#event-log -->
-
-The detail panel shows both tiers' projections side-by-side.
-
-- **Platform record:** answers "did the delivery arrive at the relay and where was it routed".
-- **Orchestrator record:** answers "what was the body and what happened next" — including the matched workflow count and spawned run links.
-- **Payload:** the raw webhook body. Streams over the dashboard's existing WebSocket connection in 64 KiB chunks so Platform never buffers the full body and you see progress for large deliveries. Requires `event_log:read_payload`.
-
-Oversized or storage-failed payloads show an "omitted" badge, with the hash preserved for correlation against raw logs.
-
-<!-- /help:settings-event-log-detail -->
-
-## Activity
-
-The activity page (`/orgs/:customerId/activity`) is the org-level forensic log. It federates two streams into one chronological view: the upstream tenant-plane audit log (every tenant-plane mutation -- invites, role changes, source registrations, plan changes) and orchestrator `access_log` rows (every read and admin action -- run cancels, secret reveals, environment edits, dashboard data fetches via the Platform proxy). Filters live in the URL via search params so a filtered view is bookmarkable and shareable. The page uses cursor-based pagination and supports filtering by source (audit / access_log / all), free-text search, run ID, and other dimensions. Requires `audit:read` permission. The legacy `/orgs/:customerId/audit-log` URL redirects here to preserve bookmarks.
-
-## Settings
-
-The settings page (`/orgs/:customerId/settings`) uses a tabbed layout:
-
-1. **General** -- displays the organization name (editable by owners via inline click-to-edit) and the organization ID
-2. **Members** -- team management with invite, role assignment, and member removal
-3. **Roles** -- custom role management with granular permission matrix
-4. **API keys** -- API key creation and revocation for dashboard/programmatic access
-5. **Orchestrator keys** -- orchestrator API key management for Platform WebSocket connections
-6. **Sources** -- read-only list of registered webhook sources (see below)
-7. **Billing** -- plan and payment management (hidden in the `kici-admin` org)
-8. **CI trust** -- trust policy configuration for CI runs (visible with `ci_trust:read` permission)
-9. **Global workflows** -- org-level security knobs for cross-repo workflows (visible with `org_settings:read` permission)
-10. **Webhooks** -- outbound webhook endpoint management with delivery logs and test ping
-11. **Event log** -- inbound webhook delivery log (visible with `event_log:read` permission)
-12. **Security** -- read-only view of the orchestrator's dashboard-write policy matrix (visible with `org_settings:read` permission)
-13. **Support access** -- opt-in switch that controls whether KiCI support staff may open read-only support sessions against your org (visible with `support:read`; toggled with `support:admin`)
-
-Audit-log-style entries are no longer a settings tab; they live on the dedicated **Activity** page accessible from the sidebar.
-
-Tab selection syncs with the URL path (`/settings/members`, `/settings/api-keys`, etc.), making tabs bookmarkable.
-
-### Support access
-
-The Support access tab controls whether KiCI support staff may open a read-only **support session** against your organization to help diagnose an issue. The setting is **off by default** -- until you opt in here, no one outside your org can read your data.
-
-When support access is enabled:
-
-- A KiCI operator can open a time-boxed (30-minute, renewable), read-only support session scoped to a stated reason.
-- A support session is **runs-only**: the operator can browse your run list and, by confirming each run individually, view that run's detail and step logs. Nothing else is visible, and no write is ever possible.
-- Every run an operator opens is recorded in your [Activity](#activity) audit trail, attributed to the operator with the support reason -- so you can see exactly what was looked at and why.
-
-**Disabling immediately ends any active session.** Toggling the switch off closes every in-progress support session for your org at once. Enabling and disabling the setting is itself audited, attributed to the user who changed it.
-
-Viewing the setting requires the `support:read` permission; changing it requires `support:admin` (granted to owners by default).
-
-### Orchestrator keys
-
-The orchestrator keys tab manages API keys used to authenticate orchestrator-to-Platform WebSocket connections. These are separate from user API keys (which grant dashboard/API access).
-
-**List view** -- shows all active orchestrator keys with name, description, key prefix, creation date, and last used date.
-
-**Create** -- opens a modal to enter a name and optional description. After creation, the raw key is shown once in a copyable box. Set this key as the `KICI_PLATFORM_TOKEN` environment variable in your orchestrator configuration.
-
-**Revoke** -- opens a confirmation modal before soft-deleting the key. Any orchestrators using the revoked key will be disconnected.
-
-### Sources
-
-The sources tab shows webhook sources registered by connected orchestrators. Sources appear here **automatically** when an orchestrator connects to the Platform via WebSocket and sends a `source.register` message -- there is no manual "add source" action in the UI.
-
-**What causes a source to appear:**
-
-1. An orchestrator is configured with one or more providers (e.g., a GitHub App with `appId: 12345`)
-2. The orchestrator connects to the Platform using an orchestrator API key for your organization
-3. On connection, the orchestrator sends `source.register` with its provider sources (e.g., `github:12345`)
-4. The Platform records the source against your organization
-5. The source immediately appears in the dashboard
-
-**Each source displays:**
-
-- **Routing key** -- the source identifier (e.g., `github:12345` for a GitHub App, `generic:my-source` for a generic webhook)
-- **Webhook URL** -- the URL to configure in your provider's webhook settings (constructed by the Platform based on the provider type and org ID)
-- **Registered at** -- when the orchestrator first registered this source
-- **Copy button** -- copies the webhook URL to the clipboard
-
-**Read-only** -- sources cannot be created, edited, or deleted from the dashboard. They are managed entirely by orchestrator connections. When an orchestrator disconnects, its sources remain visible (they are not automatically removed).
-
-**Empty state** -- if no orchestrator has connected yet, the tab shows "No webhook sources registered" with a link to the operator setup guide.
-
-**Webhook secrets** -- webhook HMAC secrets are not visible in the dashboard. They are stored in the orchestrator's database (`webhook_secrets` table) and pushed to the Platform via the `source.secrets` WebSocket message after registration. The Platform uses these secrets to verify incoming webhook signatures. Secrets are configured in the orchestrator's database, not through the UI.
-
-**Adding a new source** requires:
-
-1. Configure a new provider in the orchestrator (e.g., add a GitHub App to the orchestrator's provider config)
-2. Seed the webhook secret in the orchestrator's `webhook_secrets` database table
-3. Restart the orchestrator -- it will register the new source with the Platform on connection
-4. Configure the webhook URL (shown in the sources tab) in the provider's settings (e.g., GitHub App webhook URL)
-
-### Event log
-
-The event log tab (`/orgs/:customerId/settings/event-log`) shows every inbound webhook this organization has received. Each row joins two tiers of records:
-
-1. **Platform record** -- written by the Platform relay on every delivery: routing key, event, action, repo, routing target, status, SHA-256 payload hash. The Platform never persists the payload (trust boundary).
-2. **Orchestrator record** -- written by the destination orchestrator when it processes the delivery: full payload (in object storage), processing outcome (`processed` / `duplicate` / `lockfile_missing` / `failed`), matched workflow count, first run spawned (if any), and a payload hash that matches the Platform record for cross-tier correlation.
-
-The list view supports filters for routing key, event type, status, and free-text delivery ID search. Click a row to open a detail panel with both tiers' projections side-by-side, plus the payload viewer.
-
-**Permissions:**
-
-- `event_log:read` -- list rows and view metadata in the detail panel.
-- `event_log:read_payload` -- additionally view the raw webhook payload body. (Owners and admins inherit this. Lower-tier roles see "Payload not available" with a hint to ask for an elevated role.)
-
-**Edge cases the UI surfaces:**
-
-- **Payload omitted** -- when the inbound payload exceeded the orchestrator's `eventLog.maxPayloadBytes` soft cap (default 5 MB) or the object-storage write failed, the row is still recorded with `payload_omitted=true`. The hash is preserved so operators can correlate against `KICI_WEBHOOK_PAYLOAD_DIR` or raw logs.
-- **Orchestrator unavailable** -- when the orchestrator does not respond within 2 seconds of the merge fan-out, the list still loads with Platform-side metadata only, marked with an `orchestrator_unavailable` banner.
-- **Orchestrator-only deliveries** -- direct-ingress deliveries (independent / hybrid mode) that never crossed the Platform appear with `platform.status = orchestrator_only`.
-
-Retention is 30 days on both tiers, matching the Platform `event_log` audit window.
-
-<!-- help:personal-profile#account -->
-
-Account settings let you view your profile information (name, email) and manage your KiCI account. Changes here apply across all organizations you belong to.
-
-<!-- /help:personal-profile -->
-
-<!-- help:personal-pats#account -->
-
-Personal access tokens (PATs) are long-lived credentials for programmatic API access.
-
-Create a PAT to authenticate CLI tools or scripts without going through the OIDC login flow. Tokens can be revoked at any time.
-
-Use a token's clone button to open the creation modal prefilled with that token's name, expiry, and permissions.
-
-<!-- /help:personal-pats -->
-
-<!-- help:personal-linked-accounts#account -->
-
-Linked accounts connect your external provider identities (like GitHub) to your KiCI account. Linking shows your provider username in run metadata and sets your contributor trust level.
-
-**Unlinking here removes the display link only** — it does not remove a sign-in method. To change how you sign in (add a password, remove GitHub login), use the **Account console** link, or see [Account and sign-in](./account-and-login.md).
-
-<!-- /help:personal-linked-accounts -->
-
-<!-- help:orgs-list#organizations -->
-
-Organizations are the top-level container for your CI/CD resources. Each org has its own runs, settings, environments, secrets, and team members. Select an organization to manage its workflows and configuration.
-
-<!-- /help:orgs-list -->
-
-<!-- help:orchestrators-list#orchestrators -->
-
-The Orchestrators page lists every orchestrator currently connected to this org, keyed by **cluster name**. Each row shows:
-
-- **Cluster** — the human-friendly cluster name set on the orch via `kici-admin cluster-name set <name>`, or an auto-generated `cluster-<6hex>` if no operator has renamed it.
-- **Role** — `coordinator` (talks to Platform directly) or `worker` (relays through a coordinator).
-- **Version**, **mode**, **routing keys**, and **last heartbeat**.
-
-Click a cluster to drill into its per-orch surfaces (security policy, environments, secrets, DLQ, registrations, global workflows). Different clusters in the same org can have different settings — this page is the entry point that lets you pick which cluster you're configuring.
-
-<!-- /help:orchestrators-list -->
-
-<!-- help:orchestrators-scope#orchestrators -->
-
-Every panel inside this view scopes to the named cluster. Settings shown here come from that orchestrator's own database — a sibling orchestrator in the same org may have a different security policy, different environments, and different secrets.
-
-When the cluster shows **disconnected**, the orch is offline and its current state can't be queried. Most child pages will return 404 in that state; return to the orchestrator list to find a connected cluster.
-
-To rename a cluster, run `kici-admin cluster-name set <new>` on the orchestrator host and restart the orch service so the new name reaches Platform on the next `source.register`.
-
-<!-- /help:orchestrators-scope -->
-
-## Workflows
-
-The workflows page (`/orgs/:customerId/workflows`) shows permanently registered workflows listening for events. It displays a filterable table with columns for workflow name, repository, trigger types, last triggered time, next fire time (for scheduled workflows), source repos, and actions.
-
-Each row is expandable to show trigger configuration details. Rows include action controls: a "Run now" button for manual triggering, a toggle switch to enable/disable the workflow, and a delete button with a confirmation modal (optionally cancelling active runs). Stale workflows (no triggers in the last 30 days) show a yellow "Stale" badge. Registry health indicators (version, sync status, last updated) appear above the table.
-
-Filters include trigger type, repository, and workflow name.
-
-## Diagnostics
-
-The diagnostics page (`/orgs/:customerId/diagnostics`) provides infrastructure health monitoring. It has four sections:
-
-1. **Execution metrics** -- cards showing total runs (24h), success rate, average duration, and active jobs (queued + running). Refreshes every 30 seconds.
-2. **Infrastructure alerts** -- banner summarizing any critical or warning alerts from connected orchestrators
-3. **Infrastructure tree** -- hierarchical view of orchestrators, their scalers, and agents. Refreshes every 10 seconds. Each orchestrator row shows:
-   - **`orchestrator:`** (bold monospace, left group) -- the orchestrator's cluster instance ID, set via `KICI_CLUSTER_INSTANCE_ID` env var or auto-generated as a UUID. If no instance ID is set, the first 8 characters of the connection ID are shown here instead.
-   - **`conn:`** (dimmed monospace, left group) -- first 8 characters of the WebSocket connection ID assigned by the Platform relay. Only shown when an explicit instance ID is present.
-   - Connection status badge, role badge (coordinator or worker), version badge (left group, after the ID labels)
-   - **`host:`** badge (right side) -- the system hostname of the machine running the orchestrator process
-   - Additional badges on the right side: running-as user, CPU count, memory usage, uptime
-
-   Each orchestrator lists its **scalers** (indented at level 1) showing scaler name, type badge (container/firecracker/bare-metal), active/max agent count, and a config info popover. Below each scaler, its **agents** (indented at level 2) display agent ID, platform/arch, heartbeat age, hostname, running-as user, CPU count, memory, uptime, and version. Labels (both user-defined and auto-generated `kici:` prefixed) are shown on a separate row beneath scalers and stateful agents, with a tooltip distinguishing user labels from auto labels.
-
-4. **Secret backends** -- health cards for each configured secret backend (e.g. OpenBao), showing connection status with sync and test actions. Allows triggering a manual sync or connectivity test per backend.
-
-## Environments
-
-The environments page (`/orgs/:customerId/environments`) lists all deployment environments for the organization. Each environment shows its name, type (fixed or glob pattern), protection status (branch restrictions, concurrency limits, required reviewers, wait timers), and enabled/disabled state.
-
-Users with `environments:admin` permission can create new environments via a modal dialog, choosing between fixed and glob (pattern-matching) types. Clicking an environment row navigates to the environment detail page.
-
-### Environment detail
-
-The environment detail page (`/orgs/:customerId/environments/:environmentId`) shows a header with the environment name, type badge, enabled/disabled toggle, and a delete button. Below the header, a tabbed layout provides four sections:
-
-1. **Variables** (default) -- environment-scoped variables
-2. **Secrets** -- secrets bound to this environment
-3. **Protection** -- protection rules (branch restrictions, concurrency limits, required reviewers, wait timers)
-4. **History** -- audit history of changes to this environment
-
-Tab selection syncs with the URL path (`/orgs/:customerId/environments/:environmentId/variables`, `/orgs/:customerId/environments/:environmentId/protection`, etc.).
-
-## Secrets
+```
 
-The secrets page (`/orgs/:customerId/secrets`) provides a scope-centric view of all secrets in the organization. Secrets are organized into a scope tree with environment binding checkboxes, allowing you to control which secret scopes are available in which environments.
+In queue mode, the agent that picked up the queued run **stays connected** to the orchestrator and parks on a long-poll wait. When the holder finishes (success, failure, or cancel), the orchestrator dequeues the FIFO-next entry and pushes a `proceed` notification over the same WebSocket; the queued agent then continues with normal step execution against the workspace it already has. The agent's slot is therefore held for the duration of the queue wait — bound by `KICI_CONCURRENCY_WAIT_TIMEOUT_MS` (default 1 hour).
 
-Permission-gated: `secrets:read` to view scopes, `secrets:write` to add or delete secrets, `environments:write` to modify environment bindings.
+```typescript
+workflow('migrate-db', {
+  concurrency: {
+    group: () => 'migrations',
+    cancelInProgress: false,
+    max: 1,
+  },
+  jobs: [
+    /* ... */
+  ],
+});
+```
 
-### Where secrets live
+The dashboard will show a "Queued" badge with the reason: "Waiting for deploy-main (1 ahead)".
 
-Secret values are stored in the orchestrator's secret store and authorized through the orchestrator's RBAC. The dashboard surfaces secret **names** and scope membership for every secret regardless of where the value was entered.
+## Max concurrent runs
 
-Whether secret **values** can be set from the dashboard depends on the orchestrator's [dashboard-write policy](/operator/security/dashboard-write-policy):
+The `max` field controls how many runs can execute simultaneously in the same group:
 
-- **Permissive (default):** the "Add secret" and "Edit value" controls accept plaintext directly in the dashboard. This is how a typical SaaS CI tool works and is the right default for small teams.
-- **`secrets.set` disabled by policy:** the controls render with a lock icon, grayed out. Hovering shows the exact `kici-admin secret set` invocation needed; a copy button puts it on the clipboard. The control is inert — the dashboard issues no mutating request. Use the CLI to enter values; the dashboard refreshes within ~30 seconds and shows the new secret name.
+```typescript
+// Allow up to 3 parallel test runs per branch
+workflow('test', {
+  concurrency: {
+    group: (ctx) => `test-${ctx.branch}`,
+    cancelInProgress: false,
+    max: 3,
+  },
+  jobs: [
+    /* ... */
+  ],
+});
+```
 
-The policy state is visible at three layers in the UI:
+When `max: 1` (default), runs are fully serialized within the group.
 
-- A **lock-icon prefix** on every disabled control, with a per-control CLI hint.
-- A **per-page banner** on any page containing at least one disabled operation, listing every disabled op on that page and its CLI equivalent.
+## Group key examples
 
-The Security policy page (Settings → Security → Dashboard policy) renders the full 24-row read-only matrix with the current state and the `kici-admin` command for each row. The policy itself cannot be changed from the dashboard — the orchestrator operator manages it via `kici-admin org-settings dashboard-writes`. See [Dashboard-write policy](/operator/security/dashboard-write-policy) for the operator-side details.
+### Deploy per environment
 
-## Approval queue
+```typescript
+workflow('deploy', {
+  concurrency: {
+    group: (ctx) => `deploy-${ctx.branch}`,
+    cancelInProgress: true,
+  },
+  jobs: [
+    job('deploy-staging', {
+      runsOn: 'linux',
+      environment: 'staging',
+      steps: [
+        /* ... */
+      ],
+    }),
+  ],
+});
+```
 
-The approval queue page (`/orgs/:customerId/approval-queue`) shows held runs that are pending approval. Runs can be held due to environment protection rules (required reviewers, wait timers). The page supports filtering by status (pending, approved, rejected, expired) and provides approve/reject actions for users with `environments:write` permission. Users with `environments:admin` permission can skip wait timers.
+### Global singleton
 
-## Account
+```typescript
+// Only one migration can run at a time, regardless of branch
+workflow('migrate', {
+  concurrency: {
+    group: () => 'db-migration',
+    cancelInProgress: false,
+  },
+  jobs: [
+    /* ... */
+  ],
+});
+```
 
-The standalone account page (`/account`) provides access to personal settings outside of any organization context. It has three tabs:
+### Environment-aware groups
 
-- **Profile** -- view your name and email
-- **Personal access tokens** -- create and revoke PATs for programmatic API access
-- **Linked accounts** -- connect external provider identities (e.g. GitHub) to your KiCI account
+```typescript
+// Serialize deploys per environment
+workflow('deploy', {
+  concurrency: {
+    group: (ctx) => {
+      const env = ctx.branch === 'main' ? 'production' : 'staging';
+      return `deploy-${env}`;
+    },
+    cancelInProgress: true,
+  },
+  jobs: [
+    /* ... */
+  ],
+});
+```
 
-Linked accounts control run-attribution metadata only — unlinking a provider here does not remove it as a way to sign in. To change how you sign in, see [Account and sign-in](./account-and-login.md).
+## Interaction with environment protection
 
-This page is also accessible within an org context via the user menu in the sidebar (`/orgs/:customerId/account`).
+When a workflow has both `concurrency` and `environment` protection rules:
 
-## Admin section
+1. Environment protection gates (required reviewers, wait timer) apply first
+2. Concurrency group check happens after protection gates pass
+3. If the run is queued by concurrency, it keeps its protection approval
 
-When viewing the `kici-admin` organization, the dashboard switches to an admin-mode interface for platform-wide management. The admin pages are:
+This means a run that passed approval won't need re-approval if it gets queued by concurrency.
 
-- **Overview** (`/orgs/kici-admin/admin`) -- embedded Grafana dashboards with three tabs: System, Orgs, and Execution
-- **Organizations** (`/orgs/kici-admin/admin/orgs`) -- table of all organizations with plan type, member count, Stripe status, and creation date; rows link to org detail pages
-  - **Org detail** (`/orgs/kici-admin/admin/orgs/:orgId`) -- org info summary, plan limit controls, current usage stats with over-limit warnings, quick actions, and a tabbed section with audit log
-- **Connections** (`/orgs/kici-admin/admin/connections`) -- table of connected orchestrators showing org, routing keys, heartbeat age, running jobs, and force-disconnect action
-- **Scheduled jobs** (`/orgs/kici-admin/admin/jobs`) -- table of Platform scheduled background jobs with cron schedule, last run status, consecutive failure count, estimated next run time, and a "Run now" action to trigger immediate execution
-- **Audit log** (`/orgs/kici-admin/admin/audit-log`) -- paginated table of platform-level admin actions with expandable JSON details
-- **Metrics** -- external link to the Grafana instance
+## Cancelling queued runs
 
-## Organizations
+Queued runs can be cancelled before they start executing. The cancel request removes them from the queue immediately -- they don't go through the grace period since no step is running.
 
-The organizations page (`/orgs`) lists all organizations your account has access to.
+## Job-level concurrency groups
 
-Organizations are sorted alphabetically by display name. Each entry shows your role (owner or member). A "Create organization" button opens an inline form to create a new org by name.
+In addition to workflow-level concurrency, individual jobs can define their own concurrency group via the `concurrencyGroup` property. This controls concurrent execution at the job level rather than the workflow level. See [Environments — concurrency groups](environments.md#concurrency-groups) for details.
 
-## Theme
+## Local execution
 
-The dashboard supports three theme modes:
+`kici run local` honors workflow-level `concurrency` per-machine, per-user. The `group` callback is evaluated against the simulated event identically to the remote orchestrator path; `cancelInProgress` carries the same semantics — `true` interrupts the holder via `SIGTERM` (escalating to `SIGKILL` after a grace window) and proceeds with the new run, while `false` queues the new invocation in FIFO order until the holder finishes.
 
-- **System** (default) -- follows your operating system's dark/light preference
-- **Dark** -- forced dark mode
-- **Light** -- forced light mode
+Coordination is local only. Running the same workflow on two different machines does not serialize across them — that requires the orchestrator. For full cross-host enforcement (queueing across agents, dashboard visibility, `max > 1`), use `kici run remote` against a deployed orchestrator.
 
-Toggle between modes using the sun/moon icon in the sidebar footer. The selection persists to `localStorage`.
+Lock files live under `$XDG_RUNTIME_DIR/kici-local-locks/` on Linux, falling back to `os.tmpdir()/kici-local-locks-<uid>/`. A workflow whose `group` callback throws aborts the run with a clear error rather than running unprotected. See [`kici run local` — Concurrency enforcement](cli-reference.md#concurrency-enforcement) for the `KICI_LOCAL_LOCK_KILL_GRACE_MS` override and the diagnostic output emitted while contending on a busy lock.
 
-## Date and time preferences
+The `kici run local --concurrency <n>` flag is a separate concept — it caps **job-level** parallelism within a single run (how many jobs from one workflow run at once), not cross-run serialization.
 
-A toggle button in the sidebar lets you switch between **local time** and **UTC time** display. When UTC mode is enabled:
+---
 
-- All timestamps in the run list, run detail header, metadata panel, and log viewer show UTC times
-- Tooltips on relative timestamps (e.g. "5 minutes ago") show the absolute time in UTC
-- The timeline Gantt chart uses UTC for time labels
+_Source: `packages/sdk/src/types.ts` (WorkflowOptions.concurrency, JobOptions.concurrencyGroup)_
 
-The preference persists to `localStorage`.
+---
 
-## Keyboard shortcuts
+## Dashboard
 
-| Key           | Context    | Action                 |
-| ------------- | ---------- | ---------------------- |
-| Arrow Up/Down | Job tree   | Move focus             |
-| Enter         | Job tree   | Select job or step     |
-| Escape        | Job tree   | Navigate to first job  |
-| Enter         | Log search | Jump to next match     |
-| Shift+Enter   | Log search | Jump to previous match |
-| Escape        | Log search | Clear search           |
+Source: https://docs.kici.dev/user/dashboard/
 
-## Error pages
+The KiCI dashboard is the browser interface for monitoring workflow runs, inspecting jobs and logs, and managing your organization. It signs in via OIDC and talks to KiCI over its API.
 
-The dashboard shows informative error pages instead of blank screens:
+This guide is split across the following pages:
 
-- **404** -- "Page not found" with a "Go home" button linking to the organizations page
-- **500** -- "Failed to load" with an error message, a trace ID for support, and a "Go home" button (shown when API requests fail)
-- **Client-side rendering errors** -- caught by the error boundary, showing "Something went wrong" with a trace ID and a "Reload page" button
-- **Auth errors** -- authentication failures on the OIDC callback page show the error message with a retry mechanism and a "Back to login" link
+| Page                                                                                  | Covers                                                                  |
+| ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| [Getting started](./dashboard/getting-started.md)                                     | Onboarding checklist and your organizations list                        |
+| [Navigation and layout](./dashboard/navigation.md)                                    | Sidebar, mobile nav, theme, time display, shortcuts, error pages        |
+| [Runs and logs](./dashboard/runs.md)                                                  | Run list, run detail, the log viewer                                    |
+| [Settings](./dashboard/settings.md)                                                   | Members, roles, teams, keys, sources, billing, security, support access |
+| [Workflows, diagnostics, and orchestrators](./dashboard/workflows-and-diagnostics.md) | Registered workflows, infra health, per-cluster views                   |
+| [Environments, secrets, and approvals](./dashboard/environments-and-secrets.md)       | Environments, secret scopes, approval queue                             |
+| [Activity and DLQ](./dashboard/activity-and-dlq.md)                                   | Forensic activity log and dead-letter queue                             |
+| [Account](./dashboard/account.md)                                                     | Personal account settings                                               |
 
 ---
 
@@ -9184,29 +9054,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 +9096,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 +9507,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 +9908,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 +10051,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,9 +10277,9 @@ 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.
+> **Lock file schema version:** The lock file uses schema version 17, which widens per-job init to typed presets (`mise` / `{ mise }`) and `auto` detection on top of v16's normalized approval config, v15's per-job init config, 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.
 
 ## Webhook delivery flow
 
@@ -10117,6 +10349,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.
@@ -10218,7 +10485,7 @@ Dep cache misses alone do **not** trigger a build job. Deps are platform-specifi
 
 ### Cross-source / no-contentHash workflows
 
-- **Lock files without `contentHash`** (schema v1) skip the source cache entirely; agents compile from source. Regenerate lock files with `kici compile` to enable caching. The current lock file schema version is 15.
+- **Lock files without `contentHash`** (schema v1) skip the source cache entirely; agents compile from source. Regenerate lock files with `kici compile` to enable caching. The current lock file schema version is 17.
 - **Cross-source / global-workflow dispatch** (a workflow registered against source A fired by a webhook on source B) bypasses both caches. The registration's lock file entry still carries `contentHash`, but the cross-source path always clone-and-installs — the eval temp dir doesn't ship `@kici-dev/sdk`. The execution agent still verifies `contentHash` against the cloned source for drift detection.
 
 ### Build deduplication
@@ -10935,7 +11202,7 @@ The agent is the execution worker. It runs on customer infrastructure and has fu
 
 ### `@kici-dev/engine`
 
-Shared business logic used by all three tiers. Single source of truth for cross-tier concerns. Has no internal `@kici-dev/*` dependencies (only zod, picomatch, and jsonpath-plus).
+Shared business logic used by all three tiers. Single source of truth for cross-tier concerns. Has no internal `@kici-dev/*` dependencies -- only a handful of third-party libraries.
 
 - Protocol message schemas (Zod-based, direction-specific unions including dashboard REST-over-WS, browser live streaming, test run lifecycle, observer channel, log pull, run events, peer-to-peer, cluster join, and source registration)
 - Provider interfaces (WebhookNormalizer, LockFileFetcher, ChangedFilesFetcher, CloneTokenProvider, RepoUrlBuilder, ContributorResolver, CheckStatusPoster)
@@ -10947,7 +11214,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)