@kici-dev/compiler 0.1.27 → 0.2.0

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

@@ -0,0 +1,2013 @@
+# KiCI SDK reference: runtime and advanced
+
+This bundle covers: Runtime and advanced authoring: step runtime context, event payloads, host fan-out, idempotent steps, caching, artifacts, waiting.
+
+## Artifacts
+
+Source: https://docs.kici.dev/user/sdk/artifacts/
+
+An **artifact** is a named, durable build output — a compiled binary, a bundle, a report — that one job produces and a later job (or a human) consumes. `ctx.artifacts.upload(name, paths)` packs the given files and stores them under a name; `ctx.artifacts.download(name, destDir?)` retrieves them in a later job of the same run. Uploaded artifacts also appear on the run detail page, where anyone with access can download them.
+
+```ts
+import { workflow, job } from '@kici-dev/sdk';
+
+const build = job('build', {
+  runsOn: 'kici:os:linux',
+  run: async (ctx) => {
+    await ctx.$`npm run build`;
+    // Pack ./dist and upload it as the "app" artifact.
+    await ctx.artifacts.upload('app', ['dist']);
+  },
+});
+
+const publish = job('publish', {
+  runsOn: 'kici:os:linux',
+  needs: [build],
+  run: async (ctx) => {
+    // Download what `build` produced, into the working directory.
+    await ctx.artifacts.download('app');
+    await ctx.$`ls dist && ./scripts/publish.sh`;
+  },
+});
+
+export default workflow('release', {
+  on: [/* triggers */],
+  jobs: [build, publish],
+});
+```
+
+## The API
+
+```ts
+interface ArtifactsApi {
+  /** Pack `paths` and upload them as `name`. Returns the packed size + sha256. */
+  upload(name: string, paths: string[]): Promise<{ size: number; sha256: string }>;
+  /** Download `name` (uploaded by an earlier job of this run) into destDir
+   *  (default: the step's working directory). Returns the size + sha256. */
+  download(name: string, destDir?: string): Promise<{ size: number; sha256: string }>;
+}
+```
+
+- **`name`** is a short token of letters, digits, `.`, `_`, and `-` (up to 128 chars), and cannot be made only of dots. It is how a downstream job addresses the artifact. A name that breaks the rule fails the step with the reason — `invalid artifact name`, plus which part of the rule it broke — rather than being quietly rewritten. The orchestrator enforces the same rule when it receives the upload and reports it with the same sentence, so the error reads the same whichever side caught it.
+- **`paths`** are repo-root-relative or `~`-prefixed, exactly like [cache paths](https://docs.kici.dev/user/sdk/caching/) — the same packing, path-safety, and multi-root anchoring apply. Absolute paths and `..` escapes are rejected.
+- **`destDir`** on download defaults to the step's working directory; pass an explicit directory to extract elsewhere.
+
+Both methods verify the content hash end to end: the SHA-256 computed at upload is checked again when the tarball is downloaded, so a corrupted transfer fails loudly.
+
+`upload()` returns only once the orchestrator confirms it recorded the artifact. If that commit cannot be completed — the uploaded object never landed, or the orchestrator's storage or database is unreachable long enough for its retries to run out — the step fails with that reason instead of returning successfully. So a green upload step always means a downstream job can download the artifact. The reason names which kind of failure it was, not the orchestrator's internal error text — an internal commit failure is one to take to whoever runs the orchestrator, who can read the details in its logs.
+
+A connection blip while that confirmation is in flight does not fail the step. Recording the artifact is idempotent, so the agent re-sends the confirmation once the connection is back and waits for the answer, within the same overall deadline it already had. If the connection never comes back in time, the step still fails — and says the artifact may nevertheless have been recorded, so you know to check the run's artifacts before assuming the upload was lost.
+
+## Immutable per run
+
+The **first upload of a name within a run wins.** A second `upload('app', ...)` in the same run — from a retry, a parallel writer, or a copy-paste — fails with a clear error rather than silently overwriting the first. This makes artifacts a deterministic contract between jobs: once `build` has uploaded `app`, every downstream job that downloads `app` gets exactly those bytes.
+
+Downloading a name that was never uploaded in the run throws a not-found error.
+
+## Viewing artifacts in the dashboard
+
+Every artifact a run uploads is listed on the run detail page under the **Artifacts** tab, with its name, the job that produced it, size, content hash, and creation time. Anyone with read access to the run can download an artifact directly from there — a link straight to the stored object, so the bytes never pass through the control plane.
+
+<!-- help:run-artifacts#viewing-artifacts-in-the-dashboard -->
+
+The **Artifacts** tab lists every named build artifact this run uploaded with `ctx.artifacts.upload`.
+
+Each row shows the artifact name, the job that produced it, its size, content hash, and creation time.
+
+Use **Download** to fetch an artifact directly — the link points straight at the stored object. Artifacts expire after the orchestrator's configured retention, after which they no longer appear here.
+<!-- /help:run-artifacts -->
+
+## From the CLI
+
+You can also list and fetch a run's artifacts from a terminal:
+
+- `kici runs artifacts list <run-id>` — the same rows the dashboard **Artifacts** tab shows (`--json` for machine-readable output).
+- `kici runs artifacts download <run-id> [name]` — download one artifact, or every artifact of the run if you omit the name. Each one extracts into its own `<name>/` directory; `--archive` keeps the raw `.tar.gz` and `-o <dir>` sets the target directory.
+
+Like the dashboard download, the bytes stream straight from object storage over a short-lived signed URL and never pass through the control plane — and the CLI verifies the content hash end to end. See the [CLI reference](https://docs.kici.dev/user/cli/runs-and-approvals/#kici-runs-artifacts-list) for the full flag list.
+
+## Artifacts vs cache vs outputs
+
+KiCI gives you three ways to move data between jobs. They look similar but solve different problems:
+
+| Mechanism     | Addressed by             | Lifetime                              | Use it for                                                           |
+| ------------- | ------------------------ | ------------------------------------- | -------------------------------------------------------------------- |
+| **Outputs**   | job/step name (`needs`)  | the run                               | small JSON values — a version string, a computed flag, a list of ids |
+| **Cache**     | a content key you choose | shared across runs, eviction-tolerant | recomputable speedups — a package store, a toolchain, a build cache  |
+| **Artifacts** | a name you choose        | this run, durable + downloadable      | deliverables — a built binary, a bundle, a test report               |
+
+- Reach for **[outputs](https://docs.kici.dev/user/sdk/core/#job-dependencies-needs)** when the value is small and structured (it rides the `needs` graph as JSON).
+- Reach for **[cache](https://docs.kici.dev/user/sdk/caching/)** when the data is a recomputable speedup keyed by its inputs (a cache miss just recomputes; entries are evicted under quota).
+- Reach for **artifacts** when the data is a _deliverable_ that a later job or a person needs verbatim — something you would be unhappy to see silently recomputed or evicted.
+
+## Limits
+
+An orchestrator enforces a few limits, each surfaced as a clear step error when hit:
+
+- A **per-artifact size cap** (1 GiB by default).
+- A **per-run count cap** (50 artifacts by default).
+- A **per-org storage quota** (20 GiB by default) across all non-expired artifacts.
+- An **expiry** (30 days by default) after which an artifact is no longer downloadable or listed.
+
+Operators can raise or lower the quota and expiry per organization; see the [orchestrator storage layout](https://docs.kici.dev/operator/orchestrator/storage-layout/#artifacts) for the operator-facing knobs.
+
+When an upload or download fails for a reason that is **not** one of these limits — the orchestrator has no artifact storage configured, or it could not service the request — the step error says exactly that, instead of reporting a quota rejection or a missing artifact. So an error that names a limit really is a limit you can act on, and an error that names an orchestrator problem is one to take to whoever runs it.
+
+---
+
+## 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
+
+---
+
+## 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).                                                                                                                                    |
+| `changedFilesStatus?` | `import('@kici-dev/engine').ChangedFilesStatus` | Availability of `changedFiles` — `fetched` (real diff), `unavailable` (no diff / could not compute), or `skipped` (orchestrator did not fetch; the agent recomputes from its clone). |
+| `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: 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.                                                                                                                          |
+| `RunsOnPick`      | Single-agent selection policy when several agents match a `runsOn` selector: `'deterministic'` (stable hash — same job lands on the same host across re-runs) or `'any'` (spread load). See [runsOnAll](https://docs.kici.dev/user/sdk/runs-on-all/#targeting-by-pattern) for the fan-out forms.              |
+| `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 23 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 }`                                                                 |
+| `AgentInfo`           | Facts about the pinned agent (`hostname`, `labels`, `platform`, `arch`), set on `runsOnAll` fan-out jobs         |
+| `FanoutPosition`      | Position of a child within its fan-out (host or matrix), deterministically ordered                               |
+| `MatrixJobOutputs`    | Envelope returned by `jobOutputs()` for a matrix upstream: `{ byMatrix, merged }`                                |
+| `HostJobOutputs`      | Envelope returned by `jobOutputs()` for a `runsOnAll` upstream, keyed per host                                   |
+| `RepoInfo`            | Repository metadata available in step context                                                                    |
+| `StepSecrets`         | Async accessor interface for step secrets (`get`, `expose`, `has`, `getMeta`, `list`, `mountFile`, `exposeFile`) |
+| `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;
+  /** Aborted when this step should stop early (job cancelled, job timeout, fail-fast sibling) */
+  signal: AbortSignal;
+  /** Typed inputs from dependency step outputs */
+  inputs: TInputs;
+  /** Validated workflow-dispatch inputs declared via `dispatch({ inputs })` */
+  dispatchInputs: Readonly<Record<string, string | number | boolean | null>>;
+  /** Current workflow metadata */
+  workflow: WorkflowInfo;
+  /** Current job metadata */
+  job: JobInfo;
+  /** Matrix values for current job instance (undefined without matrix) */
+  matrix?: MatrixValues;
+  /** Hostname of the pinned agent — set only on `runsOnAll` host fan-out */
+  host?: string;
+  /** Facts about the pinned agent — set only on `runsOnAll` host fan-out */
+  agent?: AgentInfo;
+  /** Position of this child within its fan-out (host or matrix); undefined otherwise */
+  fanout?: FanoutPosition;
+  /** Raw webhook payload from the git provider */
+  rawPayload?: Record<string, unknown>;
+  /** Which git provider triggered this workflow (e.g. 'github', 'gitlab') */
+  provider?: string;
+  /** Whether this execution was triggered by `kici run remote` (developer-initiated remote run) */
+  isTestRun: boolean;
+  /** Registering repo of a global workflow (undefined for non-global workflows) */
+  workflowRepo?: RepoInfo;
+  /** Repo where the triggering event occurred (undefined for non-global workflows) */
+  sourceRepo?: RepoInfo;
+  /** The resolved context name for this job (undefined for jobs without a context) */
+  context?: string;
+  /** Secrets resolved for this job's context. Never injected into env automatically. */
+  secrets: StepSecretsTyped;
+  /** Emit a custom event that can trigger other workflows — typed or ad-hoc by name */
+  emit<T extends z.ZodTypeAny>(
+    definition: EventDefinition<T>,
+    payload: z.infer<T>,
+    options?: EventEmitOptions,
+  ): Promise<{ deliveryId: string }>;
+  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 (fan-out upstreams return an envelope) */
+  jobOutputs<T>(ref: Job<T>): T | MatrixJobOutputs<T> | HostJobOutputs<T>;
+  /** Publish a secret output value from this job (encrypted before leaving the agent) */
+  setSecretOutput(key: string, value: string): void;
+  /** Typed KiCI API — orchestrator queries over WS (e.g. `kici.infrastructure.list()`) */
+  kici: KiciApi;
+  /** Imperative cache API — `cache.restore(spec)` / `cache.save(spec)` */
+  cache: CacheApi;
+  /** Imperative artifacts API — `artifacts.upload(name, paths)` / `artifacts.download(name)` */
+  artifacts: ArtifactsApi;
+  /** Build, sign, and persist a build-provenance attestation for a produced artifact */
+  attestProvenance(opts: AttestProvenanceOptions): Promise<AttestProvenanceResult>;
+  /** Allocate a job-scoped scratch directory, removed automatically when the job ends */
+  mktemp(label?: string): Promise<TempHandle>;
+  /** Allocate a job-scoped scratch file, removed automatically when the job ends */
+  mktempFile(label?: string, opts?: { suffix?: string }): Promise<TempHandle>;
+  /** Upstream needs keyed by job or group name — `needs.<job>.result` / `.status` */
+  needs?: NeedsContext;
+}
+```
+
+### 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 `context` / `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 `context` / `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 your orchestrator from the run context — a step cannot spoof them. Use it to authenticate the build to an external service that trusts the orchestrator'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 signing credentials — the orchestrator mints and signs the token on the step's behalf from its own run records.
+- Only available inside a running job step; calling it outside one (a dynamic-job generator, or the workflow module's top level) rejects with a clear error. `kici run --local` runs are supported: the local dev plane mints dev-signed tokens under the clearly-non-production issuer `kici-local`.
+
+### 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 your orchestrator — 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 an orchestrator-minted identity token, so it is **offline-verifiable** against the orchestrator'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 (a dynamic-job generator, or the workflow module's top level) rejects with a clear error. `kici run --local` runs are supported: the offline local dev plane signs with a dev identity under the clearly-non-production issuer `kici-local`, and those bundles verify against a trust root exported with `kici local trust-root`.
+
+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 context
+
+Each job picks its secret context via the `context` option on `job()`. The orchestrator resolves the context's scoped-secret store at dispatch time, evaluates access rules, and sends the decrypted secrets to the agent:
+
+```typescript
+const deploy = job('deploy', {
+  runsOn: 'linux',
+  context: 'production',
+  steps: [/* ... */],
+});
+
+export default workflow('deploy', {
+  on: push({ branches: 'main' }),
+  jobs: [deploy],
+});
+```
+
+`context` accepts either a static string or an async function `(event) => string | Promise<string>` for dynamic resolution at trigger-evaluation time. The resolved context's secrets are flattened into `ctx.secrets`.
+
+### Accessing secrets (ctx.secrets)
+
+`ctx.secrets` provides flat access to the secrets resolved for the job's context.
+
+```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',
+  context: '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 preview`, you can provide secrets locally without an orchestrator.
+
+#### .kici/.secrets file
+
+Create a `.kici/.secrets` file in your project (auto-gitignored by `kici init`):
+
+```ini
+# Flat secrets (before any section)
+DEPLOY_TOKEN=my-deploy-token
+API_KEY=my-api-key
+
+# Context-scoped secrets
+[production]
+DB_PASSWORD=prod-secret
+API_KEY=prod-key
+
+[npm-publish]
+NPM_TOKEN=npm-abc123
+```
+
+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 preview push --secret DEPLOY_TOKEN=my-token --secret API_KEY=my-key
+
+# Inject context-scoped secrets (repeatable)
+kici preview 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: temp directories
+
+Source: https://docs.kici.dev/user/sdk/temp-directories/
+
+Steps often need a throwaway working directory — somewhere to unpack an archive, stage a build, or write an intermediate file. `ctx.mktemp()` and `ctx.mktempFile()` allocate that scratch space and clean it up for you when the job ends, so you never leak temp trees on the agent.
+
+## ctx.mktemp(label?)
+
+Allocate a scratch **directory** for the current job. Returns a handle:
+
+```typescript
+interface TempHandle {
+  /** Absolute path to the allocated directory (or file, for mktempFile). */
+  readonly path: string;
+  /** Remove the allocation. Idempotent — safe to call more than once. */
+  cleanup(): Promise<void>;
+  /** Enables `await using` — disposes on scope exit. */
+  [Symbol.asyncDispose](): Promise<void>;
+}
+```
+
+```typescript
+step('build', async (ctx) => {
+  const scratch = await ctx.mktemp();
+  await ctx.$`git clone --depth 1 https://example.com/repo.git ${scratch.path}`;
+  await ctx.$`tar -czf out.tgz -C ${scratch.path} .`;
+});
+```
+
+The `label` argument is optional. When omitted it defaults to a sanitized step id, so the directory name carries a hint about which step created it. Pass an explicit label to make it obvious in the temp root:
+
+```typescript
+const cache = await ctx.mktemp('npm-cache');
+// path looks like /tmp/kici-npm-cache-a1b2c3
+```
+
+A label must be lowercase alphanumeric with hyphens (`a-z`, `0-9`, `-`).
+
+## ctx.mktempFile(label?, { suffix? })
+
+Allocate a scratch **file** instead of a directory. Same handle shape; `path` points at an empty file you can write to. Pass `suffix` to give the file an extension:
+
+```typescript
+step('render', async (ctx) => {
+  const config = await ctx.mktempFile('render-config', { suffix: '.json' });
+  await ctx.$`echo ${JSON.stringify({ mode: 'prod' })} > ${config.path}`;
+  await ctx.$`my-tool --config ${config.path}`;
+  // path looks like /tmp/kici-render-config-a1b2c3/render-config.json
+});
+```
+
+## Automatic cleanup
+
+Every allocation from `ctx.mktemp()` / `ctx.mktempFile()` is tied to the job. When the job ends — on **success, failure, or cancellation** — its scratch dirs and files are removed automatically. You do not have to clean up in a `finally` block or worry about a failing step leaving debris behind.
+
+## Manual cleanup
+
+The returned `cleanup()` lets you release a large allocation early, before the job finishes — useful when a later step no longer needs a multi-gigabyte checkout:
+
+```typescript
+step('extract', async (ctx) => {
+  const work = await ctx.mktemp('extract');
+  await ctx.$`tar -xzf big-archive.tgz -C ${work.path}`;
+  await ctx.$`./process.sh ${work.path}`;
+  await work.cleanup(); // free the space now; don't wait for job end
+});
+```
+
+`cleanup()` is **idempotent** — calling it a second time (or letting the automatic job-end cleanup run after you already called it) is a no-op, never an error.
+
+## The `await using` form
+
+Because a handle is an async disposable, you can bind its lifetime to the enclosing scope with `await using`. The directory is removed as soon as the block exits, whether it returns normally or throws:
+
+```typescript
+step('sign', async (ctx) => {
+  await using keydir = await ctx.mktemp('gpg-home');
+  await ctx.$`gpg --homedir ${keydir.path} --import key.asc`;
+  await ctx.$`gpg --homedir ${keydir.path} --detach-sign artifact.tar`;
+  // keydir is disposed here, at the end of the block
+});
+```
+
+This is the tidiest form when a scratch dir is only needed for a bounded section of a step and you want it gone the moment you are done with it — you get the same guaranteed cleanup as a `try/finally` without the boilerplate.
+
+## See also
+
+- [SDK reference: runtime](https://docs.kici.dev/user/sdk/runtime/) — the full `StepContext` surface (`$`, `log`, `env`, `secrets`, and more).
+- [Artifacts](https://docs.kici.dev/user/sdk/artifacts/) — for durable, named build deliverables that outlive the job, use `ctx.artifacts` instead of a temp dir.
+
+---
+
+## 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.
+
+---