@kici-dev/compiler 0.1.17 → 0.1.18

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

@@ -312,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, pnpm, or yarn classic (v1). yarn berry (v2+) is not yet supported. 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:
 
@@ -1150,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()`:
@@ -1939,7 +1979,7 @@ const build = job({
 
 #### runsOn forms
 
-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:
+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
@@ -1981,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.
@@ -3186,6 +3268,29 @@ 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`:
@@ -3275,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:
@@ -3303,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/
@@ -3313,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
 
@@ -4262,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`.
@@ -4860,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.
 
@@ -6582,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.
 
@@ -7229,7 +7595,7 @@ kici reject <run-id> --job deploy-production --reason "Wrong release branch"
 
 You must be eligible for at least one unsatisfied clause — being a member of a named team or being a named user. The orchestrator verifies eligibility against the operator-defined teams, so naming a team in your workflow can never let an ineligible person release the gate. The command reports whether the element was released, how many clauses remain, or that it was rejected. See [`kici approve`](cli-reference.md#kici-approve) for the full command reference.
 
-You can also approve from the dashboard approval queue. See [Dashboard](dashboard.md#approval-queue).
+You can also approve from the dashboard approval queue. See [Dashboard](dashboard/environments-and-secrets.md#approval-queue).
 
 ## See also
 
@@ -7468,1034 +7834,20 @@ _Source: `packages/sdk/src/types.ts` (WorkflowOptions.concurrency, JobOptions.co
 
 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, Graph, 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
-- **Graph** -- dependency graph (DAG) view of the run's jobs: each job is a node, and arrows point from a job to the jobs that depend on it. Matrix jobs appear as one node per variant. Each node shows the job name, status, and duration; a job's left accent border and the status line are colored by run state (running nodes pulse, failed nodes are red, skipped nodes are dimmed). Click a node to open that job's details (the same selection the Timeline and right panel use); hover a node to highlight what it depends on and what depends on it. Dependency edges flagged to run even when the upstream failed are drawn as dashed orange arrows. The Timeline tab remains the place to see durations and overlap on a time axis
-- **Summary** -- contextual overview scoped to the current selection (run-level trigger/repo/timing info, or job-level execution context with environment variables, runtime info, and sandbox details)
-- **Attestations** -- build-provenance attestations produced by the run's steps (via `ctx.attestProvenance`), one row per attested artifact with a **verified** badge and a bundle download. See [Build provenance and attestations](./provenance.md#viewing-attestations-in-the-dashboard) for what the badge checks and how to verify a bundle against a specific file.
-
-On wide desktop (>= 1200px), Metadata is shown in a dedicated sidebar panel instead of as a tab.
-
-### 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.
-
-Permission-gated: `secrets:read` to view scopes, `secrets:write` to add or delete secrets, `environments:write` to modify environment bindings.
-
-### Where secrets live
-
-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.
-
-Whether secret **values** can be set from the dashboard depends on the orchestrator's [dashboard-write policy](/operator/security/dashboard-write-policy):
-
-- **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.
-
-The policy state is visible at three layers in the UI:
-
-- 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.
-
-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.
-
-## Approval queue
-
-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.
-
-## Account
-
-The standalone account page (`/account`) provides access to personal settings outside of any organization context. It has three tabs:
-
-- **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
-
-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).
-
-This page is also accessible within an org context via the user menu in the sidebar (`/orgs/:customerId/account`).
-
-## Admin section
-
-When viewing the `kici-admin` organization, the dashboard switches to an admin-mode interface for platform-wide management. The admin pages are:
-
-- **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
-
-## Organizations
-
-The organizations page (`/orgs`) lists all organizations your account has access to.
-
-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.
-
-## Theme
-
-The dashboard supports three theme modes:
-
-- **System** (default) -- follows your operating system's dark/light preference
-- **Dark** -- forced dark mode
-- **Light** -- forced light mode
-
-Toggle between modes using the sun/moon icon in the sidebar footer. The selection persists to `localStorage`.
-
-## Date and time preferences
-
-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
-
-The preference persists to `localStorage`.
-
-## Keyboard shortcuts
-
-| 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           |
-
-## 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                                               |
 
 ---
 
@@ -10927,7 +10279,7 @@ Source: https://docs.kici.dev/architecture/data-flows/
 
 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
 
@@ -11133,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
@@ -11850,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)