@kici-dev/compiler 0.1.20 → 0.1.22

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

@@ -576,7 +576,7 @@ export default workflow('ci', {
 });
 ```
 
-The `test` and `typecheck` jobs both depend on `lint`, so they run in parallel after lint succeeds. KiCI validates the dependency graph at compile time -- cycles and missing references are caught before you commit. At runtime, jobs are gated on upstream completion: a job only dispatches after every entry in its `needs` array reaches a terminal state. If an upstream fails, downstream jobs skip by default (override per-edge with `ifFailed: 'run'`). See [Job dependencies (`needs`)](../sdk/core.md#job-dependencies-needs) in the SDK reference for the full matrix of `needs` forms (string, `Job` ref, `{ name, ifFailed }`, `dynamicGroup()`) and [needs-scheduler](../../architecture/execution/needs-scheduler.md) for the dispatch semantics.
+The `test` and `typecheck` jobs both depend on `lint`, so they run in parallel after lint succeeds. KiCI validates the dependency graph at compile time -- cycles and missing references are caught before you commit. At runtime, jobs are gated on upstream completion: a job only dispatches after every entry in its `needs` array reaches a terminal status that satisfies the edge. If an upstream fails, downstream jobs skip by default (override per-edge with `when: 'always'`). See [Job dependencies (`needs`)](../sdk/core.md#job-dependencies-needs) in the SDK reference for the full matrix of `needs` forms (string, `Job` ref, `{ name, when }`, `dynamicGroup()`) and [needs-scheduler](../../architecture/execution/needs-scheduler.md) for the dispatch semantics.
 
 **Single-step jobs don't need a `steps` array.** When a job only does one thing, pass `run` to `job()` instead of wrapping it in `steps: [step(...)]`:
 
@@ -1109,6 +1109,116 @@ This workflow:
 
 ---
 
+## Host restart & wait-for-alive
+
+Source: https://docs.kici.dev/user/patterns/host-restart/
+
+When a KiCI agent runs on a host you are provisioning, a workflow can reboot
+that host and resume work once it comes back — the Ansible `reboot` +
+`wait_for_connection` pattern, expressed as two jobs pinned to the same host.
+
+## The two-job pattern
+
+Host restart is a **job-boundary** capability: the reboot is the last step of a
+"restart" job, and the post-restart work lives in a **separate job** pinned to
+the same host that `needs` the restart job. The orchestrator holds the
+post-restart job until the host completes a reboot cycle, then dispatches it.
+
+```typescript
+import { workflow, job, step, restartHost, waitForHostAlive } from '@kici-dev/sdk';
+
+export default workflow('patch-and-verify', {
+  on: [
+    /* ... */
+  ],
+  jobs: [
+    // Restart job: apply updates, then reboot. restartHost() MUST be the last step.
+    job('patch', {
+      runsOn: 'kici:host:box-01',
+      steps: [
+        step('upgrade', async (ctx) => {
+          await ctx.$`apt-get upgrade -y`;
+        }),
+        restartHost(),
+      ],
+    }),
+    // Post-restart job: pinned to the SAME host, needs the restart job.
+    job('verify', {
+      runsOn: 'kici:host:box-01',
+      needs: ['patch'],
+      steps: [
+        waitForHostAlive(() => fetch('http://localhost:8080/health')),
+        step('check-service', async (ctx) => {
+          await ctx.$`systemctl is-active myservice`;
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+## `restartHost()`
+
+`restartHost(opts?)` reboots the host the job runs on. It signals the
+orchestrator that a reboot is pending (which holds the post-restart job and
+treats the agent's imminent disconnect as expected, not a failure), reports the
+step success, and the agent issues the OS reboot once the step completes.
+
+- **Must be the last step** of its job — the job completes before the box goes
+  down.
+- `deadlineMs` (optional) overrides how long the orchestrator waits for the host
+  to return after the reboot. The default is the orchestrator's
+  `KICI_HOST_REBOOT_DEADLINE_MS` (15 minutes). If the host does not reconnect by
+  the deadline, the held post-restart job fails with a clear "host did not
+  return after reboot" reason.
+- The reboot command is chosen per operating system (Linux `systemctl reboot`,
+  macOS `shutdown -r now`, Windows `shutdown /r /t 0`).
+
+## `waitForHostAlive(probe, opts?)`
+
+`waitForHostAlive()` is the optional first step of the post-restart job. The
+baseline "the host is back" guarantee comes for free — the post-restart job only
+dispatches after the agent reconnects. `waitForHostAlive(probe)` adds a
+**service-readiness** gate on top: it polls `probe` until it resolves, for hosts
+where "agent connected" does not yet mean "services ready".
+
+- The probe can return anything (an HTTP response, an open port check, a marker
+  file). Any non-null resolution means "ready"; a throw or rejection keeps
+  polling.
+- `intervalMs` (default 3000) and `timeoutMs` (default 300000) tune the poll. If
+  the probe never succeeds within `timeoutMs`, the step fails with "services did
+  not come up".
+
+## Same-host pinning
+
+The "same host" relationship is the pin: both jobs target the same host via
+`runsOn` (a `kici:host:<id>` label or another label the host carries), and the
+post-restart job `needs` the restart job. Durable provisioning hosts MUST set a
+stable agent id (`KICI_AGENT_ID`) so the host re-registers under the same
+identity after the reboot — that stable identity is what lets the orchestrator
+recognise the down-then-up cycle and release the held job.
+
+## Failure behavior
+
+- **Host never returns by the deadline** → the held post-restart job fails.
+- **Reboot privilege denied** → the restart step fails with a clear privilege
+  error (see the operator note below), and the orchestrator clears the
+  reboot-pending hold.
+- **`waitForHostAlive` probe never succeeds** → that step fails.
+
+The orchestrator refuses to reboot the host it runs on, so a co-located agent
+cannot take down the orchestrator's own box.
+
+## Operator prerequisite: reboot privilege
+
+Rebooting needs host privilege. An agent used for host provisioning must be able
+to run the OS reboot primitive — run the agent service with reboot privilege, or
+grant a narrow `shutdown` / `systemctl reboot` permission. Agents used for
+provisioning generally need broad, near-root host privileges; see the operator
+agent documentation for the full posture.
+
+---
+
 ## Integration patterns
 
 Source: https://docs.kici.dev/user/patterns/integrations/
@@ -2108,6 +2218,28 @@ const build = step('build', {
 
 **StepRunFn type:** `(ctx: StepContext) => Promise<void>`
 
+**With a check facet (idempotent step):**
+
+Add a `check` function to describe _desired state_ instead of a fixed action. When
+`check` is present, `run` becomes the _apply_ function and receives the drift value
+`check` returned; `summarize` (required) renders that drift for logs and the
+dashboard; `whenInSync` optionally produces the step's outputs when already in sync.
+
+```typescript
+const configureNginx = step('configure-nginx', {
+  check: async (ctx) => ((await inSync(ctx)) ? null : { want: DESIRED }),
+  summarize: (drift) => `would rewrite nginx.conf (${drift.want.length} bytes)`,
+  run: async (ctx, drift) => {
+    await writeConfig(drift.want);
+    return { reloaded: true };
+  },
+  whenInSync: async () => ({ reloaded: false }),
+});
+```
+
+A checked step can run in apply mode (converge) or `--check` preview mode (report
+drift, change nothing). See [Idempotent steps and check mode](../idempotent-steps.md).
+
 ### Per-job resources
 
 `options.resources` declares the CPU and memory the job needs. The orchestrator's auto-scaler uses these numbers to:
@@ -2467,9 +2599,9 @@ const test = job('test', { needs: [lint], ... });
 // 2. Reference by string name
 const test = job('test', { needs: ['lint'], ... });
 
-// 3. Object form with per-edge failure policy
+// 3. Object form with a per-edge run condition (`when`)
 const cleanup = job('cleanup', {
-  needs: [{ name: 'build', ifFailed: 'run' }],
+  needs: [{ name: 'build', when: 'always' }],
   ...
 });
 
@@ -2480,16 +2612,36 @@ const deploy = job('deploy', {
 });
 ```
 
-**Failure policy (`ifFailed`):** controls what happens to a downstream job when an upstream reaches a non-success terminal state (`failed`, `cancelled`, `drift_dropped`).
+**Run condition (`when`):** controls when a downstream edge is satisfied, based on the upstream's terminal status. `when` is keyword sugar (or a raw status-set) that resolves at compile time to the set of upstream terminal statuses that satisfy the edge. The downstream edge is satisfied when the upstream's terminal status is a member of that set.
+
+| Keyword                  | Satisfied when the upstream is… | Use for                                     |
+| ------------------------ | ------------------------------- | ------------------------------------------- |
+| `'on-success'` (default) | `success`                       | normal dependencies                         |
+| `'always'`               | any terminal status             | cleanup / notification / teardown jobs      |
+| `'on-skip'`              | `success` or `skipped`          | continue when an upstream was narrowed out  |
+| `'on-failure'`           | `failed` or `timed_out_stale`   | error-handler jobs that run only on failure |
+
+For full control, pass a raw status-set instead of a keyword: `when: ['skipped', 'failed', 'timed_out_stale']`. The valid members are the terminal job statuses: `success`, `failed`, `cancelled`, `skipped`, `timed_out_stale`, `drift_dropped`.
 
-| Value  | Behavior                                                                                    |
-| ------ | ------------------------------------------------------------------------------------------- |
-| `skip` | (Default) Downstream transitions directly to `skipped`. Failures cascade through the DAG.   |
-| `run`  | Downstream dispatches anyway. Use for cleanup, notification, or "always-run" teardown jobs. |
+String and `Job`-reference entries default to `when: 'on-success'`. To override, use the object form (`{ name, when }` for static upstreams, `{ group, when }` for dynamic groups -- `dynamicGroup(name, { when: 'always' })` produces the latter).
 
-String and `Job`-reference entries default to `ifFailed: 'skip'`. To override, use the object form (`{ name, ifFailed }` for static upstreams, `{ group, ifFailed }` for dynamic groups -- `dynamicGroup(name, { ifFailed: 'run' })` produces the latter).
+When an upstream's terminal status is **not** in the edge's set, the downstream transitions directly to `skipped`. Because a skipped job is itself terminal, this propagates transitively: each downstream's `when` set governs whether the skip cascades further.
 
-**Dispatch gate:** `needs` is a hard dispatch gate. A job only dispatches after every upstream in its `needs` array reaches a terminal state (success, or failure with `ifFailed: 'run'`). Root jobs (empty `needs`, no dynamic group refs) dispatch immediately. The scheduler is DB-backed and fully recovers across orchestrator restarts.
+**Dispatch gate:** `needs` is a hard dispatch gate. A job dispatches only after every upstream in its `needs` array reaches a terminal status that satisfies that edge's `when` set. Root jobs (empty `needs`, no dynamic group refs) dispatch immediately. The scheduler is DB-backed and fully recovers across orchestrator restarts.
+
+**Reading an upstream's status in a step:** inside a running job, `ctx.needs.<job>.status` exposes each upstream's terminal status (`success`, `failed`, `skipped`, …) and `ctx.needs.<job>.result` its outputs. A group / matrix / `runsOnAll` fan-out upstream is an ordered array of `{ name, result, status }`, one per child. Use this to branch in TypeScript:
+
+```typescript
+job('report', {
+  needs: [{ name: 'probe', when: 'always' }],
+  run: async (ctx) => {
+    if (ctx.needs.probe.status === 'failed') await fileIncident(ctx.needs.probe.result);
+    else await publish(ctx.needs.probe.result);
+  },
+});
+```
+
+For an arbitrary outcome-based gate that prevents a job from dispatching at all, use a result-aware `dynamicJob` that returns `[]` or `[job]` based on `ctx.needs.<job>.status` — see [Dynamic jobs](../../architecture/execution/dynamic-jobs.md).
 
 **DAG validation:** three-layer cycle detection.
 
@@ -2502,7 +2654,10 @@ String and `Job`-reference entries default to `ifFailed: 'skip'`. To override, u
 Create a reference to a dynamic job group, for use inside a static job's `needs` array.
 
 ```typescript
-function dynamicGroup(name: string, options?: { ifFailed?: 'skip' | 'run' }): DynamicGroupRef;
+function dynamicGroup(
+  name: string,
+  options?: { when?: 'on-success' | 'always' | 'on-skip' | 'on-failure' | string[] },
+): DynamicGroupRef;
 ```
 
 Use when a static downstream must wait for every generated job tagged with a given group name to complete. If the dynamic group produces zero jobs, the downstream dispatches immediately (empty group satisfies all upstreams).
@@ -3423,10 +3578,10 @@ export default workflow('discovery-fan-out', { jobs: [discover, reports] });
 
 `ctx.needs` shape:
 
-| Need form                                               | `ctx.needs[...]` value                                                                                                                                    |
-| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `'jobName'` / `{ name, ifFailed }`                      | `{ result }` — `result` is an `OutputProxy` (`ctx.needs.<job>.result.<step>.<field>`; single-step `run` jobs flatten to `ctx.needs.<job>.result.<field>`) |
-| `dynamicGroup('g')` / `dynamicGroup('g', { ifFailed })` | ordered array of `{ name, result }`, one per group member                                                                                                 |
+| Need form                                           | `ctx.needs[...]` value                                                                                                                                                                                        |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `'jobName'` / `{ name, when }`                      | `{ result, status }` — `result` is an `OutputProxy` (`ctx.needs.<job>.result.<step>.<field>`; single-step `run` jobs flatten to `ctx.needs.<job>.result.<field>`); `status` is the upstream's terminal status |
+| `dynamicGroup('g')` / `dynamicGroup('g', { when })` | ordered array of `{ name, result, status }`, one per group member                                                                                                                                             |
 
 `ctx.needs` is deterministic — a snapshot of upstream outputs frozen at first eval and replayed unchanged on re-eval, like `ctx.event`. Use result-aware generation for same-run fan-out from a prior job's result; use [`jobComplete()`](./triggers.md) for cross-workflow reactions to a job finishing. See the architecture deep-dive in [dynamic jobs](../../architecture/execution/dynamic-jobs.md#result-aware-generation).
 
@@ -3663,6 +3818,32 @@ A held host occupies a wave slot indefinitely while it waits to reconnect, stall
 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](/user/cli-reference/#host-narrowing-with---target)
+for the full flag behavior and the [`needs` gating model](./core.md#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
@@ -4021,6 +4202,70 @@ const publish = job('publish', {
 - The step never holds platform credentials — the request is relayed through the orchestrator, which mints the token on the step's behalf.
 - Only available inside a running job step; calling it outside one (for example, during local execution) rejects with a clear error.
 
+### ctx.kici.inventory.query(selector?) / .get(agentId)
+
+Query the **host inventory** — the roster of agents in the caller's orchestrator cluster — from inside a workflow. Each host is a `HostInventoryEntry`:
+
+```typescript
+interface HostInventoryEntry {
+  agentId: string;
+  labels: string[]; // flat-string grouping/tags dimension
+  properties: Record<string, string | number | boolean>; // typed host-vars dimension
+  hostname: string | null;
+  platform: string | null;
+  arch: string | null;
+  lifecycleClass: 'static' | 'ephemeral';
+  status: 'ready' | 'unreachable' | 'stale';
+  lastSeen: string; // ISO timestamp
+}
+```
+
+Two dimensions describe a host. **Labels** are flat strings used for grouping and targeting (the same labels `runsOn` / `runsOnAll` match). **Properties** are typed host-vars (`string | number | boolean`) — the place for facts like `region`, `cores`, or `gpu`. A host reports its own properties via the agent's `KICI_PROPERTIES` config, and an operator can pre-declare them with `kici-admin host declare --prop key=value`; the two are shallow-merged (agent-reported keys win).
+
+```typescript
+// All hosts:
+const all = await ctx.kici.inventory.query();
+
+// Server-side label filter (OR-of-AND include groups, plus exclude):
+const dbHosts = await ctx.kici.inventory.query({
+  include: [[{ kind: 'exact', value: 'role:db' }]],
+});
+
+// Property filtering is client-side — plain JS in the workflow:
+const euDbHosts = dbHosts.filter((h) => h.properties.region === 'eu');
+
+// One host by id:
+const host = await ctx.kici.inventory.get('box-1'); // HostInventoryEntry | null
+```
+
+**The label selector is applied server-side** (reusing the same glob/regex matchers as `runsOnAll`). **Property filtering is client-side** — you filter the returned array in plain JavaScript, so there is no query DSL to learn.
+
+**Headline use — dynamic-job fan-out.** A dynamic-job generator can query the inventory and return one job per matching host, fanning a workflow out across a fleet:
+
+```typescript
+const migrate = job('migrate', async (ctx) => {
+  const hosts = await ctx.kici.inventory.query({
+    include: [[{ kind: 'exact', value: 'role:db' }]],
+  });
+  return hosts
+    .filter((h) => h.properties.region === 'eu')
+    .map((h) =>
+      job(`migrate-${h.agentId}`, {
+        runsOn: [h.agentId],
+        run: async (c) => {
+          await c.$`./migrate.sh`;
+        },
+      }),
+    );
+});
+```
+
+A `runsOn` of a single host's `agentId` (as in `runsOn: [h.agentId]` above) **pins the job to that host**: the orchestrator routes it to that agent only, and queues it with the pin if the host is momentarily offline — the same host-pin path `runsOnAll` uses. A `runsOn` with multiple labels or a glob/regex pattern stays ordinary label routing.
+
+`ctx.kici.inventory` is available to **both** steps and dynamic-job generators (unlike `ctx.kici.oidc.token`, which is job-bound — the inventory is cluster-scoped, not job-bound).
+
+**Determinism caveat.** The inventory is **live**: it can change between when a dynamic-job generator first runs (at dispatch) and when it re-evaluates (at agent time). Generating jobs from `inventory.query()` therefore inherits the same non-determinism contract as `infrastructure.list()` — KiCI warns when the re-evaluated job set drifts (a sibling job name changed) and hard-errors when a targeted job vanishes. Prefer stable inputs where you can, and treat a fanned-out job set as a snapshot of the roster at generation time.
+
 ### ctx.attestProvenance({ subject })
 
 Build, sign, and persist a build-provenance attestation for an artifact your step produced. KiCI assembles an in-toto SLSA v1.0 provenance statement whose build identity (`repository`, `ref`, `sha`, run/job ids) comes from the platform — not from the step — so it cannot be spoofed, signs it, and stores a verifiable bundle that the dashboard surfaces and the `kici verify-attestation` CLI checks.
@@ -5563,6 +5808,8 @@ kici run remote [fixture] [options]
 | `--history`                 | `false` | Show table of recent test runs                                                                    |
 | `--context <ctx.key=value>` | none    | Inject a namespaced context secret, uploaded encrypted (repeatable)                               |
 | `--env <KEY=VALUE>`         | none    | Provide a per-run secret, uploaded encrypted (repeatable) — see [testing guide](testing-guide.md) |
+| `--target <selector>`       | none    | Narrow `runsOnAll` jobs to hosts matching this label selector (repeatable, AND-combined)          |
+| `--target-allow-empty`      | `false` | A `--target` that narrows a `runsOnAll` job to zero hosts skips it instead of failing             |
 | `--debug`                   | `false` | Verbose internals                                                                                 |
 | `--kici-dir <path>`         | `.kici` | Path to .kici directory                                                                           |
 
@@ -5582,7 +5829,7 @@ kici run remote push-main --org xyz789ghi012
 kici run remote push-main --orchestrator us-east
 
 # Run all push-related fixtures
-kici run remote push-*
+kici run remote 'push-*'
 
 # Run everything
 kici run remote --all
@@ -5601,8 +5848,44 @@ kici run remote push-main --no-wait
 
 # View recent test run history
 kici run remote --history
+
+# Narrow runsOnAll jobs to a subset of the host roster
+kici run remote deploy --target role:web
+
+# AND-combine repeated --target values (hosts must match every selector)
+kici run remote deploy --target role:web --target dc:eu
+
+# Skip a runsOnAll job instead of failing it when the target matches no host
+kici run remote deploy --target role:gpu --target-allow-empty
 ```
 
+#### Host narrowing with `--target`
+
+`--target <selector>` is a runtime narrowing for `runsOnAll` jobs, analogous to
+Ansible's `--limit`. A `runsOnAll` job normally fans out to **every** roster host
+matching its predicate, one pinned execution per host. `--target` intersects that
+matched roster with a label selector, so the effective host set is
+`runsOnAll ∩ target`:
+
+- **Narrow-only.** `--target` can only _remove_ hosts from the matched set, never
+  add them. The widening dimension (OR across host groups) lives in the workflow's
+  `runsOnAll`; `--target` only subtracts.
+- **Run-global, `runsOnAll`-only.** A single `--target` applies to every
+  `runsOnAll` job in the run. Jobs pinned to a single host with `runsOn` are
+  untouched.
+- **Repeatable and AND-combined.** Each `--target` value is its own selector; a
+  host must satisfy **all** of them to survive the narrowing. Use a single value
+  for an OR-style match within one selector and repeated values for AND.
+- **Selector syntax** matches `runsOn`: an exact label (`role:web`), a glob
+  (`role:*`), or a regex (`/^box-0[1-3]$/`).
+
+When `--target` narrows a `runsOnAll` job to zero hosts, the default is to **fail**
+the run (fail-loud — a typo in the selector shouldn't silently skip work). Pass
+`--target-allow-empty` to **skip** the zeroed job instead; the job records a
+`skipped` status, and any downstream job that needs it with `when: 'on-skip'` (or
+`when: 'always'`) still runs. See [Job dependencies](./sdk/core.md#job-dependencies-needs)
+for the `when` gating model.
+
 **Exit codes:**
 
 | Code | Meaning                      |
@@ -5743,18 +6026,21 @@ By default, `kici login` opens your browser for OIDC authentication using PKCE.
 
 After OAuth, the CLI exchanges the OIDC token for a personal access token (PAT) stored in the config directory (`~/.kici/config` by default, overridable with `KICI_CONFIG_DIR`).
 
+`kici login` targets the hosted KiCI Platform by default. To authenticate against another environment (a self-hosted Platform, for example), pass `--platform-endpoint` / `--oidc-issuer` or set `KICI_PLATFORM_URL` / `KICI_OIDC_ISSUER`. Login persists the platform endpoint and OIDC issuer it authenticated against alongside the PAT, so a saved PAT always matches its endpoint. Because the config describes one environment at a time, **switching the endpoint resets the active organization and default clusters** — re-run `kici org use <name>` after switching environments.
+
 ```bash
 kici login [options]
 ```
 
 **Options:**
 
-| Option                      | Default | Description                                    |
-| --------------------------- | ------- | ---------------------------------------------- |
-| `--token <key>`             | none    | API key for direct authentication (legacy)     |
-| `--device`                  | false   | Force device authorization flow (headless/SSH) |
-| `--platform-endpoint <url>` | none    | Platform relay URL                             |
-| `--routing-key <key>`       | none    | Routing key for webhook source identification  |
+| Option                      | Default | Description                                         |
+| --------------------------- | ------- | --------------------------------------------------- |
+| `--token <key>`             | none    | API key for direct authentication (legacy)          |
+| `--device`                  | false   | Force device authorization flow (headless/SSH)      |
+| `--platform-endpoint <url>` | none    | Platform relay URL                                  |
+| `--oidc-issuer <url>`       | none    | OIDC issuer URL (selects a non-default environment) |
+| `--routing-key <key>`       | none    | Routing key for webhook source identification       |
 
 **Environment variables:**
 
@@ -5780,7 +6066,8 @@ kici login --device
 kici login --token kici_sk_abc123...
 
 # Log in against a self-hosted Platform
-kici login --platform-endpoint https://platform.example.com
+kici login --platform-endpoint https://platform.example.com \
+  --oidc-issuer https://auth.example.com/realms/kici-internal
 
 # Suppress browser opening (print authorize URL to stdout)
 KICI_BROWSER_CMD=none kici login
@@ -6813,7 +7100,7 @@ The lock file (`kici.lock.json`) is a JSON file with the following top-level fie
 
 | Field           | Description                                                                                                                                                                                                                                                                                                                                           |
 | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `schemaVersion` | Lock file schema version (currently 17). Incremented on breaking format changes.                                                                                                                                                                                                                                                                      |
+| `schemaVersion` | Lock file schema version (currently 20). Incremented on breaking format changes.                                                                                                                                                                                                                                                                      |
 | `source`        | Reference to the source file and export (e.g., `{ file: “.kici/workflows/ci.ts”, export: “#default” }`).                                                                                                                                                                                                                                              |
 | `contentHash`   | SHA-256 of the serialized lock file content (excluding itself). Changes when any workflow, trigger, or job changes.                                                                                                                                                                                                                                   |
 | `lockfileHash`  | SHA-256 of the detected package manager's lockfile, used as the dependency cache key. The lockfile is `.kici/package-lock.json` for npm, or the repo-root `pnpm-lock.yaml` / `yarn.lock` for a pnpm/yarn workspace; the hash input is prefixed with the manager name so a manager change is a guaranteed cache miss. Omitted when no lockfile exists. |
@@ -6988,12 +7275,14 @@ kici run remote
 kici run remote push-main
 
 # Run all fixtures matching a glob
-kici run remote push-*
+kici run remote 'push-*'
 
 # Run everything
 kici run remote --all
 ```
 
+The single quotes keep your shell from expanding `push-*` against local files, so the pattern reaches KiCI intact for its own fixture-glob matching.
+
 ## Fixture reference
 
 ### Event types
@@ -7089,7 +7378,7 @@ kici run remote
 kici run remote push-main
 
 # Glob matching -- run all push-related fixtures
-kici run remote push-*
+kici run remote 'push-*'
 
 # Run all fixtures sequentially
 kici run remote --all
@@ -7432,12 +7721,14 @@ Source: https://docs.kici.dev/user/approvals/
 
 An **approval gate** pauses execution until an authorized person approves it. Execution resumes from exactly where it paused; a rejection (or an expired hold) fails the run.
 
-You declare a gate in your workflow with `requireApproval`. It is available at three levels of granularity:
+You declare a gate in your workflow with `approval`. It is available at three levels of granularity:
 
 - **Step** — pause mid-job, before a specific step runs. The agent holds the live workspace (with all prior-step state intact) for the duration of the wait.
 - **Job** — hold the job before any of its steps run.
 - **Workflow** — hold the whole run before any job is dispatched.
 
+A step-level gate can also fire **only when a check/apply step finds drift** — Terraform's plan→apply, per step. See [Drift gates](#drift-gates-whendrift) below.
+
 Approvers are named as **teams** and **users**. A team is an operator-defined group of org members; your workflow code may name a team but can never change its membership, which is what makes a team clause a real gate rather than a suggestion. See [Approval gates (operator guide)](../operator/approvals.md) for how operators define teams, the approval queue, and expiry; see [the architecture overview](../architecture/approvals.md) for how a hold is evaluated and resumed.
 
 ## Quick start
@@ -7452,7 +7743,7 @@ export default workflow('deploy', {
   jobs: [
     job('deploy-production', {
       runsOn: 'default',
-      requireApproval: [{ team: 'leads' }],
+      approval: [{ team: 'leads' }],
       steps: [step('deploy', async (ctx) => ctx.$`deploy --prod`)],
     }),
   ],
@@ -7461,28 +7752,28 @@ export default workflow('deploy', {
 
 When the run reaches this job, it is held instead of dispatched. The held run appears in the dashboard approval queue and can be released from there or with the [`kici approve`](#approving-from-the-cli) command. Once a member of `leads` approves, the job dispatches normally.
 
-## The `requireApproval` field
+## The `approval` field
 
-`requireApproval` accepts three forms.
+`approval` accepts three forms.
 
 ### Shorthand: `true`
 
 ```typescript
 job('deploy', {
   runsOn: 'default',
-  requireApproval: true,
+  approval: true,
   steps: [
     /* ... */
   ],
 });
 ```
 
-`requireApproval: true` holds the element until **any** org member who can act on approvals signs off — anyone with the `environments:write` or `ci_trust:write` permission. Use it when you want a manual gate without restricting who may release it.
+`approval: true` holds the element until **any** org member who can act on approvals signs off — anyone with the `environments:write` or `ci_trust:write` permission. Use it when you want a manual gate without restricting who may release it.
 
 ### Approver list (AND)
 
 ```typescript
-requireApproval: [{ team: 'leads' }, { user: 'cto' }],
+approval: [{ team: 'leads' }, { user: 'cto' }],
 ```
 
 A list of approver clauses is an **AND** list: every clause must be satisfied before the element is released.
@@ -7494,27 +7785,29 @@ A single approver may satisfy more than one clause. If `cto` is also a member of
 
 There is no OR or nested logic — clauses are always a flat AND list.
 
-### Object form: reason and timeout
+### Object form: when, reason, and timeout
 
 ```typescript
-requireApproval: {
+approval: {
+  when: 'always',
   approvers: [{ team: 'security' }, { team: 'leads' }],
   reason: 'Production deploy requires security + leads sign-off',
   timeout: 7200, // seconds
 },
 ```
 
-| Field       | Type               | Description                                                                                         |
-| ----------- | ------------------ | --------------------------------------------------------------------------------------------------- |
-| `approvers` | `ApproverClause[]` | The AND list of `{ team }` / `{ user }` clauses. An empty list means "any approval-capable member". |
-| `reason`    | `string`           | A human-readable label shown in the dashboard queue and the held-for-approval status check.         |
-| `timeout`   | `number`           | Per-gate expiry in **seconds**, overriding the org default. On expiry the element is rejected.      |
+| Field       | Type                  | Description                                                                                                                                                                 |
+| ----------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `when`      | `'always' \| 'drift'` | When the gate fires. `'always'` (default) gates before the element; `'drift'` gates a check/apply step only when it finds drift. See [Drift gates](#drift-gates-whendrift). |
+| `approvers` | `ApproverClause[]`    | The AND list of `{ team }` / `{ user }` clauses. An empty list means "any approval-capable member".                                                                         |
+| `reason`    | `string`              | A human-readable label shown in the dashboard queue and the held-for-approval status check.                                                                                 |
+| `timeout`   | `number`              | Per-gate expiry in **seconds**, overriding the org default. On expiry the element is rejected.                                                                              |
 
 When `timeout` is omitted, the gate uses the org's default approval expiry (set by the operator). On expiry, the held element is rejected and the run fails — see [expiry](../operator/approvals.md#expiry).
 
 ## Granularity
 
-The same `requireApproval` field is accepted on a workflow, a job, and a step.
+The same `approval` field is accepted on a workflow, a job, and a step.
 
 ### Workflow-level
 
@@ -7523,7 +7816,7 @@ A workflow-level gate holds the entire run before any job is dispatched:
 ```typescript
 export default workflow('release', {
   on: [push({ branches: ['main'] })],
-  requireApproval: [{ team: 'release-managers' }],
+  approval: [{ team: 'release-managers' }],
   jobs: [buildJob, publishJob],
 });
 ```
@@ -7535,7 +7828,7 @@ A job-level gate holds just that job; other jobs in the run proceed normally:
 ```typescript
 job('publish', {
   runsOn: 'default',
-  requireApproval: [{ team: 'leads' }],
+  approval: [{ team: 'leads' }],
   steps: [
     /* ... */
   ],
@@ -7552,7 +7845,7 @@ job('migrate-and-deploy', {
   steps: [
     step('build-plan', async (ctx) => ctx.$`./gen-migration-plan.sh`),
     step('apply-migration', {
-      requireApproval: [{ team: 'dba' }],
+      approval: [{ team: 'dba' }],
       run: async (ctx) => ctx.$`./apply-migration.sh`,
     }),
     step('deploy', async (ctx) => ctx.$`deploy --prod`),
@@ -7564,9 +7857,39 @@ Here `build-plan` runs, then the job pauses for a `dba` approval. On approval, `
 
 Because a step-level hold keeps an agent and its workspace occupied for the whole human wait, prefer job- or workflow-level gates when you do not need prior-step state, and keep step-level timeouts short. See the [operator note on agent occupancy](../operator/approvals.md#agent-occupancy-during-step-level-holds).
 
+## Drift gates (`when: 'drift'`)
+
+A `when: 'drift'` gate is **step-scope only** and requires a [check/apply step](idempotent-steps.md). Instead of pausing unconditionally, it fires **between the step's `check` and `run`, only when `check` finds drift in apply mode** — exactly Terraform's plan→apply, scoped to one step. When the step is already in sync (no drift), nothing pauses and the step skips.
+
+When the gate fires, the held run carries the **computed drift** as a payload: the rendering your `summarize(drift)` produced (the per-file diff, the commands that would run), plus the structured drift. The dashboard approval queue and the [CLI](#approving-from-the-cli) show the actual diff the operator is approving — not a static reason string.
+
+```typescript
+job('patch-prod', {
+  runsOn: 'default',
+  steps: [
+    step('apply-nginx-config', {
+      check: async (ctx) => ((await inSync(ctx)) ? null : { want: DESIRED_CONF }),
+      summarize: (drift) => `would rewrite nginx.conf (${drift.want.length} bytes)`,
+      run: async (ctx, drift) => {
+        await writeConfig(drift.want);
+      },
+      approval: { when: 'drift', approvers: [{ team: 'ops' }], reason: 'prod patch' },
+    }),
+  ],
+});
+```
+
+Behavior:
+
+- The gate fires **only in apply mode**. In `--check` mode nothing applies, so nothing gates — drift is just reported.
+- **Approve** → the step's `run(ctx, drift)` applies the change.
+- **Reject** → fail-stop: the step fails, the job fails, and the `needs:` skip-cascade aborts everything downstream.
+
+A `when: 'drift'` gate on a step without a `check` facet, or at job/workflow scope, is a compile error.
+
 ## Mandatory vs. explicit gates
 
-`requireApproval` is the **explicit** gate — a deliberate "pause for a human here" written by the workflow author. It composes with the **mandatory** gate an operator can attach to a protected environment via required reviewers (see [Environments](environments.md#required-reviewers)). When both apply to the same job, all clauses from both sources must be satisfied before the job is released. The two funnel into one held-element mechanism, so the dashboard queue and `kici approve` work the same way regardless of which source held the element.
+`approval` is the **explicit** gate — a deliberate "pause for a human here" written by the workflow author. It composes with the **mandatory** gate an operator can attach to a protected environment via required reviewers (see [Environments](environments.md#required-reviewers)). When both apply to the same job, all clauses from both sources must be satisfied before the job is released. The two funnel into one held-element mechanism, so the dashboard queue and `kici approve` work the same way regardless of which source held the element.
 
 ## Approving from the CLI
 
@@ -7588,10 +7911,23 @@ kici reject <run-id> --job deploy-production --reason "Wrong release branch"
 
 You must be eligible for at least one unsatisfied clause — being a member of a named team or being a named user. The orchestrator verifies eligibility against the operator-defined teams, so naming a team in your workflow can never let an ineligible person release the gate. The command reports whether the element was released, how many clauses remain, or that it was rejected. See [`kici approve`](cli-reference.md#kici-approve) for the full command reference.
 
+### Inline approval and `--approve-all` in `kici run remote`
+
+When you trigger a run with `kici run remote` and it pauses on a gate, the CLI prints the gate (and, for a drift gate, the computed drift) and — in an interactive terminal — prompts you to approve or reject right there, without leaving the watch. In a non-interactive shell it prints how to approve out of band and keeps watching.
+
+To auto-approve **every gate of the run you just dispatched**, pass `--approve-all` (alias `--yes`):
+
+```bash
+kici run remote deploy-prod --approve-all
+```
+
+`--approve-all` is **run-scoped** — it only auto-approves holds belonging to the run this invocation dispatched; there is no fleet-wide or account-wide auto-approve. Eligibility is still enforced per hold: if you are not eligible for a gate, that gate still blocks. Each auto-approved gate prints its payload before resolving and is recorded distinctly in the audit trail (`held_run.auto_approve`).
+
 You can also approve from the dashboard approval queue. See [Dashboard](dashboard/environments-and-secrets.md#approval-queue).
 
 ## See also
 
+- [Idempotent steps](idempotent-steps.md) — the check/apply step facet that drift gates build on.
 - [Environments](environments.md) — operator-required reviewers on protected environments.
 - [Approval gates (operator guide)](../operator/approvals.md) — teams, the approval queue, expiry, and self-approval.
 - [Approval gates (architecture)](../architecture/approvals.md) — the unified hold model and the step-level round-trip.
@@ -8224,7 +8560,7 @@ Required reviewers: alice, bob
 
 When reviewers are required, the job enters a "held" state. Reviewers can approve or reject via the dashboard, the [`kici approve`](cli-reference.md#kici-approve) command, or the API. Held runs expire after a configurable timeout.
 
-This operator-set rule is the **mandatory** form of an approval gate. Workflow authors can also declare gates in code with `requireApproval` at step, job, or workflow level — see [Approval gates](approvals.md). Both forms use the same held-element mechanism and the same queue.
+This operator-set rule is the **mandatory** form of an approval gate. Workflow authors can also declare gates in code with `approval` at step, job, or workflow level — see [Approval gates](approvals.md). Both forms use the same held-element mechanism and the same queue.
 
 ### Wait timer
 
@@ -8833,6 +9169,135 @@ Non-push triggers work too — `pr()`, `tag()`, `comment()`, `release()`, `workf
 
 ---
 
+## Idempotent steps and check mode
+
+Source: https://docs.kici.dev/user/idempotent-steps/
+
+An **idempotent step** describes _desired state_ rather than a fixed sequence of
+commands. You give the step a `check` function that inspects the world and a
+`run` function that converges it. KiCI then executes the workflow in one of two
+modes:
+
+- **Apply mode** (the default): for each step, `check()` runs first; on drift the
+  step applies the change; when already in sync the step is skipped.
+- **Check mode** (`--check`): for each step, `check()` runs and KiCI reports what
+  _would_ change — **without changing anything**. This is the same model as a
+  dry-run plan: you see the drift before any side effect happens.
+
+This turns a workflow into convergent configuration management: re-running an
+apply is safe (in-sync steps do nothing), and a check-mode run is a read-only
+preview you can gate a build on.
+
+## Authoring a checked step
+
+Add a `check` facet to the existing `step()` factory. When `check` is present,
+`run` becomes the _apply_ function and receives the drift value `check`
+returned:
+
+```typescript
+import { step, z } from '@kici-dev/sdk';
+
+const configureNginx = step('configure-nginx', {
+  // optional schema for the drift value — gives the dashboard a typed shape
+  drift: z.object({ want: z.string() }),
+
+  // read-only inspection; return null when already in the desired state
+  check: async (ctx) => {
+    const current = await ctx.$`nginx -T`;
+    return current.stdout.includes(DESIRED) ? null : { want: DESIRED };
+  },
+
+  // human-readable preview line — REQUIRED when check is set. It is the drift's
+  // serializable face: it streams to the logs and persists for the dashboard.
+  summarize: (drift) => `would rewrite nginx.conf (${drift.want.length} bytes)`,
+
+  // apply — runs only when check returned drift (apply mode); receives that drift
+  run: async (ctx, drift) => {
+    await writeConfig(drift.want);
+    return { reloaded: true };
+  },
+
+  // optional — runs when check returned null, to produce the step's outputs
+  whenInSync: async () => ({ reloaded: false }),
+});
+```
+
+### The facet fields
+
+| Field        | Required         | Purpose                                                                |
+| ------------ | ---------------- | ---------------------------------------------------------------------- |
+| `check`      | to opt in        | Read-only inspection. Return a drift value, or `null` when in sync.    |
+| `summarize`  | when `check` set | Human-readable, serializable preview of the drift. Streams + persists. |
+| `run`        | always           | Apply function. With `check`, it receives the drift as its second arg. |
+| `whenInSync` | optional         | Produces the step's outputs when `check` returned `null`.              |
+| `drift`      | optional         | Schema that validates / shapes the drift value.                        |
+
+`summarize` is **required** whenever `check` is declared. `run` and `whenInSync`
+both produce the same output type — one output shape per step, whichever path
+runs. Every other step facet (`cache`, `rules`, `continueOnError`, `timeout`,
+`approval`, `onCancel`, `cleanup`, `outputs`) composes unchanged.
+
+A plain `step()` without `check` keeps its exact current behavior — the check
+facet is fully optional.
+
+## Run modes
+
+A run carries one of three modes:
+
+| Mode                  | CLI flags                 | Behavior                                                                                   |
+| --------------------- | ------------------------- | ------------------------------------------------------------------------------------------ |
+| `apply`               | (default, no flags)       | Converge: drift ⇒ apply ⇒ **applied**; null ⇒ **in sync** (skipped).                       |
+| `check`               | `--check`                 | Preview only: drift ⇒ **would change**; null ⇒ **in sync**. Never applies. Always exits 0. |
+| `check-fail-on-drift` | `--check --fail-on-drift` | Same as check, but the run **fails** if any step reports drift.                            |
+
+Per-step outcomes:
+
+- **applied** — drift was found and the step applied the change (apply mode).
+- **in sync** — `check` returned `null`; nothing to do.
+- **would change** — drift was found in check mode; the change was previewed, not applied.
+- **no check** — a plain step (no `check`) reached under check mode. A
+  side-effecting step can't be safely previewed, so it is skipped.
+
+In check mode KiCI never invokes a checked step's `run` (apply) — the preview is
+guaranteed side-effect-free.
+
+## Running in check mode
+
+`--check` and `--fail-on-drift` work on both local and remote runs:
+
+```bash
+# Apply (default): converge the workflow.
+kici run local push
+kici run remote my-fixture
+
+# Check: report drift, change nothing. Always exits 0.
+kici run local push --check
+kici run remote my-fixture --check
+
+# Check + fail on drift: exit non-zero (2) locally, or fail the run remotely,
+# when any step reports drift. Use this as a CI gate ("fail the build if prod
+# has drifted").
+kici run local push --check --fail-on-drift
+```
+
+`--fail-on-drift` only modifies check mode — passing it without `--check` is an
+error.
+
+## Where outcomes show up
+
+A check-mode run is labeled in the dashboard with a **CHECK MODE — preview**
+badge on the run header. Each step shows its outcome chip — applied / in sync /
+would change / no check — and, when drift was detected, the `summarize` line
+describing what would change. The rendering is read-only.
+
+## See also
+
+- [Idempotent SDK helpers](./sdk/idempotent.md) — the `idempotent()` / `idempotentStep()` convenience wrappers, which always apply on drift inside a single step (no run-level check mode).
+- [Core SDK reference](./sdk/core.md) — the `step()`, `job()`, and `workflow()` factories the check facet extends.
+- [Lock file and drift](./lock-file-and-drift.md) — how the lock file carries step capability flags.
+
+---
+
 ## Private npm registries
 
 Source: https://docs.kici.dev/user/private-registries/
@@ -9618,7 +10083,83 @@ forge side looks like:
 Use the App when you can; the `github-repo` preset is a fallback for
 repos where you can't install an App.
 
-## Create the GitHub App on GitHub's side
+## One-click setup (recommended)
+
+`kici-admin source add github --manifest` creates **and** configures the
+GitHub App for you via GitHub's App Manifest flow. KiCI builds a manifest
+with the exact permissions, events, webhook URL, and webhook secret baked
+in, so you never pick permissions, paste a URL, generate a secret, or
+download a `.pem` by hand — the App is correct by construction.
+
+```bash
+kici-admin --url http://<orchestrator-host>:4000 --token $KICI_BOOTSTRAP_ADMIN_TOKEN \
+  source add github --manifest --name my-org --github-org my-org
+```
+
+`--github-org <slug>` creates the App under a GitHub **organization** (the
+`<slug>` is the org's `github.com/<slug>` URL slug, not its display name) — the
+recommended default, since org-owned Apps can be installed across the org. Drop
+the flag only when you deliberately want a personal-account App, which can be
+installed solely on repos you own. You need permission to create Apps in that
+org (be an org owner, or have the org allow member App creation).
+
+What happens:
+
+1. The CLI resolves your org's webhook URL and opens GitHub with a
+   pre-filled App manifest. You click **"Create GitHub App"** once — the
+   only manual step.
+2. GitHub redirects back to a localhost callback; the CLI exchanges the
+   returned setup code for the App's id, private key, and webhook secret.
+   **The private key is exchanged and stored only on your orchestrator
+   host — it never transits the KiCI Platform.**
+3. The CLI stores the credentials encrypted under `KICI_SECRET_KEY` and
+   registers the routing key `github:<appId>`, reusing the same storage
+   path as the manual flow.
+4. It opens the App's install page so you can pick repos, then verifies
+   end-to-end: it waits for the installation, mints an installation token,
+   and confirms repo access before declaring success.
+
+```
+$ kici-admin source add github --manifest --name my-org --github-org my-org
+→ Opening GitHub to create your App…
+→ ✓ App created (id 12345), credentials captured
+→ ✓ Stored on orchestrator (encrypted), registered as github:12345
+→ Install the App on your repos: https://github.com/apps/my-org/installations/new
+→ ✓ Installation detected (account my-org)
+→ ✓ Credentials verified (3 repositories reachable)
+
+GitHub App "my-org" is live.
+  Webhook: https://<platform-host>/webhook/<orgId>/github
+```
+
+**Flags:**
+
+| Flag                  | Effect                                                                                                                                                                                                                                                                                |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--name <name>`       | The App name you _request_ on GitHub (required). GitHub assigns the final name + slug; the stored, displayed name always comes from GitHub (see [Display name and slug](#display-name-and-slug)).                                                                                     |
+| `--github-org <slug>` | Create the App under a GitHub organization instead of your personal account.                                                                                                                                                                                                          |
+| `--webhook-url <url>` | **Advanced / self-hosted.** Bake this `https://` URL into the App's webhook verbatim and skip the platform-mode webhook-URL resolution (so it works even where the auto-resolved KiCI Platform URL is unavailable). See [Self-hosted webhook URL](#self-hosted-webhook-url-override). |
+| `--no-browser`        | Headless mode: the CLI prints a `kici.dev` URL to open, then reads the setup code you paste back. The page is pure client-side — it only displays the short-lived code, which is useless once the CLI exchanges it.                                                                   |
+
+The manifest flow always creates a **new** App on GitHub. If a source for
+that App id already exists on the orchestrator, the command refuses — use
+`source update` to rotate an existing App's credentials.
+
+If any step after App creation fails (e.g. storage), the CLI prints the
+captured App id and writes the private key to a `0600` file, then tells
+you how to finish with the manual `source add github` command — so a
+created App is never orphaned.
+
+Independent-mode orchestrators have no GitHub-App ingress (it is
+Platform-relayed), so the manifest flow is unavailable there; use a
+generic webhook source instead.
+
+## Manual setup (fallback)
+
+When you'd rather create the App by hand — or your environment can't run
+the manifest flow — follow these steps.
+
+### Create the GitHub App on GitHub's side
 
 1. **Decide the App scope.** User-owned Apps can only be installed on
    repos you own; organization-owned Apps can be installed anywhere in
@@ -9694,7 +10235,7 @@ repos where you can't install an App.
    KiCI runs. Re-install to add repos later — this is live and
    revocable without redeploying the App.
 
-## Register the App with the orchestrator
+### Register the App with the orchestrator
 
 With the App ID, private key `.pem`, and webhook secret in hand:
 
@@ -9762,6 +10303,53 @@ its own source record and the orchestrator looks up the right one by
 combining the URL's `<orgId>` with the App ID from the
 `X-GitHub-Hook-Installation-Target-ID` header.
 
+## Display name and slug
+
+For a GitHub App source, **GitHub is the source of truth for the displayed
+name**. `--name` is only the name you _request_ when the App is created;
+GitHub assigns the final display name and a URL-safe **slug**
+(`my-org` → `my-org-1` if the name was taken). KiCI captures both at creation
+and shows them in the dashboard **Sources** tab — the display name prominently,
+with the slug as dimmed secondary text.
+
+If you later rename the App in GitHub's UI, KiCI keeps the displayed name in
+sync two ways:
+
+- **Automatically**, on a daily schedule. The orchestrator re-reads each GitHub
+  source's name + slug from GitHub and updates the dashboard if they changed.
+  The interval is configurable via `KICI_GITHUB_APP_NAME_REFRESH_INTERVAL_MS`
+  (default 24h).
+- **On demand**, with `source refresh`:
+
+  ```bash
+  kici-admin source refresh github:<appId>   # one source
+  kici-admin source refresh --all            # every GitHub source
+  ```
+
+  It prints `old → new` for any name or slug that changed, and is a no-op when
+  GitHub already matches what KiCI has stored. Non-GitHub routing keys are
+  rejected — name/slug sync applies only to GitHub App sources.
+
+## Self-hosted webhook URL override
+
+By default the manifest flow bakes the KiCI Platform webhook endpoint
+(`https://<platform-host>/webhook/<orgId>/github`) into the App. If you run
+your own ingress and want GitHub to deliver events to it instead, pass
+`--webhook-url` when creating the App:
+
+```bash
+kici-admin source add github --manifest --name my-org \
+  --webhook-url https://hooks.my-infra.example/github
+```
+
+The supplied URL must be an absolute `https://` URL; it is written into the
+App's webhook configuration **verbatim**. This is the operator asserting "I own
+webhook delivery": KiCI adds **no** ingress at this URL and does **not** receive
+events there — your own infrastructure is responsible for accepting GitHub's
+deliveries and routing them onward. Supplying the flag also decouples App
+creation from platform-mode URL resolution, so it works even in a configuration
+where the auto-resolved KiCI Platform URL is unavailable.
+
 ## Global workflows
 
 A GitHub App source opts in to org-wide global workflows using the
@@ -10273,7 +10861,7 @@ Source: https://docs.kici.dev/architecture/data-flows/
 
 This document describes the key data flows through the KiCI architecture: webhook delivery, job execution, developer-initiated remote runs, dependency caching, re-run and cancel, trace ID propagation, internal event routing, and generic webhook ingestion.
 
-> **Lock file schema version:** The lock file uses schema version 17, which widens per-job init to typed presets (`mise` / `{ mise }`) and `auto` detection on top of v16's normalized approval config, v15's per-job init config, v14's declarative cache specs, v11's `LockInlineValue` for pure function inline evaluation, v10's simplified negative patterns (! prefix in repos/paths arrays), v9's global workflow repos matching, and v8's runsOn polymorphic type support.
+> **Lock file schema version:** The lock file uses schema version 21, which adds the `CheckMode` / `CheckStepOutcome` enums for check-mode step execution on top of v20's `LabelMatcher` (exact/regex) selectors for `runsOn`/`runsOnAll`/`excludeLabels`, v19's `maxParallel`/`failFast` fan-out concurrency, v18's `runsOnAll` host fan-out predicate and `onUnreachable` policy, v17's typed init presets (`mise` / `{ mise }`) and `auto` detection, v16's normalized approval config, v15's per-job init config, v14's declarative cache specs, v11's `LockInlineValue` for pure function inline evaluation, v10's simplified negative patterns (! prefix in repos/paths arrays), v9's global workflow repos matching, and v8's runsOn polymorphic type support.
 
 ## Webhook delivery flow
 
@@ -10479,7 +11067,7 @@ Dep cache misses alone do **not** trigger a build job. Deps are platform-specifi
 
 ### Cross-source / no-contentHash workflows
 
-- **Lock files without `contentHash`** (schema v1) skip the source cache entirely; agents compile from source. Regenerate lock files with `kici compile` to enable caching. The current lock file schema version is 17.
+- **Lock files without `contentHash`** (schema v1) skip the source cache entirely; agents compile from source. Regenerate lock files with `kici compile` to enable caching. The current lock file schema version is 21.
 - **Cross-source / global-workflow dispatch** (a workflow registered against source A fired by a webhook on source B) bypasses both caches. The registration's lock file entry still carries `contentHash`, but the cross-source path always clone-and-installs — the eval temp dir doesn't ship `@kici-dev/sdk`. The execution agent still verifies `contentHash` against the cloned source for drift detection.
 
 ### Build deduplication
@@ -10518,7 +11106,7 @@ Both source and dep caches use `S3CacheStorage` as the sole backend. The `CacheS
 
 Cache keys reflect that source tarballs and deps have different platform characteristics:
 
-- **Source:** `source/{contentHash}.tar.gz` — platform-agnostic. Raw TypeScript source is identical regardless of CPU architecture, so one entry is shared across all platforms. `contentHash` is the per-workflow hash from the lock file (`SHA-256(schemaVersion + ":" + rawSource [+ "\0" + assetDigest])`).
+- **Source:** `source/{contentHash}.tar.gz` — platform-agnostic. Raw TypeScript source is identical regardless of CPU architecture, so one entry is shared across all platforms. `contentHash` is the per-workflow hash from the lock file (`SHA-256(COMPILE_SCHEMA_VERSION + ":" + rawSource [+ "\0" + assetDigest])`, where `COMPILE_SCHEMA_VERSION = 5` and line endings are normalized to LF so the hash agrees across platforms).
 - **Deps:** `deps/{platform}-{arch}/{lockfileHash}.tar.gz` (e.g., `deps/linux-arm64/def456.tar.gz`) — platform-specific. Native dependencies in `node_modules` differ across architectures, so each platform/arch combination gets its own cache entry.
 
 The orchestrator derives the target platform/arch for dep cache lookups by probing `AgentRegistry.findAvailable()` with the workflow's first job's `runsOn` labels to find a representative matching agent, then using that agent's platform and arch. Falls back to `linux/x64` if no matching agents are registered.
@@ -11163,7 +11751,9 @@ This model also enables fully self-hosted deployment: all three tiers can run on
 
 ### Platform
 
-The Platform tier is a thin webhook router. It verifies inbound webhook signatures, relays the payload to the correct orchestrator over WebSocket, and writes a delivery row to its event log. It does not process, store, or execute any customer code. Multi-tenant SaaS specifics (Stripe-driven billing, dashboard surface, identity provider integration) are documented in the internal docs.
+The Platform is KiCI's hosted, multi-tenant control plane. It provides the hosted dashboard (run listing, run detail, live log streaming, settings), identity and authentication (OIDC, personal access tokens, API keys, JWTs), multi-tenant organization / team / role-based access management, billing, and webhook ingestion -- verifying inbound signatures (HMAC-SHA256, timing-safe) and relaying payloads to the correct orchestrator over WebSocket. It aggregates execution telemetry and status forwarded by orchestrators, registers sources, and matchmakes peers for clustering.
+
+The Platform never processes, stores, or executes customer code, and never sees customer secrets. It routes webhook payloads and aggregates execution status; the code itself only ever lives on the customer's orchestrator and agent tiers. In the execution path the Platform is deliberately thin -- it does not run jobs -- but functionally it is a full platform, not merely a relay. The hosted Platform is EU-sovereign.
 
 ### Orchestrator (`@kici-dev/orchestrator`)
 
@@ -11198,7 +11788,7 @@ The agent is the execution worker. It runs on customer infrastructure and has fu
 
 Shared business logic used by all three tiers. Single source of truth for cross-tier concerns. Has no internal `@kici-dev/*` dependencies -- only a handful of third-party libraries.
 
-- Protocol message schemas (Zod-based, direction-specific unions including dashboard REST-over-WS, browser live streaming, test run lifecycle, observer channel, log pull, run events, peer-to-peer, cluster join, and source registration)
+- Protocol message schemas (Zod-based, direction-specific unions including dashboard REST-over-WS, browser live streaming, the test-relay control plane, log pull, run events, peer-to-peer, cluster join, and source registration)
 - Provider interfaces (WebhookNormalizer, LockFileFetcher, ChangedFilesFetcher, CloneTokenProvider, RepoUrlBuilder, ContributorResolver, CheckStatusPoster)
 - Trigger matching engine (branch, path, event evaluation)
 - Execution state machine (11 states, 16 events, pure functions)