@kici-dev/compiler 0.5.0 → 0.6.0

package/dist/llm-context/llms-getting-started.txt

@@ -76,6 +76,8 @@ Trigger matching can query the **contents** of individual source files, not just
 
 The orchestrator also does **not** run `dynamicJob` generator bodies itself: for the event-only (function) form it dispatches a dedicated dynamic-evaluation job to an agent at event time; the generator function then runs agent-side (see below).
 
+A workflow-level `filter` predicate is the same shape: the orchestrator sees only the lock's `hasFilter` flag, never the predicate, so it dispatches an evaluation job and lets an agent decide whether the workflow applies. Prefer the declarative filters where they answer the question — `commitMessage` on the trigger and `requires` over source files cost no evaluation job at all.
+
 See [dynamic values](https://docs.kici.dev/user/dynamic-values/) for how dynamic `context`, `env`, and `concurrencyGroup` functions resolve.
 
 ## Agent time
@@ -86,20 +88,33 @@ After dispatch, each job runs in its own ephemeral agent sandbox: a shallow clon
 2. **Step-level rules**, then each step's `run()` body and its hooks.
 3. **Dynamic values** (`context`, `env`, `concurrencyGroup` functions) are resolved here, via a short `__init__` job that runs the function before the real job runs; this shows in the run timeline as an `Init:` entry.
 4. **`dynamicJob` generators run here — both forms.** The event-only (function) form runs in a dedicated evaluation job dispatched at event time; the result-aware (options) form is deferred until its declared `needs` complete, then run with the upstream outputs frozen as `ctx.needs`.
+5. **A workflow-level `filter` predicate runs here too**, before the jobs it gates. A global workflow evaluates it once per (event × workflow repo), before any run row exists, so a `false` verdict leaves no run at all. A same-repo workflow evaluates it once per job that reaches dispatch and once per job generator, after the run row exists, so a `false` verdict leaves a run whose only entries are the evaluation jobs. Keep the predicate cheap, pure, and side-effect free — a ten-job workflow calls it ten times for one event. See [narrowing with a filter](https://docs.kici.dev/user/global-workflows/#narrowing-with-a-filter).
 
 See [job execution](https://docs.kici.dev/architecture/execution/job-execution/) and [hooks and rules](https://docs.kici.dev/user/hooks/) for the details.
 
+## How a reused agent stays clean between jobs
+
+An ephemeral agent is discarded after one job, so residue never matters. A **reused agent** — a long-lived process on a shared host (the bare-metal profile) — serves many jobs in turn. Between them, the agent runs a supervisor-owned cleanup phase so one job's leftovers never reach the next:
+
+1. **It reaps the finished job's process tree.** A step may background a daemon that outlives the job. The agent runs each job's process in its own process group and signals the whole group when the job ends, so a stray daemon does not survive into the next job. Set `KICI_AGENT_ORPHAN_CLEANUP=false` to keep only the runner and leave a backgrounded process alive on purpose.
+2. **It re-runs declared cleanup after a hard kill.** A job's `cleanup` / `onFailure` hooks normally run in the job process. If that process is killed hard (out of memory, forced stop), the agent re-runs the declared cleanup against the preserved work directory.
+3. **It deletes the work directory.**
+4. **It runs an optional operator reset command.** Set `KICI_AGENT_BETWEEN_JOBS_RESET_COMMAND` to a host-reset command (for example, pruning a container cache). It runs after the reap and work-directory deletion. A failure never fails the finished job.
+
+This phase is the primary cross-job cleanup. The agent's startup temp-directory sweep stays as a backstop for anything a between-jobs phase missed. See [agent configuration](https://docs.kici.dev/operator/agent/configuration/) for the full env-var reference.
+
 ## What re-evaluates where
 
-| Construct                    | Runs on          | When                            |
-| ---------------------------- | ---------------- | ------------------------------- |
-| Static value                 | Compile → lock   | Never re-evaluated              |
-| Dynamic value                | Agent init step  | Per event                       |
-| Job-level rules              | Agent            | After clone                     |
-| Step-level rules             | Agent            | Per step                        |
-| `dynamicJob` (function form) | Agent (eval job) | Dispatched at event time        |
-| `dynamicJob` (options form)  | Agent            | Deferred until `needs` complete |
-| Step / job body + hooks      | Agent            | Per job                         |
+| Construct                    | Runs on          | When                                                 |
+| ---------------------------- | ---------------- | ---------------------------------------------------- |
+| Static value                 | Compile → lock   | Never re-evaluated                                   |
+| Dynamic value                | Agent init step  | Per event                                            |
+| Job-level rules              | Agent            | After clone                                          |
+| Step-level rules             | Agent            | Per step                                             |
+| `dynamicJob` (function form) | Agent (eval job) | Dispatched at event time                             |
+| `dynamicJob` (options form)  | Agent            | Deferred until `needs` complete                      |
+| Workflow `filter` predicate  | Agent (eval job) | Per event (global) / per job + generator (same-repo) |
+| Step / job body + hooks      | Agent            | Per job                                              |
 
 **Determinism note.** `ctx.event` and `ctx.needs` are frozen snapshots — captured once and replayed unchanged on any re-evaluation. A generator that derives its output from them is stable across re-evaluations; one that reads the wall clock (`Date.now()`) or a random source (`Math.random()`) is not.
 
@@ -149,6 +164,124 @@ Outputs are typed across the job boundary too: reading `jobRef.result.…` or `c
 
 ---
 
+## Getting help
+
+Source: https://docs.kici.dev/user/getting-help/
+
+When something goes wrong, the fastest path to a fix is a report that already
+carries the context. This page covers what to try first, what to send, and how
+to send it privately.
+
+## Diagnose it yourself first
+
+Two commands answer most problems without anyone else involved:
+
+```bash
+# Check your own setup: login, org, lock file, orchestrator, agent labels
+kici doctor
+
+# Look at the org's infrastructure: orchestrators, scalers, agents
+kici diagnostics
+```
+
+`kici doctor` prints the next command to run for each problem it finds. Work
+down its output before reporting — a stale lock file or an expired login is a
+one-command fix.
+
+If your workflow ran and failed, read its logs:
+
+```bash
+kici runs show <run-id>
+kici runs logs <run-id>
+```
+
+[Common failures](https://docs.kici.dev/user/common-failures/) covers the errors people hit most.
+
+## Report a problem
+
+When you cannot resolve it yourself, gather a diagnostic bundle:
+
+```bash
+kici report --run <run-id> --message "what you expected, and what happened"
+```
+
+The command writes a ZIP and prints its path and `sha256`. It sends nothing.
+The bundle holds:
+
+- your CLI, Node, and orchestrator versions,
+- your redacted KiCI configuration,
+- your project's workflow list and lock-file state,
+- the failing run's detail and logs, when you pass `--run`,
+- a collection report saying which of those the command could and could not
+  read.
+
+Open the file and read it. It is yours until you decide to share it.
+
+### What gets redacted
+
+KiCI removes known secret shapes before anything enters the bundle:
+
+- API keys and access tokens (AWS, GitHub, Slack, KiCI agent tokens),
+- `Authorization` headers and JSON web tokens,
+- passwords inside connection URLs,
+- private keys and encrypted-value blocks,
+- values assigned to a secret-named key, such as `api_key=` or `password=`.
+
+Configuration is redacted twice: an allowlist keeps only known-safe fields, and
+the free-text scrubber runs over what remains.
+
+**Redaction is best effort.** A secret in a format KiCI does not recognize can
+survive it. Review the bundle before you share it. `--no-redact` turns
+redaction off and prints a warning — use it only for a bundle you keep.
+
+## Send it privately
+
+Reports contain your data, so there is no public tracker for them. Add
+`--upload` to send the bundle to KiCI directly:
+
+```bash
+kici report --run <run-id> --upload --message "matrix job hangs on macOS"
+```
+
+The command prints a reference id. Quote it in any conversation about the
+problem. The bundle goes straight from your machine to KiCI storage over a
+one-time upload link — it never passes through the dashboard.
+
+Add `--email` if you want a reply address attached to the report.
+
+## Manage what you have sent
+
+An upload is not permanent, and it is yours to revoke:
+
+```bash
+# See the reports you have uploaded
+kici report list
+
+# Delete an uploaded bundle
+kici report withdraw <ref>
+```
+
+Uploaded bundles expire automatically after 90 days.
+
+Anyone in your organization can upload a report. By default you see and
+withdraw your own. A member with the `support:admin` permission can manage
+every report in the organization, which is how an owner cleans up on behalf of
+someone who has left.
+
+## Reporting a security issue
+
+Do not use `kici report` for a suspected vulnerability. Follow the disclosure
+process in [SECURITY.md](https://github.com/kici-dev/kici/blob/master/SECURITY.md)
+instead.
+
+## See also
+
+- [Common failures](https://docs.kici.dev/user/common-failures/) — the errors people hit most, and their fixes
+- [CLI reference](https://docs.kici.dev/user/cli-reference/) — every `kici` command
+- [Dashboard](https://docs.kici.dev/user/dashboard/) — inspecting runs in the browser
+
+---
+
 ## Getting started with workflows
 
 Source: https://docs.kici.dev/user/getting-started/
@@ -171,11 +304,11 @@ npx kici init
 
 This will:
 
-1. Create `.kici/` directory with `workflows/`, `tests/`, `types/`, `package.json`, and `tsconfig.json`
+1. Create `.kici/` directory with `workflows/`, `tests/`, `types/`, `package.json`, and `tsconfig.json`. The `types/` folder holds a local development aid — TypeScript declarations that `kici types` (and an authenticated `kici compile`) generate from your orchestrator's secret contexts. Its content is a snapshot of one org's secret keys, so it is not committed.
 2. Create a `.kiciignore` file with sensible defaults
 3. Let you choose from starter workflow templates (hello-world, pr-checks)
 4. Install dependencies using the package manager detected for your repo (npm, pnpm, or yarn)
-5. Update `.gitignore` to exclude `.kici/node_modules/`
+5. Update `.gitignore` to exclude `.kici/node_modules/`, and write `.kici/.gitignore` to keep the generated `types/` declarations untracked (`kici.lock.json` stays tracked — the orchestrator fetches it from your repo)
 6. Optionally install a pre-commit hook to auto-compile workflows
 
 The package manager is detected from your repo's `packageManager` field, lockfile, or the manager that invoked `kici`, defaulting to npm. Pass `--package-manager <npm|pnpm|yarn>` to override it.
@@ -496,7 +629,7 @@ For coding agents that want the entire documentation set up front, KiCI follows
 
 - `https://kici.dev/llms.txt` — curated link index grouped by SDK / patterns / CLI / architecture.
 - `https://kici.dev/llms-full.txt` — concatenated markdown of every page indexed above.
-- `kici docs llm` — print the same `llms-full.txt` bundle to stdout, offline, straight from the installed `@kici-dev/compiler` package. Add `--index` to print the curated `llms.txt` index instead. The agent can pipe the output into its own context buffer with no network call.
+- `kici docs llm` — print the same curated `llms.txt` index to stdout, offline, straight from the installed `@kici-dev/compiler` package. `kici docs llm <topic>` prints one task bundle (`getting-started`, `patterns`, `sdk`, `sdk-runtime`, `cli`, `features`, `features-execution`, `providers`, `architecture`), and `kici docs llm full` prints the whole `llms-full.txt`. Add `--out <path>` to write to a file. The agent can pipe the output into its own context buffer with no network call.
 - `kici docs` — open the docs site in your browser.
 
 The offline bundle is regenerated from `docs/` every time the package is built, so it always matches the version of KiCI you've installed.

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

@@ -577,6 +577,181 @@ This workflow:
 
 ---
 
+## Git credentials
+
+Source: https://docs.kici.dev/user/patterns/git-credentials/
+
+Two facts drive everything on this page, and neither is guessable:
+
+- **Cloning your own repository needs no credential.** The framework checks it
+  out for you, and the app KiCI installs already holds read access.
+- **Pushing always needs a credential you supply.** The KiCI app holds read
+  access only, so every push — including to the job's own repository — needs one.
+
+## Declare credentials once, by name
+
+Credentials are declared on the job as a named map. **Every value is the name of
+a secret**, in `<context>:<secret-name>` form — never the credential itself:
+
+```typescript
+job('release', {
+  runsOn: 'linux',
+  gitCredentials: {
+    // `default` is used whenever a call names no credential
+    default: {
+      kind: 'app',
+      appIdSecret: 'ci:ACME_APP_ID',
+      installationIdSecret: 'ci:ACME_INSTALL_ID',
+      privateKeySecret: 'ci:ACME_APP_KEY',
+    },
+    forge: { kind: 'token', tokenSecret: 'ci:FORGE_PAT' },
+    vendor: { kind: 'ssh', privateKeySecret: 'ci:VENDOR_DEPLOY_KEY' },
+  },
+  steps: [build, tagAndPush],
+});
+```
+
+Store the secrets first with `kici-admin secret set`. Pasting a private key
+straight into the workflow is rejected when the workflow is defined, naming the
+field — a key written into `.kici/` would be committed to your repository.
+
+## Push
+
+Your checkout is read-only by default. Opening a write window is explicit:
+
+```typescript
+step('tag', async ({ $, repo }) => {
+  await $`git tag v${version}`;
+  await repo.withWrite({ permissions: { contents: 'write' } }, async () => {
+    await $`git push origin v${version}`;
+  });
+});
+```
+
+Inside the callback, git operations on that repository use a write credential.
+Outside it they do not, so an accidental push elsewhere in the job fails.
+
+Pass `credential: 'forge'` to use a named entry instead of `default`.
+
+**KiCI never guesses the permission set.** What a push needs depends on what is
+being pushed — changing anything under `.github/workflows/` additionally requires
+`workflows`:
+
+```typescript
+await repo.withWrite({ permissions: { contents: 'write', workflows: 'write' } }, async () => {
+  await $`git push origin HEAD`;
+});
+```
+
+If the app was not granted a permission you request, the forge refuses to issue
+the credential at all. The error names the repository and the permissions you
+asked for, **before any git command runs** — not at the end of a long build.
+
+## Clone more than one repository
+
+A workflow often needs several repositories, not just its own. Mint one token
+that covers all of them, then clone each with it:
+
+```typescript
+const { token } = await kici.git.github.getToken({
+  repositories: ['acme/app', 'acme/shared-lib'],
+  permissions: { contents: 'read' },
+});
+
+for (const repo of ['acme/app', 'acme/shared-lib']) {
+  await $`git clone https://x-access-token:${token}@github.com/${repo}.git`;
+}
+```
+
+A GitHub App token is issued per installation, so one call covers every
+repository you name. Each repository must be inside the app's installation. If
+one is not, the forge refuses the whole request and the error names it.
+
+The credential helper is installed on your own checkout only, so a repository
+you clone yourself does not inherit it. That is why this case mints a token
+rather than relying on the helper.
+
+## Call the forge API
+
+`gh` does not read git credential helpers, so this is the one case that wants the
+token as a value:
+
+```typescript
+const { token } = await kici.git.github.getToken({
+  repositories: ['acme/app'],
+  permissions: { contents: 'write' },
+});
+await $({ env: { ...process.env, GH_TOKEN: token } })`gh release create v${version}`;
+```
+
+The token is masked in step logs. Prefer `withWrite` for git itself, which never
+places a credential in the step environment.
+
+## Credentials that only exist at run time
+
+A credential fetched during the run — from a vault, or a cloud secret store via
+the job's OIDC identity — cannot be named ahead of time. Use the `*Value` half of
+the pair, which says "this is the credential, not a name for one":
+
+```typescript
+gitCredentials: { default: { kind: 'token', tokenValue: fetchedAtRuntime } }
+```
+
+To pass a derived credential to a **later** job, publish it with
+`ctx.setSecretOutput()` and name it with the reserved `needs:` context — that
+path is encrypted, scoped to the run, and deleted when the run ends:
+
+```typescript
+const mint = job('mint', {
+  runsOn: 'linux',
+  run: async (ctx) => {
+    const token = (await ctx.$`vault write -f auth/token/create`).stdout.trim();
+    ctx.setSecretOutput('FORGE_TOKEN', token);
+  },
+});
+
+const build = job('build', {
+  runsOn: 'linux',
+  needs: [mint],
+  gitCredentials: { default: { kind: 'token', tokenSecret: 'needs:FORGE_TOKEN' } },
+  steps: [cloneAndPush],
+});
+```
+
+Never put a credential in a regular job output: regular outputs are not masked,
+are stored, and are shown in the dashboard.
+
+For a **minted app token**, prefer re-deriving over transporting — those expire
+after an hour, so one minted in an earlier job is often already dead by the time
+a later job reads it. Have the later job name the same secret, or mint its own.
+
+## How it works, and why long jobs still push
+
+An app token expires an hour after it is issued, and cannot be renewed. Rather
+than capture one at checkout time, the agent installs a git credential helper on
+the checkout: git asks it on every network operation, and it obtains a fresh
+credential each time. A push at the end of a three-hour build works exactly as it
+does at the start, and no credential is ever written into `.git/config`, into
+`git remote -v`, or into the step's environment.
+
+## Limits worth knowing
+
+- **Container jobs cannot use this yet.** A container job runs git inside the
+  container, which has no route to the credential service. Bare-metal jobs are
+  unaffected.
+- **The reserved `needs:` context is not resolvable yet** on a deployed
+  orchestrator; naming it produces a clear error rather than a wrong credential.
+- **A write window is bounded by the repository and the callback, not the step.**
+  Steps running concurrently in the same job can push to the same repository
+  while it is open. They cannot reach a different one.
+- **A credential you supply yourself cannot be narrowed.** A personal access
+  token or SSH key grants whatever it was created with, so a requested permission
+  set is reported as unscoped rather than pretended to be enforced.
+- **Being allowed to push is not the same as the push succeeding.** A branch
+  protection rule or repository ruleset can still reject it.
+
+---
+
 ## Host restart & wait-for-alive
 
 Source: https://docs.kici.dev/user/patterns/host-restart/
@@ -939,7 +1114,7 @@ export default workflow('on-forgejo-push', {
 **Caveat — cloning:** generic webhook sources deliver only the payload; they do not carry a clone token, and KiCI's automatic pre-step clone (`packages/agent/src/checkout/git-clone.ts`) is GitHub-only today (HTTPS + `http.extraHeader` Basic auth with a GitHub installation token). Three practical patterns:
 
 - **Mirror to GitHub and fan out.** Keep the repo on GitHub, register the workflow via a GitHub default-branch push, and have Gogs/Forgejo webhooks fan out via [cross-source delivery](https://docs.kici.dev/architecture/webhooks/webhook-delivery/#cross-source-delivery). The clone runs against the GitHub mirror using the GitHub App's token.
-- **Clone yourself using a secret.** Set `checkout: false` on the job to skip the framework clone, store an SSH private key or forge personal access token as a secret, and run `git clone` explicitly in the first step. This works for any forge the agent can reach, no mirror needed. You still need a way to **register** the workflow — either keep a one-file GitHub repo whose only job is to own the registration, or bootstrap the registration manually against the orchestrator DB.
+- **Clone yourself using a declared credential.** Set `checkout: false` on the job to skip the framework clone, declare the forge credential on the job as a named `gitCredentials` entry (values are **secret names**, never the credential), and run `git clone` in the first step — the agent authenticates it for you, and the credential never appears in workflow source. See [Git credentials](https://docs.kici.dev/user/patterns/git-credentials/). This works for any forge the agent can reach, no mirror needed. You still need a way to **register** the workflow — either keep a one-file GitHub repo whose only job is to own the registration, or bootstrap the registration manually against the orchestrator DB.
 - **Self-contained workflow.** No clone at all. The step reads whatever it needs from `rawPayload` (e.g., `rawPayload.after`, `rawPayload.repository.clone_url`) and drives external systems — notifications, deploys, third-party CI triggers.
 
 Manual-clone example (pattern 2) using an SSH deploy key:

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

@@ -144,38 +144,22 @@ the manifest flow — follow these steps.
 
 5. **Pick permissions.** Minimum required:
 
-   | Scope                       | Access       | Why                                                                                                                                                       |
-   | --------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-   | Repository -> Contents      | Read         | Clone the repo to read the lock file                                                                                                                      |
-   | Repository -> Metadata      | Read (auto)  | Default for every App; also lets KiCI look up a pull-request author's repository access level for CI trust                                                |
-   | Repository -> Pull requests | Read         | Match `pull_request` triggers                                                                                                                             |
-   | Repository -> Checks        | Read & write | Post KiCI's enriched Check runs                                                                                                                           |
-   | Organization -> Members     | Read         | (optional, org installs) Receive `organization` / `membership` / `team` events so KiCI's CI-trust permission cache invalidates promptly on access changes |
-
-   The first four rows cover the core flow (clone, trigger matching,
-   Check runs). The **Organization -> Members** row is only relevant if
-   you use [CI trust tiers](https://docs.kici.dev/architecture/security/ci-security/)
-   on an org-level install — see the event note below.
+   | Scope                       | Access       | Why                                  |
+   | --------------------------- | ------------ | ------------------------------------ |
+   | Repository -> Contents      | Read         | Clone the repo to read the lock file |
+   | Repository -> Metadata      | Read (auto)  | Default for every App                |
+   | Repository -> Pull requests | Read         | Match `pull_request` triggers        |
+   | Repository -> Checks        | Read & write | Post KiCI's enriched Check runs      |
+
+   Those four cover the whole flow: clone, trigger matching, Check runs.
+   [CI trust](https://docs.kici.dev/architecture/security/ci-security/) needs no
+   permission of its own — it reads the fork relationship straight out of
+   the webhook payload and calls no GitHub API.
 
 6. **Subscribe to events.** At minimum: `push`, `pull_request`,
    `check_run`, `check_suite`. Add others (`issues`, `release`, ...) if
    your workflows use those triggers.
 
-   **For CI trust (optional but recommended on org installs):** also
-   subscribe to `member`, `organization`, `membership`, and `team`.
-   KiCI caches each pull-request author's repository access level (used
-   to decide whether workflow changes take effect immediately or are
-   held for approval — see
-   [CI security](https://docs.kici.dev/architecture/security/ci-security/)). These
-   events let the orchestrator drop stale cache entries the moment a
-   contributor's access changes. They are not required for correctness:
-   without them the cache simply ages out on its own 15-minute TTL, so a
-   permission change can take up to 15 minutes to take effect. The
-   `organization` / `membership` / `team` events require the
-   **Organization -> Members** read permission and an org-level
-   installation; `member` is a repository event covered by the default
-   Metadata permission.
-
 7. **Generate a private key.** Scroll to the bottom of the App settings
    and click _Generate a private key_. A `.pem` file downloads —
    store it safely; you cannot redownload it.

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

@@ -109,7 +109,7 @@ An orchestrator enforces a few limits, each surfaced as a clear step error when
 - 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.
+Each of the four is a cluster-wide default an operator can raise or lower 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.
 
@@ -266,7 +266,7 @@ Source: https://docs.kici.dev/user/sdk/event-payloads/
 
 ## 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.
+The normalized event envelope is the single event contract in KiCI. Rules receive it as `ctx.event`, and every dynamic function — `context:`, `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.
 
@@ -712,7 +712,7 @@ export const setup = job('setup', {
 
 ## `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`):
+The check-mode-aware sibling of `idempotentStep()`. It takes a closely related option shape, but behaves differently when a run is started in check mode (`kici run --check`):
 
 | Factory          | Behavior under `kici run --check`         |
 | ---------------- | ----------------------------------------- |
@@ -730,10 +730,16 @@ Use `checkStep()` for deploy-style steps where you want a dry-run preview of pen
 | `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).                                              |
+| `outputs`         | `OutputSchema`                              | No       | Zod schema validating the step's outputs at runtime.                                                |
 | `continueOnError` | `boolean`                                   | No       | When true, the job proceeds even if this step fails.                                                |
 | `timeout`         | `number`                                    | No       | Step-level timeout in milliseconds.                                                                 |
+| `retry`           | `number \| RetryConfig`                     | No       | Retry policy for the step; `retry: N` is shorthand for `{ maxAttempts: N }`.                        |
+| `cache`           | `CacheInput`                                | No       | Declarative cache restored before the step and saved after it succeeds.                             |
+| `rules`           | `Rule[]`                                    | No       | Step-level conditional rules, evaluated agent-side.                                                 |
 
-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`.
+Everything from `outputs` down is a plain [`step()` option](https://docs.kici.dev/user/sdk/core/) forwarded to the underlying step. The three step options `checkStep` does **not** accept are `onCancel`, `cleanup`, and `approval`.
+
+There are two signature differences from `idempotentStep`. First, `apply` and `whenInSync` receive `ctx` as their first argument, so the apply logic has access to `ctx.$`, `ctx.log`, and `ctx.secrets`. Second, `summarize` is **required** here, because it is what check mode prints; `idempotentStep` defaults it to a JSON dump of the drift. `idempotentStep` also takes none of the step-option passthroughs above.
 
 ### Result
 
@@ -841,6 +847,21 @@ const patch = job('patch', {
 });
 ```
 
+### Which hosts are targets
+
+`runsOnAll` targets the hosts you declare as members of your fleet. A host becomes
+a target when it registers with the orchestrator under a stable agent identity, or
+when an operator declares it with `kici-admin host declare`.
+
+Agents that an auto-scaler starts are **not** targets, even when their labels match
+the predicate. An auto-scaler starts an agent at the fixed shape of its pool, so a
+pinned child would run at that shape and not at its own. Auto-scaler agents stay
+available to `runsOn` and to the queue, and `ctx.kici.inventory` continues to list
+them.
+
+The fleet preview and the host detail page in the web UI apply the same rule, so
+they show the hosts a run targets.
+
 ### Input forms
 
 `runsOnAll` accepts three shapes:

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

@@ -961,7 +961,7 @@ Source: https://docs.kici.dev/user/sdk/rules-matrix-dynamic/
 
 Rules control conditional execution of workflows and jobs. A rule that returns `false` (or whose check function returns `false`) prevents execution.
 
-A rule's check function that **returns `false`** cleanly skips the job or step. A check function that **throws** is treated as an evaluation failure, not a skip: the job or step **fails** with the error surfaced (both on a remote run and when running locally with `kici run --local`), so a broken rule can never silently pass as a green run. For example, `rule('main only', (ctx) => ctx.event.ref.endsWith('main'))` throws on an event whose `ref` is undefined — that run fails with the error instead of quietly skipping every step. Fix the thrown error (guard the access) rather than relying on the skip.
+A rule's check function that **returns `false`** cleanly skips the job or step. A check function that **throws** counts as an evaluation failure, not a skip. The job or step **fails** with the error surfaced (both on a remote run and when running locally with `kici run --local`), so a broken rule can never silently pass as a green run. For example, `rule('main only', (ctx) => ctx.event.ref.endsWith('main'))` throws on an event whose `ref` is undefined — that run fails with the error instead of quietly skipping every step. Fix the thrown error (guard the access) rather than relying on the skip.
 
 ### rule(label) / rule(label, check)
 
@@ -2435,6 +2435,36 @@ workflow('post-deploy', {
 
 The orchestrator automatically emits system events for workflow and job completions. You do not need to call `ctx.emit()` for these -- they are generated by the orchestrator after execution. Listen for them with `workflowComplete()` and `jobComplete()` triggers.
 
+### Event scaler events
+
+The [event scaler backend](https://docs.kici.dev/operator/orchestrator/event-scaler/) emits two reserved events that your provisioning and teardown workflows subscribe to. The SDK exports their names and payload schemas, so a workflow imports the contract instead of re-declaring it.
+
+| Export                   | What it is                                                                                                              |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| `SCALER_EVENT_NAMES`     | The two reserved event names: `SCALER_EVENT_NAMES.scaleUp` and `SCALER_EVENT_NAMES.scaleDown`.                          |
+| `ScalerScaleUpPayload`   | Schema of the scale-up payload. `.parse(ctx.rawPayload)` returns the typed payload and rejects a malformed one.         |
+| `ScalerScaleDownPayload` | Schema of the scale-down payload, including the narrowed `reason`.                                                      |
+| `ScaleDownReason`        | Why the scaler asked for a teardown: `idle`, `job-complete`, `heartbeat-timeout`, `spawn-timeout`, `drain`, `shutdown`. |
+
+```ts
+import { workflow, job, kiciEvent, SCALER_EVENT_NAMES, ScalerScaleUpPayload } from '@kici-dev/sdk';
+
+export default workflow('provision', {
+  on: [kiciEvent({ name: SCALER_EVENT_NAMES.scaleUp, match: { '$.scalerName': 'hetzner' } })],
+  jobs: [
+    job('provision', {
+      runsOn: ['kici:os:linux'],
+      run: async (ctx) => {
+        const payload = ScalerScaleUpPayload.parse(ctx.rawPayload);
+        ctx.log.info(`provision agent ${payload.agentId}`);
+      },
+    }),
+  ],
+});
+```
+
+These names are reserved. `ctx.emit()` rejects any event name that starts with `kici.`, so a workflow step cannot forge a scaler event. For every payload field, see the [event contract reference](https://docs.kici.dev/operator/orchestrator/event-scaler-events/). For complete provisioning and teardown workflows, see [autoscaling workflows](https://docs.kici.dev/user/workflows/autoscaling-workflows/).
+
 ---
 
 ## SDK reference