@kici-dev/compiler 0.1.27 → 0.2.0

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

@@ -1,149 +1,6 @@
-# KiCI SDK reference
+# KiCI SDK reference: core
 
-This bundle covers: Authoring API: workflow/job/step factories, triggers, rules, matrix, runtime, caching.
-
-## Caching
-
-Source: https://docs.kici.dev/user/sdk/caching/
-
-KiCI ships a general-purpose cache for any files or directories your workflow produces — compiled artifacts, downloaded toolchains, package manager stores, build outputs. A cache entry is keyed, immutable once written, and shared across runs of the same repository so a later run can restore what an earlier run produced instead of recomputing it.
-
-Two surfaces drive the same cache:
-
-- **Declarative** — a `cache` field on a job or a step. The runtime restores before the work runs and saves after it succeeds, with no code in your step body.
-- **Imperative** — `ctx.cache.restore(spec)` / `ctx.cache.save(spec)` inside a step body, for fine-grained control over when restore and save happen.
-
-The cache is backed by the orchestrator's object storage. Entries are isolated per organization and per ref scope (see [Isolation](https://docs.kici.dev/user/sdk/caching/#isolation)); no other tenant can read your cache, and an untrusted/fork ref can never poison the cache a trusted branch reads.
-
-## CacheSpec
-
-Both surfaces take the same shape:
-
-```typescript
-interface CacheSpec {
-  /** Exact cache key. First save wins; re-saving an existing key is a no-op. */
-  key: string;
-  /** Files/directories to cache. Repo-root-relative or `~`-prefixed. */
-  paths: string[];
-  /** Ordered prefix fallbacks for partial restore; newest matching entry wins. */
-  restoreKeys?: string[];
-}
-```
-
-- **`key`** is the exact cache key. It is **immutable** — the first save under a given key wins, and any later save under the same exact key is a no-op (the existing entry is never overwritten). Build keys from inputs that change when the cached content should change, e.g. a hash of your lockfile: `` key: `deps-${await ctx.$`sha256sum pnpm-lock.yaml`}` ``.
-- **`paths`** are the files and directories to archive, repo-root-relative or `~`-prefixed (the agent expands `~` to the workspace home). At least one path is required.
-- **`restoreKeys`** are ordered **prefix** fallbacks tried only when the exact `key` misses on restore. Each prefix is matched against existing entries; the **newest** matching entry wins. This lets a run that changed its lockfile still restore the closest previous cache and rebuild incrementally.
-
-## Declarative cache
-
-Add a `cache` field to a job or a step. It accepts one `CacheSpec` or an array of them. The runtime restores every spec before the job/step runs (surfaced as a `cache:restore` pseudo-step) and saves every spec after it completes successfully (surfaced as a `cache:save` pseudo-step):
-
-```typescript
-import { job } from '@kici-dev/sdk';
-
-job('build', {
-  runsOn: 'linux-x64',
-  cache: {
-    key: 'mise-tools-v1',
-    paths: ['~/.local/share/mise'],
-  },
-  steps: [
-    step('install-tools', async (ctx) => {
-      await ctx.$`mise install`;
-    }),
-    step('build', async (ctx) => {
-      await ctx.$`mise exec -- pnpm build`;
-    }),
-  ],
-});
-```
-
-Step-level cache scopes the restore/save to a single step:
-
-```typescript
-step('deps', {
-  cache: { key: `npm-${lockfileHash}`, paths: ['node_modules'], restoreKeys: ['npm-'] },
-  run: async (ctx) => {
-    await ctx.$`pnpm install --frozen-lockfile`;
-  },
-});
-```
-
-On a cache **hit**, the archived paths are restored before the step body runs, so `pnpm install` sees a warm `node_modules`. On a **miss**, the step runs cold and the resulting paths are saved under the exact key for the next run.
-
-## Imperative cache (`ctx.cache`)
-
-When you need to decide at runtime whether to restore or save — for example, save only when a build actually changed something — use the imperative API on the step context:
-
-```typescript
-step('build', async (ctx) => {
-  const result = await ctx.cache.restore({
-    key: `build-${sourceHash}`,
-    paths: ['dist'],
-    restoreKeys: ['build-'],
-  });
-
-  if (result.hit) {
-    ctx.log.info(`restored cache (matched ${result.matchedKey})`);
-  }
-
-  await ctx.$`pnpm build`;
-
-  await ctx.cache.save({ key: `build-${sourceHash}`, paths: ['dist'] });
-});
-```
-
-`restore(spec)` returns `{ hit, matchedKey? }`:
-
-- `hit` is `true` when the exact `key` matched **or** a `restoreKeys` prefix matched.
-- `matchedKey` is the full key that actually matched — the exact key on a direct hit, or the full key of the matched prefix entry on a fallback hit.
-
-`save(spec)` archives `spec.paths` under `spec.key`. Like the declarative surface, it is immutable: the first save under an exact key wins, and re-saving the same key is a no-op.
-
-## Restore semantics
-
-A restore resolves in this order:
-
-1. **Exact key.** If an entry exists under the exact `key`, it is restored and `matchedKey === key`.
-2. **restoreKeys prefix fallback.** Each `restoreKeys` prefix is tried in order. Within a prefix, the **newest** matching entry wins; `matchedKey` is that entry's full key.
-3. **Miss.** If nothing matches, `hit` is `false` and no paths are restored.
-
-This mirrors the familiar lockfile-hash pattern: key the entry on the exact lockfile hash, and add a `restoreKeys` prefix so a changed lockfile still restores the most recent prior cache to rebuild from.
-
-## Immutability
-
-Cache keys are write-once. The **first** save under an exact key wins; every subsequent save under that same exact key is a no-op and the original bytes are preserved. To publish new content, use a new key (typically by including a content hash in the key). Immutability is what makes a cache hit safe to trust — the bytes behind a given key never change after they are first written.
-
-## Isolation
-
-Each cache entry is scoped to your organization and to the ref's trust level:
-
-- **Trusted refs** (your repository's own branches, default branch) read and write a **shared** scope visible to the whole org for that repository.
-- **Untrusted / fork refs** read the shared scope as a fallback but write to an **isolated** per-run scope. A fork build can therefore benefit from a warm cache the trusted branch produced, but can never write into the shared scope — so a malicious fork cannot poison the cache a trusted branch later restores.
-
-No tenant can read another tenant's cache; the org boundary is enforced in the cache key namespace.
-
-## Eviction
-
-Cache storage is bounded per organization. Two mechanisms keep it bounded:
-
-- **Quota** — when a save pushes the org over its byte quota (`KICI_USER_CACHE_QUOTA_BYTES`, default 5 GiB), the oldest entries are evicted until the org is back under quota.
-- **TTL** — entries unused for `KICI_USER_CACHE_TTL_MS` (default 7 days) expire. The TTL refreshes on read (touch-on-read), so an actively used cache stays warm.
-
-Both knobs are operator-configured on the orchestrator — see [orchestrator storage layout](https://docs.kici.dev/operator/orchestrator/storage-layout/).
-
-## Observability
-
-Each cache restore and save surfaces in the run timeline as a `cache:restore` / `cache:save` pseudo-step, reporting the outcome (hit/miss/saved, the matched key, bytes). The same outcomes are recorded as `cache.restore` / `cache.save` run events. See [data flows](https://docs.kici.dev/architecture/data-flows/#user-facing-cache-flow) for the restore/save protocol.
-
-## See also
-
-- [Core](https://docs.kici.dev/user/sdk/core/) -- `job()` / `step()` factories the `cache` field attaches to
-- [Runtime](https://docs.kici.dev/user/sdk/runtime/) -- `StepContext`, where `ctx.cache` lives
-- [Orchestrator storage layout](https://docs.kici.dev/operator/orchestrator/storage-layout/) -- cache prefix, quota, TTL, and eviction
-- [Data flows](https://docs.kici.dev/architecture/data-flows/#user-facing-cache-flow) -- restore/save protocol and trust→scope mapping
-
----
+This bundle covers: Core authoring API: workflow/job/step factories, triggers, rules, matrix, dynamic jobs, cross-job outputs.
 
 ## SDK reference: core
 
@@ -189,7 +46,7 @@ export default workflow('ci', {
 });
 ```
 
-Secret scoping happens at the job level via `environment` (see [job options](https://docs.kici.dev/user/sdk/core/#jobname-options--joboptions) and [Secrets](https://docs.kici.dev/user/secrets/)) — the workflow itself does not declare which secret environments it can read.
+Secret scoping happens at the job level via `context` (see [job options](https://docs.kici.dev/user/sdk/core/#jobname-options--joboptions) and [Secrets](https://docs.kici.dev/user/secrets/)) — the workflow itself does not declare which secret contexts it can read.
 
 ### job(name, options) / job(options)
 
@@ -202,33 +59,34 @@ function job(options: JobOptions): Job;
 
 **Parameters:**
 
-| Parameter                  | Type                                                            | Required             | Description                                                                                                                                                                                              |
-| -------------------------- | --------------------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `name`                     | `string`                                                        | no                   | Job name (auto-generated UUID if omitted)                                                                                                                                                                |
-| `options.runsOn`           | `RunsOn`                                                        | yes                  | Runner label(s) and optional exclusions (see below)                                                                                                                                                      |
-| `options.steps`            | `StepInput[]`                                                   | yes (or use `run`)   | Steps to execute in order. Mutually exclusive with `run`.                                                                                                                                                |
-| `options.run`              | `(ctx) => Promise<unknown>`                                     | yes (or use `steps`) | Single-step shorthand -- see [Single-step job shorthand](https://docs.kici.dev/user/sdk/core/#single-step-job-shorthand). Mutually exclusive with `steps`.                                                                                   |
-| `options.needs`            | `NeedsEntry[]`                                                  | no                   | Job dependencies (must complete first) -- see [Job dependencies (`needs`)](https://docs.kici.dev/user/sdk/core/#job-dependencies-needs)                                                                                                      |
-| `options.rules`            | `Rule[]`                                                        | no                   | Conditions for conditional execution                                                                                                                                                                     |
-| `options.description`      | `string`                                                        | no                   | Human-readable description                                                                                                                                                                               |
-| `options.matrix`           | `Matrix`                                                        | no                   | Matrix configuration for job expansion                                                                                                                                                                   |
-| `options.include`          | `MatrixInclude[]`                                               | no                   | Additional matrix combinations                                                                                                                                                                           |
-| `options.exclude`          | `MatrixExclude[]`                                               | no                   | Matrix combinations to remove                                                                                                                                                                            |
-| `options.checkout`         | `boolean`                                                       | no (default: `true`) | When `false`, agent skips git clone. Useful for deploy/notify jobs.                                                                                                                                      |
-| `options.container`        | `string \| ContainerConfig`                                     | no                   | Docker image for job execution. String form is the image name; object form adds `env`. All steps run inside the container.                                                                               |
-| `options.environment`      | `string \| ((event) => string \| Promise<string>)`              | no                   | Deployment environment for this job. Static string or async/dynamic function -- see [Dynamic values](https://docs.kici.dev/user/dynamic-values/).                                                                              |
-| `options.env`              | `Record<string, string> \| ((event) => Record<string, string>)` | no                   | Environment variables. Static object or async/dynamic function -- see [Dynamic values](https://docs.kici.dev/user/dynamic-values/).                                                                                            |
-| `options.concurrencyGroup` | `string \| ((event) => string \| Promise<string>)`              | no                   | Concurrency group name (defaults to environment name) -- see [Concurrency](https://docs.kici.dev/user/concurrency/).                                                                                                           |
-| `options.onCancel`         | `HookInput`                                                     | no                   | Hook that runs when the job is cancelled                                                                                                                                                                 |
-| `options.cleanup`          | `HookInput`                                                     | no                   | Hook that always runs after completion                                                                                                                                                                   |
-| `options.onSuccess`        | `HookInput`                                                     | no                   | Hook that runs when the job succeeds                                                                                                                                                                     |
-| `options.onFailure`        | `HookInput`                                                     | no                   | Hook that runs when the job fails                                                                                                                                                                        |
-| `options.beforeStep`       | `HookInput`                                                     | no                   | Hook that runs before each step                                                                                                                                                                          |
-| `options.afterStep`        | `HookInput`                                                     | no                   | Hook that runs after each step                                                                                                                                                                           |
-| `options.gracePeriod`      | `number`                                                        | no                   | Seconds before SIGKILL after SIGTERM during cancellation -- see [Hooks](https://docs.kici.dev/user/hooks/#hook-timeout).                                                                                                       |
-| `options.timeout`          | `number`                                                        | no                   | Total job wall-clock timeout in milliseconds (init + all steps + hooks). On breach the job is aborted and reported timed out. See [Timeouts](https://docs.kici.dev/user/sdk/core/#timeouts).                                                 |
-| `options.resources`        | `ResourceRequest`                                               | no                   | Per-job CPU / memory request and limit. See [Per-job resources](https://docs.kici.dev/user/sdk/core/#per-job-resources) below.                                                                                                               |
-| `options.init`             | `InitConfig`                                                    | no                   | Per-job initialization run after clone, before steps -- provisions a toolchain. A generic config, a typed preset (`'mise'` / `{ mise }`), `'auto'`, or `false`. See [Per-job init](https://docs.kici.dev/user/sdk/core/#per-job-init) below. |
+| Parameter                  | Type                                                                   | Required             | Description                                                                                                                                                                                                  |
+| -------------------------- | ---------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `name`                     | `string`                                                               | no                   | Job name (auto-generated UUID if omitted)                                                                                                                                                                    |
+| `options.runsOn`           | `RunsOn`                                                               | yes                  | Runner label(s) and optional exclusions (see below)                                                                                                                                                          |
+| `options.steps`            | `StepInput[]`                                                          | yes (or use `run`)   | Steps to execute in order. Mutually exclusive with `run`.                                                                                                                                                    |
+| `options.run`              | `(ctx) => Promise<unknown>`                                            | yes (or use `steps`) | Single-step shorthand -- see [Single-step job shorthand](https://docs.kici.dev/user/sdk/core/#single-step-job-shorthand). Mutually exclusive with `steps`.                                                                                       |
+| `options.needs`            | `NeedsEntry[]`                                                         | no                   | Job dependencies (must complete first) -- see [Job dependencies (`needs`)](https://docs.kici.dev/user/sdk/core/#job-dependencies-needs)                                                                                                          |
+| `options.rules`            | `Rule[]`                                                               | no                   | Conditions for conditional execution                                                                                                                                                                         |
+| `options.description`      | `string`                                                               | no                   | Human-readable description                                                                                                                                                                                   |
+| `options.matrix`           | `Matrix`                                                               | no                   | Matrix configuration for job expansion                                                                                                                                                                       |
+| `options.include`          | `MatrixInclude[]`                                                      | no                   | Additional matrix combinations                                                                                                                                                                               |
+| `options.exclude`          | `MatrixExclude[]`                                                      | no                   | Matrix combinations to remove                                                                                                                                                                                |
+| `options.checkout`         | `boolean`                                                              | no (default: `true`) | When `false`, agent skips git clone. Useful for deploy/notify jobs.                                                                                                                                          |
+| `options.container`        | `string \| ContainerConfig`                                            | no                   | Docker image for job execution. String form is the image name; object form adds `env`. All steps run inside the container.                                                                                   |
+| `options.sandbox`          | `{ capabilities?: string[]; network?: 'default' \| 'none' \| 'host' }` | no                   | Per-job container sandbox escape hatch (container jobs only). Request extra Linux capabilities / host networking; granted only within your operator's allow-list, else the run fails at dispatch. See below. |
+| `options.environment`      | `string \| ((event) => string \| Promise<string>)`                     | no                   | Deployment environment for this job. Static string or async/dynamic function -- see [Dynamic values](https://docs.kici.dev/user/dynamic-values/).                                                                                  |
+| `options.env`              | `Record<string, string> \| ((event) => Record<string, string>)`        | no                   | Environment variables. Static object or async/dynamic function -- see [Dynamic values](https://docs.kici.dev/user/dynamic-values/).                                                                                                |
+| `options.concurrencyGroup` | `string \| ((event) => string \| Promise<string>)`                     | no                   | Concurrency group name (defaults to environment name) -- see [Concurrency](https://docs.kici.dev/user/concurrency/).                                                                                                               |
+| `options.onCancel`         | `HookInput`                                                            | no                   | Hook that runs when the job is cancelled                                                                                                                                                                     |
+| `options.cleanup`          | `HookInput`                                                            | no                   | Hook that always runs after completion                                                                                                                                                                       |
+| `options.onSuccess`        | `HookInput`                                                            | no                   | Hook that runs when the job succeeds                                                                                                                                                                         |
+| `options.onFailure`        | `HookInput`                                                            | no                   | Hook that runs when the job fails                                                                                                                                                                            |
+| `options.beforeStep`       | `HookInput`                                                            | no                   | Hook that runs before each step                                                                                                                                                                              |
+| `options.afterStep`        | `HookInput`                                                            | no                   | Hook that runs after each step                                                                                                                                                                               |
+| `options.gracePeriod`      | `number`                                                               | no                   | Seconds before SIGKILL after SIGTERM during cancellation -- see [Hooks](https://docs.kici.dev/user/hooks/#hook-timeout).                                                                                                           |
+| `options.timeout`          | `number`                                                               | no                   | Total job wall-clock timeout in milliseconds (init + all steps + hooks). On breach the job is aborted and reported timed out. See [Timeouts](https://docs.kici.dev/user/sdk/core/#timeouts).                                                     |
+| `options.resources`        | `ResourceRequest`                                                      | no                   | Per-job CPU / memory request and limit. See [Per-job resources](https://docs.kici.dev/user/sdk/core/#per-job-resources) below.                                                                                                                   |
+| `options.init`             | `InitConfig`                                                           | no                   | Per-job initialization run after clone, before steps -- provisions a toolchain. A generic config, a typed preset (`'mise'` / `{ mise }`), `'auto'`, or `false`. See [Per-job init](https://docs.kici.dev/user/sdk/core/#per-job-init) below.     |
 
 **Returns:** `Job` -- an immutable job definition.
 
@@ -463,6 +321,29 @@ Per-backend kernel enforcement of `limits`:
 - **Firecracker backend:** always enforced. Fractional CPU rounds up to the nearest integer vCPU.
 - **Bare-metal backend:** advisory by default — the scaler caps still apply, but no cgroup is created. Operators can opt in to kernel enforcement via `enforceCgroups: true` on the scaler entry.
 
+### Per-job sandbox escape hatch
+
+Container-sandbox jobs (a job with a `container:` image) run with all Linux capabilities dropped by default. When a job genuinely needs one extra capability or the host network namespace, request it with `sandbox:`:
+
+```ts
+job('probe', {
+  runsOn: 'kici:os:linux',
+  container: 'node:20',
+  sandbox: {
+    capabilities: ['NET_ADMIN'], // added back on top of the dropped-all default
+    network: 'host', // share the host network namespace
+  },
+  steps: [/* ... */],
+});
+```
+
+Two levers are exposed, and only these two are ever grantable:
+
+- **`capabilities`** — extra Linux capabilities (bare or `CAP_`-prefixed; both accepted). An unknown capability name is rejected when you compile.
+- **`network`** — `'default'` (bridge, the default), `'none'` (loopback only), or `'host'`.
+
+Every request is checked at dispatch against an allow-list your orchestrator operator controls. A capability or `network: 'host'` that the operator has not allow-listed **fails the whole run** with a reason naming what was blocked — the request is never silently ignored. `'none'` and the default bridge never need approval. Ask your operator to allow-list a capability (`kici-admin org-settings sandbox-allowlist`) before relying on it. A job with no `sandbox:` field keeps the fully hardened default.
+
 ### Per-job init
 
 `options.init` declares a hand-written command that runs **after the repo is cloned and before the job's steps execute**. Its purpose is to provision a repo-declared toolchain (a `mise` toolchain, a custom setup script, a language runtime) and put it on the environment every subsequent step sees.
@@ -757,6 +638,25 @@ const pipeline = job('pipeline', {
 });
 ```
 
+The `.result` proxy works for id-less steps too. An id-less step (`step(fn)` or `step({ run, outputs })` without a name) receives a deterministic `step-N` name when the job's steps are enumerated at execution start — before any step runs — and its `.result` resolves under that assigned name from any later step's `run` function:
+
+```typescript
+const build = step({ outputs: { version: z.string() }, run: async () => ({ version: '2.0.0' }) });
+
+const pipeline = job('pipeline', {
+  runsOn: 'default',
+  steps: [
+    build,
+    step(async () => {
+      const version = build.result.version; // resolves under the assigned step-N name
+      console.log(version); // '2.0.0'
+    }),
+  ],
+});
+```
+
+Reference `.result` only from inside another step's `run` function. Accessing it outside execution (for example at module top level, before names are assigned) raises "this step has no name yet".
+
 **Cross-job output chaining:**
 
 ```typescript
@@ -771,8 +671,13 @@ const build = job('build', {
   runsOn: 'default',
   needs: [setup],
   steps: [
-    step('compile', async (ctx) => {
-      return { version: '2.0.0' };
+    // The options form `step(name, { run })` carries the return type through, so
+    // `build.result.compile.version` is typed `string`. A bare `step(name, fn)`
+    // is a void step and contributes no typed key.
+    step('compile', {
+      run: async (ctx) => {
+        return { version: '2.0.0' };
+      },
     }),
   ],
 });
@@ -782,19 +687,43 @@ const deploy = job('deploy', {
   needs: [build],
   steps: [
     step(async (ctx) => {
-      // Multi-step job: jobRef.result.stepName.field
+      // Multi-step job: jobRef.result.stepName.field — typed `string`, a typo on
+      // `.version` or `.compile` is a compile error.
       const version = build.result.compile.version;
 
-      // Single-step job (run shorthand): jobRef.result.field
+      // Single-step job (run shorthand): jobRef.result.field — typed `string`.
       const env = setup.result.env;
 
-      // Explicit context method
+      // Explicit context method — typed to the job's output shape for a Job ref.
       const buildOutputs = ctx.jobOutputs(build);
     }),
   ],
 });
 ```
 
+**Cross-job outputs are typed.** When you pass a **job reference** (not a string)
+in `needs` and read `jobRef.result.…` or `ctx.jobOutputs(jobRef)`, the output
+types thread across the job boundary — a typo on an output field or a renamed
+step is a compile error, the same guarantee you get within a job. Two authoring
+rules unlock it:
+
+- **Name your steps and use the options form** — `step('name', { run })` carries
+  the return type into `jobRef.result.name.field` (nested by step name for
+  multi-step jobs; flat `jobRef.result.field` for the `run:` shorthand). A bare
+  `step('name', fn)` or an id-less `step(fn)` is a void step and contributes no
+  typed key.
+- **Pass references, not strings** — reading `buildJob.result.…` on the job
+  reference is typed from any job. In a `run:` shorthand job, a referenced
+  `needs: [buildJob]` also types `ctx.needs.buildJob.result.…` (the run
+  function's `ctx` derives from the job's `needs` tuple). A string
+  `needs: ['build']` still works but stays loosely typed
+  (`Record<string, unknown>`).
+
+For a dynamically-shaped job whose outputs the inference can't reproduce, supply
+the shape explicitly: `job<{ url: string }>('deploy', { … })`. A **matrix** or
+`runsOnAll` upstream returns a typed envelope — discriminate it with
+`isMatrixJobOutputs` / `isHostJobOutputs`.
+
 **Access patterns summary:**
 
 | Pattern                        | Scope                     | Notes                         |
@@ -835,14 +764,20 @@ const deploy = job('deploy', {
 
 **Run condition (`when`):** controls when a downstream edge is satisfied, based on the upstream's terminal status. `when` is keyword sugar (or a raw status-set) that resolves at compile time to the set of upstream terminal statuses that satisfy the edge. The downstream edge is satisfied when the upstream's terminal status is a member of that set.
 
-| Keyword                  | Satisfied when the upstream is… | Use for                                     |
-| ------------------------ | ------------------------------- | ------------------------------------------- |
-| `'on-success'` (default) | `success`                       | normal dependencies                         |
-| `'always'`               | any terminal status             | cleanup / notification / teardown jobs      |
-| `'on-skip'`              | `success` or `skipped`          | continue when an upstream was narrowed out  |
-| `'on-failure'`           | `failed` or `timed_out_stale`   | error-handler jobs that run only on failure |
+| Keyword                  | Satisfied when the upstream is…                               | Use for                                     |
+| ------------------------ | ------------------------------------------------------------- | ------------------------------------------- |
+| `'on-success'` (default) | `success`                                                     | normal dependencies                         |
+| `'always'`               | any terminal status                                           | cleanup / notification / teardown jobs      |
+| `'on-skip'`              | `success` or `skipped`                                        | continue when an upstream was narrowed out  |
+| `'on-failure'`           | `failed`, `timed_out_stale`, `drift_dropped`, or `unroutable` | error-handler jobs that run only on failure |
 
-For full control, pass a raw status-set instead of a keyword: `when: ['skipped', 'failed', 'timed_out_stale']`. The valid members are the terminal job statuses: `success`, `failed`, `cancelled`, `skipped`, `timed_out_stale`, `drift_dropped`.
+`'on-failure'` covers every terminal status that means the job did not do what
+the workflow declared, which includes a job dropped by determinism drift and a
+job whose `runsOn` matched no agent. It
+does **not** cover `cancelled` (deliberately stopped) or `skipped` (never ran) —
+use a raw status set if you need those.
+
+For full control, pass a raw status-set instead of a keyword: `when: ['skipped', 'failed', 'timed_out_stale']`. The valid members are the terminal job statuses: `success`, `failed`, `cancelled`, `skipped`, `timed_out_stale`, `drift_dropped`, `unroutable`.
 
 String and `Job`-reference entries default to `when: 'on-success'`. To override, use the object form (`{ name, when }` for static upstreams, `{ group, when }` for dynamic groups -- `dynamicGroup(name, { when: 'always' })` produces the latter).
 
@@ -884,10 +819,11 @@ function dynamicGroup(
 Use when a static downstream must wait for every generated job tagged with a given group name to complete. If the dynamic group produces zero jobs, the downstream dispatches immediately (empty group satisfies all upstreams).
 
 ```typescript
-const shardedTests = dynamicJob('test-shards', async (ctx) => {
-  return ctx.shardIndices.map((i) =>
-    job(`test-shard-${i}`, { runsOn: 'linux', run: async () => {} }),
-  );
+const shardedTests = dynamicJob('test-shards', async () => {
+  // Decide the shard set however you like — a constant, the event payload, or
+  // an upstream job's outputs via the result-aware `{ needs, generate }` form.
+  const shards = [0, 1, 2, 3];
+  return shards.map((i) => job(`test-shard-${i}`, { runsOn: 'linux', run: async () => {} }));
 });
 
 const deploy = job('deploy', {
@@ -899,14 +835,19 @@ const deploy = job('deploy', {
 });
 ```
 
-### dynamicJob(groupName, fn)
+### dynamicJob(groupName, fnOrConfig)
 
-Tag a dynamic job generator function with a group name so other jobs can reference it via `dynamicGroup()`.
+Tag a dynamic job generator with a group name so other jobs can reference it via `dynamicGroup()`.
 
 ```typescript
-function dynamicJob(groupName: string, fn: DynamicJobFn): DynamicJobFn;
+function dynamicJob(
+  groupName: string,
+  fnOrConfig: DynamicJobFn | { needs: DynamicJobNeed[]; generate: DynamicJobFn },
+): TaggedDynamicJobFn;
 ```
 
+The second argument is either a plain generator (event-only, evaluated at webhook time) or a result-aware `{ needs, generate }` config, which defers the generator until its declared upstreams complete and exposes their frozen outputs as `ctx.needs`. See [Rules, matrix, dynamic jobs](https://docs.kici.dev/user/sdk/rules-matrix-dynamic/#dynamicjob--result-aware-generation) for the result-aware form.
+
 The generator runs twice: once in the init phase (to register expected job names) and once inside the executing agent (to produce the actual jobs). Mismatches between the two evaluations are detected as determinism drift -- see [dynamic-jobs](https://docs.kici.dev/architecture/execution/dynamic-jobs/).
 
 ### Auto-generated IDs
@@ -920,2012 +861,537 @@ These IDs are stable as long as the order of unnamed entries does not change. Ad
 
 ---
 
-## Event payload reference
+## SDK reference: parallel
 
-Source: https://docs.kici.dev/user/sdk/event-payloads/
+Source: https://docs.kici.dev/user/sdk/parallel/
 
-<!-- Generated by scripts/docs-gen-event-payloads.ts — do not edit by hand. Regenerate: pnpm docs:gen:events -->
+`parallel([...steps], opts?)` runs a group of independent steps **concurrently**
+within one job, behind a join barrier: execution continues past the group only
+once every child has settled. Each child is its own observable step — it gets its
+own logs, status, timing, and retry — instead of being hidden inside one step's
+`Promise.all`.
 
-## The envelope
+```ts
+import { workflow, job, step, parallel, push } from '@kici-dev/sdk';
 
-The normalized event envelope is the single event contract in KiCI. Rules receive it as `ctx.event`, and every dynamic function — `environment:`, `env:`, and `concurrencyGroup:` resolvers, generated jobs, and a workflow's `concurrency.group` — receives the same envelope as its argument.
+export default workflow('ci', {
+  on: push(),
+  jobs: [
+    job('checks', {
+      runsOn: 'kici:os:linux',
+      steps: [
+        checkout,
+        // lint, typecheck, and the unit tests have no ordering between them,
+        // so they run together — the job's wall-clock is the slowest child,
+        // not the sum of all three.
+        parallel([lint, typecheck, unitTests], { failFast: true }),
+        deploy,
+      ],
+    }),
+  ],
+});
+```
 
-Narrow on the `type` field to branch per trigger kind (`if (event.type === 'push')`). The raw provider webhook body is nested at `payload`; the typed variants below describe its shape per event type.
+`parallel(...)` returns a `ParallelGroup` that sits in the ordinary flat
+`steps: [...]` array — there is no new `job` field. A group's children are
+**sequential steps only**; groups cannot be nested.
 
-These fields are present on every envelope (the `EventBase` shape):
+## Options
 
-| Field             | Type                      | Description                                                                     |
-| ----------------- | ------------------------- | ------------------------------------------------------------------------------- |
-| `type`            | `string`                  | Normalized event type discriminant.                                             |
-| `action?`         | `string`                  | Sub-action (e.g. 'opened', 'created', 'submitted').                             |
-| `targetBranch?`   | `string`                  | Target branch (push target, PR base, or default branch).                        |
-| `sourceBranch?`   | `string`                  | Source branch (PR head branch). Only set for PR-like events.                    |
-| `provider?`       | `string`                  | Provider that originated this event.                                            |
-| `isForkPR?`       | `boolean`                 | Whether this PR comes from a fork. Only set for PR-like events.                 |
-| `baseBranch?`     | `string`                  | Base branch ref for PR events.                                                  |
-| `senderUsername?` | `string`                  | Sender username from the webhook payload.                                       |
-| `sourceRepo?`     | `string`                  | Repository identifier (e.g. "owner/repo").                                      |
-| `changedFiles?`   | `string[]`                | Files changed in this event (for path filtering).                               |
-| `payload?`        | `Record<string, unknown>` | Raw webhook payload from the provider. May be absent in flattened event forms.  |
-| `[key: string]`   | `unknown`                 | Index signature for backward compatibility — untyped fields resolve to unknown. |
+`parallel(steps, opts?)` accepts:
 
-## Event types
+- **`failFast?: boolean`** — default `true`. When a child fails, the in-flight
+  siblings are cancelled immediately and the job fails. With `failFast: false`
+  every child runs to completion first, then the job fails if any child failed.
+- **`maxParallel?: number`** — default unlimited. Caps how many children run at
+  once; children waiting for a slot report a `pending` status until they launch.
+- **`name?: string`** — a label for the group's dashboard band.
 
-One section per member of the `EventPayload` union. The heading is the `type` literal; the table lists the fields of that event's `payload` property when it declares a typed shape.
+A child marked `continueOnError: true` never trips fail-fast and never fails the
+job — it still shows a `failed` status badge, but the group treats it as
+non-fatal.
 
-### `pull_request`
+## Statuses
 
-Carried by `PullRequestEventPayload`. The `payload` property has the following shape:
+Parallel steps introduce two step statuses:
 
-| Field           | Type                | Description |
-| --------------- | ------------------- | ----------- |
-| `action`        | `string`            |             |
-| `number`        | `number`            |             |
-| `pull_request`  | `GitHubPullRequest` |             |
-| `repository`    | `GitHubRepository`  |             |
-| `sender`        | `GitHubUser`        |             |
-| `[key: string]` | `unknown`           |             |
+- **`pending`** — a child queued behind `maxParallel`, not yet launched.
+- **`cancelled`** — a sibling aborted by fail-fast. A cancelled step is **not** a
+  failure: only the child that actually failed fails the job; the cancelled
+  siblings render in gray (distinct from the red failing step) on the dashboard.
 
-### `push`
+Children may also complete **out of order** — the fastest child finishes first
+regardless of array position. A later sequential step can read a parallel child's
+`.result` after the barrier; children within a group cannot read each other's
+results (there is no ordering inside the group).
 
-Carried by `PushEventPayload`. The `payload` property has the following shape:
+## Scope: nests inside job-level fan-out
 
-| Field           | Type               | Description |
-| --------------- | ------------------ | ----------- |
-| `ref`           | `string`           |             |
-| `after`         | `string`           |             |
-| `before`        | `string`           |             |
-| `head_commit?`  | `GitHubCommit`     |             |
-| `commits?`      | `GitHubCommit[]`   |             |
-| `repository`    | `GitHubRepository` |             |
-| `sender?`       | `GitHubUser`       |             |
-| `forced?`       | `boolean`          |             |
-| `[key: string]` | `unknown`          |             |
+`parallel()`'s `failFast` / `maxParallel` are **step-group** scopes — they govern
+only the steps inside the group. They are a different layer from the **job-level**
+`failFast` / `maxParallel` on a matrix / `runsOnAll` fan-out, which govern how a
+job's child _jobs_ spread across the matrix or host roster. A `parallel()` group
+inside a fan-out job nests its concurrency inside each fan-out child.
 
-### `tag`
+## Local vs remote execution
 
-Carried by `TagEventPayload`. The `payload` property has the following shape:
+Run remotely (the orchestrator + agent), parallel children execute concurrently
+and each surfaces as its own dashboard step. `kici run <event> --local` executes the same
+children in array order in its single-process model — the results are identical,
+only the wall-clock and the live fail-fast cancellation differ. Use a remote run
+to observe the concurrent timeline.
 
-| Field           | Type               | Description |
-| --------------- | ------------------ | ----------- |
-| `ref`           | `string`           |             |
-| `after`         | `string`           |             |
-| `repository`    | `GitHubRepository` |             |
-| `sender?`       | `GitHubUser`       |             |
-| `[key: string]` | `unknown`          |             |
+---
 
-### `comment`
-
-Carried by `CommentEventPayload`. The `payload` property has the following shape:
+## SDK reference: rules, matrix, dynamic jobs
 
-| Field           | Type                                                                                 | Description |
-| --------------- | ------------------------------------------------------------------------------------ | ----------- |
-| `action`        | `string`                                                                             |             |
-| `comment`       | `GitHubComment`                                                                      |             |
-| `issue?`        | `{ number: number; title?: string; pull_request?: unknown; [key: string]: unknown }` |             |
-| `repository`    | `GitHubRepository`                                                                   |             |
-| `sender`        | `GitHubUser`                                                                         |             |
-| `[key: string]` | `unknown`                                                                            |             |
-
-### `review`
+Source: https://docs.kici.dev/user/sdk/rules-matrix-dynamic/
 
-Carried by `ReviewEventPayload`. The `payload` property has the following shape:
+## Rules
 
-| Field           | Type                | Description |
-| --------------- | ------------------- | ----------- |
-| `action`        | `string`            |             |
-| `review`        | `GitHubReview`      |             |
-| `pull_request`  | `GitHubPullRequest` |             |
-| `repository`    | `GitHubRepository`  |             |
-| `sender`        | `GitHubUser`        |             |
-| `[key: string]` | `unknown`           |             |
+Rules control conditional execution of workflows and jobs. A rule that returns `false` (or whose check function returns `false`) prevents execution.
 
-### `review_comment`
+A rule's check function that **returns `false`** cleanly skips the job or step. A check function that **throws** is treated as an evaluation failure, not a skip: the job or step **fails** with the error surfaced (both on a remote run and when running locally with `kici run --local`), so a broken rule can never silently pass as a green run. For example, `rule('main only', (ctx) => ctx.event.ref.endsWith('main'))` throws on an event whose `ref` is undefined — that run fails with the error instead of quietly skipping every step. Fix the thrown error (guard the access) rather than relying on the skip.
 
-Carried by `ReviewCommentEventPayload`. The `payload` property has the following shape:
+### rule(label) / rule(label, check)
 
-| Field           | Type                | Description |
-| --------------- | ------------------- | ----------- |
-| `action`        | `string`            |             |
-| `comment`       | `GitHubComment`     |             |
-| `pull_request`  | `GitHubPullRequest` |             |
-| `repository`    | `GitHubRepository`  |             |
-| `sender`        | `GitHubUser`        |             |
-| `[key: string]` | `unknown`           |             |
-
-### `release`
-
-Carried by `ReleaseEventPayload`. The `payload` property has the following shape:
-
-| Field           | Type               | Description |
-| --------------- | ------------------ | ----------- |
-| `action`        | `string`           |             |
-| `release`       | `GitHubRelease`    |             |
-| `repository`    | `GitHubRepository` |             |
-| `sender`        | `GitHubUser`       |             |
-| `[key: string]` | `unknown`          |             |
-
-### `dispatch`
+Create a rule.
 
-Carried by `DispatchEventPayload`. The `payload` property has the following shape:
+```typescript
+function rule(label: string): Rule;
+function rule(label: string, check: RuleCheckFn): Rule;
+```
 
-| Field             | Type                      | Description |
-| ----------------- | ------------------------- | ----------- |
-| `action`          | `string`                  |             |
-| `client_payload?` | `Record<string, unknown>` |             |
-| `repository`      | `GitHubRepository`        |             |
-| `sender?`         | `GitHubUser`              |             |
-| `[key: string]`   | `unknown`                 |             |
+**Without check function:** Always passes. Useful as a marker in the decision trace.
 
-### `create`
+```typescript
+rule('ci: required check');
+```
 
-Carried by `CreateEventPayload`. The `payload` property has the following shape:
+**With check function:** Passes when the function returns `true`.
 
-| Field           | Type               | Description |
-| --------------- | ------------------ | ----------- |
-| `ref`           | `string`           |             |
-| `ref_type`      | `string`           |             |
-| `repository`    | `GitHubRepository` |             |
-| `sender`        | `GitHubUser`       |             |
-| `[key: string]` | `unknown`          |             |
+```typescript
+rule('has source changes', async (ctx) => {
+  return ctx.changedFiles.some((f) => f.startsWith('src/'));
+});
+```
 
-### `delete`
+### skip(label, check)
 
-Carried by `DeleteEventPayload`. The `payload` property has the following shape:
+Create a rule that skips when the condition is met. Inverts the check function.
 
-| Field           | Type               | Description |
-| --------------- | ------------------ | ----------- |
-| `ref`           | `string`           |             |
-| `ref_type`      | `string`           |             |
-| `repository`    | `GitHubRepository` |             |
-| `sender`        | `GitHubUser`       |             |
-| `[key: string]` | `unknown`          |             |
+```typescript
+function skip(label: string, check: RuleCheckFn): Rule;
+```
 
-### `status`
+When the check returns `true` (condition met), the rule returns `false` (skip execution).
+When the check returns `false` (condition not met), the rule returns `true` (allow execution).
 
-Carried by `StatusEventPayload`. The `payload` property has the following shape:
+```typescript
+// Skip when only docs changed
+skip('docs only PR', async (ctx) => {
+  return ctx.changedFiles.every((f) => f.endsWith('.md'));
+});
+```
 
-| Field           | Type                                              | Description |
-| --------------- | ------------------------------------------------- | ----------- |
-| `state`         | `string`                                          |             |
-| `sha`           | `string`                                          |             |
-| `context`       | `string`                                          |             |
-| `description?`  | `string`                                          |             |
-| `target_url?`   | `string`                                          |             |
-| `branches?`     | `Array<{ name: string; [key: string]: unknown }>` |             |
-| `repository`    | `GitHubRepository`                                |             |
-| `sender`        | `GitHubUser`                                      |             |
-| `[key: string]` | `unknown`                                         |             |
+### RuleCheckFn
 
-### `workflow_run`
+```typescript
+type RuleCheckFn = (ctx: RuleContext) => Promise<boolean> | boolean;
+```
 
-Carried by `WorkflowRunEventPayload`. The `payload` property has the following shape:
+Can be sync or async. Receives a `RuleContext`:
 
-| Field           | Type                                                                                                   | Description |
-| --------------- | ------------------------------------------------------------------------------------------------------ | ----------- |
-| `action`        | `string`                                                                                               |             |
-| `workflow_run`  | `{ head_branch: string; name: string; conclusion?: string; status?: string; [key: string]: unknown; }` |             |
-| `repository`    | `GitHubRepository`                                                                                     |             |
-| `sender`        | `GitHubUser`                                                                                           |             |
-| `[key: string]` | `unknown`                                                                                              |             |
+| Property             | Type                                      | Description                                                           |
+| -------------------- | ----------------------------------------- | --------------------------------------------------------------------- |
+| `event`              | `EventPayload`                            | The triggering event payload (discriminated union — narrow on `type`) |
+| `changedFiles`       | `string[]`                                | Files changed in this event (see availability note below)             |
+| `changedFilesStatus` | `'fetched' \| 'unavailable' \| 'skipped'` | Whether `changedFiles` is available                                   |
+| `env`                | `Record<string, string\|undefined>`       | Environment variables                                                 |
+| `$`                  | zx shell                                  | Shell executor for running commands                                   |
 
-### `fork`
+`changedFiles` is available on `push` and `pull_request` events — the agent computes the diff from its checkout, so no `paths:` trigger is required. It is `unavailable` for events with no diff (`schedule`, `tag`, `manual_schedule`), and in the rare case where the diff cannot be computed (e.g. a history deeper than the agent's bounded fetch). Reading `changedFiles` when it is unavailable throws and fails the job, so guard with `changedFilesStatus` first when a rule can run on such events:
 
-Carried by `ForkEventPayload`. The `payload` property has the following shape:
+```typescript
+rule('has source changes', (ctx) => {
+  if (ctx.changedFilesStatus !== 'fetched') return true; // no diff — don't gate on files
+  return ctx.changedFiles.some((f) => f.startsWith('src/'));
+});
+```
 
-| Field           | Type                                            | Description |
-| --------------- | ----------------------------------------------- | ----------- |
-| `forkee`        | `{ full_name: string; [key: string]: unknown }` |             |
-| `repository`    | `GitHubRepository`                              |             |
-| `sender`        | `GitHubUser`                                    |             |
-| `[key: string]` | `unknown`                                       |             |
+### evaluateRules(rules, context, label, onRuleResult?)
 
-### `star`
+Evaluate an array of rules sequentially with fail-fast behavior. Stops on the first failure.
 
-Carried by `StarEventPayload`. The `payload` property has the following shape:
+```typescript
+function evaluateRules(
+  rules: Rule[],
+  context: RuleContext,
+  label: string,
+  onRuleResult?: (result: RuleResult) => void,
+): Promise<RuleEvaluationResult>;
+```
 
-| Field           | Type               | Description |
-| --------------- | ------------------ | ----------- |
-| `action`        | `string`           |             |
-| `repository`    | `GitHubRepository` |             |
-| `sender`        | `GitHubUser`       |             |
-| `[key: string]` | `unknown`          |             |
+Returns a `RuleEvaluationResult`:
 
-### `watch`
+```typescript
+interface RuleEvaluationResult {
+  allPassed: boolean;
+  results: RuleResult[];
+}
+```
 
-Carried by `WatchEventPayload`. The `payload` property has the following shape:
+### isEventType(event, type)
 
-| Field           | Type               | Description |
-| --------------- | ------------------ | ----------- |
-| `action`        | `string`           |             |
-| `repository`    | `GitHubRepository` |             |
-| `sender`        | `GitHubUser`       |             |
-| `[key: string]` | `unknown`          |             |
+Type guard that narrows an `EventPayload` to a specific event type variant. Use this in rule check functions to get autocomplete on provider-specific fields.
 
-### `webhook`
+```typescript
+function isEventType<T extends EventPayload['type']>(
+  event: EventPayload,
+  type: T,
+): event is Extract<EventPayload, { type: T }>;
+```
 
-Carried by `WebhookEventPayload`. Adds no typed fields beyond the shared envelope; `payload` is the raw provider body (`Record<string, unknown>`).
+**Example — skip draft PRs:**
 
-### `kici_event`
+```typescript
+rule('skip-draft-prs', (ctx) => {
+  if (!isEventType(ctx.event, 'pull_request')) return true;
+  // ctx.event is now PullRequestEventPayload — full autocomplete
+  return !ctx.event.payload.pull_request.draft;
+});
+```
 
-Carried by `KiciEventPayload`. Adds no typed fields beyond the shared envelope; `payload` is the raw provider body (`Record<string, unknown>`).
+**Example — branch-based rule with push narrowing:**
 
-### `workflow_complete`
+```typescript
+rule('only-main-pushes', (ctx) => {
+  if (!isEventType(ctx.event, 'push')) return false;
+  // ctx.event.payload.ref is typed as string
+  return ctx.event.payload.ref === 'refs/heads/main';
+});
+```
 
-Carried by `WorkflowCompleteEventPayload`. Adds no typed fields beyond the shared envelope; `payload` is the raw provider body (`Record<string, unknown>`).
+You can also narrow directly with `if (ctx.event.type === 'pull_request')` — TypeScript's discriminated union narrowing works on the `type` field.
 
-### `job_complete`
+### EventPayload
 
-Carried by `JobCompleteEventPayload`. Adds no typed fields beyond the shared envelope; `payload` is the raw provider body (`Record<string, unknown>`).
+`EventPayload` is a discriminated union over the `type` field. Each variant provides typed access to the normalized event fields and the raw webhook payload.
 
-### `generic_webhook`
+Every variant carries the shared `EventBase` fields — `type`, `action`, `targetBranch`, `sourceBranch`, `provider`, `isForkPR`, `baseBranch`, `senderUsername`, `sourceRepo`, `changedFiles`, and the raw `payload` — plus a per-type `payload` shape for the typed variants. The complete field-by-field schema, including every typed `payload` shape and the shared GitHub object types, is in the [event payload reference](https://docs.kici.dev/user/sdk/event-payloads/).
 
-Carried by `GenericWebhookEventPayload`. Adds no typed fields beyond the shared envelope; `payload` is the raw provider body (`Record<string, unknown>`).
+**Typed variants** (with GitHub-specific payload fields): `pull_request`, `push`, `tag`, `comment`, `review`, `review_comment`, `release`, `dispatch`, `create`, `delete`, `status`, `workflow_run`, `fork`, `star`, `watch`.
 
-### `schedule`
+**Generic variants** (payload is `Record<string, unknown>`): `webhook`, `kici_event`, `workflow_complete`, `job_complete`, `generic_webhook`, `schedule`, `lifecycle`.
 
-Carried by `ScheduleEventPayload`. Adds no typed fields beyond the shared envelope; `payload` is the raw provider body (`Record<string, unknown>`).
+## Matrix
 
-### `lifecycle`
+Matrix configurations expand a single job into multiple instances, one per parameter combination. Maximum 256 combinations.
 
-Carried by `LifecycleEventPayload`. Adds no typed fields beyond the shared envelope; `payload` is the raw provider body (`Record<string, unknown>`).
+Combinations must be **unique**. Two combinations that would produce the same instance name — most simply, the same value listed twice — fail the job instead of quietly running it twice.
 
-### `rerun`
+Expansion happens at **dispatch time**: the orchestrator materializes the matrix into N execution jobs — one per combination, each dispatched to its own agent — before any job runs. Each instance receives its combination as `ctx.matrix`. This is identical whether the workflow runs via `kici run <event> --local` or remotely through a webhook trigger, and the dashboard groups the N instances under one parent node.
 
-Carried by `RerunEventPayload`. Adds no typed fields beyond the shared envelope; `payload` is the raw provider body (`Record<string, unknown>`).
+### Static array (single dimension)
 
-### `manual_schedule`
+```typescript
+matrix: ['18', '20', '22'];
+```
 
-Carried by `ManualScheduleEventPayload`. Adds no typed fields beyond the shared envelope; `payload` is the raw provider body (`Record<string, unknown>`).
-
-### `unknown`
-
-Carried by `UnknownEventPayload`. Adds no typed fields beyond the shared envelope; `payload` is the raw provider body (`Record<string, unknown>`).
-
-## Shared GitHub object shapes
-
-The typed `payload` shapes above reference these partial GitHub object types. Each lists only the commonly accessed fields; the index signature on every shape resolves any other field to `unknown`.
-
-### `GitHubRepository`
-
-| Field            | Type                                        | Description |
-| ---------------- | ------------------------------------------- | ----------- |
-| `full_name`      | `string`                                    |             |
-| `default_branch` | `string`                                    |             |
-| `name?`          | `string`                                    |             |
-| `owner?`         | `{ login: string; [key: string]: unknown }` |             |
-| `private?`       | `boolean`                                   |             |
-| `[key: string]`  | `unknown`                                   |             |
-
-### `GitHubUser`
-
-| Field           | Type      | Description |
-| --------------- | --------- | ----------- |
-| `login`         | `string`  |             |
-| `id?`           | `number`  |             |
-| `[key: string]` | `unknown` |             |
-
-### `GitHubPullRequest`
-
-| Field           | Type                                                                                                          | Description |
-| --------------- | ------------------------------------------------------------------------------------------------------------- | ----------- |
-| `number`        | `number`                                                                                                      |             |
-| `draft?`        | `boolean`                                                                                                     |             |
-| `title?`        | `string`                                                                                                      |             |
-| `body?`         | `string`                                                                                                      |             |
-| `state?`        | `string`                                                                                                      |             |
-| `merged?`       | `boolean`                                                                                                     |             |
-| `head`          | `{ ref: string; sha: string; repo?: { full_name: string; [key: string]: unknown }; [key: string]: unknown; }` |             |
-| `base`          | `{ ref: string; repo?: { full_name: string; [key: string]: unknown }; [key: string]: unknown; }`              |             |
-| `user?`         | `GitHubUser`                                                                                                  |             |
-| `labels?`       | `Array<{ name: string; [key: string]: unknown }>`                                                             |             |
-| `[key: string]` | `unknown`                                                                                                     |             |
-
-### `GitHubCommit`
-
-| Field           | Type                                                                           | Description |
-| --------------- | ------------------------------------------------------------------------------ | ----------- |
-| `id`            | `string`                                                                       |             |
-| `message`       | `string`                                                                       |             |
-| `author?`       | `{ name?: string; email?: string; username?: string; [key: string]: unknown }` |             |
-| `timestamp?`    | `string`                                                                       |             |
-| `added?`        | `string[]`                                                                     |             |
-| `removed?`      | `string[]`                                                                     |             |
-| `modified?`     | `string[]`                                                                     |             |
-| `[key: string]` | `unknown`                                                                      |             |
-
-### `GitHubComment`
-
-| Field           | Type         | Description |
-| --------------- | ------------ | ----------- |
-| `id`            | `number`     |             |
-| `body`          | `string`     |             |
-| `user`          | `GitHubUser` |             |
-| `[key: string]` | `unknown`    |             |
-
-### `GitHubReview`
-
-| Field           | Type         | Description |
-| --------------- | ------------ | ----------- |
-| `id`            | `number`     |             |
-| `state`         | `string`     |             |
-| `body?`         | `string`     |             |
-| `user`          | `GitHubUser` |             |
-| `[key: string]` | `unknown`    |             |
-
-### `GitHubRelease`
-
-| Field               | Type      | Description |
-| ------------------- | --------- | ----------- |
-| `id`                | `number`  |             |
-| `tag_name`          | `string`  |             |
-| `name?`             | `string`  |             |
-| `body?`             | `string`  |             |
-| `draft?`            | `boolean` |             |
-| `prerelease?`       | `boolean` |             |
-| `target_commitish?` | `string`  |             |
-| `[key: string]`     | `unknown` |             |
-
----
-
-## SDK reference: idempotent
-
-Source: https://docs.kici.dev/user/sdk/idempotent/
-
-The SDK exposes three idempotency helpers — a generic function `idempotent()`, the step factory `idempotentStep()`, and its check-mode-aware sibling `checkStep()` — for the common case where a workflow step should:
-
-1. **Check** whether the desired state is already in place.
-2. **Apply** the change only when drift is detected.
-3. **Surface** the resource (or its identifier) on both branches, so downstream steps don't need to know whether work happened or was skipped.
-
-`idempotent()` and `idempotentStep()` wrap the same underlying runner and always apply on drift. Pick `idempotentStep()` when the operation is the whole job of a step; use `idempotent()` from anywhere — inside a multi-action step, a hook, or a bare async function. Pick `checkStep()` when the step should respect the run-level check mode — `kici run --check` previews the drift without applying it.
-
-## `idempotent(options)`
-
-Run a single check / apply cycle and return a discriminated result describing the outcome.
-
-### Parameters
-
-| Name         | Type                                   | Required | Description                                                                                      |
-| ------------ | -------------------------------------- | -------- | ------------------------------------------------------------------------------------------------ |
-| `name`       | `string`                               | No       | Label that appears in log lines. Defaults to `'idempotent'`.                                     |
-| `check`      | `() => Promise<TDrift \| null>`        | Yes      | Read-only inspection. Return `null` when the system is already in the desired state.             |
-| `apply`      | `(drift: TDrift) => Promise<TApplied>` | Yes      | Brings the system to the desired state when `check()` returned a non-null drift value.           |
-| `whenInSync` | `() => Promise<TInSync>`               | No       | Runs when `check()` returned `null`. Use it to fetch the already-satisfied resource.             |
-| `summarize`  | `(drift: TDrift) => string`            | No       | Human-readable, multi-line summary of what `apply()` would do. Defaults to a JSON dump of drift. |
-| `log`        | `(line: string) => void`               | No       | Sink for status lines. Defaults to `console.log`.                                                |
-
-### Result
-
-`idempotent()` resolves to a discriminated `IdempotentResult` union:
-
-| Outcome     | `drift`  | `result`                                         |
-| ----------- | -------- | ------------------------------------------------ |
-| `'skipped'` | `null`   | The `whenInSync()` return value, or `undefined`. |
-| `'applied'` | `TDrift` | The `apply()` return value.                      |
-
-Narrow on `result.outcome` before reading `result.result` to get the correct typed shape.
-
-### Example
-
-```typescript
-import { idempotent } from '@kici-dev/sdk';
-
-const result = await idempotent({
-  name: 'create-dns-record',
-  check: async () => {
-    const existing = await dns.getRecord('api.example.com');
-    return existing ? null : { fqdn: 'api.example.com', target: '203.0.113.10' };
-  },
-  whenInSync: async () => {
-    const existing = await dns.getRecord('api.example.com');
-    return { id: existing.id };
-  },
-  apply: async (drift) => {
-    const created = await dns.createRecord(drift.fqdn, drift.target);
-    return { id: created.id };
-  },
-  summarize: (drift) => `Create A record ${drift.fqdn} → ${drift.target}`,
-});
-
-// Both branches surface the record id.
-const recordId = result.result.id;
-```
-
-## `idempotentStep(name, options)`
-
-A factory returning an SDK `Step` whose `run` body executes `idempotent(...)` and routes status lines through the step's structured logger.
-
-### Parameters
-
-| Name      | Type                                       | Required | Description                                                                                            |
-| --------- | ------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------ |
-| `name`    | `string`                                   | Yes      | Step name. Appears in the run timeline and in log lines.                                               |
-| `options` | `Omit<IdempotentOptions, 'name' \| 'log'>` | Yes      | Same shape as `idempotent()` minus `name` (already provided) and `log` (provided by the step context). |
-
-### Result
-
-`idempotentStep(...)` returns `Step<IdempotentResult<TDrift, TInSync, TApplied>>`. Other steps can consume the result through the standard step output mechanisms.
-
-### Example
-
-```typescript
-import { idempotentStep, job } from '@kici-dev/sdk';
-
-const ensureBucket = idempotentStep('ensure-bucket', {
-  check: async () => {
-    const exists = await s3.bucketExists('app-cache');
-    return exists ? null : { bucket: 'app-cache', region: 'eu-central-1' };
-  },
-  whenInSync: async () => ({ arn: 'arn:aws:s3:::app-cache' }),
-  apply: async (drift) => {
-    const created = await s3.createBucket(drift.bucket, drift.region);
-    return { arn: created.arn };
-  },
-  summarize: (drift) => `Create S3 bucket ${drift.bucket} in ${drift.region}`,
-});
-
-export const setup = job('setup', {
-  runsOn: 'linux',
-  steps: [ensureBucket],
-});
-```
-
-## `checkStep(name, options)`
-
-The check-mode-aware sibling of `idempotentStep()`. It takes the **same option shape**, but behaves differently when a run is started in check mode (`kici run --check`):
-
-| Factory          | Behavior under `kici run --check`         |
-| ---------------- | ----------------------------------------- |
-| `idempotentStep` | always applies on drift                   |
-| `checkStep`      | reports drift, applies only in apply mode |
-
-Use `checkStep()` for deploy-style steps where you want a dry-run preview of pending changes before committing them, and `idempotentStep()` for steps that must always converge (for example inside a hook). A `checkStep()` desugars to the first-class step check facet (`check` / `summarize` / `run(ctx, drift)` / `whenInSync`), so it participates in run-level check mode automatically: `kici run --check` reports the drift and skips `apply`, `kici run --check --fail-on-drift` exits non-zero when drift is detected, and apply mode applies the change.
-
-### Parameters
-
-| Name              | Type                                        | Required | Description                                                                                         |
-| ----------------- | ------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------- |
-| `name`            | `string`                                    | Yes      | Step name. Appears in the run timeline and in log lines.                                            |
-| `check`           | `(ctx) => Promise<TDrift \| null>`          | Yes      | Read-only inspection. Return `null` when the system is already in the desired state.                |
-| `apply`           | `(ctx, drift: TDrift) => Promise<TApplied>` | Yes      | Brings the system to the desired state. Runs only in apply mode (skipped under `kici run --check`). |
-| `summarize`       | `(drift: TDrift) => string`                 | Yes      | Human-readable summary of what `apply()` would do; shown in check-mode drift output.                |
-| `whenInSync`      | `(ctx) => Promise<TInSync>`                 | No       | Runs when `check()` returned `null` (already in sync).                                              |
-| `continueOnError` | `boolean`                                   | No       | When true, the job proceeds even if this step fails.                                                |
-| `timeout`         | `number`                                    | No       | Step-level timeout in milliseconds.                                                                 |
-
-The one signature difference from `idempotentStep`: `apply` and `whenInSync` receive `ctx` as their first argument, so the apply logic has access to `ctx.$`, `ctx.log`, and `ctx.secrets`.
-
-### Result
-
-`checkStep(...)` returns `Step<TApplied | TInSync>` — the output is whichever of `apply` / `whenInSync` ran.
-
-### Example
-
-```typescript
-import { checkStep, job } from '@kici-dev/sdk';
-
-const ensureDnsRecord = checkStep('ensure-dns-record', {
-  check: async (ctx) => {
-    const existing = await ctx.$`dig +short api.example.com`;
-    return existing.stdout.trim() ? null : { fqdn: 'api.example.com', target: '203.0.113.10' };
-  },
-  summarize: (drift) => `Create A record ${drift.fqdn} → ${drift.target}`,
-  apply: async (ctx, drift) => {
-    await ctx.$`dns-cli create ${drift.fqdn} ${drift.target}`;
-    return { created: true };
-  },
-  whenInSync: async () => ({ created: false }),
-});
-
-export const deploy = job('deploy', {
-  runsOn: 'linux',
-  steps: [ensureDnsRecord],
-});
-```
-
-Run `kici run --check` against this workflow to see the drift summary without touching DNS; run it without `--check` to apply.
-
-## Worked example: create-if-missing returning a resource id
-
-The typical use case is **resource provisioning that should be safe to re-run**. The helper guarantees the same downstream typed shape whether the resource already existed or was just created:
-
-```typescript
-import { idempotent } from '@kici-dev/sdk';
-
-interface BucketDrift {
-  bucket: string;
-  region: string;
-}
-
-interface BucketHandle {
-  arn: string;
-}
-
-async function ensureBucket(bucket: string, region: string): Promise<BucketHandle> {
-  const result = await idempotent<BucketDrift, BucketHandle, BucketHandle>({
-    name: `ensure-${bucket}`,
-    check: async () => {
-      const existing = await s3.describeBucket(bucket);
-      return existing ? null : { bucket, region };
-    },
-    whenInSync: async () => {
-      const existing = await s3.describeBucket(bucket);
-      return { arn: existing.arn };
-    },
-    apply: async (drift) => {
-      const created = await s3.createBucket(drift.bucket, drift.region);
-      return { arn: created.arn };
-    },
-    summarize: (drift) => `Create S3 bucket ${drift.bucket} in ${drift.region}`,
-  });
-
-  return result.result;
-}
-```
-
-The caller never has to branch on outcome — `result.result` is always a `BucketHandle`. A second invocation against the same bucket logs a single "in sync, skipping" line and returns the same ARN.
-
-## See also
-
-- [Core SDK reference](https://docs.kici.dev/user/sdk/core/) — the `step()`, `job()`, and `workflow()` factories that `idempotentStep()` builds on.
-- [Runtime types](https://docs.kici.dev/user/sdk/runtime/) — `StepContext`, `Logger`, and other surface used inside the helpers.
-
----
-
-## SDK reference: parallel
-
-Source: https://docs.kici.dev/user/sdk/parallel/
-
-`parallel([...steps], opts?)` runs a group of independent steps **concurrently**
-within one job, behind a join barrier: execution continues past the group only
-once every child has settled. Each child is its own observable step — it gets its
-own logs, status, timing, and retry — instead of being hidden inside one step's
-`Promise.all`.
-
-```ts
-import { workflow, job, step, parallel, push } from '@kici-dev/sdk';
-
-export default workflow('ci', {
-  on: push(),
-  jobs: [
-    job('checks', {
-      runsOn: 'kici:os:linux',
-      steps: [
-        checkout,
-        // lint, typecheck, and the unit tests have no ordering between them,
-        // so they run together — the job's wall-clock is the slowest child,
-        // not the sum of all three.
-        parallel([lint, typecheck, unitTests], { failFast: true }),
-        deploy,
-      ],
-    }),
-  ],
-});
-```
-
-`parallel(...)` returns a `ParallelGroup` that sits in the ordinary flat
-`steps: [...]` array — there is no new `job` field. A group's children are
-**sequential steps only**; groups cannot be nested.
-
-## Options
-
-`parallel(steps, opts?)` accepts:
-
-- **`failFast?: boolean`** — default `true`. When a child fails, the in-flight
-  siblings are cancelled immediately and the job fails. With `failFast: false`
-  every child runs to completion first, then the job fails if any child failed.
-- **`maxParallel?: number`** — default unlimited. Caps how many children run at
-  once; children waiting for a slot report a `pending` status until they launch.
-- **`name?: string`** — a label for the group's dashboard band.
-
-A child marked `continueOnError: true` never trips fail-fast and never fails the
-job — it still shows a `failed` status badge, but the group treats it as
-non-fatal.
-
-## Statuses
-
-Parallel steps introduce two step statuses:
-
-- **`pending`** — a child queued behind `maxParallel`, not yet launched.
-- **`cancelled`** — a sibling aborted by fail-fast. A cancelled step is **not** a
-  failure: only the child that actually failed fails the job; the cancelled
-  siblings render in gray (distinct from the red failing step) on the dashboard.
-
-Children may also complete **out of order** — the fastest child finishes first
-regardless of array position. A later sequential step can read a parallel child's
-`.result` after the barrier; children within a group cannot read each other's
-results (there is no ordering inside the group).
-
-## Scope: nests inside job-level fan-out
-
-`parallel()`'s `failFast` / `maxParallel` are **step-group** scopes — they govern
-only the steps inside the group. They are a different layer from the **job-level**
-`failFast` / `maxParallel` on a matrix / `runsOnAll` fan-out, which govern how a
-job's child _jobs_ spread across the matrix or host roster. A `parallel()` group
-inside a fan-out job nests its concurrency inside each fan-out child.
-
-## Local vs remote execution
-
-Run remotely (the orchestrator + agent), parallel children execute concurrently
-and each surfaces as its own dashboard step. `kici run <event> --local` executes the same
-children in array order in its single-process model — the results are identical,
-only the wall-clock and the live fail-fast cancellation differ. Use a remote run
-to observe the concurrent timeline.
-
----
-
-## SDK reference: rules, matrix, dynamic jobs
-
-Source: https://docs.kici.dev/user/sdk/rules-matrix-dynamic/
-
-## Rules
-
-Rules control conditional execution of workflows and jobs. A rule that returns `false` (or whose check function returns `false`) prevents execution.
-
-### rule(label) / rule(label, check)
-
-Create a rule.
-
-```typescript
-function rule(label: string): Rule;
-function rule(label: string, check: RuleCheckFn): Rule;
-```
-
-**Without check function:** Always passes. Useful as a marker in the decision trace.
-
-```typescript
-rule('ci: required check');
-```
-
-**With check function:** Passes when the function returns `true`.
-
-```typescript
-rule('has source changes', async (ctx) => {
-  return ctx.changedFiles.some((f) => f.startsWith('src/'));
-});
-```
-
-### skip(label, check)
-
-Create a rule that skips when the condition is met. Inverts the check function.
-
-```typescript
-function skip(label: string, check: RuleCheckFn): Rule;
-```
-
-When the check returns `true` (condition met), the rule returns `false` (skip execution).
-When the check returns `false` (condition not met), the rule returns `true` (allow execution).
-
-```typescript
-// Skip when only docs changed
-skip('docs only PR', async (ctx) => {
-  return ctx.changedFiles.every((f) => f.endsWith('.md'));
-});
-```
-
-### RuleCheckFn
-
-```typescript
-type RuleCheckFn = (ctx: RuleContext) => Promise<boolean> | boolean;
-```
-
-Can be sync or async. Receives a `RuleContext`:
-
-| Property       | Type                                | Description                                                           |
-| -------------- | ----------------------------------- | --------------------------------------------------------------------- |
-| `event`        | `EventPayload`                      | The triggering event payload (discriminated union — narrow on `type`) |
-| `changedFiles` | `string[]`                          | Files changed in this event                                           |
-| `env`          | `Record<string, string\|undefined>` | Environment variables                                                 |
-| `$`            | zx shell                            | Shell executor for running commands                                   |
-
-### evaluateRules(rules, context, label, onRuleResult?)
-
-Evaluate an array of rules sequentially with fail-fast behavior. Stops on the first failure.
-
-```typescript
-function evaluateRules(
-  rules: Rule[],
-  context: RuleContext,
-  label: string,
-  onRuleResult?: (result: RuleResult) => void,
-): Promise<RuleEvaluationResult>;
-```
-
-Returns a `RuleEvaluationResult`:
-
-```typescript
-interface RuleEvaluationResult {
-  allPassed: boolean;
-  results: RuleResult[];
-}
-```
-
-### isEventType(event, type)
-
-Type guard that narrows an `EventPayload` to a specific event type variant. Use this in rule check functions to get autocomplete on provider-specific fields.
-
-```typescript
-function isEventType<T extends EventPayload['type']>(
-  event: EventPayload,
-  type: T,
-): event is Extract<EventPayload, { type: T }>;
-```
-
-**Example — skip draft PRs:**
-
-```typescript
-rule('skip-draft-prs', (ctx) => {
-  if (!isEventType(ctx.event, 'pull_request')) return true;
-  // ctx.event is now PullRequestEventPayload — full autocomplete
-  return !ctx.event.payload.pull_request.draft;
-});
-```
-
-**Example — branch-based rule with push narrowing:**
-
-```typescript
-rule('only-main-pushes', (ctx) => {
-  if (!isEventType(ctx.event, 'push')) return false;
-  // ctx.event.payload.ref is typed as string
-  return ctx.event.payload.ref === 'refs/heads/main';
-});
-```
-
-You can also narrow directly with `if (ctx.event.type === 'pull_request')` — TypeScript's discriminated union narrowing works on the `type` field.
-
-### EventPayload
-
-`EventPayload` is a discriminated union over the `type` field. Each variant provides typed access to the normalized event fields and the raw webhook payload.
-
-Every variant carries the shared `EventBase` fields — `type`, `action`, `targetBranch`, `sourceBranch`, `provider`, `isForkPR`, `baseBranch`, `senderUsername`, `sourceRepo`, `changedFiles`, and the raw `payload` — plus a per-type `payload` shape for the typed variants. The complete field-by-field schema, including every typed `payload` shape and the shared GitHub object types, is in the [event payload reference](https://docs.kici.dev/user/sdk/event-payloads/).
-
-**Typed variants** (with GitHub-specific payload fields): `pull_request`, `push`, `tag`, `comment`, `review`, `review_comment`, `release`, `dispatch`, `create`, `delete`, `status`, `workflow_run`, `fork`, `star`, `watch`.
-
-**Generic variants** (payload is `Record<string, unknown>`): `webhook`, `kici_event`, `workflow_complete`, `job_complete`, `generic_webhook`, `schedule`, `lifecycle`.
-
-## Matrix
-
-Matrix configurations expand a single job into multiple instances, one per parameter combination. Maximum 256 combinations.
-
-Expansion happens at **dispatch time**: the orchestrator materializes the matrix into N execution jobs — one per combination, each dispatched to its own agent — before any job runs. Each instance receives its combination as `ctx.matrix`. This is identical whether the workflow runs via `kici run <event> --local` or remotely through a webhook trigger, and the dashboard groups the N instances under one parent node.
-
-### Static array (single dimension)
-
-```typescript
-matrix: ['18', '20', '22'];
-```
-
-Creates 3 job instances. In steps, the current value is `matrix.value`:
-
-```typescript
-step('test', async ({ $, matrix }) => {
-  console.log(matrix!.value); // '18', '20', or '22'
-});
-```
-
-### Static object (multi-dimensional)
-
-```typescript
-matrix: {
-  os: ['linux', 'arm64'],
-  node: ['18', '20'],
-}
-```
-
-Creates 4 job instances (2 x 2). The `os` values (`linux`, `arm64`) are **customer-defined scaler labels** matched by subset semantics against the labels your orchestrator advertises in its scaler `labelSets` — not hosted-runner names. In steps, values are named properties:
-
-```typescript
-step('test', async ({ $, matrix }) => {
-  console.log(matrix!.os); // 'linux' or 'arm64'
-  console.log(matrix!.node); // '18' or '20'
-});
-```
-
-### Dynamic function
-
-Compute matrix values at runtime:
-
-```typescript
-matrix: async ({ $ }) => {
-  const result = await $`ls packages/`;
-  return result.stdout.trim().split('\n');
-};
-```
-
-The function receives a `DynamicMatrixContext`:
-
-| Property | Type                                | Description               |
-| -------- | ----------------------------------- | ------------------------- |
-| `$`      | zx shell                            | Shell executor            |
-| `ctx`    | `{ workflow, job }`                 | Workflow and job metadata |
-| `log`    | `Logger`                            | Structured logger         |
-| `env`    | `Record<string, string\|undefined>` | Environment variables     |
-
-Must return `string[]` (single dimension) or `Record<string, string[]>` (multi-dimensional).
-
-A dynamic matrix is resolved at runtime, then materialized into N instances exactly like a static matrix. Because the combinations are not known until the function runs, the 256-combination cap (and the "zero combinations" guard) is enforced at that point: a dynamic matrix that resolves to more than 256 combinations, or to none, fails the job with a matrix-expansion error rather than dispatching.
-
-### Include and exclude
-
-Fine-tune matrix combinations on multi-dimensional matrices:
-
-```typescript
-matrix: {
-  os: ['linux', 'arm64', 'windows'],
-  node: ['18', '20', '22'],
-},
-exclude: [
-  { os: 'windows', node: '18' },
-],
-include: [
-  { os: 'linux', node: '23' },
-],
-```
-
-**Exclude** removes combinations matching all specified keys. Applied first.
-**Include** adds exact combinations. Applied after exclude.
-
-Types:
-
-```typescript
-type MatrixInclude = Record<string, string>;
-type MatrixExclude = Record<string, string>;
-```
-
-### MatrixValues
-
-The shape of `matrix` in `StepContext`:
-
-```typescript
-interface MatrixValues {
-  value?: string; // Single-dimension value
-  [dimension: string]: string | undefined; // Named dimensions
-}
-```
-
-### 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`](https://docs.kici.dev/user/sdk/runs-on-all/#rolling-rollout-maxparallel--failfast) host fan-out:
-
-```typescript
-const test = job('test', {
-  runsOn: 'linux',
-  matrix: { os: ['ubuntu', 'macos', 'windows'] },
-  maxParallel: 1, // run one combination at a time (sliding window)
-  failFast: true, // stop launching combinations after the first failure
-  run: async (ctx) => {
-    /* ctx.matrix.os */
-  },
-});
-```
-
-`maxParallel` is a sliding window (each combination that finishes releases the next;
-`1` = serial; must be `>= 1`); `failFast` halts the fan-out on the first failure and
-skips the held remainder (default `false`). They are ignored on a job with no `matrix`
-or `runsOnAll`.
-
-### Consuming matrix outputs downstream
-
-A downstream job that lists a matrix job in its `needs` receives a **keyed envelope** instead of a flat outputs object, because the upstream produced N sets of outputs (one per combination). `ctx.jobOutputs(matrixJob)` returns a `MatrixJobOutputs`:
-
-```typescript
-interface MatrixJobOutputs<T = Record<string, unknown>> {
-  /** Keyed by the combination suffix — the text inside `(...)` of the child name. */
-  byMatrix: Record<string, T>;
-  /** Last-write-wins flat merge across children, in child (name) order. */
-  merged: T;
-}
-```
-
-The suffix key matches the child job's display name: `byMatrix['a']` for a single-dimension `['a', 'b']` matrix, `byMatrix['linux, arm64']` for a multi-dimension combination. Use `isMatrixJobOutputs` (or `'byMatrix' in result`) to discriminate:
-
-```typescript
-import { isMatrixJobOutputs } from '@kici-dev/sdk';
-
-step('collect', async ({ jobOutputs }) => {
-  const out = jobOutputs(buildMatrixJob);
-  if (isMatrixJobOutputs(out)) {
-    console.log(out.byMatrix['a']); // outputs of the `a` combination
-    console.log(out.merged); // last-write-wins across all combinations
-  }
-});
-```
-
-The downstream job waits for **all** matrix combinations to terminate before it dispatches. A non-matrix upstream keeps the flat outputs shape. The envelope is identical under `kici run <event> --local` and the remote path.
-
-### Matrix type guards
-
-```typescript
-import { isStaticArray, isStaticObject, isDynamicFunction } from '@kici-dev/sdk';
-
-isStaticArray(matrix); // true if string[]
-isStaticObject(matrix); // true if Record<string, string[]>
-isDynamicFunction(matrix); // true if async function
-```
-
-### Matrix expansion utilities
-
-```typescript
-import { expandMatrix, applyIncludeExclude } from '@kici-dev/sdk';
-```
-
-`expandMatrix(matrix)` takes a `StaticMatrixArray` or `StaticMatrixObject` and returns all combinations as `MatrixValues[]`. For a single-dimension array, each value becomes `{ value: '...' }`. For multi-dimensional objects, it produces the Cartesian product.
-
-`applyIncludeExclude(values, include?, exclude?)` filters an expanded matrix: removes combinations matching any exclude entry, then appends include entries. Returns the filtered `MatrixValues[]`.
-
-## Dynamic jobs
-
-Generate jobs at runtime using async factory functions.
-
-### DynamicJobFn
-
-```typescript
-type DynamicJobFn = (context: DynamicJobContext) => Promise<Job[]>;
-```
-
-Receives a `DynamicJobContext`:
-
-| Property | Type                                | Description                 |
-| -------- | ----------------------------------- | --------------------------- |
-| `$`      | zx shell                            | Shell executor              |
-| `ctx`    | `{ workflow, event? }`              | Workflow metadata and event |
-| `log`    | `Logger`                            | Structured logger           |
-| `env`    | `Record<string, string\|undefined>` | Environment variables       |
-
-```typescript
-const discoverJobs: DynamicJobFn = async ({ $ }) => {
-  const result = await $`ls packages/`;
-  const packages = result.stdout.trim().split('\n');
-  return packages.map((pkg) =>
-    job(`test-${pkg}`, {
-      runsOn: 'linux',
-      steps: [
-        step('test', async ({ $ }) => {
-          await $`cd packages/${pkg} && pnpm test`;
-        }),
-      ],
-    }),
-  );
-};
-
-export default workflow('ci', {
-  jobs: [discoverJobs],
-});
-```
-
-### 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, when }`                      | `{ result, status }` — `result` is an `OutputProxy` (`ctx.needs.<job>.result.<step>.<field>`; single-step `run` jobs flatten to `ctx.needs.<job>.result.<field>`); `status` is the upstream's terminal status |
-| `dynamicGroup('g')` / `dynamicGroup('g', { when })` | ordered array of `{ name, result, status }`, 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()`](https://docs.kici.dev/user/sdk/triggers/) for cross-workflow reactions to a job finishing. See the architecture deep-dive in [dynamic jobs](https://docs.kici.dev/architecture/execution/dynamic-jobs/#result-aware-generation).
-
-### JobOrFactory
-
-The `jobs` array in `WorkflowOptions` accepts both static jobs and dynamic generators:
+Creates 3 job instances. In steps, the current value is `matrix.value`:
 
 ```typescript
-type JobOrFactory = Job | DynamicJobFn;
+step('test', async ({ $, matrix }) => {
+  console.log(matrix!.value); // '18', '20', or '22'
+});
 ```
 
-### isDynamicJobFn(item)
-
-Type guard to distinguish static jobs from dynamic generators:
-
-```typescript
-function isDynamicJobFn(item: JobOrFactory): item is DynamicJobFn;
-```
+### Static object (multi-dimensional)
 
 ```typescript
-for (const item of workflow.jobs) {
-  if (isDynamicJobFn(item)) {
-    const generatedJobs = await item(context);
-  } else {
-    // item is Job
-  }
+matrix: {
+  os: ['linux', 'arm64'],
+  node: ['18', '20'],
 }
 ```
 
----
-
-## 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`](https://docs.kici.dev/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`](https://docs.kici.dev/user/sdk/core/#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):
+Creates 4 job instances (2 x 2). The `os` values (`linux`, `arm64`) are **customer-defined scaler labels** matched by subset semantics against the labels your orchestrator advertises in its scaler `labelSets` — not hosted-runner names. In steps, values are named properties:
 
 ```typescript
-const fanout = job('deploy', {
-  runsOnAll: {
-    include: [{ all: ['kici:os:linux', 'kici:host:web-*'] }],
-    exclude: [/.*-canary$/],
-  },
-  run: async (ctx) => {
-    /* runs once per matched host */
-  },
+step('test', async ({ $, matrix }) => {
+  console.log(matrix!.os); // 'linux' or 'arm64'
+  console.log(matrix!.node); // '18' or '20'
 });
 ```
 
-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`.
-
-### ctx.fanout — fan-out position
+### Dynamic function
 
-Every fan-out child — a `runsOnAll` host **or** a matrix combination — also
-carries its **position** within the fan-out:
+Compute matrix values at runtime:
 
 ```typescript
-ctx.fanout?: {
-  index: number;   // 0-based position in the deterministically-ordered fan-out
-  total: number;   // number of children in this fan-out
-  first: boolean;  // index === 0
-  last: boolean;   // index === total - 1
+matrix: async ({ $ }) => {
+  const result = await $`ls packages/`;
+  return result.stdout.trim().split('\n');
 };
 ```
 
-The order is a **documented guarantee**: host fan-out is ordered by agent id,
-matrix fan-out by its combination label. So `ctx.fanout.first` is always the
-same (lowest-agent-id) host across re-runs, and `ctx.fanout.last` the same final
-one. `ctx.fanout` is `undefined` on a job that is not fanned out.
-
-### Run-once steps: onlyOnFirstHost / onlyOnLastHost / onlyOnFanoutIndex
-
-For ordered, stateful rollouts you often need a step that runs on exactly **one**
-host — enable a leader before the rest join, run a one-time migration, take a
-single dump. Three rule helpers express this by reading `ctx.fanout`:
-
-```typescript
-import { job, step, onlyOnFirstHost, onlyOnLastHost, onlyOnFanoutIndex } from '@kici-dev/sdk';
-
-const rollout = job('rollout', {
-  runsOnAll: 'role:db',
-  maxParallel: 1, // serial, so "first" runs before the rest
-  steps: [
-    // Runs only on the first (lowest-agent-id) host — KiCI's run-once primitive.
-    step('enable-sync-mode', { rules: [onlyOnFirstHost()] }, async (ctx) => {
-      /* configure the leader before standbys join */
-    }),
-    // Runs on every host.
-    step('apply', async (ctx) => {
-      /* ... */
-    }),
-    // Runs only on the last host.
-    step('finalize', { rules: [onlyOnLastHost()] }, async (ctx) => {
-      /* ... */
-    }),
-  ],
-});
-```
-
-- A step gated this way is **skipped** (not failed) on non-matching hosts — its
-  outputs exist only on the host where it ran.
-- `onlyOnFanoutIndex(n)` targets the host at a specific position.
-- **Non-fan-out safety:** on a job that is not fanned out, `ctx.fanout` is
-  `undefined` and these helpers treat the job as a single implicit child at
-  index 0 — so `onlyOnFirstHost()` runs normally there (there is one host, which
-  is the first). This means you can author a step with `onlyOnFirstHost()` and it
-  behaves correctly whether or not the job ends up fanning out.
-- The helpers are host-flavored by name (the dominant use case) but read
-  `ctx.fanout`, so they work for matrix fan-out too — `onlyOnFirstHost()` runs on
-  the first combination.
-
-### 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;
-    }
-  },
-});
-```
+The function receives a `DynamicMatrixContext`:
 
-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.
+| Property | Type                                | Description               |
+| -------- | ----------------------------------- | ------------------------- |
+| `$`      | zx shell                            | Shell executor            |
+| `ctx`    | `{ workflow, job }`                 | Workflow and job metadata |
+| `log`    | `Logger`                            | Structured logger         |
+| `env`    | `Record<string, string\|undefined>` | Environment variables     |
 
-### onUnreachable: skip | fail | hold
+Must return `string[]` (single dimension) or `Record<string, string[]>` (multi-dimensional).
 
-Resolution is backed by the **declared host roster** (see the operator
-[host roster](https://docs.kici.dev/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:
+The contract is enforced at runtime. A function that returns anything else — `undefined` (a
+missing `return`), a bare string, or an object whose values are not arrays — fails the job with
+an error naming the job and the expected shape. Numbers and booleans are accepted and converted
+to strings, since matrix values appear in job names as text.
 
-- **`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.
+Values must also be unique. A matrix containing the same value twice would produce two children
+with the same name, so it fails the job instead — de-duplicate the values your function returns
+(for example, `[...new Set(values)]`). The same rule applies to a static matrix.
 
-```typescript
-const patch = job('patch', {
-  runsOnAll: 'role:web',
-  onUnreachable: 'skip',
-  run: async (ctx) => {
-    /* ... */
-  },
-});
-```
+A dynamic matrix that would expand to an unreasonable number of raw combinations is refused
+before it is built, so a runaway discovery command fails the job with an error rather than
+exhausting the agent.
 
-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.
+A dynamic matrix is resolved at runtime, then materialized into N instances exactly like a static matrix. Because the combinations are not known until the function runs, the 256-combination cap (and the "zero combinations" guard) is enforced at that point: a dynamic matrix that resolves to more than 256 combinations, or to none, fails the job with a matrix-expansion error rather than dispatching.
 
-### includeUninitialized: converge a fresh fleet
+### Include and exclude
 
-`onUnreachable` governs declared hosts that _had_ an agent and are momentarily absent.
-A **never-initialized** host — a freshly-provisioned box reachable over SSH but with no
-agent yet — is a different case: there is nothing to run on. Set
-`includeUninitialized: true` to widen the fan-out to those hosts and bring them up:
+Fine-tune matrix combinations on multi-dimensional matrices:
 
 ```typescript
-const converge = job('converge', {
-  runsOnAll: 'kici:group:prod',
-  includeUninitialized: true,
-  steps: [partitionDisk, formatLuks, debootstrap, installAgent],
-});
+matrix: {
+  os: ['linux', 'arm64', 'windows'],
+  node: ['18', '20', '22'],
+},
+exclude: [
+  { os: 'windows', node: '18' },
+],
+include: [
+  { os: 'linux', node: '23' },
+],
 ```
 
-For each un-agented declared host (one carrying SSH reach metadata), KiCI brings up a
-temporary init-runner over SSH and runs the **same steps** on it; hosts that already
-have a live agent run the steps on their own agent. One workflow converges the whole
-fleet — fresh boxes get built, live boxes run the same phases.
-
-Because the steps run on already-initialized hosts too, the bootstrap phases **must be
-idempotent [check-steps](https://docs.kici.dev/user/sdk/core/)**: each step's `check()` reports in-sync on a
-live box so the partition / format / install steps **skip** there and run only on fresh
-boxes. This is the safety guard — an OS or disk-format step must never re-run on a host
-that is already built. Re-running the workflow is a no-op everywhere. See the operator
-[fresh-box bootstrap](https://docs.kici.dev/operator/orchestrator/host-roster/) doc for the bring-up,
-capability gating, and lifecycle details.
-
-`includeUninitialized` is only meaningful alongside `runsOnAll`; it is ignored on a
-single-agent `runsOn` job.
-
-### Rolling rollout: maxParallel + failFast
+**Exclude** removes combinations matching all specified keys. Applied first.
+**Include** adds exact combinations. Applied after exclude.
 
-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:
+Values appear in the expanded job name ordered by their dimension name, alphabetically, whichever
+order you write the keys in. The include entry above therefore becomes `test (23, linux)` — the
+`node` value then the `os` value, the same order as its expanded siblings `test (18, linux)` and
+`test (20, linux)`. That order is also the `byMatrix` key a downstream job reads its outputs under
+(see [Consuming matrix outputs downstream](https://docs.kici.dev/user/sdk/rules-matrix-dynamic/#consuming-matrix-outputs-downstream)), so an include
+entry whose keys you wrote out of
+alphabetical order is keyed alphabetically too.
 
-- **`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).
+Types:
 
 ```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.
-
-### Narrowing the roster at run time with `--target`
-
-A `runsOnAll` predicate is authored once in the workflow, but you can narrow it for a
-single run with `kici run --target <selector>` — an Ansible-`--limit`-style runtime
-filter. The effective host set becomes `runsOnAll ∩ target`: the selector can only
-_remove_ hosts from the matched roster, never add them. The narrowing is **run-global**
-(it applies to every `runsOnAll` job) and **`runsOnAll`-only** (single `runsOn`-pinned
-jobs are untouched). Repeated `--target` values AND-combine — a host must satisfy every
-selector to survive.
-
-```bash
-# Patch only the role:web subset of whatever role:* hosts the job would match
-kici run remote deploy --target role:web
-
-# Intersect two selectors: hosts must be BOTH role:web AND dc:eu
-kici run remote deploy --target role:web --target dc:eu
+type MatrixInclude = Record<string, string>;
+type MatrixExclude = Record<string, string>;
 ```
 
-When `--target` narrows a `runsOnAll` job to zero hosts, the run **fails** by default
-(a mistyped selector should be loud, not silently no-op). Pass `--target-allow-empty`
-to **skip** the zeroed job instead — it records a `skipped` status, and downstream jobs
-gated with `when: 'on-skip'` (or `when: 'always'`) still run, exactly as for an
-`onUnreachable: 'skip'` zero-host fan-out. See the [CLI reference](https://docs.kici.dev/user/cli-reference/#host-narrowing-with---target)
-for the full flag behavior and the [`needs` gating model](https://docs.kici.dev/user/sdk/core/#job-dependencies-needs)
-for how a skipped upstream propagates.
-
-### 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/
-
-## Types
-
-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 \| 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](https://docs.kici.dev/user/sdk/core/#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](https://docs.kici.dev/user/sdk/runs-on-all/#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
-
-| Type                            | Description                                                           |
-| ------------------------------- | --------------------------------------------------------------------- |
-| `Trigger`                       | Trigger definition (trigger config + source location)                 |
-| `TriggerConfig`                 | Union of all 22 trigger config types                                  |
-| `PrTriggerConfig`               | PR trigger configuration (from `pr()`)                                |
-| `PushTriggerConfig`             | Push trigger configuration (from `push()`)                            |
-| `TagTriggerConfig`              | Tag trigger configuration (from `tag()`)                              |
-| `CommentTriggerConfig`          | Comment trigger configuration (from `comment()`)                      |
-| `ReviewTriggerConfig`           | Review trigger configuration (from `review()`)                        |
-| `ReviewCommentTriggerConfig`    | Review comment trigger configuration (from `reviewComment()`)         |
-| `ReleaseTriggerConfig`          | Release trigger configuration (from `release()`)                      |
-| `DispatchTriggerConfig`         | Repository dispatch trigger configuration (from `dispatch()`)         |
-| `CreateTriggerConfig`           | Ref creation trigger configuration (from `create()`)                  |
-| `DeleteTriggerConfig`           | Ref deletion trigger configuration (from `delete()`)                  |
-| `StatusTriggerConfig`           | Commit status trigger configuration (from `status()`)                 |
-| `WorkflowRunTriggerConfig`      | Workflow run trigger configuration (from `workflowRun()`)             |
-| `ForkTriggerConfig`             | Fork trigger configuration (from `fork()`)                            |
-| `StarTriggerConfig`             | Star trigger configuration (from `star()`)                            |
-| `WatchTriggerConfig`            | Watch trigger configuration (from `watch()`)                          |
-| `WebhookTriggerConfig`          | Catch-all webhook trigger configuration (from `webhook()`)            |
-| `KiciEventTriggerConfig`        | Custom event trigger configuration (from `kiciEvent()`)               |
-| `WorkflowCompleteTriggerConfig` | Workflow completion trigger configuration (from `workflowComplete()`) |
-| `JobCompleteTriggerConfig`      | Job completion trigger configuration (from `jobComplete()`)           |
-| `GenericWebhookTriggerConfig`   | Generic webhook trigger configuration (from `genericWebhook()`)       |
-| `ScheduleTriggerConfig`         | Schedule trigger configuration (from `schedule()`)                    |
-| `LifecycleTriggerConfig`        | Lifecycle trigger configuration (from `lifecycle()`)                  |
-| `PrConfigInput`                 | Config object for `pr()` factory                                      |
-| `PushConfigInput`               | Config object for `push()` factory                                    |
-| `BranchPattern`                 | `{ type: 'glob', pattern } \| { type: 'regex', pattern, flags? }`     |
-| `PrEvent`                       | PR event string literal union (17 event types)                        |
-| `GenericWebhookConfigInput`     | Config object for `genericWebhook()` factory                          |
-| `GenericWebhookAuth`            | Union of generic webhook auth types (HMAC or API key)                 |
-| `GenericWebhookHmacAuth`        | HMAC-SHA256 auth configuration for generic webhooks                   |
-| `GenericWebhookApiKeyAuth`      | API key auth configuration for generic webhooks                       |
-| `GenericWebhookAuthMethod`      | Auth method string literal (`'hmac-sha256' \| 'api-key'`)             |
-
-### Rule types
-
-| Type                   | Description                                                             |
-| ---------------------- | ----------------------------------------------------------------------- |
-| `Rule`                 | Rule definition returned by `rule()` / `skip()`                         |
-| `RuleCheckFn`          | `(ctx: RuleContext) => Promise<boolean> \| boolean`                     |
-| `RuleContext`          | Context passed to rule check functions                                  |
-| `RuleResult`           | Result of rule evaluation (label, passed, duration)                     |
-| `EventPayload`         | Discriminated union over event type (narrow on `type` for autocomplete) |
-| `RuleEvaluationResult` | Result of `evaluateRules()` (allPassed + results)                       |
-
-### Matrix types
-
-| Type                   | Description                                                         |
-| ---------------------- | ------------------------------------------------------------------- |
-| `Matrix`               | Union: `StaticMatrixArray \| StaticMatrixObject \| DynamicMatrixFn` |
-| `StaticMatrixArray`    | `string[]`                                                          |
-| `StaticMatrixObject`   | `Record<string, string[]>`                                          |
-| `DynamicMatrixFn`      | `(ctx) => Promise<StaticMatrixArray \| StaticMatrixObject>`         |
-| `DynamicMatrixContext` | Context passed to dynamic matrix functions                          |
-| `MatrixValues`         | Values exposed to steps (`value?` + named dimensions)               |
-| `MatrixInclude`        | `Record<string, string>` -- additional combinations                 |
-| `MatrixExclude`        | `Record<string, string>` -- removed combinations                    |
-
-### Hook types
-
-| Type              | Description                                                     |
-| ----------------- | --------------------------------------------------------------- |
-| `HookConfig`      | Hook definition returned by hook factories (`onCancel()`, etc.) |
-| `HookFn`          | Hook function type: `(ctx: HookContext) => Promise<void>`       |
-| `HookInput`       | Hook input: `HookFn \| { run: HookFn; timeout?: number }`       |
-| `HookContext`     | Context passed to hook functions                                |
-| `OutcomeMetadata` | Metadata about the outcome that triggered the hook              |
-
-### Dynamic job types
-
-| Type                | Description                        |
-| ------------------- | ---------------------------------- |
-| `DynamicJobFn`      | `(ctx) => Promise<Job[]>`          |
-| `DynamicJobContext` | Context for dynamic job generators |
-| `JobOrFactory`      | `Job \| DynamicJobFn`              |
-
-### Context types
-
-| Type                  | Description                                                        |
-| --------------------- | ------------------------------------------------------------------ |
-| `StepContext<T>`      | Context passed to step run functions                               |
-| `Logger`              | Logger interface (info, warn, error, debug)                        |
-| `WorkflowInfo`        | Workflow metadata: `{ name: string }`                              |
-| `JobInfo`             | Job metadata: `{ name: string, runsOn: string }`                   |
-| `RepoInfo`            | Repository metadata available in step context                      |
-| `StepSecrets`         | Async accessor interface for step secrets (`get`, `expose`, `has`) |
-| `StepSecretsTyped`    | Typed step secrets with known key inference                        |
-| `KnownSecretKeys`     | String literal union of declared secret context keys               |
-| `SecretNotFoundError` | Thrown when accessing a nonexistent key in secrets                 |
-
-## StepContext
-
-The context object passed to every step's `run` function:
-
-```typescript
-interface StepContext<TInputs = Record<string, unknown>> {
-  /** zx shell executor for running commands */
-  $: typeof Shell;
-  /** Structured logger */
-  log: Logger;
-  /** Environment variables */
-  env: Record<string, string | undefined>;
-  /** Set an environment variable visible to this step and all subsequent steps */
-  setEnv(key: string, value: string): void;
-  /** Prepend a directory to PATH, visible to this step and all subsequent steps */
-  addPath(dir: string): void;
-  /** Typed inputs from dependency step outputs */
-  inputs: TInputs;
-  /** Current workflow metadata */
-  workflow: WorkflowInfo;
-  /** Current job metadata */
-  job: JobInfo;
-  /** Matrix values for current job instance (undefined without matrix) */
-  matrix?: MatrixValues;
-  /** Raw webhook payload from the git provider */
-  rawPayload?: Record<string, unknown>;
-  /** Which git provider triggered this workflow (e.g. 'github', 'gitlab') */
-  provider?: string;
-  /** Whether this execution was triggered by `kici run remote` (developer-initiated remote run) */
-  isTestRun: boolean;
-  /** The resolved deployment environment name for this job (undefined without environment) */
-  environment?: string;
-  /** Flat secrets resolved for this job. Throws SecretNotFoundError on missing key. */
-  secrets: StepSecrets;
-  /** Emit a custom event that can trigger other workflows */
-  emit(
-    eventName: string,
-    payload?: Record<string, unknown>,
-    options?: EventEmitOptions,
-  ): Promise<{ deliveryId: string }>;
-  /** Resolve outputs from a preceding step by reference */
-  outputsOf<T>(ref: { _tag: 'Step'; name: string } | ((...args: any[]) => any)): T;
-  /** Resolve outputs from a preceding job by reference */
-  jobOutputs(ref: { name: string }): Record<string, unknown>;
-  /** Publish a secret output value from this job (encrypted before leaving the agent) */
-  setSecretOutput(key: string, value: string): void;
-}
-```
+### MatrixValues
 
-### Logger
+The shape of `matrix` in `StepContext`:
 
 ```typescript
-interface Logger {
-  info(message: string, ...args: unknown[]): void;
-  warn(message: string, ...args: unknown[]): void;
-  error(message: string, ...args: unknown[]): void;
-  debug(message: string, ...args: unknown[]): void;
+interface MatrixValues {
+  value?: string; // Single-dimension value
+  [dimension: string]: string | undefined; // Named dimensions
 }
-```
-
-### Usage
-
-```typescript
-step('example', async ({ $, log, env, matrix, workflow, job }) => {
-  log.info(`Running in workflow: ${workflow.name}`);
-  log.info(`Job: ${job.name} on ${job.runsOn}`);
-
-  if (matrix) {
-    log.info(`Matrix value: ${matrix.value}`);
-  }
-
-  const token = env.GITHUB_TOKEN;
-  await $`echo "Building..."`;
-});
-```
-
-### `rawPayload` and rule-context parity
-
-`ctx.rawPayload` carries the same data that rule contexts access via `ctx.event.payload` — the unmodified webhook body from the git provider. A rule that branches on `ctx.event.payload.client_payload.foo` and a step body that reads `ctx.rawPayload.client_payload.foo` see the same value. Use it inside steps when the operator's dispatch payload (or any other provider-specific field) needs to drive runtime behavior — e.g. a `--dry-run` toggle or a deploy target — without bouncing the data through an env var.
-
-**What's captured in the dashboard log viewer.** KiCI captures user output from every place in a workflow that can run TypeScript:
-
-- **Inside a step body** — the agent merges three streams into the step's log: `ctx.log.*` structured calls, subprocess stdout/stderr from `ctx.$`, and any direct `console.log` / `.error` / `.warn` / `.info` / `.debug` (or other library that writes to `process.stdout` / `process.stderr`).
-- **Inside hooks** (`beforeStep`, `afterStep`, `onSuccess`, `onFailure`, `onCancel`, `cleanup`) — the same three streams are captured; per-step hooks share the step's log, post-loop hooks get their own dashboard row.
-- **At workflow module top-level, in rule `check` functions, and in the workflow `concurrency.group` function** — captured to the workflow-level `prepare` log bucket for the job, alongside KiCI's own setup narration.
-- **Inside a dynamic `environment` / `env` / `concurrencyGroup` function** on a static job — captured to the `__init__` job's synthetic step-0 log, which appears in the timeline as "Init: _jobname_".
-- **Inside a `DynamicJobFn` body and the per-generated-job `environment` / `env` / `concurrencyGroup` / `matrix` functions** — captured to the `__dynamic__` job's synthetic step-0 log ("Evaluate: _jobname_" in the timeline). The `$` parameter in that context is a scoped zx shell, so `await $\`...\`` subprocess output is captured too.
-
-Use whichever style is convenient — you don't have to wrap `console.log` in the provided `log` parameter to make it visible. One limitation applies to in-process contexts only (init, build, dynamic-eval): direct `process.stdout.write` / `printf` is not captured there, because the agent's own logger uses that path and we don't want agent-internal output leaking into your step logs. Use `console.*` or the `log` parameter instead. See [Log streaming](https://docs.kici.dev/architecture/execution/job-execution/#log-streaming) for the full capture surface and limits (default 10 MB per step, backpressure behavior).
-
-### setEnv(key, value)
-
-Export an environment variable to later steps in the same job. This is the canonical way to hand a value computed in one step to the steps that follow — the equivalent of `echo "KEY=VALUE" >> $GITHUB_ENV` in GitHub Actions. The value is visible to the current step and all subsequent steps in the job.
-
-```typescript
-step('setup', async (ctx) => {
-  // Install a tool and record its version
-  await ctx.$`npm install -g some-tool`;
-  const version = (await ctx.$`some-tool --version`).stdout.trim();
-  ctx.setEnv('TOOL_VERSION', version);
-});
-
-step('use', async (ctx) => {
-  // TOOL_VERSION is available here
-  ctx.log.info(`Using tool version: ${ctx.env.TOOL_VERSION}`);
-});
-```
-
-**Behavior:**
-
-- Last-write-wins -- if multiple steps set the same key, the last value is used
-- Cannot override operator-injected secrets (the operator value takes precedence)
-- Changes take effect immediately in the current step and persist for all subsequent steps
-- Shell commands export the same way by appending to `$KICI_ENV` (see [Exporting env from shell commands](https://docs.kici.dev/user/sdk/runtime/#exporting-env-from-shell-commands-kici_env--kici_path) below)
-
-### addPath(dir)
-
-Prepend a directory to `PATH` for the current step and all subsequent steps in the same job. Useful for tools installed to non-standard locations.
-
-```typescript
-step('install-go', async (ctx) => {
-  await ctx.$`curl -L https://go.dev/dl/go1.22.0.linux-amd64.tar.gz | tar -C /tmp -xz`;
-  ctx.addPath('/tmp/go/bin');
-});
-
-step('build', async (ctx) => {
-  // `go` is now on PATH
-  await ctx.$`go build ./...`;
-});
-```
-
-### Exporting env from shell commands ($KICI_ENV / $KICI_PATH)
-
-`setEnv` and `addPath` are the TypeScript form of "export env to later steps". A shell command — including a non-JS toolchain installer — exports env the same way by appending to two files the agent points at before every step:
-
-- **`$KICI_ENV`** — append `KEY=value` lines. Each becomes an environment variable visible to subsequent steps, exactly like `ctx.setEnv('KEY', 'value')`.
-- **`$KICI_PATH`** — append one directory per line. Each is prepended to `PATH` for subsequent steps, exactly like `ctx.addPath(dir)`. The first directory appended ends up first on `PATH`.
-
-```typescript
-step('install-tool', async (ctx) => {
-  await ctx.$`./install-mytool.sh`; // installs to /opt/mytool
-  // Export from the shell, no JS round-trip needed:
-  await ctx.$`echo "MYTOOL_HOME=/opt/mytool" >> "$KICI_ENV"`;
-  await ctx.$`echo "/opt/mytool/bin" >> "$KICI_PATH"`;
-});
-
-step('build', async (ctx) => {
-  // MYTOOL_HOME is set and /opt/mytool/bin is on PATH here.
-  await ctx.$`mytool build`;
-});
-```
-
-**Format (v1):**
-
-- One `KEY=value` per line in `$KICI_ENV`. The split is on the first `=`, so the value may contain `=`. Blank lines and lines without a `=` are ignored.
-- One directory per line in `$KICI_PATH`. Blank lines are ignored.
-- Values must be single-line — embedded newlines are not supported in v1.
-
-**Behavior (shared with `setEnv` / `addPath`):**
-
-- Applied after the step completes and visible to every later step in the job.
-- Last-write-wins on a repeated key.
-- Cannot override an operator-injected secret — a collision is ignored and logged, and the operator value is preserved.
-- The files are reset before each step, so each step sees only its own appended lines.
-
-### setSecretOutput(key, value)
-
-Publish an encrypted secret output from this job. Downstream jobs that list this job in their `needs` array receive the value merged into `ctx.secrets`.
-
-```typescript
-const generateToken = job('generate-token', {
-  steps: [
-    step('create', async (ctx) => {
-      const token = (await ctx.$`vault write -f auth/token/create`).stdout.trim();
-      ctx.setSecretOutput('DEPLOY_TOKEN', token);
-    }),
-  ],
-});
-
-const deploy = job('deploy', {
-  needs: [generateToken],
-  steps: [
-    step('deploy', async (ctx) => {
-      // DEPLOY_TOKEN is available as a secret (decrypted by the orchestrator)
-      const token = await ctx.secrets.get('DEPLOY_TOKEN');
-      await ctx.$`DEPLOY_TOKEN=${token} ./deploy.sh`;
-    }),
-  ],
-});
-```
-
-**Security model:**
-
-- The value is encrypted on the agent before leaving the machine (X25519 ECDH + AES-256-GCM)
-- The orchestrator decrypts and re-encrypts with its own key before storing
-- The ephemeral key pair is deleted when the run completes (forward secrecy)
-- Downstream agents never see the plaintext -- they receive it as part of their injected secrets
-
-**Limits:**
-
-- Maximum 20 secret outputs per job
-- Maximum 64 KB per value
+```
 
-### ctx.kici.oidc.token({ audience })
+### Bounding matrix concurrency (maxParallel / failFast)
 
-Request a short-lived OIDC ID token for the current job, bound to an `audience`. The token is a signed JWT whose identity claims (`repository`, `ref`, `sha`, `kici_run_id`, `kici_job_id`) are derived by the build platform from the run context — a step cannot spoof them. Use it to authenticate the build to an external service that trusts the platform's OIDC issuer (for example, when generating build provenance).
+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`](https://docs.kici.dev/user/sdk/runs-on-all/#rolling-rollout-maxparallel--failfast) host fan-out:
 
 ```typescript
-const publish = job('publish', {
-  steps: [
-    step('mint', async (ctx) => {
-      const { token, expiresIn } = await ctx.kici.oidc.token({ audience: 'sigstore' });
-      ctx.log.info(`Got an ID token valid for ${expiresIn}s`);
-      // Hand `token` to a tool that exchanges it with the trusting service.
-    }),
-  ],
+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 */
+  },
 });
 ```
 
-**Behavior:**
-
-- The token is short-lived (about 10 minutes) and scoped to the current run and job.
-- The returned token value is automatically masked in step logs.
-- The step never holds platform credentials — the request is relayed through the orchestrator, which mints the token on the step's behalf.
-- Only available inside a running job step; calling it outside one (for example, during local execution) rejects with a clear error.
+`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`.
 
-### ctx.kici.inventory.query(selector?) / .get(agentId)
+### Consuming matrix outputs downstream
 
-Query the **host inventory** — the roster of agents in the caller's orchestrator cluster — from inside a workflow. Each host is a `HostInventoryEntry`:
+A downstream job that lists a matrix job in its `needs` receives a **keyed envelope** instead of a flat outputs object, because the upstream produced N sets of outputs (one per combination). `ctx.jobOutputs(matrixJob)` returns a `MatrixJobOutputs`:
 
 ```typescript
-interface HostInventoryEntry {
-  agentId: string;
-  labels: string[]; // flat-string grouping/tags dimension
-  properties: Record<string, string | number | boolean>; // typed host-vars dimension
-  hostname: string | null;
-  platform: string | null;
-  arch: string | null;
-  lifecycleClass: 'static' | 'ephemeral';
-  status: 'ready' | 'unreachable' | 'stale';
-  lastSeen: string; // ISO timestamp
+interface MatrixJobOutputs<T = Record<string, unknown>> {
+  /** Keyed by the combination suffix — the text inside `(...)` of the child name. */
+  byMatrix: Record<string, T>;
+  /** Last-write-wins flat merge across children, in child (name) order. */
+  merged: T;
 }
 ```
 
-Two dimensions describe a host. **Labels** are flat strings used for grouping and targeting (the same labels `runsOn` / `runsOnAll` match). **Properties** are typed host-vars (`string | number | boolean`) — the place for facts like `region`, `cores`, or `gpu`. A host reports its own properties via the agent's `KICI_PROPERTIES` config, and an operator can pre-declare them with `kici-admin host declare --prop key=value`; the two are shallow-merged (agent-reported keys win).
+The suffix key matches the child job's display name: `byMatrix['a']` for a single-dimension `['a', 'b']` matrix, and for a multi-dimension combination the values ordered by dimension name — `byMatrix['arm64, linux']` for `{ arch: 'arm64', os: 'linux' }`. Use `isMatrixJobOutputs` (or `'byMatrix' in result`) to discriminate:
 
 ```typescript
-// All hosts:
-const all = await ctx.kici.inventory.query();
+import { isMatrixJobOutputs } from '@kici-dev/sdk';
 
-// Server-side label filter (OR-of-AND include groups, plus exclude):
-const dbHosts = await ctx.kici.inventory.query({
-  include: [[{ kind: 'exact', value: 'role:db' }]],
+step('collect', async ({ jobOutputs }) => {
+  const out = jobOutputs(buildMatrixJob);
+  if (isMatrixJobOutputs(out)) {
+    console.log(out.byMatrix['a']); // outputs of the `a` combination
+    console.log(out.merged); // last-write-wins across all combinations
+  }
 });
-
-// Property filtering is client-side — plain JS in the workflow:
-const euDbHosts = dbHosts.filter((h) => h.properties.region === 'eu');
-
-// One host by id:
-const host = await ctx.kici.inventory.get('box-1'); // HostInventoryEntry | null
 ```
 
-**The label selector is applied server-side** (reusing the same glob/regex matchers as `runsOnAll`). **Property filtering is client-side** — you filter the returned array in plain JavaScript, so there is no query DSL to learn.
+The downstream job waits for **all** matrix combinations to terminate before it dispatches. A non-matrix upstream keeps the flat outputs shape. The envelope is identical under `kici run <event> --local` and the remote path.
 
-**Headline use — dynamic-job fan-out.** A dynamic-job generator can query the inventory and return one job per matching host, fanning a workflow out across a fleet:
+### Matrix type guards
 
 ```typescript
-const migrate = job('migrate', async (ctx) => {
-  const hosts = await ctx.kici.inventory.query({
-    include: [[{ kind: 'exact', value: 'role:db' }]],
-  });
-  return hosts
-    .filter((h) => h.properties.region === 'eu')
-    .map((h) =>
-      job(`migrate-${h.agentId}`, {
-        runsOn: [h.agentId],
-        run: async (c) => {
-          await c.$`./migrate.sh`;
-        },
-      }),
-    );
-});
-```
-
-A `runsOn` of a single host's `agentId` (as in `runsOn: [h.agentId]` above) **pins the job to that host**: the orchestrator routes it to that agent only, and queues it with the pin if the host is momentarily offline — the same host-pin path `runsOnAll` uses. A `runsOn` with multiple labels or a glob/regex pattern stays ordinary label routing.
-
-`ctx.kici.inventory` is available to **both** steps and dynamic-job generators (unlike `ctx.kici.oidc.token`, which is job-bound — the inventory is cluster-scoped, not job-bound).
-
-**Determinism caveat.** The inventory is **live**: it can change between when a dynamic-job generator first runs (at dispatch) and when it re-evaluates (at agent time). Generating jobs from `inventory.query()` therefore inherits the same non-determinism contract as `infrastructure.list()` — KiCI warns when the re-evaluated job set drifts (a sibling job name changed) and hard-errors when a targeted job vanishes. Prefer stable inputs where you can, and treat a fanned-out job set as a snapshot of the roster at generation time.
-
-### ctx.attestProvenance({ subject })
+import { isStaticArray, isStaticObject, isDynamicFunction } from '@kici-dev/sdk';
 
-Build, sign, and persist a build-provenance attestation for an artifact your step produced. KiCI assembles an in-toto SLSA v1.0 provenance statement whose build identity (`repository`, `ref`, `sha`, run/job ids) comes from the platform — not from the step — so it cannot be spoofed, signs it, and stores a verifiable bundle that the dashboard surfaces and the `kici verify-attestation` CLI checks.
+isStaticArray(matrix); // true if string[]
+isStaticObject(matrix); // true if Record<string, string[]>
+isDynamicFunction(matrix); // true if async function
+```
 
-The artifact is **caller-supplied**: give it either a precomputed digest or a path (relative to the step working directory) that KiCI digests with SHA-256. For a container image, pass the manifest digest your build tool emitted.
+### Matrix expansion utilities
 
 ```typescript
-const publish = job('publish', {
-  steps: [
-    step('build', async (ctx) => {
-      await ctx.$`npm pack`;
-    }),
-    step('attest', async (ctx) => {
-      // Digest a file KiCI hashes for you:
-      const result = await ctx.attestProvenance({
-        subject: { name: 'my-pkg-1.2.3.tgz', path: 'my-pkg-1.2.3.tgz' },
-      });
-      ctx.log.info(`Attestation stored at ${result.storageKey}`);
-
-      // Or supply a precomputed digest (e.g. a container manifest digest):
-      await ctx.attestProvenance({
-        subject: { name: 'ghcr.io/acme/app', digest: { sha256: '<manifest-digest>' } },
-      });
-    }),
-  ],
-});
+import { expandMatrix, applyIncludeExclude } from '@kici-dev/sdk';
 ```
 
-**Behavior:**
-
-- The attestation is a signed [DSSE](https://github.com/secure-systems-lab/dsse) envelope over an [in-toto](https://in-toto.io) statement carrying the [SLSA v1.0](https://slsa.dev/spec/v1.0/provenance) provenance predicate.
-- It is signed with an ephemeral key bound to a platform-minted identity token, so it is **offline-verifiable** against the platform's published signing keys — no online lookup needed at verify time.
-- The bundle is persisted to object storage and recorded so the dashboard can show it and `kici verify-attestation` can retrieve it.
-- The returned `{ storageKey, subjectDigest, bundleMediaType }` identifies the stored bundle.
-- Only available inside a running job step; calling it outside one (for example, during local execution) rejects with a clear error.
+`expandMatrix(matrix)` takes a string array or an object of string arrays and returns all combinations as `MatrixValues[]`. For a single-dimension array, each value becomes `{ value: '...' }`. For multi-dimensional objects, it produces the Cartesian product. Anything else throws a `MatrixShapeError` naming the expected shape; numbers and booleans inside the values are accepted and converted to strings.
 
-See the [build provenance guide](https://docs.kici.dev/user/provenance/) for the end-to-end attest →
-verify → view journey, including how to verify a bundle with `kici verify-attestation`.
+`applyIncludeExclude(values, include?, exclude?)` filters an expanded matrix: removes combinations matching any exclude entry, then appends a key-sorted copy of each include entry that is not already present. Returns the filtered `MatrixValues[]`.
 
-## Secrets
-
-Workflows access secrets through `ctx.secrets` on `StepContext`. Use `await ctx.secrets.get('KEY')` to retrieve a value (rejects with `SecretNotFoundError` if the key is missing, fail-fast on typos), `ctx.secrets.has('KEY')` for a synchronous existence check, and `await ctx.secrets.expose('KEY')` when you need the value as a `process.env` entry for a child process.
+## Dynamic jobs
 
-### Declaring the secret context
+Generate jobs at runtime using async factory functions.
 
-Each job picks its secret context via the `context` option on `job()`. The orchestrator resolves the context's scoped-secret store at dispatch time, evaluates access rules, and sends the decrypted secrets to the agent:
+### DynamicJobFn
 
 ```typescript
-const deploy = job('deploy', {
-  runsOn: 'linux',
-  context: 'production',
-  steps: [
-    /* ... */
-  ],
-});
-
-export default workflow('deploy', {
-  on: push({ branches: 'main' }),
-  jobs: [deploy],
-});
+type DynamicJobFn = (context: DynamicJobContext) => Promise<Job[]>;
 ```
 
-`context` accepts either a static string or an async function `(event) => string | Promise<string>` for dynamic resolution at trigger-evaluation time. The resolved context's secrets are flattened into `ctx.secrets`.
-
-### Accessing secrets (ctx.secrets)
+Receives a `DynamicJobContext`:
 
-`ctx.secrets` provides flat access to the secrets resolved for the job's context.
+| Property | Type                                | Description                 |
+| -------- | ----------------------------------- | --------------------------- |
+| `$`      | zx shell                            | Shell executor              |
+| `ctx`    | `{ workflow, event? }`              | Workflow metadata and event |
+| `log`    | `Logger`                            | Structured logger           |
+| `env`    | `Record<string, string\|undefined>` | Environment variables       |
 
 ```typescript
-step('deploy', async ({ secrets }) => {
-  // get() rejects with SecretNotFoundError if DEPLOY_TOKEN is not found
-  const token = await secrets.get('DEPLOY_TOKEN');
+const discoverJobs: DynamicJobFn = async ({ $ }) => {
+  const result = await $`ls packages/`;
+  const packages = result.stdout.trim().split('\n');
+  return packages.map((pkg) =>
+    job(`test-${pkg}`, {
+      runsOn: 'linux',
+      steps: [
+        step('test', async ({ $ }) => {
+          await $`cd packages/${pkg} && pnpm test`;
+        }),
+      ],
+    }),
+  );
+};
 
-  // Safe check before access (no throw, synchronous)
-  if (secrets.has('OPTIONAL_KEY')) {
-    const optional = await secrets.get('OPTIONAL_KEY');
-  }
+export default workflow('ci', {
+  jobs: [discoverJobs],
 });
 ```
 
-**Throw behavior:** `get()` rejects with `SecretNotFoundError` and the message lists all available keys. This catches typos immediately rather than producing silent `undefined` values.
+### 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:
 
-### Complete example
+- **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, push } from '@kici-dev/sdk';
+import { workflow, job, step, dynamicJob, dynamicGroup, z } from '@kici-dev/sdk';
 
-const deploy = job('deploy', {
+// Upstream job A discovers a list of targets at runtime.
+const discover = job('discover', {
   runsOn: 'linux',
-  environment: 'production',
   steps: [
-    step('deploy', async (ctx) => {
-      const token = await ctx.secrets.get('DEPLOY_TOKEN');
-
-      // Safe check before access
-      if (ctx.secrets.has('OPTIONAL_NOTIFICATION_URL')) {
-        const url = await ctx.secrets.get('OPTIONAL_NOTIFICATION_URL');
-        ctx.log.info('Sending notification...');
-      }
-
-      // Pass to subprocess explicitly (secrets are NOT auto-injected as env vars)
-      await ctx.$`DEPLOY_TOKEN=${token} ./scripts/deploy.sh`;
+    step('emit', {
+      outputs: { targets: z.array(z.string()) },
+      run: async () => ({ targets: ['api', 'web'] }),
     }),
   ],
 });
 
-export default workflow('deploy-production', {
-  on: push({ branches: 'main' }),
-  jobs: [deploy],
+// 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}`),
+      }),
+    );
+  },
 });
-```
-
-### Security notes
-
-- Secrets are **not** automatically injected as environment variables. You must explicitly pass them to subprocesses.
-- All secret values are automatically **masked** in log output. If a step logs a string containing a secret value, the value is replaced with `***`.
-- Secrets flow from the orchestrator to the agent via the authenticated WebSocket channel. The Platform tier never handles secret material.
-
-### Enumerating available keys (ctx.secrets.list)
 
-`ctx.secrets.list()` returns every secret key available to the step, sorted alphabetically. Synchronous, never throws, names only — call `getMeta(key)` to inspect backend / scope per key. Useful when the set of provisioned keys isn't known at workflow-author time, for example to pick up every `AGE_KEY_*` the operator has seeded:
-
-```typescript
-step('discover', async (ctx) => {
-  const ageKeys = ctx.secrets.list().filter((k) => k.startsWith('AGE_KEY_'));
-  ctx.log.info(`Found ${ageKeys.length} age keys`);
-});
+export default workflow('discovery-fan-out', { jobs: [discover, reports] });
 ```
 
-### File-mounted secrets (ctx.secrets.mountFile / exposeFile)
-
-Tools that require a file path on disk (sops `SOPS_AGE_KEY_FILE`, kubectl `KUBECONFIG`, gcloud `GOOGLE_APPLICATION_CREDENTIALS`) get a typed step-side API: `ctx.secrets.mountFile(opts)` writes the concatenation of one or more existing secrets to a per-step tmpfile and returns the path; `ctx.secrets.exposeFile(envVar, opts)` additionally sets `process.env[envVar] = path`. Files are removed and env vars are unset automatically when the step completes (success, failure, or timeout) — no manual cleanup. See [Mounting secrets as files](https://docs.kici.dev/user/secrets/#mounting-secrets-as-files) for the full options table, lifecycle details, and the canonical sops example.
-
-### Local test mode secrets
-
-When running `kici preview`, you can provide secrets locally without an orchestrator.
-
-#### .kici/.secrets file
-
-Create a `.kici/.secrets` file in your project (auto-gitignored by `kici init`):
-
-```ini
-# Flat secrets (before any section)
-DEPLOY_TOKEN=my-deploy-token
-API_KEY=my-api-key
-
-# Context-scoped secrets
-[production]
-DB_PASSWORD=prod-secret
-API_KEY=prod-key
-
-[npm-publish]
-NPM_TOKEN=npm-abc123
-```
+`ctx.needs` shape:
 
-Lines before any `[section]` header are flat secrets. Lines within a section become context-scoped secrets. Comments start with `#`. Values are everything after the first `=` (so values can contain `=` characters).
+| Need form                                           | `ctx.needs[...]` value                                                                                                                                                                                        |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `'jobName'` / `{ name, when }`                      | `{ result, status }` — `result` is an `OutputProxy` (`ctx.needs.<job>.result.<step>.<field>`; single-step `run` jobs flatten to `ctx.needs.<job>.result.<field>`); `status` is the upstream's terminal status |
+| `dynamicGroup('g')` / `dynamicGroup('g', { when })` | ordered array of `{ name, result, status }`, one per group member                                                                                                                                             |
 
-#### CLI flags
+`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()`](https://docs.kici.dev/user/sdk/triggers/) for cross-workflow reactions to a job finishing. See the architecture deep-dive in [dynamic jobs](https://docs.kici.dev/architecture/execution/dynamic-jobs/#result-aware-generation).
 
-Override or supplement file-based secrets with CLI flags:
+### JobOrFactory
 
-```bash
-# Inject flat secrets (repeatable)
-kici preview push --secret DEPLOY_TOKEN=my-token --secret API_KEY=my-key
+The `jobs` array in `WorkflowOptions` accepts both static jobs and dynamic generators:
 
-# Inject context-scoped secrets (repeatable)
-kici preview push --context production.DB_PASSWORD=prod-secret --context npm-publish.NPM_TOKEN=abc123
+```typescript
+type JobOrFactory = Job | DynamicJobFn;
 ```
 
-**Precedence:** CLI flags override `.kici/.secrets` file values. Context secrets are auto-flattened into `ctx.secrets` using the same merge logic as production (last context wins).
-
-## Fixtures
-
-Test fixtures define event replicas for `kici run remote`. They simulate trigger events without requiring real webhooks.
+### isDynamicJobFn(item)
 
-### fixture(id, options)
+Type guard to distinguish static jobs from dynamic generators:
 
 ```typescript
-function fixture(
-  id: string,
-  options: FixtureOptions | (() => FixtureOptions | Promise<FixtureOptions>),
-): Fixture;
+function isDynamicJobFn(item: JobOrFactory): item is DynamicJobFn;
 ```
 
-**Parameters:**
-
-- `id` — unique fixture name (no whitespace). Used in `kici run remote <id>`.
-- `options` — a `FixtureOptions` object, or an async factory function returning one.
-
 ```typescript
-import { fixture, push } from '@kici-dev/sdk';
-
-export const pushMain = fixture('push-main', {
-  event: push({ branches: ['main'] }),
-});
+for (const item of workflow.jobs) {
+  if (isDynamicJobFn(item)) {
+    const generatedJobs = await item(context);
+  } else {
+    // item is Job
+  }
+}
 ```
 
-### FixtureOptions
-
-| Property       | Type                     | Description                                                |
-| -------------- | ------------------------ | ---------------------------------------------------------- |
-| `event`        | `TriggerConfig`          | The trigger event to simulate (required)                   |
-| `branch`       | `string`                 | Override branch name (defaults to git-detected)            |
-| `sha`          | `string`                 | Override commit SHA (defaults to HEAD)                     |
-| `repo`         | `string`                 | Override repository (defaults to git-detected)             |
-| `pr`           | `number`                 | For PR events, override PR number                          |
-| `secrets`      | `Record<string, string>` | Secret context mappings: `{ localName: 'remote-context' }` |
-| `workflowName` | `string`                 | Bypass trigger matching and run this workflow directly     |
-
-Options can also be provided as an async factory function for dynamic fixture generation.
-
 ---
 
 ## SDK reference: triggers
@@ -2934,7 +1400,7 @@ Source: https://docs.kici.dev/user/sdk/triggers/
 
 ## Triggers
 
-Triggers define when a workflow runs. KiCI provides 22 trigger types: 16 GitHub webhook triggers and 6 internal/generic triggers for event routing, scheduling, and non-GitHub sources. Each trigger returns a frozen config object with a unique `_tag` discriminator.
+Triggers define when a workflow runs. KiCI provides 23 trigger types: 16 GitHub webhook triggers and 7 internal/generic triggers for event routing, scheduling, and non-GitHub sources. Each trigger returns a frozen config object with a unique `_tag` discriminator.
 
 All triggers use a config object form -- pass an options object to configure the trigger.
 
@@ -3012,6 +1478,17 @@ push({ branches: ['main', 'develop'], paths: ['src/**'] });
 push({ tags: ['v*'] });
 ```
 
+### Path filter behavior
+
+A `pr()` or `push()` trigger with `paths` matches the event's changed files
+against your patterns. An available list is matched exactly (an event with no
+matching change — including a diff-less branch create or delete — does not run).
+When the diff is **unavailable** (chiefly a universal-git pull-request event,
+whose webhook carries no diff), path filters match **conservatively** so the
+workflow runs rather than being silently dropped, and the delivery is recorded
+as degraded. GitHub always provides an exact list; a transient API error fails
+loudly, not as empty.
+
 ### tag()
 
 Create a tag trigger. Returns a frozen `TagTriggerConfig`.
@@ -3300,7 +1777,7 @@ The orchestrator emits `kici_cross_source_fanout_size` (histogram) per inbound w
 
 ### Event triggers
 
-The following 6 trigger types support internal event routing, scheduling, lifecycle orchestration, and non-GitHub webhook sources.
+The following 7 trigger types support internal event routing, scheduling, lifecycle orchestration, and non-GitHub webhook sources.
 
 ### kiciEvent()
 
@@ -3356,6 +1833,51 @@ workflowComplete({ name: 'CI', status: ['success'] }); // Success only
 workflowComplete({ name: 'CI', status: ['success'], source: 'org/repo' }); // Cross-repo
 ```
 
+### workflowsFailedBatch()
+
+Create a batched failure trigger. Instead of firing once per failed workflow, it accumulates every failed workflow completion over a time window and fires the subscribing workflow **once** with the whole list — so a mass incident (a bad deploy failing hundreds of runs at once) notifies a single time, not once per failure. Returns a frozen `WorkflowsFailedBatchTriggerConfig`.
+
+```typescript
+function workflowsFailedBatch(
+  config: WorkflowsFailedBatchConfigInput,
+): WorkflowsFailedBatchTriggerConfig;
+```
+
+**Config options:**
+
+```typescript
+interface WorkflowsFailedBatchConfigInput {
+  accumulateFor: number; // Accumulation window in milliseconds (opens on the first failure)
+  name?: string; // Filter by failed workflow name
+  source?: string; // Cross-repo source filter
+  description?: string;
+}
+```
+
+The first failure inside the window opens it; when the window closes, the subscribing workflow is dispatched once. The batch is delivered on `ctx.event.payload`:
+
+```typescript
+// ctx.event.payload for a workflowsFailedBatch dispatch:
+// {
+//   total: number,               // total failures in the window
+//   runs: Array<{                // the failed runs (bounded — the first 200)
+//     runId: string;
+//     repo: string;
+//     workflowName: string;
+//     failureClass?: string;     // why the run failed
+//     senderUsername?: string;   // triggering actor, when known
+//   }>,
+// }
+```
+
+```typescript
+workflowsFailedBatch({ accumulateFor: 10000 }); // One notification per 10s burst of failures
+workflowsFailedBatch({ accumulateFor: 30000, name: 'CI' }); // Only CI failures
+workflowsFailedBatch({ accumulateFor: 30000, source: 'org/repo' }); // Cross-repo source filter
+```
+
+A workflow dispatched by a failure trigger (`workflowsFailedBatch`, or `workflowComplete({ status: ['failed'] })`) never re-triggers the same batch on its own failure — a notifier that itself fails cannot loop.
+
 ### jobComplete()
 
 Create a job completion trigger. Fires automatically when a specific job within a workflow finishes. Returns a frozen `JobCompleteTriggerConfig`.
@@ -3447,6 +1969,14 @@ schedule({ cron: '0 9 * * 1', timezone: 'America/New_York' }); // Monday 9am ET
 schedule({ cron: '*/15 * * * *', description: 'health check every 15 min' });
 ```
 
+A workflow may declare **multiple** `schedule()` triggers. Each schedule is
+evaluated and fired independently — a `Monday 9am` schedule and a `Friday 6pm`
+schedule on the same workflow both run at their own times:
+
+```typescript
+on: [schedule({ cron: '0 9 * * 1' }), schedule({ cron: '0 18 * * 5' })];
+```
+
 #### Schedule inputs (defaults-only)
 
 A `schedule()` trigger may declare typed `inputs`. A cron or dashboard
@@ -3621,6 +2151,14 @@ Workflow steps can emit custom events via `ctx.emit()`. Emitted events are deliv
 ### ctx.emit(eventName, payload?, options?)
 
 ```typescript
+// Typed — a defineEvent() definition drives payload type-checking
+emit<T extends z.ZodTypeAny>(
+  definition: EventDefinition<T>,
+  payload: z.infer<T>,
+  options?: EventEmitOptions,
+): Promise<{ deliveryId: string }>;
+
+// Ad-hoc — event name string, payload typed as Record<string, unknown>
 emit(
   eventName: string,
   payload?: Record<string, unknown>,
@@ -3630,17 +2168,30 @@ emit(
 
 **Parameters:**
 
-| Parameter        | Type                      | Required | Description                                   |
-| ---------------- | ------------------------- | -------- | --------------------------------------------- |
-| `eventName`      | `string`                  | yes      | Name of the event to emit                     |
-| `payload`        | `Record<string, unknown>` | no       | Event payload data                            |
-| `options.target` | `{ repos?: string[] }`    | no       | Target specific repos for cross-repo delivery |
+| Parameter        | Type                      | Required | Description                                                                  |
+| ---------------- | ------------------------- | -------- | ---------------------------------------------------------------------------- |
+| `definition`     | `EventDefinition<T>`      | —        | A `defineEvent()` definition; its Zod schema types `payload` as `z.infer<T>` |
+| `eventName`      | `string`                  | yes      | Name of the event to emit                                                    |
+| `payload`        | `Record<string, unknown>` | no       | Event payload data                                                           |
+| `options.target` | `{ repos?: string[] }`    | no       | Target specific repos for cross-repo delivery                                |
 
 **Returns:** `Promise<{ deliveryId: string }>` -- a delivery receipt after the event is persisted and routed.
 
 **Examples:**
 
 ```typescript
+// Typed emit — payload is checked against the deploy-complete schema
+import { defineEvent, z } from '@kici-dev/sdk';
+
+const deployComplete = defineEvent(
+  'deploy-complete',
+  z.object({ env: z.string(), version: z.string() }),
+);
+
+step('notify-typed', async (ctx) => {
+  await ctx.emit(deployComplete, { env: 'prod', version: '1.2.3' });
+});
+
 // Emit a simple event
 step('notify', async (ctx) => {
   await ctx.emit('deploy-complete', { env: 'prod', version: '1.2.3' });
@@ -3690,139 +2241,27 @@ The orchestrator automatically emits system events for workflow and job completi
 
 ---
 
-## SDK reference: waitFor
-
-Source: https://docs.kici.dev/user/sdk/wait-for/
-
-The SDK exposes two wait-for helpers — a generic function `waitFor()` and a step factory `waitForStep()` — for the common case where a workflow step should:
-
-1. **Poll** a condition on a fixed interval.
-2. **Proceed** as soon as the condition is met, optionally running a success action.
-3. **Fail or recover** gracefully when the deadline is exceeded, with an optional timeout action.
-
-Both helpers wrap the same polling loop, so they share semantics and return shape. Pick `waitForStep()` when the wait is the whole job of a step; use `waitFor()` from anywhere — inside a multi-action step, a hook, or a bare async function.
-
-## `waitFor(options)`
-
-Poll `check()` on a fixed interval until it returns a non-null value or the deadline is exceeded. Resolves to a discriminated result describing which outcome occurred.
-
-### Parameters
-
-| Name             | Type                                                                   | Required | Description                                                                                                |
-| ---------------- | ---------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------- |
-| `name`           | `string`                                                               | No       | Label that appears in log lines and in the timeout error. Defaults to `'waitFor'`.                         |
-| `check`          | `() => Promise<TValue \| null>`                                        | Yes      | Polled inspection. Return the resolved value when the condition is met, or `null` to keep polling.         |
-| `intervalMs`     | `number`                                                               | No       | Time between successive `check()` invocations. Defaults to `2000` milliseconds.                            |
-| `timeoutMs`      | `number`                                                               | No       | Total time budget for the wait. Defaults to `60000` milliseconds.                                          |
-| `initialDelayMs` | `number`                                                               | No       | Time to wait before the first `check()` invocation. Defaults to `0`.                                       |
-| `onSuccess`      | `(value: TValue) => Promise<TSuccess>`                                 | No       | Runs once after `check()` returns a non-null value. Its return value is surfaced as `result` on success.   |
-| `onTimeout`      | `(info: { elapsedMs: number; attempts: number }) => Promise<TTimeout>` | No       | Runs when the deadline is exceeded. Its return value is surfaced as `result` on the `'timed-out'` outcome. |
-| `swallowErrors`  | `boolean`                                                              | No       | When `true` (default), errors thrown by `check()` are logged and polling continues.                        |
-| `log`            | `(line: string) => void`                                               | No       | Sink for status lines. Defaults to `console.log`.                                                          |
-
-### Result
-
-`waitFor()` resolves to a discriminated `WaitForResult` union:
-
-| Outcome       | Branch fields                                                                                         |
-| ------------- | ----------------------------------------------------------------------------------------------------- |
-| `'succeeded'` | `value: TValue`, `elapsedMs`, `attempts`, `result: TSuccess` (the `onSuccess` return or `undefined`). |
-| `'timed-out'` | `elapsedMs`, `attempts`, `result: TTimeout` (the `onTimeout` return).                                 |
-
-Narrow on `result.outcome` before reading the branch-specific fields.
-
-When `onTimeout` is **not** supplied, the helper throws a `WaitForTimeoutError` instead of returning a `'timed-out'` result. The error exposes `stepName`, `elapsedMs`, and `attempts` as instance fields so a catch block can branch on them.
-
-### Cancellation and the deadline check
-
-The loop inspects the deadline at the top of each iteration. A `check()` that takes longer than `intervalMs` is not aborted mid-flight; the helper has no `AbortSignal` plumbing. The step's own `timeout` field is the hard kill if the step needs to be interrupted unconditionally.
-
-### Example
-
-```typescript
-import { waitFor } from '@kici-dev/sdk';
-
-const result = await waitFor({
-  name: 'await-build-artifact',
-  check: async () => {
-    const artifact = await registry.findArtifact('myapp', 'v1.2.3');
-    return artifact ?? null;
-  },
-  onSuccess: async (artifact) => ({ digest: artifact.digest }),
-  intervalMs: 5000,
-  timeoutMs: 5 * 60 * 1000,
-});
-
-if (result.outcome === 'succeeded') {
-  console.log(`Artifact ready: ${result.result.digest} (${result.attempts} polls)`);
-} else {
-  console.log(`Gave up after ${result.elapsedMs} ms`);
-}
-```
-
-## `waitForStep(name, options)`
-
-A factory returning an SDK `Step` whose `run` body executes `waitFor(...)` and routes status lines through the step's structured logger.
-
-### Parameters
-
-| Name      | Type                                    | Required | Description                                                                                         |
-| --------- | --------------------------------------- | -------- | --------------------------------------------------------------------------------------------------- |
-| `name`    | `string`                                | Yes      | Step name. Appears in the run timeline and in log lines.                                            |
-| `options` | `Omit<WaitForOptions, 'name' \| 'log'>` | Yes      | Same shape as `waitFor()` minus `name` (already provided) and `log` (provided by the step context). |
-
-### Result
-
-`waitForStep(...)` returns `Step<WaitForResult<TValue, TSuccess, TTimeout>>`. Other steps can consume the result through the standard step output mechanisms.
-
-### Example
-
-```typescript
-import { waitForStep, job } from '@kici-dev/sdk';
-
-const awaitMarker = waitForStep('await-marker', {
-  check: async () => {
-    const stat = await tryStatMarker('/tmp/build-ready');
-    return stat ? { path: '/tmp/build-ready' } : null;
-  },
-  intervalMs: 1000,
-  timeoutMs: 60_000,
-  onTimeout: async ({ attempts }) => ({ aborted: true, attempts }),
-});
-
-export const release = job('release', {
-  runsOn: 'linux',
-  steps: [awaitMarker],
-});
-```
-
-If `check()` throws while polling, the error is logged and polling continues — the default `swallowErrors: true` matches the "poll until healthy" pattern. Pass `swallowErrors: false` to fail fast on the first error instead.
-
-## See also
-
-- [Core SDK reference](https://docs.kici.dev/user/sdk/core/) — the `step()`, `job()`, and `workflow()` factories that `waitForStep()` builds on.
-- [Idempotent helpers](https://docs.kici.dev/user/sdk/idempotent/) — `idempotent()` and `idempotentStep()` for check / apply patterns.
-- [Runtime types](https://docs.kici.dev/user/sdk/runtime/) — `StepContext`, `Logger`, and other surface used inside the helpers.
-
----
-
 ## SDK reference
 
 Source: https://docs.kici.dev/user/sdk-reference/
 
 Reference documentation for `@kici-dev/sdk`. The reference is split across the per-topic pages below.
 
-| Page                                                         | Covers                                                                                                                                                                                                                      |
-| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [Core](https://docs.kici.dev/user/sdk/core/)                                        | `workflow()`, `job()`, `step()` factory functions and step / job authoring patterns (bare functions, output chaining, `needs`, dynamic groups).                                                                             |
-| [Triggers](https://docs.kici.dev/user/sdk/triggers/)                                | All 22 trigger factories -- GitHub events (`pr`, `push`, `tag`, `comment`, ...), event triggers (`kiciEvent`, `workflowComplete`, `jobComplete`), `genericWebhook`, `schedule`, `lifecycle`, plus branch-pattern semantics. |
-| [Rules, matrix, dynamic jobs](https://docs.kici.dev/user/sdk/rules-matrix-dynamic/) | `rule()`, `skip()`, matrix builds (static + dynamic), and `dynamicJob()` / `dynamicGroup()`.                                                                                                                                |
-| [Caching](https://docs.kici.dev/user/sdk/caching/)                                  | `CacheSpec`, declarative `cache` on jobs/steps, imperative `ctx.cache.restore()` / `ctx.cache.save()`, immutable keys, `restoreKeys` prefix fallback, per-org + per-ref isolation.                                          |
-| [Validation & events](https://docs.kici.dev/user/sdk/validation-events/)            | `validateDag()`, `defineEvent()`, event emission patterns.                                                                                                                                                                  |
-| [Runtime](https://docs.kici.dev/user/sdk/runtime/)                                  | Types index, `StepContext`, secrets, and fixtures.                                                                                                                                                                          |
-| [Idempotent helpers](https://docs.kici.dev/user/sdk/idempotent/)                    | `idempotent()`, `idempotentStep()`, and the check-mode-aware `checkStep()` — check / apply pattern with typed results on both the skipped and applied branches.                                                             |
-| [Wait-for helpers](https://docs.kici.dev/user/sdk/wait-for/)                        | `waitFor()` and `waitForStep()` — poll a condition on an interval, run an optional success action, recover gracefully on timeout.                                                                                           |
-| [Parallel steps](https://docs.kici.dev/user/sdk/parallel/)                          | `parallel()` — run independent steps concurrently within one job behind a join barrier, each as its own observable step, with `failFast` and `maxParallel` controls.                                                        |
+| Page                                                         | Covers                                                                                                                                                                                                                                              |
+| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Core](https://docs.kici.dev/user/sdk/core/)                                        | `workflow()`, `job()`, `step()` factory functions and step / job authoring patterns (bare functions, output chaining, `needs`, dynamic groups).                                                                                                     |
+| [Triggers](https://docs.kici.dev/user/sdk/triggers/)                                | All 23 trigger factories -- GitHub events (`pr`, `push`, `tag`, `comment`, ...), event triggers (`kiciEvent`, `workflowComplete`, `workflowsFailedBatch`, `jobComplete`), `genericWebhook`, `schedule`, `lifecycle`, plus branch-pattern semantics. |
+| [Rules, matrix, dynamic jobs](https://docs.kici.dev/user/sdk/rules-matrix-dynamic/) | `rule()`, `skip()`, matrix builds (static + dynamic), and `dynamicJob()` / `dynamicGroup()`.                                                                                                                                                        |
+| [runsOnAll host fan-out](https://docs.kici.dev/user/sdk/runs-on-all/)               | `runsOnAll` — fan one job out to every matching connected host, one pinned execution per host, with exact / glob / regex host selectors.                                                                                                            |
+| [Caching](https://docs.kici.dev/user/sdk/caching/)                                  | `CacheSpec`, declarative `cache` on jobs/steps, imperative `ctx.cache.restore()` / `ctx.cache.save()`, immutable keys, `restoreKeys` prefix fallback, per-org + per-ref isolation.                                                                  |
+| [Artifacts](https://docs.kici.dev/user/sdk/artifacts/)                              | `ctx.artifacts` — share named, durable build outputs between jobs of a run and download them from the run page.                                                                                                                                     |
+| [Validation & events](https://docs.kici.dev/user/sdk/validation-events/)            | `validateDag()`, `defineEvent()`, event emission patterns.                                                                                                                                                                                          |
+| [Runtime](https://docs.kici.dev/user/sdk/runtime/)                                  | Types index, `StepContext`, secrets, and fixtures.                                                                                                                                                                                                  |
+| [Temp directories](https://docs.kici.dev/user/sdk/temp-directories/)                | `ctx.mktemp()` / `ctx.mktempFile()` — allocate job-scoped scratch dirs and files that are cleaned up automatically when the job ends.                                                                                                               |
+| [Event payload reference](https://docs.kici.dev/user/sdk/event-payloads/)           | Generated schema of the normalized event envelope passed to rules and dynamic functions.                                                                                                                                                            |
+| [Idempotent helpers](https://docs.kici.dev/user/sdk/idempotent/)                    | `idempotent()`, `idempotentStep()`, and the check-mode-aware `checkStep()` — check / apply pattern with typed results on both the skipped and applied branches.                                                                                     |
+| [Wait-for helpers](https://docs.kici.dev/user/sdk/wait-for/)                        | `waitFor()` and `waitForStep()` — poll a condition on an interval, run an optional success action, recover gracefully on timeout.                                                                                                                   |
+| [Parallel steps](https://docs.kici.dev/user/sdk/parallel/)                          | `parallel()` — run independent steps concurrently within one job behind a join barrier, each as its own observable step, with `failFast` and `maxParallel` controls.                                                                                |
 
 The `@kici-dev/sdk` package re-exports the entire surface from a single entry point. Pick what you need:
 
@@ -3839,6 +2278,6 @@ For the complete list of every named export (factory functions, triggers, rules,
 - [Workflow patterns](https://docs.kici.dev/user/workflow-patterns/) -- common patterns using the SDK features documented above
 - [Secrets management (operator)](https://docs.kici.dev/operator/security/secrets/) -- configure encrypted secret storage and admin API
 - [Secrets architecture](https://docs.kici.dev/architecture/security/secrets/) -- encryption model, multi-backend, and data flow
-- [State machine](https://docs.kici.dev/architecture/execution/state-machine/) -- how execution states map to the lifecycle of jobs and steps
+- [Execution status vocabulary](https://docs.kici.dev/architecture/execution/state-machine/) -- run/job/step statuses and terminal states
 
 ---