@kici-dev/compiler 0.1.22 → 0.1.23

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

@@ -0,0 +1,3725 @@
+# KiCI SDK reference
+
+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
+
+---
+
+## SDK reference: core
+
+Source: https://docs.kici.dev/user/sdk/core/
+
+## Factory functions
+
+### workflow(name, options)
+
+Create a workflow containing jobs.
+
+```typescript
+function workflow(name: string, options: WorkflowOptions): Workflow;
+```
+
+**Parameters:**
+
+| Parameter             | Type                                                                   | Required | Description                                                                                                                                                 |
+| --------------------- | ---------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`                | `string`                                                               | yes      | Unique workflow name                                                                                                                                        |
+| `options.jobs`        | `JobOrFactory[]`                                                       | yes      | Static jobs and/or dynamic job generators                                                                                                                   |
+| `options.on`          | `Trigger \| Trigger[]`                                                 | no       | When the workflow should trigger                                                                                                                            |
+| `options.rules`       | `Rule[]`                                                               | no       | Conditions that must pass for execution                                                                                                                     |
+| `options.description` | `string`                                                               | no       | Human-readable description                                                                                                                                  |
+| `options.hashFiles`   | `string[]`                                                             | no       | Extra repo-relative paths or globs mixed into the workflow content hash. Changes invalidate the source cache.                                               |
+| `options.registries`  | `Registry[]`                                                           | no       | Private npm registries the agent authenticates against before `npm install`. Each `tokenSecret` uses qualified `<environment>:<secret>` syntax.             |
+| `options.installEnv`  | `string[]`                                                             | no       | Qualified `<environment>:<secret>` refs projected as env vars onto the install subprocess (used with a customer-committed `.kici/.npmrc`).                  |
+| `options.onCancel`    | `HookInput`                                                            | no       | Runs when the workflow is cancelled                                                                                                                         |
+| `options.cleanup`     | `HookInput`                                                            | no       | Always runs after the workflow (success, failure, or cancel)                                                                                                |
+| `options.onSuccess`   | `HookInput`                                                            | no       | Runs on workflow success                                                                                                                                    |
+| `options.onFailure`   | `HookInput`                                                            | no       | Runs on workflow failure                                                                                                                                    |
+| `options.concurrency` | `{ group: (ctx) => string; cancelInProgress?: boolean; max?: number }` | no       | Workflow-scoped concurrency. See [Concurrency](https://docs.kici.dev/user/concurrency/).                                                                                          |
+| `options.timeout`     | `number`                                                               | no       | Whole-run wall-clock timeout in milliseconds across all jobs. On breach the orchestrator cancels the run and marks it timed out. See [Timeouts](https://docs.kici.dev/user/sdk/core/#timeouts). |
+
+**Returns:** `Workflow` -- an immutable workflow definition.
+
+```typescript
+export default workflow('ci', {
+  on: [pr({ target: 'main' }), push({ branches: 'main' })],
+  rules: [rule('has source changes')],
+  jobs: [lint, test, deploy],
+  description: 'Main CI pipeline',
+});
+```
+
+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.
+
+### job(name, options) / job(options)
+
+Create a job with an explicit name or auto-generated ID.
+
+```typescript
+function job(name: string, options: JobOptions): Job;
+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. |
+
+**Returns:** `Job` -- an immutable job definition.
+
+```typescript
+// Named job
+const build = job('build', {
+  runsOn: 'linux',
+  steps: [checkout, install, compile],
+  needs: [lint],
+});
+
+// Anonymous job (auto-generated UUID name)
+const build = job({
+  runsOn: 'linux',
+  steps: [checkout, install],
+});
+```
+
+#### runsOn forms
+
+A job's `runsOn` selects which agents may run it. Every label listed must be present on the agent (a subset match). It accepts three forms, and each label can be an exact string, a glob, or a regular expression (see [Targeting by pattern](https://docs.kici.dev/user/sdk/core/#targeting-by-pattern) below):
+
+```typescript
+// 1. Simple string -- agent must have this label
+runsOn: 'kici:os:linux'
+
+// 2. Array of required labels -- agent must have ALL labels
+runsOn: ['kici:os:linux', 'gpu']
+
+// 3. Object form with exclusions -- agent must have ALL required labels
+//    and NONE of the excluded labels
+runsOn: { labels: ['kici:os:linux'], exclude: ['kici:host:box-01'] }
+```
+
+**The label model:**
+
+- Every agent automatically reports `kici:os:<platform>`, `kici:arch:<cpu>`, and `kici:host:<hostname>`, so `runsOn: 'kici:os:linux'` targets any connected Linux agent without configuring labels — a fresh `kici init` matches out of the box.
+- Use **custom labels** (e.g. `'gpu'`, `'prod-pool'`) — defined in your scaler's `labelSet` — to target a specific agent pool.
+- You can also target scaler-assigned labels (`kici:agent:<backend>`, `kici:scaler:<name>`), but those names are deployment-specific, so custom labels are more portable.
+- `runsOn` is a _requirement_ on candidate agents, never a _grant_: targeting a label only narrows the candidate set. Users cannot _set_ `kici:` labels on agents — that namespace is reserved for the scaler and the agent's self-reported platform facts — but they may freely _target_ any label in `runsOn`.
+
+**Semantics:**
+
+- **Required labels:** The agent must have every label in the `labels` array (or the string/array form).
+- **Excluded labels:** The agent must NOT have any label in the `exclude` array. This includes auto-derived labels like `kici:arch:arm64`, `kici:os:linux`, etc.
+- **Compile-time validation:** The compiler will error if any label appears in both `labels` and `exclude` (overlap detection).
+- **Operator-declared mandatory labels:** Operators may mark a scaler with `mandatoryLabels` (Kubernetes-taint-style opt-in). When a scaler declares a mandatory label, a job is only allowed to land on it if `runsOn.labels` includes that label. A workflow targeting such a scaler must explicitly list the mandatory label in `runsOn`. See the [auto-scaler mandatory labels](https://docs.kici.dev/operator/orchestrator/auto-scaler/common-config/#mandatory--exclude-labels) for details.
+
+```typescript
+// Route to any Linux agent that does NOT have the 'gpu' label
+const build = job('build', {
+  runsOn: { labels: ['linux'], exclude: ['gpu'] },
+  steps: [checkout, compile],
+});
+
+// Route to arm64 Linux agents, excluding those with 'staging' label
+const deploy = job('deploy', {
+  runsOn: { labels: ['linux', 'arch:arm64'], exclude: ['staging'] },
+  steps: [deployStep],
+});
+```
+
+#### Single-host selection: `pick`
+
+When more than one agent matches a `runsOn` selector, the object form's `pick`
+field controls **which** one runs the job:
+
+```typescript
+// Always the same host across re-runs (default — can be omitted)
+runsOn: { labels: ['role:db'], pick: 'deterministic' }
+
+// Any available host (load spread)
+runsOn: { labels: ['role:db'], pick: 'any' }
+```
+
+- **`'deterministic'` (the default)** — the orchestrator sorts the matching
+  agents by their agent id and picks the lowest. A job that must run exactly
+  once on one stable host — a database migration, a backup dump — lands on the
+  **same** host every run. The string and array shorthand forms
+  (`runsOn: 'role:db'`, `runsOn: ['role:db', 'linux']`) inherit this default.
+- **`'any'`** — pick any available matching agent. Use this for jobs that don't
+  need a stable host and benefit from spreading load across an equivalent pool.
+
+**Trade-off:** `'deterministic'` can hot-spot — if many jobs target the same
+label set, they all pin to the same lowest-id agent. Use `'any'` to spread those
+across the pool; keep `'deterministic'` when reproducibility matters more than
+balance. (`pick` selects among **single-agent** candidates; to fan a job out to
+**every** matching host, use [`runsOnAll`](https://docs.kici.dev/user/sdk/runs-on-all/) instead.)
+
+#### Targeting by pattern
+
+Every selector element — in `runsOn`, in `runsOnAll`, on both the include and the exclude side — can be a plain string, a glob pattern, or a regular expression. KiCI picks the matching mode from the value itself:
+
+- **Plain string → exact match.** `'kici:os:linux'` matches the label `kici:os:linux` and nothing else.
+- **String with glob metacharacters (`*`, `?`, `[]`, `{}`) → glob.** `'kici:host:web-*'` matches every host label starting with `kici:host:web-`. `'kici:host:box-0[1-3]'` matches `box-01`, `box-02`, `box-03`.
+- **`RegExp` literal → regular expression.** `/kici:host:box-0[1-3]/` matches any label the expression matches.
+
+Both the required (include) side and the excluded side accept all three forms:
+
+```typescript
+// Glob include + regex exclude, single-agent targeting.
+const build = job('build', {
+  runsOn: { labels: ['kici:os:linux', 'kici:host:web-*'], exclude: [/.*-canary$/] },
+  steps: [compile],
+});
+
+// A bare regex picks any agent whose label the expression matches.
+const probe = job('probe', {
+  runsOn: /kici:host:box-0[1-3]/,
+  steps: [smoke],
+});
+```
+
+In the `runsOnAll` array form, a leading `!` still routes an entry to the exclude side. The `!` is stripped **before** the matching mode is decided, so `'!kici:host:box-*'` is an exclude **glob** and `'!box-01'` an exclude **exact** match. Regular-expression exclusions use the structured `exclude: [/…/]` form (a `RegExp` cannot carry a `!` prefix). The structured `runsOnAll` form below targets every Linux host in the `db` or `replica` role except those whose hostname ends in `-canary`:
+
+```typescript
+const fanout = job('deploy', {
+  runsOnAll: {
+    include: [{ all: ['kici:os:linux', 'kici:host:web-*'] }],
+    exclude: [/.*-canary$/],
+  },
+  run: async (ctx) => {
+    /* runs once per matched host */
+  },
+});
+```
+
+**Edge case — custom labels that contain glob metacharacters.** Because the matching mode is inferred from the value, a custom label that literally contains `*`, `?`, `[]`, or `{}` is always treated as a glob and can no longer be matched exactly. Avoid glob metacharacters in label names you intend to target by exact string.
+
+**ReDoS protection.** Glob patterns are linear by construction. A regular expression you supply is validated for catastrophic-backtracking (ReDoS) when you run `kici compile` — a pattern that could hang on a crafted input is rejected with an error, so it never reaches the orchestrator. The orchestrator re-validates every pattern when it loads the lock file.
+
+### step(name, run) / step(name, options)
+
+Create a step with a run function or with typed outputs.
+
+```typescript
+// Simple form (no outputs)
+function step(name: string, run: StepRunFn): Step;
+
+// Full form (with outputs)
+function step<TOutputs extends OutputSchema>(
+  name: string,
+  options: StepOptions<TOutputs>,
+): Step<TOutputs>;
+```
+
+**Simple form:**
+
+```typescript
+const checkout = step('checkout', async ({ $ }) => {
+  await $`git checkout`;
+});
+```
+
+**With typed outputs:**
+
+```typescript
+import { z } from 'zod';
+
+const build = step('build', {
+  outputs: {
+    version: z.string(),
+    artifacts: z.array(z.string()),
+  },
+  run: async ({ $ }) => {
+    await $`pnpm build`;
+    return { version: '1.0.0', artifacts: ['dist/main.js'] };
+  },
+});
+```
+
+**StepRunFn type:** `(ctx: StepContext) => Promise<void>`
+
+**With a check facet (idempotent step):**
+
+Add a `check` function to describe _desired state_ instead of a fixed action. When
+`check` is present, `run` becomes the _apply_ function and receives the drift value
+`check` returned; `summarize` (required) renders that drift for logs and the
+dashboard; `whenInSync` optionally produces the step's outputs when already in sync.
+
+```typescript
+const configureNginx = step('configure-nginx', {
+  check: async (ctx) => ((await inSync(ctx)) ? null : { want: DESIRED }),
+  summarize: (drift) => `would rewrite nginx.conf (${drift.want.length} bytes)`,
+  run: async (ctx, drift) => {
+    await writeConfig(drift.want);
+    return { reloaded: true };
+  },
+  whenInSync: async () => ({ reloaded: false }),
+});
+```
+
+A checked step can run in apply mode (converge) or `--check` preview mode (report
+drift, change nothing). See [Idempotent steps and check mode](https://docs.kici.dev/user/idempotent-steps/).
+
+### Per-job resources
+
+`options.resources` declares the CPU and memory the job needs. The orchestrator's auto-scaler uses these numbers to:
+
+1. **Bill against capacity caps** (`request`). Decides whether the job can be admitted under the per-scaler `maxAgents`, per-scaler `resourceCap`, orchestrator-wide `globalResourceCap`, and machine-pool caps.
+2. **Enforce kernel limits** (`limit`). Sets the cgroup `memory.max` and CPU quota on the running container / VM / scope.
+
+The shape mirrors Kubernetes:
+
+```typescript
+const heavy = job('build', {
+  runsOn: 'linux',
+  resources: {
+    requests: { memory: '2g', cpus: 1 },
+    limits: { memory: '4g', cpus: 2 },
+  },
+  steps: [...],
+});
+```
+
+Three input shapes are accepted; all normalise to the same `{ requests, limits }` pair:
+
+| Shape          | Example                                                    | Effective behavior                               |
+| -------------- | ---------------------------------------------------------- | ------------------------------------------------ |
+| Both           | `{ requests: { memory: '2g' }, limits: { memory: '4g' } }` | Used as-is                                       |
+| Request only   | `{ requests: { memory: '2g' } }`                           | `limits` mirrors the request                     |
+| Limit only     | `{ limits: { memory: '4g' } }`                             | `requests` mirrors the limit                     |
+| Flat shorthand | `{ memory: '2g', cpus: 1 }`                                | Both `requests` and `limits` set to these values |
+
+Memory accepts container-style suffixes: `512m`, `4g`, `2048k`. CPUs are fractional cores (`0.5`, `2`).
+
+If `resources` is omitted, the job inherits the matched scaler's label-set or default resources (configured by the operator in `scalers.yaml`). This keeps existing workflows behaving as they did before per-job resources existed.
+
+Per-backend kernel enforcement of `limits`:
+
+- **Container backend** (Docker / Podman): always enforced via cgroup.
+- **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 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.
+
+```typescript
+import { workflow, job, step, push } from '@kici-dev/sdk';
+
+export const build = workflow('build', {
+  on: [push()],
+  jobs: [
+    job('build', {
+      runsOn: 'linux',
+      init: {
+        run: `
+          set -euo pipefail
+          command -v mise >/dev/null || curl -fsSL https://mise.run | sh
+          export PATH="$HOME/.local/bin:$PATH"
+          mise install
+          mise env -s bash | sed -n 's/^export //p' >> "$KICI_ENV"
+          echo "$HOME/.local/share/mise/shims" >> "$KICI_PATH"
+        `,
+        cache: { key: 'mise-jq-1.7.1', paths: ['~/.local/share/mise'] },
+        timeout: 600_000,
+      },
+      steps: [
+        step('show-jq-version', async (ctx) => {
+          // jq is on PATH because the init phase appended the mise shims dir to $KICI_PATH.
+          const { stdout } = await ctx.$`jq --version`;
+          ctx.log.info(`jq version: ${stdout.trim()}`);
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+**`GenericInitConfig` shape:**
+
+| Field     | Type                    | Required | Description                                                                                                                                    |
+| --------- | ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `run`     | `string`                | yes      | Command run after clone, before steps. Runs in the job's sandbox at the clone root. Must be a non-empty command.                               |
+| `shell`   | `string`                | no       | Shell used to run `run`. Defaults to `bash`.                                                                                                   |
+| `cache`   | `CacheSpec`             | no       | Cache spec for binaries the command installs -- restored before the command, saved after on a key miss. See [Caching](https://docs.kici.dev/user/sdk/caching/).           |
+| `timeout` | `number`                | no       | Max wall-clock for this init command in milliseconds. Defaults to 10 minutes. On breach the init is aborted and the job is reported timed out. |
+| `env`     | `Record<string,string>` | no       | Static environment variables available to the command.                                                                                         |
+
+**The `$KICI_ENV` / `$KICI_PATH` handoff.** The init command does not mutate the step environment directly. Instead it writes what it wants visible to later steps to two files the agent allocates and exposes as environment variables:
+
+- **`$KICI_ENV`** -- append one `KEY=value` line per environment variable. The agent reads the file after the command and makes each variable available to every subsequent step.
+- **`$KICI_PATH`** -- append one directory per line. The agent prepends each directory to `PATH` for every subsequent step.
+
+The agent reads both files after the command succeeds, applies the delta, and the resulting environment is visible to all steps that follow (and to any later init command).
+
+**Failure before steps.** If the init command exits non-zero or exceeds its `timeout`, the job **fails before any step runs** -- the init surfaces as a failed `init:<n>` pseudo-step in the run timeline (alongside the step list), its logs are attached, and the step loop never executes. This makes a broken toolchain a clear, early failure rather than a confusing mid-run error.
+
+**Arrays run in order.** Passing `GenericInitConfig[]` runs the inits sequentially; each one's `$KICI_ENV` / `$KICI_PATH` delta is applied before the next runs, so a later init sees an earlier init's tools on `PATH`. The first init to fail stops the sequence and fails the job.
+
+**`init: false`** is an explicit opt-out; it behaves the same as omitting `init`.
+
+#### Toolchain presets
+
+For the common case, a typed preset removes the hand-written `run` block entirely. The agent expands the preset to the same generic init it would otherwise run.
+
+- **`init: 'mise'`** -- zero-config. Installs mise, trusts and runs `mise install` against the committed mise config (`mise.toml` / `.mise.toml` / `.tool-versions`), hands mise's env + shims dir to subsequent steps, and caches mise's data dir under a key derived from the committed config (so a config change rotates the cache). The committed config is trusted automatically — committing it to your repo is the trust signal.
+- **`init: { mise: { cache, timeout, env, shell } }`** -- the same preset with overrides. These tune the generic fields a hand-written init exposes (minus `run`): `cache: false` disables caching, a `CacheSpec` replaces the default key/paths, and `timeout` / `env` / `shell` map straight through. `init: 'mise'` is exactly `init: { mise: {} }`.
+
+```typescript
+const build = job('build', {
+  runsOn: 'linux',
+  init: 'mise', // committed mise.toml pins the toolchain; jq, node, etc. land on PATH
+  steps: [
+    step('show-jq-version', async (ctx) => {
+      const { stdout } = await ctx.$`jq --version`;
+      ctx.log.info(`jq version: ${stdout.trim()}`);
+    }),
+  ],
+});
+```
+
+#### Auto-detect (`init: 'auto'`)
+
+**`init: 'auto'`** detects the toolchain from committed files instead of naming a preset. The agent scans the clone root and selects a preset when a marker is present: `mise.toml` / `.mise.toml` / `.tool-versions` -> the mise preset. With no markers found, `'auto'` is a logged no-op.
+
+`'auto'` is opt-in: an **unset** `init` does nothing even when the repo carries a `mise.toml` for local development. Use `'auto'` to enable detection and `false` to keep the explicit opt-out.
+
+#### Cross-platform
+
+The mise preset works on Linux, macOS, and Windows. On Linux and macOS mise is installed via its standalone install script; on Windows it is installed from its standalone GitHub release. The resulting toolchain reaches every step the same way on all three. On Windows the standalone mise binary requires the Microsoft Visual C++ runtime (`vc_redist.x64`) to be present on the agent host — install it once when provisioning a Windows agent that uses the mise preset.
+
+## Step & job authoring patterns
+
+KiCI supports several authoring patterns for steps and jobs to reduce boilerplate and improve developer experience.
+
+### Bare function steps
+
+Async functions are accepted directly in a job's `steps` array without wrapping in `step()`. They receive auto-generated counter names (`step-1`, `step-2`) at compile time. Return values are captured at runtime.
+
+```typescript
+const myJob = job('example', {
+  runsOn: 'default',
+  steps: [
+    async (ctx) => {
+      ctx.log.info('hello from bare function');
+    },
+    step('named', async (ctx) => {
+      // Named steps keep their explicit name
+    }),
+    async (ctx) => {
+      // This becomes step-2 (counter skips named steps)
+      return { value: 42 };
+    },
+  ],
+});
+```
+
+### Id-less steps and jobs
+
+Steps and jobs can be created without a name. The compiler assigns counter-based IDs at compile time.
+
+**Id-less steps:**
+
+```typescript
+// Id-less step with just a function
+const s = step(async (ctx) => {
+  await ctx.$`echo hello`;
+});
+
+// Id-less step with full options
+const s = step({
+  run: async (ctx) => {
+    return { version: '1.0.0' };
+  },
+  timeout: 60000,
+});
+```
+
+**Id-less jobs:**
+
+```typescript
+const deploy = job({
+  runsOn: 'default',
+  steps: [step('deploy', async (ctx) => { ... })],
+});
+// deploy.name is a UUID at definition time, replaced with job-1 at compile time
+```
+
+### Step output types
+
+Steps have three output tiers:
+
+| Tier | Syntax                         | Naming           | TypeScript Type       | Zod Validation |
+| ---- | ------------------------------ | ---------------- | --------------------- | -------------- |
+| 1    | Bare function                  | Auto (`step-N`)  | Inferred return type  | No             |
+| 2    | `step(name, fn)` or `step(fn)` | Explicit or auto | Inferred return type  | No             |
+| 3    | `step(name, { outputs, run })` | Explicit or auto | Inferred + Zod schema | Yes (runtime)  |
+
+```typescript
+import { z } from '@kici-dev/sdk';
+
+// Tier 3: step with Zod outputs (validated at runtime)
+const build = step('build', {
+  outputs: {
+    version: z.string(),
+    artifact: z.string(),
+  },
+  run: async (ctx) => {
+    return { version: '2.0.0', artifact: 'dist/main.js' };
+  },
+});
+```
+
+### Single-step job shorthand
+
+Use the `run` property as an alternative to `steps` for jobs with a single step:
+
+```typescript
+const deploy = job('deploy', {
+  runsOn: 'default',
+  run: async (ctx) => {
+    ctx.log.info('Deploying...');
+    return { url: 'https://app.example.com' };
+  },
+});
+```
+
+The `run` function is stored as the job's only step with an auto-generated name (`step-1`). `run` and `steps` are mutually exclusive -- providing both throws an error.
+
+### Timeouts
+
+`timeout` (milliseconds) can be set at three levels. Each level caps **its own scope** independently — a workflow or job timeout is a separate wall-clock cap, **not** a default that flows down to steps.
+
+| Level        | Field                        | Caps                                                   | Enforced by      | On breach                                                         |
+| ------------ | ---------------------------- | ------------------------------------------------------ | ---------------- | ----------------------------------------------------------------- |
+| **step**     | `step(..., { timeout })`     | A single step's wall-clock.                            | the agent        | The step fails; falls back to the 30-minute default when unset.   |
+| **job**      | `job(..., { timeout })`      | The job's total wall-clock (init + all steps + hooks). | the agent        | The job is aborted and reported failed with a "timed out" reason. |
+| **workflow** | `workflow(..., { timeout })` | The whole run's wall-clock across all jobs.            | the orchestrator | The run is cancelled with a "timed out" reason.                   |
+
+```typescript
+export default workflow('ci', {
+  timeout: 1_800_000, // whole run must finish within 30 minutes
+  jobs: [
+    job('build', {
+      runsOn: 'linux',
+      timeout: 600_000, // this job (init + steps + hooks) within 10 minutes
+      steps: [
+        step('compile', {
+          timeout: 120_000, // this single step within 2 minutes
+          run: async (ctx) => {
+            await ctx.$`make build`;
+          },
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+**Precedence — each scope caps its own scope.** The three timeouts are independent caps, not a fallback chain:
+
+- A **step** with no `timeout` falls back to the 30-minute agent default, regardless of the job or workflow timeout. A job timeout never becomes a step's default.
+- A **job** `timeout` bounds the job's total wall-clock (its init, every step including their own per-step timeouts, and its hooks). It does not change any step's individual cap.
+- A **workflow** `timeout` is a run-level deadline. The orchestrator records it when the run starts and cancels the run if its wall-clock exceeds the timeout, even when individual jobs and steps are still within their own caps.
+
+Workflow and job timeouts surface with a distinct "timed out" reason so the dashboard labels the run or job as timed out rather than a generic failure or cancel.
+
+### Retries
+
+A step can declare a `retry` policy so a thrown attempt is re-run automatically instead of failing the job on the first error. Use it for genuinely transient failures — a flaky network call, an occasional 503, a dependency that is briefly not ready.
+
+```typescript
+step('publish', {
+  retry: 3, // shorthand for { maxAttempts: 3 } with the defaults below
+  run: async (ctx) => {
+    await ctx.$`pnpm publish`;
+  },
+});
+
+step('fetch-token', {
+  retry: {
+    maxAttempts: 5, // total attempts including the first; must be >= 1
+    delayMs: 500, // base delay between attempts (default 1000)
+    backoff: 'exponential', // 'exponential' (default) or 'fixed'
+    maxDelayMs: 30_000, // cap for exponential growth (default 30000)
+    retryIf: (err) => err instanceof TransientError, // default: retry on any throw
+  },
+  run: async (ctx) => {
+    await fetchToken();
+  },
+});
+```
+
+- **`retry: N`** is shorthand for `{ maxAttempts: N }` with all defaults applied.
+- **Defaults:** `delayMs: 1000`, `backoff: 'exponential'`, `maxDelayMs: 30000`, and "retry on any throw" when no `retryIf` is given.
+- **Backoff.** With `'exponential'`, the wait after the `n`-th attempt (1-based) is `min(delayMs * 2 ** (n - 1), maxDelayMs)` — 1s, 2s, 4s, … capped at `maxDelayMs`. With `'fixed'`, the wait is always `delayMs`.
+- **`retryIf(err)`** runs against the thrown error before each retry; return `false` to stop retrying immediately and let the failure stand.
+- **Timeout is per-attempt.** Each attempt gets the step's full `timeout` budget — a timed-out attempt counts as one failed attempt and is retried while attempts remain. The total wall-clock can therefore approach `maxAttempts * (timeout + delay)`, so keep `maxAttempts` and `maxDelayMs` sane (the job-level `timeout` still bounds the whole job).
+- **Retries exhaust before `continueOnError`.** A step with both retries first; only the _final_ failure is then softened to a warning by `continueOnError`.
+
+`retry` works identically under `kici run local` and on a remote agent, and applies to dynamically-generated job steps too. The `retryIf` predicate is an in-memory function: it is honored at execution time but never serialized into the lock file.
+
+> **Retry vs. wait-until-condition.** `retry` re-runs a step that _throws_. To poll until a condition becomes true (a port listening, a `/health` endpoint returning 200, a unit becoming active), use [`waitForStep`](https://docs.kici.dev/user/sdk/wait-for/) instead — it is purpose-built for declarative wait-for-condition with intervals, a timeout, and on-timeout handling.
+
+### Output chaining
+
+Steps and jobs can access outputs from preceding steps/jobs using two patterns.
+
+**Within-job output chaining:**
+
+```typescript
+const buildStep = step('build', async (ctx) => {
+  return { version: '2.0.0' };
+});
+
+const lint = async (ctx) => {
+  return { warnings: 0 };
+};
+
+const pipeline = job('pipeline', {
+  runsOn: 'default',
+  steps: [
+    buildStep,
+    lint,
+    step(async (ctx) => {
+      // Pattern 1: .result proxy on Step objects
+      const version = buildStep.result.version;
+
+      // Pattern 2: ctx.outputsOf() for Step or bare function references
+      const lintOutputs = ctx.outputsOf(lint);
+      console.log(lintOutputs.warnings); // 0
+    }),
+  ],
+});
+```
+
+**Cross-job output chaining:**
+
+```typescript
+const setup = job('setup', {
+  runsOn: 'default',
+  run: async (ctx) => {
+    return { env: 'production' };
+  },
+});
+
+const build = job('build', {
+  runsOn: 'default',
+  needs: [setup],
+  steps: [
+    step('compile', async (ctx) => {
+      return { version: '2.0.0' };
+    }),
+  ],
+});
+
+const deploy = job('deploy', {
+  runsOn: 'default',
+  needs: [build],
+  steps: [
+    step(async (ctx) => {
+      // Multi-step job: jobRef.result.stepName.field
+      const version = build.result.compile.version;
+
+      // Single-step job (run shorthand): jobRef.result.field
+      const env = setup.result.env;
+
+      // Explicit context method
+      const buildOutputs = ctx.jobOutputs(build);
+    }),
+  ],
+});
+```
+
+**Access patterns summary:**
+
+| Pattern                        | Scope                     | Notes                         |
+| ------------------------------ | ------------------------- | ----------------------------- |
+| `stepRef.result.field`         | Within-job                | Proxy on Step object          |
+| `ctx.outputsOf(stepRef)`       | Within-job                | Works with bare function refs |
+| `jobRef.result.stepName.field` | Cross-job (multi-step)    | Proxy on Job object           |
+| `jobRef.result.field`          | Cross-job (run shorthand) | Flat for single-step jobs     |
+| `ctx.jobOutputs(jobRef)`       | Cross-job                 | Explicit context method       |
+
+**Important:** `needs` must be declared explicitly. Output chaining does not auto-infer dependencies -- you must list job dependencies in `needs` even if you access their outputs via `.result`.
+
+Cross-job output chaining works in both local test mode (`kici test`) and remote pipeline execution. The orchestrator's needs-aware dispatch scheduler guarantees upstream jobs reach a terminal state before downstream jobs dispatch, and upstream outputs are transported to the downstream agent sandbox via the `upstreamJobOutputs` field on `job.dispatch`. See [needs-scheduler](https://docs.kici.dev/architecture/execution/needs-scheduler/) for the full dispatch semantics.
+
+### Job dependencies (`needs`)
+
+The `needs` array accepts four entry forms. Mix freely within the same array.
+
+```typescript
+// 1. Reference by Job object (type-safe, preferred)
+const test = job('test', { needs: [lint], ... });
+
+// 2. Reference by string name
+const test = job('test', { needs: ['lint'], ... });
+
+// 3. Object form with a per-edge run condition (`when`)
+const cleanup = job('cleanup', {
+  needs: [{ name: 'build', when: 'always' }],
+  ...
+});
+
+// 4. Dynamic group reference (for static jobs that depend on a dynamicJob group)
+const deploy = job('deploy', {
+  needs: [dynamicGroup('test-shards')],
+  ...
+});
+```
+
+**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 |
+
+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`.
+
+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).
+
+When an upstream's terminal status is **not** in the edge's set, the downstream transitions directly to `skipped`. Because a skipped job is itself terminal, this propagates transitively: each downstream's `when` set governs whether the skip cascades further.
+
+**Dispatch gate:** `needs` is a hard dispatch gate. A job dispatches only after every upstream in its `needs` array reaches a terminal status that satisfies that edge's `when` set. Root jobs (empty `needs`, no dynamic group refs) dispatch immediately. The scheduler is DB-backed and fully recovers across orchestrator restarts.
+
+**Reading an upstream's status in a step:** inside a running job, `ctx.needs.<job>.status` exposes each upstream's terminal status (`success`, `failed`, `skipped`, …) and `ctx.needs.<job>.result` its outputs. A group / matrix / `runsOnAll` fan-out upstream is an ordered array of `{ name, result, status }`, one per child. Use this to branch in TypeScript:
+
+```typescript
+job('report', {
+  needs: [{ name: 'probe', when: 'always' }],
+  run: async (ctx) => {
+    if (ctx.needs.probe.status === 'failed') await fileIncident(ctx.needs.probe.result);
+    else await publish(ctx.needs.probe.result);
+  },
+});
+```
+
+For an arbitrary outcome-based gate that prevents a job from dispatching at all, use a result-aware `dynamicJob` that returns `[]` or `[job]` based on `ctx.needs.<job>.status` — see [Dynamic jobs](https://docs.kici.dev/architecture/execution/dynamic-jobs/).
+
+**DAG validation:** three-layer cycle detection.
+
+1. Compile time: `validateDag` (see below) catches static-to-static cycles.
+2. Eval time: after dynamic jobs are generated, a full topological sort runs on the resolved graph. Cycles reject the run with a clear error.
+3. Runtime: a defensive invariant check flags stuck jobs as an internal-bug backstop.
+
+### dynamicGroup(name, options?)
+
+Create a reference to a dynamic job group, for use inside a static job's `needs` array.
+
+```typescript
+function dynamicGroup(
+  name: string,
+  options?: { when?: 'on-success' | 'always' | 'on-skip' | 'on-failure' | string[] },
+): DynamicGroupRef;
+```
+
+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 deploy = job('deploy', {
+  runsOn: 'linux',
+  needs: [dynamicGroup('test-shards')],
+  run: async () => {
+    // Runs after ALL test-shards jobs have reached a terminal state
+  },
+});
+```
+
+### dynamicJob(groupName, fn)
+
+Tag a dynamic job generator function with a group name so other jobs can reference it via `dynamicGroup()`.
+
+```typescript
+function dynamicJob(groupName: string, fn: DynamicJobFn): DynamicJobFn;
+```
+
+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
+
+Unnamed steps and jobs receive counter-based IDs at compile time:
+
+- **Steps:** `step-1`, `step-2`, etc. Counter is scoped per job and only increments for unnamed entries. Named steps do not consume counter values.
+- **Jobs:** `job-1`, `job-2`, etc. Counter is scoped per workflow and only increments for unnamed entries.
+
+These IDs are stable as long as the order of unnamed entries does not change. Adding or removing unnamed entries shifts subsequent IDs.
+
+---
+
+## Event payload reference
+
+Source: https://docs.kici.dev/user/sdk/event-payloads/
+
+<!-- Generated by scripts/docs-gen-event-payloads.ts — do not edit by hand. Regenerate: pnpm docs:gen:events -->
+
+## The envelope
+
+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.
+
+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.
+
+These fields are present on every envelope (the `EventBase` shape):
+
+| 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. |
+
+## Event types
+
+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.
+
+### `pull_request`
+
+Carried by `PullRequestEventPayload`. The `payload` property has the following shape:
+
+| Field           | Type                | Description |
+| --------------- | ------------------- | ----------- |
+| `action`        | `string`            |             |
+| `number`        | `number`            |             |
+| `pull_request`  | `GitHubPullRequest` |             |
+| `repository`    | `GitHubRepository`  |             |
+| `sender`        | `GitHubUser`        |             |
+| `[key: string]` | `unknown`           |             |
+
+### `push`
+
+Carried by `PushEventPayload`. The `payload` property has the following shape:
+
+| Field           | Type               | Description |
+| --------------- | ------------------ | ----------- |
+| `ref`           | `string`           |             |
+| `after`         | `string`           |             |
+| `before`        | `string`           |             |
+| `head_commit?`  | `GitHubCommit`     |             |
+| `commits?`      | `GitHubCommit[]`   |             |
+| `repository`    | `GitHubRepository` |             |
+| `sender?`       | `GitHubUser`       |             |
+| `forced?`       | `boolean`          |             |
+| `[key: string]` | `unknown`          |             |
+
+### `tag`
+
+Carried by `TagEventPayload`. The `payload` property has the following shape:
+
+| 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:
+
+| 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`
+
+Carried by `ReviewEventPayload`. The `payload` property has the following shape:
+
+| Field           | Type                | Description |
+| --------------- | ------------------- | ----------- |
+| `action`        | `string`            |             |
+| `review`        | `GitHubReview`      |             |
+| `pull_request`  | `GitHubPullRequest` |             |
+| `repository`    | `GitHubRepository`  |             |
+| `sender`        | `GitHubUser`        |             |
+| `[key: string]` | `unknown`           |             |
+
+### `review_comment`
+
+Carried by `ReviewCommentEventPayload`. The `payload` property has the following shape:
+
+| 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`
+
+Carried by `DispatchEventPayload`. The `payload` property has the following shape:
+
+| Field             | Type                      | Description |
+| ----------------- | ------------------------- | ----------- |
+| `action`          | `string`                  |             |
+| `client_payload?` | `Record<string, unknown>` |             |
+| `repository`      | `GitHubRepository`        |             |
+| `sender?`         | `GitHubUser`              |             |
+| `[key: string]`   | `unknown`                 |             |
+
+### `create`
+
+Carried by `CreateEventPayload`. The `payload` property has the following shape:
+
+| Field           | Type               | Description |
+| --------------- | ------------------ | ----------- |
+| `ref`           | `string`           |             |
+| `ref_type`      | `string`           |             |
+| `repository`    | `GitHubRepository` |             |
+| `sender`        | `GitHubUser`       |             |
+| `[key: string]` | `unknown`          |             |
+
+### `delete`
+
+Carried by `DeleteEventPayload`. The `payload` property has the following shape:
+
+| Field           | Type               | Description |
+| --------------- | ------------------ | ----------- |
+| `ref`           | `string`           |             |
+| `ref_type`      | `string`           |             |
+| `repository`    | `GitHubRepository` |             |
+| `sender`        | `GitHubUser`       |             |
+| `[key: string]` | `unknown`          |             |
+
+### `status`
+
+Carried by `StatusEventPayload`. The `payload` property has the following shape:
+
+| 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`                                         |             |
+
+### `workflow_run`
+
+Carried by `WorkflowRunEventPayload`. The `payload` property has the following shape:
+
+| 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`                                                                                              |             |
+
+### `fork`
+
+Carried by `ForkEventPayload`. The `payload` property has the following shape:
+
+| Field           | Type                                            | Description |
+| --------------- | ----------------------------------------------- | ----------- |
+| `forkee`        | `{ full_name: string; [key: string]: unknown }` |             |
+| `repository`    | `GitHubRepository`                              |             |
+| `sender`        | `GitHubUser`                                    |             |
+| `[key: string]` | `unknown`                                       |             |
+
+### `star`
+
+Carried by `StarEventPayload`. The `payload` property has the following shape:
+
+| Field           | Type               | Description |
+| --------------- | ------------------ | ----------- |
+| `action`        | `string`           |             |
+| `repository`    | `GitHubRepository` |             |
+| `sender`        | `GitHubUser`       |             |
+| `[key: string]` | `unknown`          |             |
+
+### `watch`
+
+Carried by `WatchEventPayload`. The `payload` property has the following shape:
+
+| Field           | Type               | Description |
+| --------------- | ------------------ | ----------- |
+| `action`        | `string`           |             |
+| `repository`    | `GitHubRepository` |             |
+| `sender`        | `GitHubUser`       |             |
+| `[key: string]` | `unknown`          |             |
+
+### `webhook`
+
+Carried by `WebhookEventPayload`. Adds no typed fields beyond the shared envelope; `payload` is the raw provider body (`Record<string, unknown>`).
+
+### `kici_event`
+
+Carried by `KiciEventPayload`. Adds no typed fields beyond the shared envelope; `payload` is the raw provider body (`Record<string, unknown>`).
+
+### `workflow_complete`
+
+Carried by `WorkflowCompleteEventPayload`. Adds no typed fields beyond the shared envelope; `payload` is the raw provider body (`Record<string, unknown>`).
+
+### `job_complete`
+
+Carried by `JobCompleteEventPayload`. Adds no typed fields beyond the shared envelope; `payload` is the raw provider body (`Record<string, unknown>`).
+
+### `generic_webhook`
+
+Carried by `GenericWebhookEventPayload`. Adds no typed fields beyond the shared envelope; `payload` is the raw provider body (`Record<string, unknown>`).
+
+### `schedule`
+
+Carried by `ScheduleEventPayload`. Adds no typed fields beyond the shared envelope; `payload` is the raw provider body (`Record<string, unknown>`).
+
+### `lifecycle`
+
+Carried by `LifecycleEventPayload`. Adds no typed fields beyond the shared envelope; `payload` is the raw provider body (`Record<string, unknown>`).
+
+### `rerun`
+
+Carried by `RerunEventPayload`. Adds no typed fields beyond the shared envelope; `payload` is the raw provider body (`Record<string, unknown>`).
+
+### `manual_schedule`
+
+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: 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 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 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:
+
+```typescript
+type JobOrFactory = Job | DynamicJobFn;
+```
+
+### isDynamicJobFn(item)
+
+Type guard to distinguish static jobs from dynamic generators:
+
+```typescript
+function isDynamicJobFn(item: JobOrFactory): item is DynamicJobFn;
+```
+
+```typescript
+for (const item of workflow.jobs) {
+  if (isDynamicJobFn(item)) {
+    const generatedJobs = await item(context);
+  } else {
+    // item is Job
+  }
+}
+```
+
+---
+
+## 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):
+
+```typescript
+const fanout = job('deploy', {
+  runsOnAll: {
+    include: [{ all: ['kici:os:linux', 'kici:host:web-*'] }],
+    exclude: [/.*-canary$/],
+  },
+  run: async (ctx) => {
+    /* runs once per matched host */
+  },
+});
+```
+
+A custom label that literally contains glob metacharacters is always treated as a glob
+and can no longer be matched exactly. A regular expression you supply is validated for
+catastrophic-backtracking (ReDoS) when you run `kici compile` and rejected if it could
+hang on a crafted input.
+
+### Per-host execution model
+
+Each matching host runs the job as its own pinned child, named `<job> (<hostname>)`
+(e.g. `patch (web-01)`). The children fan in for downstream `needs:` exactly like a
+matrix job — a downstream that needs the base job waits for every host child.
+
+The job runs once per host with concurrency `unlimited` (all hosts in parallel).
+
+### ctx.host and ctx.agent
+
+Inside a `runsOnAll` step, two extra context fields identify the host the child is
+running on:
+
+- `ctx.host` — the hostname (string).
+- `ctx.agent` — the resolved agent facts: `{ host, labels, platform?, arch? }`.
+
+```typescript
+run: async (ctx) => {
+  ctx.log.info(`running on ${ctx.host} (${ctx.agent?.platform}/${ctx.agent?.arch})`);
+};
+```
+
+Both are `undefined` for jobs that do not use `runsOnAll`.
+
+### ctx.fanout — fan-out position
+
+Every fan-out child — a `runsOnAll` host **or** a matrix combination — also
+carries its **position** within the fan-out:
+
+```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
+};
+```
+
+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;
+    }
+  },
+});
+```
+
+Unlike the matrix envelope's last-write-wins `merged`, the host summary never collapses
+to a single scalar: `summary.outputs[key]` is an array of every host's value, and
+`succeededHosts` / `failedHosts` record each host's terminal outcome.
+
+### onUnreachable: skip | fail | hold
+
+Resolution is backed by the **declared host roster** (see the operator
+[host roster](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:
+
+- **`hold`** (default) — queue a pinned child for the absent host and wait for it to
+  reconnect. The fan-out is honest: a 5-host fleet with 1 host rebooting reports
+  `4 ran, 1 held`, not a silent 4-of-5 success.
+- **`skip`** — omit the absent durable host and run only on the reachable hosts.
+- **`fail`** — fail the run init if any expected durable host is unreachable.
+
+```typescript
+const patch = job('patch', {
+  runsOnAll: 'role:web',
+  onUnreachable: 'skip',
+  run: async (ctx) => {
+    /* ... */
+  },
+});
+```
+
+Ephemeral (scaled-down) hosts that are no longer connected are **always** skipped,
+independent of `onUnreachable` — a scaled-down node may never return. A `runsOnAll`
+that matches zero usable hosts fails the run rather than reporting a silent zero-child
+success.
+
+### includeUninitialized: converge a fresh fleet
+
+`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:
+
+```typescript
+const converge = job('converge', {
+  runsOnAll: 'kici:group:prod',
+  includeUninitialized: true,
+  steps: [partitionDisk, formatLuks, debootstrap, installAgent],
+});
+```
+
+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
+
+By default a `runsOnAll` fan-out dispatches to every matched host at once — fine for
+collecting state across the fleet, dangerous for a deploy that takes the whole tier
+down simultaneously. Two job options bound the rollout:
+
+- **`maxParallel`** — the fan-out width: at most this many hosts run at once. It is a
+  sliding window — each host that finishes (success or failure) releases the next held
+  host. `maxParallel: 1` is a strictly serial, one-host-at-a-time rolling deploy. Must
+  be `>= 1`.
+- **`failFast`** — when `true`, the first host failure halts the rollout: no further
+  held hosts are started, and the remaining ones are marked skipped. Default `false`
+  (every host runs regardless of sibling outcomes — the same as the unbounded fan-out).
+
+```typescript
+const deploy = job('deploy', {
+  runsOnAll: 'role:web',
+  onUnreachable: 'skip', // see the caveat below
+  maxParallel: 1, // strictly one host at a time
+  failFast: true, // stop the roll on the first failure
+  run: async (ctx) => {
+    /* patch ctx.host */
+  },
+});
+```
+
+Both options are **fan-out-generic** — they bound a `matrix` fan-out exactly the same
+way (the children are matrix combinations instead of hosts). They are ignored on a job
+with neither `matrix` nor `runsOnAll` (there is no fan-out to bound).
+
+**Caveat — use `onUnreachable: 'skip'` or `'fail'` for rolling deploys, not `'hold'`.**
+A held host occupies a wave slot indefinitely while it waits to reconnect, stalling the
+roll behind an absent box. `skip` (run only reachable hosts) or `fail` (refuse the roll
+if any expected host is down) keep the window moving.
+
+### 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
+```
+
+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 test` (remote test 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;
+}
+```
+
+### Logger
+
+```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;
+}
+```
+
+### 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 })
+
+Request a short-lived OIDC ID token for the current job, bound to an `audience`. The token is a signed JWT whose identity claims (`repository`, `ref`, `sha`, `kici_run_id`, `kici_job_id`) are derived by the build platform from the run context — a step cannot spoof them. Use it to authenticate the build to an external service that trusts the platform's OIDC issuer (for example, when generating build provenance).
+
+```typescript
+const publish = job('publish', {
+  steps: [
+    step('mint', async (ctx) => {
+      const { token, expiresIn } = await ctx.kici.oidc.token({ audience: 'sigstore' });
+      ctx.log.info(`Got an ID token valid for ${expiresIn}s`);
+      // Hand `token` to a tool that exchanges it with the trusting service.
+    }),
+  ],
+});
+```
+
+**Behavior:**
+
+- The token is short-lived (about 10 minutes) and scoped to the current run and job.
+- The returned token value is automatically masked in step logs.
+- The step never holds platform credentials — the request is relayed through the orchestrator, which mints the token on the step's behalf.
+- Only available inside a running job step; calling it outside one (for example, during local execution) rejects with a clear error.
+
+### ctx.kici.inventory.query(selector?) / .get(agentId)
+
+Query the **host inventory** — the roster of agents in the caller's orchestrator cluster — from inside a workflow. Each host is a `HostInventoryEntry`:
+
+```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
+}
+```
+
+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).
+
+```typescript
+// All hosts:
+const all = await ctx.kici.inventory.query();
+
+// Server-side label filter (OR-of-AND include groups, plus exclude):
+const dbHosts = await ctx.kici.inventory.query({
+  include: [[{ kind: 'exact', value: 'role:db' }]],
+});
+
+// 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.
+
+**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:
+
+```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 })
+
+Build, sign, and persist a build-provenance attestation for an artifact your step produced. KiCI assembles an in-toto SLSA v1.0 provenance statement whose build identity (`repository`, `ref`, `sha`, run/job ids) comes from the platform — not from the step — so it cannot be spoofed, signs it, and stores a verifiable bundle that the dashboard surfaces and the `kici verify-attestation` CLI checks.
+
+The artifact is **caller-supplied**: give it either a precomputed digest or a path (relative to the step working directory) that KiCI digests with SHA-256. For a container image, pass the manifest digest your build tool emitted.
+
+```typescript
+const publish = job('publish', {
+  steps: [
+    step('build', async (ctx) => {
+      await ctx.$`npm pack`;
+    }),
+    step('attest', async (ctx) => {
+      // Digest a file KiCI hashes for you:
+      const result = await ctx.attestProvenance({
+        subject: { name: 'my-pkg-1.2.3.tgz', path: 'my-pkg-1.2.3.tgz' },
+      });
+      ctx.log.info(`Attestation stored at ${result.storageKey}`);
+
+      // Or supply a precomputed digest (e.g. a container manifest digest):
+      await ctx.attestProvenance({
+        subject: { name: 'ghcr.io/acme/app', digest: { sha256: '<manifest-digest>' } },
+      });
+    }),
+  ],
+});
+```
+
+**Behavior:**
+
+- The attestation is a signed [DSSE](https://github.com/secure-systems-lab/dsse) envelope over an [in-toto](https://in-toto.io) statement carrying the [SLSA v1.0](https://slsa.dev/spec/v1.0/provenance) provenance predicate.
+- It is signed with an ephemeral key bound to a platform-minted identity token, so it is **offline-verifiable** against the platform's published signing keys — no online lookup needed at verify time.
+- The bundle is persisted to object storage and recorded so the dashboard can show it and `kici verify-attestation` can retrieve it.
+- The returned `{ storageKey, subjectDigest, bundleMediaType }` identifies the stored bundle.
+- Only available inside a running job step; calling it outside one (for example, during local execution) rejects with a clear error.
+
+See the [build provenance guide](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`.
+
+## 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.
+
+### Declaring the secret environment
+
+Each job picks its secret environment via the `environment` option on `job()`. The orchestrator resolves the environment's scoped-secret store at dispatch time, evaluates access rules, and sends the decrypted secrets to the agent:
+
+```typescript
+const deploy = job('deploy', {
+  runsOn: 'linux',
+  environment: 'production',
+  steps: [
+    /* ... */
+  ],
+});
+
+export default workflow('deploy', {
+  on: push({ branches: 'main' }),
+  jobs: [deploy],
+});
+```
+
+`environment` accepts either a static string or an async function `(event) => string | Promise<string>` for dynamic resolution at trigger-evaluation time. The resolved environment's secrets are flattened into `ctx.secrets`.
+
+### Accessing secrets (ctx.secrets)
+
+`ctx.secrets` provides flat access to the secrets resolved for the job's environment.
+
+```typescript
+step('deploy', async ({ secrets }) => {
+  // get() rejects with SecretNotFoundError if DEPLOY_TOKEN is not found
+  const token = await secrets.get('DEPLOY_TOKEN');
+
+  // Safe check before access (no throw, synchronous)
+  if (secrets.has('OPTIONAL_KEY')) {
+    const optional = await secrets.get('OPTIONAL_KEY');
+  }
+});
+```
+
+**Throw behavior:** `get()` rejects with `SecretNotFoundError` and the message lists all available keys. This catches typos immediately rather than producing silent `undefined` values.
+
+### Complete example
+
+```typescript
+import { workflow, job, step, push } from '@kici-dev/sdk';
+
+const deploy = job('deploy', {
+  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`;
+    }),
+  ],
+});
+
+export default workflow('deploy-production', {
+  on: push({ branches: 'main' }),
+  jobs: [deploy],
+});
+```
+
+### 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`);
+});
+```
+
+### 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 test`, 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
+```
+
+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).
+
+#### CLI flags
+
+Override or supplement file-based secrets with CLI flags:
+
+```bash
+# Inject flat secrets (repeatable)
+kici test push --secret DEPLOY_TOKEN=my-token --secret API_KEY=my-key
+
+# Inject context-scoped secrets (repeatable)
+kici test push --context production.DB_PASSWORD=prod-secret --context npm-publish.NPM_TOKEN=abc123
+```
+
+**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.
+
+### fixture(id, options)
+
+```typescript
+function fixture(
+  id: string,
+  options: FixtureOptions | (() => FixtureOptions | Promise<FixtureOptions>),
+): Fixture;
+```
+
+**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'] }),
+});
+```
+
+### 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
+
+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.
+
+All triggers use a config object form -- pass an options object to configure the trigger.
+
+### pr()
+
+Create a pull request trigger. Returns a frozen `PrTriggerConfig` directly.
+
+```typescript
+function pr(config?: PrConfigInput): PrTriggerConfig;
+```
+
+**Config options:**
+
+```typescript
+interface PrConfigInput {
+  events?: PrEvent[];
+  target?: string | RegExp | (string | RegExp)[];
+  source?: string | RegExp | (string | RegExp)[];
+  paths?: string[]; // Use '!' prefix for exclusions (e.g., '!docs/**')
+  repos?: string | RegExp | (string | RegExp)[]; // Cross-repo source patterns -- see global-workflows.md
+  description?: string;
+}
+```
+
+**PrEvent values:** `'opened'`, `'synchronize'`, `'reopened'`, `'closed'`, `'assigned'`, `'unassigned'`, `'labeled'`, `'unlabeled'`, `'edited'`, `'converted_to_draft'`, `'ready_for_review'`, `'locked'`, `'unlocked'`, `'review_requested'`, `'review_request_removed'`, `'auto_merge_enabled'`, `'auto_merge_disabled'`
+
+**Default events** (when `events` is not specified): `opened`, `synchronize`, `reopened`, `closed`
+
+**Examples:**
+
+```typescript
+// All PRs with default events
+pr();
+
+// PRs targeting main with path filter
+pr({ target: 'main', events: ['opened', 'synchronize'], paths: ['src/**'] });
+
+// Regex branch pattern
+pr({ target: /^release\/v\d+$/ });
+```
+
+### push()
+
+Create a push trigger. Returns a frozen `PushTriggerConfig` directly.
+
+```typescript
+function push(config?: PushConfigInput): PushTriggerConfig;
+```
+
+**Config options:**
+
+```typescript
+interface PushConfigInput {
+  branches?: string | RegExp | (string | RegExp)[];
+  tags?: string | RegExp | (string | RegExp)[];
+  paths?: string[]; // Use '!' prefix for exclusions (e.g., '!docs/**')
+  repos?: string | RegExp | (string | RegExp)[]; // Cross-repo source patterns -- see global-workflows.md
+  description?: string;
+}
+```
+
+**Examples:**
+
+```typescript
+// Any push
+push();
+
+// Push to main only
+push({ branches: 'main' });
+
+// Push with branch and path filters
+push({ branches: ['main', 'develop'], paths: ['src/**'] });
+
+// Tag pushes
+push({ tags: ['v*'] });
+```
+
+### tag()
+
+Create a tag trigger. Returns a frozen `TagTriggerConfig`.
+
+```typescript
+function tag(config?: TagConfigInput): TagTriggerConfig;
+```
+
+**Config options:** `patterns` (string/RegExp/array), `description`
+
+```typescript
+tag(); // Any tag
+tag({ patterns: ['v*'] }); // Semver tags
+tag({ patterns: /^v\d+\.\d+$/ }); // Regex match
+```
+
+### comment()
+
+Create an issue/PR comment trigger. Returns a frozen `CommentTriggerConfig`.
+
+```typescript
+function comment(config?: CommentConfigInput): CommentTriggerConfig;
+```
+
+**Config options:** `actions` (created/edited/deleted), `source` (issue/pr), `bodyMatch` (string or RegExp), `description`
+
+```typescript
+comment(); // Any comment
+comment({ bodyMatch: '/deploy' }); // Glob match on body
+comment({ bodyMatch: /^\/deploy/i }); // Regex match on body
+comment({ source: 'pr', actions: ['created'] }); // PR comments only
+```
+
+### review()
+
+Create a pull request review trigger. Returns a frozen `ReviewTriggerConfig`.
+
+```typescript
+function review(config?: ReviewConfigInput): ReviewTriggerConfig;
+```
+
+**Config options:** `actions` (submitted/edited/dismissed), `states` (approved/changes_requested/commented/dismissed), `description`
+
+```typescript
+review(); // Any review
+review({ states: ['approved'] }); // Approvals only
+review({ actions: ['submitted'], states: ['approved'] }); // Submitted approvals
+```
+
+### reviewComment()
+
+Create a PR review comment trigger. Returns a frozen `ReviewCommentTriggerConfig`.
+
+```typescript
+function reviewComment(config?: ReviewCommentConfigInput): ReviewCommentTriggerConfig;
+```
+
+**Config options:** `actions` (created/edited/deleted), `description`
+
+```typescript
+reviewComment(); // Any review comment
+reviewComment({ actions: ['created'] }); // New review comments only
+```
+
+### release()
+
+Create a release trigger. Returns a frozen `ReleaseTriggerConfig`.
+
+```typescript
+function release(config?: ReleaseConfigInput): ReleaseTriggerConfig;
+```
+
+**Config options:** `actions` (published/unpublished/created/edited/deleted/prereleased/released), `description`
+
+```typescript
+release(); // Any release event
+release({ actions: ['published'] }); // Published releases only
+```
+
+### dispatch()
+
+Create a repository_dispatch trigger. Returns a frozen `DispatchTriggerConfig`.
+
+```typescript
+function dispatch(config?: DispatchConfigInput): DispatchTriggerConfig;
+```
+
+**Config options:** `types` (string[]), `description`, `inputs` (typed dispatch inputs map)
+
+```typescript
+dispatch(); // Any dispatch
+dispatch({ types: ['deploy', 'rollback'] }); // Specific event types
+```
+
+#### Typed dispatch inputs
+
+A `dispatch()` trigger can declare a typed `inputs` schema. Operators supply
+values with `kici run --input key=value`; KiCI validates, coerces, defaults, and
+exposes them to steps and rules as `ctx.dispatchInputs`. The values are validated
+on the orchestrator from the compiled lock file — a missing required input or a
+bad value is rejected before any agent runs, without cloning the repository.
+
+```typescript
+import { workflow, job, step, dispatch, defineDispatchInputs, z } from '@kici-dev/sdk';
+
+const inputs = defineDispatchInputs({
+  target: z.string().optional(),
+  skipCveScan: z.boolean().default(false),
+  skipCveScanReason: z.string().min(1).optional(),
+  mode: z.enum(['full', 'edge-only']).default('full'),
+  retries: z.number().int().min(0).max(10).default(3),
+});
+
+export default workflow('deploy-prod', {
+  on: dispatch({ types: ['deploy-prod'], inputs }),
+  jobs: [
+    job('gates', {
+      runsOn: 'kici:group:ops',
+      steps: [
+        step('cve-gate', async (ctx) => {
+          const i = inputs.from(ctx); // fully typed per declared key
+          if (i.skipCveScan) {
+            ctx.log.warn(`CVE gate skipped: ${i.skipCveScanReason ?? '(no reason)'}`);
+            return;
+          }
+          await ctx.$`pnpm scan:cve:gate`;
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+- **`defineDispatchInputs(map)`** is the single declaration site. It returns a
+  handle that `dispatch({ inputs })` accepts and exposes `inputs.from(ctx)` — a
+  typed reader over `ctx.dispatchInputs`, typed per declared key. `dispatch({ inputs })`
+  also accepts a bare `{ name: schema }` map directly when you don't need the reader.
+- **`ctx.dispatchInputs`** is always present (a validated map of
+  `string | number | boolean | null`), distinct from `ctx.inputs` (typed outputs
+  from `needs` dependencies). Rules see the same values via `ctx.dispatchInputs`,
+  so `skipUnless(ctx => !ctx.dispatchInputs.skipCveScan)` works.
+- **Defaults are applied once**, on the orchestrator (the authoritative side); the
+  CLI pre-validates `--input` for fast feedback and forwards the raw operator pairs.
+
+**Allowed input types (closed subset):** `z.string()`, `z.number()`,
+`z.boolean()`, `z.enum([...])`, `z.literal(v)`, with the modifiers `.optional()`,
+`.nullable()`, `.default(v)`, `.min(n)`, `.max(n)`, `.regex(re)`, `.int()`.
+Anything outside this set (`.refine()`, `.transform()`, `.pipe()`, `z.object()`,
+`z.array()`, `z.union()`, `z.record()`, `z.coerce.*`) is a **compile error** —
+the closed set is what guarantees the schema survives the trip to the
+orchestrator's lock file without silently dropping any validation. CLI strings
+are coerced for you (`--input retries=3` becomes the number `3`; booleans accept
+`true`/`false`/`1`/`0`/`yes`/`no`), so author your schema with clean types.
+
+### create()
+
+Create a ref creation trigger (branches/tags). Returns a frozen `CreateTriggerConfig`.
+
+```typescript
+function create(config?: CreateConfigInput): CreateTriggerConfig;
+```
+
+**Config options:** `refTypes` (branch/tag), `patterns` (string/RegExp/array), `description`
+
+```typescript
+create(); // Any ref creation
+create({ refTypes: ['tag'], patterns: ['v*'] }); // Tag creation only
+```
+
+### delete()
+
+Create a ref deletion trigger (branches/tags). Returns a frozen `DeleteTriggerConfig`.
+
+Note: Since `delete` is a JavaScript reserved word, import as `del`: `import { delete as del } from '@kici-dev/sdk'`
+
+```typescript
+function del(config?: DeleteConfigInput): DeleteTriggerConfig;
+```
+
+**Config options:** `refTypes` (branch/tag), `patterns` (string/RegExp/array), `description`
+
+```typescript
+del(); // Any ref deletion
+del({ refTypes: ['branch'], patterns: ['temp/*'] }); // Temp branch cleanup
+```
+
+### status()
+
+Create a commit status trigger. Returns a frozen `StatusTriggerConfig`.
+
+```typescript
+function status(config?: StatusConfigInput): StatusTriggerConfig;
+```
+
+**Config options:** `contexts` (picomatch strings like 'ci/\*'), `states` (error/failure/pending/success), `description`
+
+```typescript
+status(); // Any status
+status({ contexts: ['ci/*'], states: ['success'] }); // CI success
+```
+
+### workflowRun()
+
+Create a workflow_run trigger. Returns a frozen `WorkflowRunTriggerConfig`.
+
+```typescript
+function workflowRun(config?: WorkflowRunConfigInput): WorkflowRunTriggerConfig;
+```
+
+**Config options:** `actions` (requested/completed/in_progress), `workflows` (name filters), `conclusions` (success/failure/cancelled), `description`
+
+```typescript
+workflowRun(); // Any workflow run
+workflowRun({ workflows: ['CI'], actions: ['completed'], conclusions: ['success'] });
+```
+
+### fork()
+
+Create a fork trigger. No filter fields. Returns a frozen `ForkTriggerConfig`.
+
+```typescript
+function fork(config?: ForkConfigInput): ForkTriggerConfig;
+```
+
+```typescript
+fork(); // Any fork event
+fork({ description: 'Track forks' }); // With description
+```
+
+### star()
+
+Create a star trigger. Returns a frozen `StarTriggerConfig`.
+
+```typescript
+function star(config?: StarConfigInput): StarTriggerConfig;
+```
+
+**Config options:** `actions` (created/deleted), `description`
+
+```typescript
+star(); // Any star event
+star({ actions: ['created'] }); // New stars only
+```
+
+### watch()
+
+Create a watch trigger. Returns a frozen `WatchTriggerConfig`.
+
+```typescript
+function watch(config?: WatchConfigInput): WatchTriggerConfig;
+```
+
+**Config options:** `actions` (started), `description`
+
+```typescript
+watch(); // Any watch event
+watch({ actions: ['started'] }); // Watch started only
+```
+
+### webhook()
+
+Create a catch-all webhook trigger for any GitHub event. Returns a frozen `WebhookTriggerConfig`. Unlike other triggers, `events` is **required** -- catch-all must specify what to catch.
+
+```typescript
+function webhook(config: WebhookConfigInput): WebhookTriggerConfig;
+```
+
+**Config options:** `events` (required string[]), `actions` (optional string[]), `repos` (optional cross-repo source patterns -- see [global workflows](https://docs.kici.dev/user/global-workflows/)), `description`
+
+```typescript
+webhook({ events: ['deployment'] }); // Deployment events
+webhook({ events: ['deployment', 'deployment_status'] }); // Multiple events
+webhook({ events: ['deployment'], actions: ['created'] }); // With action filter
+```
+
+#### Cross-source delivery
+
+A `webhook()` trigger fires whenever a matching event arrives via **any inbound webhook source within the same org**, not just the source the workflow's repository is bound to. If your repo is registered through a github source and a separate generic source in the same org POSTs an event with a matching name, the workflow still runs.
+
+Two important rules govern the cross-source path:
+
+1. **The registration's source owns dispatch credentials.** The runtime clone, auth, and check-status posting come from the source the workflow was registered with (via its default-branch push), never from the inbound source. A generic webhook fanning out to a github-registered workflow uses the github bundle's clone token provider — the generic source contributes only the event payload.
+2. **Org isolation is structural.** A webhook delivered to org A can never trigger a workflow registered against org B. The lookup index is keyed on `(customerId, eventName)` so cross-org leakage is impossible.
+
+The orchestrator emits `kici_cross_source_fanout_size` (histogram) per inbound webhook so operators can observe how many workflows each event reaches.
+
+### Event triggers
+
+The following 6 trigger types support internal event routing, scheduling, lifecycle orchestration, and non-GitHub webhook sources.
+
+### kiciEvent()
+
+Create a custom event trigger. Fires when a named internal event is emitted from a workflow step via `ctx.emit()`. Returns a frozen `KiciEventTriggerConfig`.
+
+```typescript
+function kiciEvent(config: KiciEventConfigInput): KiciEventTriggerConfig;
+```
+
+**Config options:**
+
+```typescript
+interface KiciEventConfigInput {
+  name: string; // Required: event name to listen for
+  match?: Record<string, unknown>; // JSONPath payload matching (e.g., { '$.env': 'prod' })
+  not?: Record<string, unknown>; // Negative JSONPath filter
+  source?: string; // Cross-repo source filter (e.g., 'org/infra-repo')
+  description?: string;
+}
+```
+
+```typescript
+kiciEvent({ name: 'deploy-complete' }); // Match by name
+kiciEvent({ name: 'deploy-complete', match: { '$.env': 'prod' } }); // With payload filter
+kiciEvent({ name: 'deploy-complete', not: { '$.env': 'staging' } }); // Negative filter
+kiciEvent({ name: 'deploy-complete', source: 'org/infra-repo' }); // Cross-repo
+```
+
+### workflowComplete()
+
+Create a workflow completion trigger. Fires automatically when another workflow finishes execution. Returns a frozen `WorkflowCompleteTriggerConfig`.
+
+```typescript
+function workflowComplete(config?: WorkflowCompleteConfigInput): WorkflowCompleteTriggerConfig;
+```
+
+**Config options:**
+
+```typescript
+interface WorkflowCompleteConfigInput {
+  name?: string; // Filter by workflow name
+  status?: WorkflowCompleteStatus[]; // Filter by completion status
+  source?: string; // Cross-repo source filter
+  description?: string;
+}
+type WorkflowCompleteStatus = 'success' | 'failed' | 'cancelled';
+```
+
+```typescript
+workflowComplete(); // Any workflow completion
+workflowComplete({ name: 'CI' }); // Specific workflow
+workflowComplete({ name: 'CI', status: ['success'] }); // Success only
+workflowComplete({ name: 'CI', status: ['success'], source: 'org/repo' }); // Cross-repo
+```
+
+### jobComplete()
+
+Create a job completion trigger. Fires automatically when a specific job within a workflow finishes. Returns a frozen `JobCompleteTriggerConfig`.
+
+```typescript
+function jobComplete(config?: JobCompleteConfigInput): JobCompleteTriggerConfig;
+```
+
+**Config options:**
+
+```typescript
+interface JobCompleteConfigInput {
+  workflow?: string; // Filter by workflow name
+  job?: string; // Filter by job name
+  status?: JobCompleteStatus[]; // Filter by completion status
+  source?: string; // Cross-repo source filter
+  description?: string;
+}
+type JobCompleteStatus = 'success' | 'failed' | 'cancelled' | 'skipped';
+```
+
+```typescript
+jobComplete(); // Any job completion
+jobComplete({ workflow: 'CI', job: 'build' }); // Specific workflow + job
+jobComplete({ workflow: 'CI', job: 'build', status: ['success'] }); // Success only
+jobComplete({ workflow: 'CI', job: 'build', source: 'org/repo' }); // Cross-repo
+```
+
+`jobComplete()` starts a **new** workflow run that reacts to another job finishing (gated on the prior job's status). For same-run fan-out — generating follow-up jobs from a prior job's _outputs_ within the same run — use a result-aware [`dynamicJob(group, { needs, generate })`](https://docs.kici.dev/user/sdk/rules-matrix-dynamic/#dynamicjob--result-aware-generation) instead.
+
+### genericWebhook()
+
+Create a generic webhook trigger. Fires when a non-GitHub webhook is received from an external source configured via the admin API. Returns a frozen `GenericWebhookTriggerConfig`.
+
+```typescript
+function genericWebhook(config: GenericWebhookConfigInput): GenericWebhookTriggerConfig;
+```
+
+**Config options:**
+
+```typescript
+interface GenericWebhookConfigInput {
+  source: string; // Required: must match `--name` from `kici-admin source add generic`
+  events?: string[]; // Filter by event types
+  match?: Record<string, unknown>; // JSONPath payload matching
+  not?: Record<string, unknown>; // Negative JSONPath filter
+  auth?: GenericWebhookAuth; // HMAC or API key authentication
+  path?: string; // URL path pattern (replaces source for URL matching)
+  description?: string;
+}
+```
+
+```typescript
+genericWebhook({ source: 'argocd' }); // Any event from ArgoCD
+genericWebhook({ source: 'argocd', events: ['deploy.success'] }); // Specific events
+genericWebhook({ source: 'argocd', match: { '$.env': 'prod' } }); // With payload filter
+genericWebhook({ source: 'argocd', not: { '$.dry_run': true } }); // Negative filter
+genericWebhook({
+  source: 'stripe',
+  auth: { method: 'hmac-sha256', secret: 'stripe-key', signatureHeader: 'stripe-signature' },
+}); // HMAC auth
+genericWebhook({ source: 'slack', auth: { method: 'api-key', secret: 'slack-token' } }); // API key auth
+genericWebhook({ source: 'stripe', path: 'stripe/payments' }); // URL path pattern
+```
+
+### schedule()
+
+Create a cron-based schedule trigger. Returns a frozen `ScheduleTriggerConfig`.
+
+```typescript
+function schedule(config: ScheduleConfigInput): ScheduleTriggerConfig;
+```
+
+**Config options:**
+
+```typescript
+interface ScheduleConfigInput {
+  cron: string; // Required: cron expression (5-field)
+  timezone?: string; // Timezone for cron evaluation (default: 'UTC')
+  description?: string; // Human-readable description of the schedule
+}
+```
+
+```typescript
+schedule({ cron: '0 * * * *' }); // Every hour
+schedule({ cron: '0 0 * * *' }); // Daily at midnight UTC
+schedule({ cron: '0 9 * * 1', timezone: 'America/New_York' }); // Monday 9am ET
+schedule({ cron: '*/15 * * * *', description: 'health check every 15 min' });
+```
+
+### lifecycle()
+
+Create a lifecycle trigger for cross-workflow orchestration events. Returns a frozen `LifecycleTriggerConfig`.
+
+```typescript
+function lifecycle(config: LifecycleConfigInput): LifecycleTriggerConfig;
+```
+
+**Config options:**
+
+```typescript
+interface LifecycleConfigInput {
+  events: LifecycleEvent[]; // Required: lifecycle events to listen for
+  sources?: string[]; // Optional: filter by source repo (e.g., 'org/repo')
+  description?: string; // Human-readable description
+}
+
+type LifecycleEvent = 'workflow_complete' | 'job_complete' | 'job_failed' | 'registration_updated';
+```
+
+```typescript
+lifecycle({ events: ['workflow_complete'] }); // Any workflow completion
+lifecycle({ events: ['job_failed'], sources: ['org/deploy-repo'] }); // Job failures from specific repo
+lifecycle({ events: ['registration_updated'] }); // Workflow registration changes
+```
+
+### Branch patterns
+
+Both `pr()` and `push()` (as well as `tag()`, `create()`, and `delete()`) accept glob strings and RegExp literals for pattern matching:
+
+```typescript
+// Glob patterns (micromatch syntax)
+pr({ target: ['main', 'release/*', 'feature/**'] });
+
+// Regex patterns
+pr({ target: /^release\/v\d+\.\d+$/ });
+
+// Mixed
+push({ branches: ['main', /^hotfix\//] });
+```
+
+Glob patterns use micromatch syntax. Regex patterns use standard JavaScript `RegExp`.
+
+---
+
+## SDK reference: validation & events
+
+Source: https://docs.kici.dev/user/sdk/validation-events/
+
+## Validation
+
+### validateDag(nodes)
+
+Validate a directed acyclic graph for correctness.
+
+```typescript
+function validateDag(nodes: DagNode[]): DagValidationResult;
+```
+
+**DagNode:**
+
+```typescript
+interface DagNode {
+  id: string;
+  needs: string[];
+}
+```
+
+**DagValidationResult** (discriminated union):
+
+```typescript
+// Valid graph with topological sort order
+{ valid: true; sortedOrder: string[] }
+
+// Cycle detected
+{ valid: false; error: 'cycle'; nodesInCycle: string[] }
+
+// Job depends on itself
+{ valid: false; error: 'self-reference'; nodeId: string }
+
+// Job depends on non-existent job
+{ valid: false; error: 'missing-dependency'; nodeId: string; missingDep: string }
+```
+
+Checks (in order): self-references, missing dependencies, cycles (Kahn's algorithm).
+
+```typescript
+const result = validateDag([
+  { id: 'lint', needs: [] },
+  { id: 'test', needs: ['lint'] },
+  { id: 'deploy', needs: ['test'] },
+]);
+
+if (result.valid) {
+  console.log(result.sortedOrder); // ['lint', 'test', 'deploy']
+}
+```
+
+## Event definitions
+
+The `defineEvent()` helper creates typed event definitions with Zod validation schemas. Event definitions serve as contracts for custom event payloads used with `ctx.emit()` and `kiciEvent()`.
+
+### defineEvent(name, schema)
+
+```typescript
+function defineEvent<T extends z.ZodTypeAny>(name: string, schema: T): EventDefinition<T>;
+```
+
+**Parameters:**
+
+| Parameter | Type        | Required | Description                       |
+| --------- | ----------- | -------- | --------------------------------- |
+| `name`    | `string`    | yes      | Unique event name                 |
+| `schema`  | `z.ZodType` | yes      | Zod schema for payload validation |
+
+**Returns:** `EventDefinition<T>` -- a frozen event definition with `name` and `schema`.
+
+```typescript
+import { defineEvent, z } from '@kici-dev/sdk';
+
+const deployComplete = defineEvent(
+  'deploy-complete',
+  z.object({
+    env: z.string(),
+    version: z.string(),
+    services: z.array(z.string()),
+  }),
+);
+```
+
+The `z` (Zod) module is re-exported from `@kici-dev/sdk` so you can define event schemas without adding Zod as a direct dependency.
+
+## Emitting events
+
+Workflow steps can emit custom events via `ctx.emit()`. Emitted events are delivered immediately (mid-workflow, not queued until completion) and can trigger other workflows that listen with `kiciEvent()`, `workflowComplete()`, or `jobComplete()` triggers.
+
+### ctx.emit(eventName, payload?, options?)
+
+```typescript
+emit(
+  eventName: string,
+  payload?: Record<string, unknown>,
+  options?: EventEmitOptions,
+): Promise<{ deliveryId: string }>;
+```
+
+**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 |
+
+**Returns:** `Promise<{ deliveryId: string }>` -- a delivery receipt after the event is persisted and routed.
+
+**Examples:**
+
+```typescript
+// Emit a simple event
+step('notify', async (ctx) => {
+  await ctx.emit('deploy-complete', { env: 'prod', version: '1.2.3' });
+});
+
+// Cross-repo targeting
+step('notify-other-repos', async (ctx) => {
+  await ctx.emit(
+    'deploy-complete',
+    { env: 'prod' },
+    {
+      target: { repos: ['org/other-repo', 'org/monitoring'] },
+    },
+  );
+});
+```
+
+### Cross-repo event delivery
+
+Events emitted from one repo can trigger workflows in another repo, provided:
+
+1. A trust relationship exists between the source and target repos (configured via the admin API)
+2. The target workflow uses a trigger with `source` filter matching the emitting repo
+
+```typescript
+// In repo A: emit event
+step('deploy', async (ctx) => {
+  await ctx.emit(
+    'deploy-complete',
+    { env: 'prod' },
+    {
+      target: { repos: ['org/repo-B'] },
+    },
+  );
+});
+
+// In repo B: listen for event from repo A
+workflow('post-deploy', {
+  on: kiciEvent({ name: 'deploy-complete', source: 'org/repo-A' }),
+  jobs: [postDeployJob],
+});
+```
+
+### System events
+
+The orchestrator automatically emits system events for workflow and job completions. You do not need to call `ctx.emit()` for these -- they are generated by the orchestrator after execution. Listen for them with `workflowComplete()` and `jobComplete()` triggers.
+
+---
+
+## 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 five pages by topic.
+
+| 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.                                                                                           |
+
+The `@kici-dev/sdk` package re-exports the entire surface from a single entry point. Pick what you need:
+
+```typescript
+import { workflow, job, step, pr, push, rule, defineEvent } from '@kici-dev/sdk';
+```
+
+For the complete list of every named export (factory functions, triggers, rules, validation, hook factories, types), see the per-topic pages above.
+
+## See also
+
+- [Getting started](https://docs.kici.dev/user/getting-started/) -- install the SDK, write your first workflow, test locally
+- [CLI reference](https://docs.kici.dev/user/cli-reference/) -- compile, test, and manage workflows from the command line
+- [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
+
+---