@kici-dev/compiler 0.1.21 → 0.1.23

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

@@ -12,75 +12,75 @@ Documentation for workflow authors -- people writing CI/CD pipelines in TypeScri
 
 ## Pages
 
-### [Getting started with KiCI](getting-started.md)
+### [Getting started with KiCI](https://docs.kici.dev/user/getting-started/)
 
 Install the SDK and compiler, write your first workflow, compile it to a lock file, and test it locally with simulated events. Covers prerequisites (Node.js 24+, pnpm), the `kici init` command for scaffolding, and the relationship between workflows, the lock file, and the three-tier runtime.
 
-### [SDK reference](sdk-reference.md)
+### [SDK reference](https://docs.kici.dev/user/sdk-reference/)
 
 Complete API reference for `@kici-dev/sdk`. Covers all factory functions (`workflow()`, `job()`, `step()`), trigger builders (`pr()`, `push()`), rule functions (`rule()`, `skip()`), matrix configuration (static arrays, static objects, dynamic functions, include/exclude), and the `StepContext` interface that steps receive at runtime.
 
-### [Lock file and workflow drift](lock-file-and-drift.md)
+### [Lock file and workflow drift](https://docs.kici.dev/user/lock-file-and-drift/)
 
 Why the lock file must stay in sync with workflow source, how to commit both together, using pre-commit and CI to catch drift early, and the agent-side hash verification when compiling from source.
 
-### [CLI reference](cli-reference.md)
+### [CLI reference](https://docs.kici.dev/user/cli-reference/)
 
 All CLI commands provided by `@kici-dev/compiler`: `kici compile` (with watch mode and check mode), `kici run` (local and remote execution), `kici test` (event simulation with dry-run, filtering, debug output, and custom payloads), `kici login`/`logout`/`org` (authentication and org management), `kici diagnostics` (infrastructure tree) and `kici runs` (`list`/`show`/`logs`/`rerun`/`cancel` — run management), `kici secrets` (secret listing), `kici types` (type generation), `kici fixture` (generate test payloads), `kici init` (interactive project scaffolding), `kici hook` (pre-commit hook installation), `kici endpoints` (webhook entrypoints), and `kici workflows` (workflow listing). Includes environment variables and exit codes.
 
-### [Workflow patterns](workflow-patterns.md)
+### [Workflow patterns](https://docs.kici.dev/user/workflow-patterns/)
 
 Common patterns for building real-world CI/CD workflows. Includes examples for basic CI pipelines with job dependencies, monorepo path-based triggering, conditional jobs with rules, matrix builds across Node versions, dynamic jobs generated at runtime, Docker-based step execution, and parallel test splitting.
 
-### [Dashboard](dashboard.md)
+### [Dashboard](https://docs.kici.dev/user/dashboard/)
 
 Guide to the KiCI web dashboard. Covers navigation (sidebar, org switcher, mobile bottom tabs), run list (table columns, filters, pagination, empty states), run detail (resizable two-panel layout, job tree, step selection, metadata tabs), log viewer (ANSI color rendering, search, permalink, copy), settings page (tabbed layout), theme toggle, keyboard shortcuts, and error pages.
 
-### [Testing guide](testing-guide.md)
+### [Testing guide](https://docs.kici.dev/user/testing-guide/)
 
 How to run and write tests for KiCI workflows, including remote test execution with `kici run remote`, fixture-based testing, and overlay mode for uncommitted changes.
 
-### [Environments](environments.md)
+### [Environments](https://docs.kici.dev/user/environments/)
 
 Configure deployment environments (staging, production, review/\*) with variables, scoped secrets, and protection rules. Covers the SDK API (`environment`, `env`, `concurrencyGroup` on jobs), the 8-layer variable merge precedence, protection rules (branch restrictions, required reviewers, wait timers, concurrency), dashboard management, type generation, and migration from the legacy contexts system.
 
-### [Environment variables](env-vars.md)
+### [Environment variables](https://docs.kici.dev/user/env-vars/)
 
 Reference for all `KICI_*` environment variables supported by the CLI. Covers authentication overrides (OIDC issuer, client ID, project ID), browser behavior (custom browser command, fixed callback port), development mode, and usage examples for CI/CD, self-hosted, and headless environments.
 
-### [CLI authentication](cli-auth.md)
+### [CLI authentication](https://docs.kici.dev/user/cli-auth/)
 
 Authenticate the KiCI CLI with browser-based OAuth (default), device authorization flow (for headless environments), or API key paste (for CI/CD pipelines). Covers org management and PATs.
 
-### [Event system](events.md)
+### [Event system](https://docs.kici.dev/user/events/)
 
 Event model concepts: event types, the registration model, event matching, and circuit breaker protection. Understanding this distinction is key to working with non-git triggers like schedules, custom events, and generic webhooks.
 
-### [Lifecycle hooks](hooks.md)
+### [Lifecycle hooks](https://docs.kici.dev/user/hooks/)
 
 SDK hook API for cancel, cleanup, success, failure, and step-level callbacks. Hooks run at specific points in the execution lifecycle to react to outcomes and perform cleanup.
 
-### [Concurrency groups](concurrency.md)
+### [Concurrency groups](https://docs.kici.dev/user/concurrency/)
 
 Control parallel execution with auto-cancel and queue modes. Prevent multiple workflow runs from executing in parallel when they target the same resource.
 
-### [Dynamic values](dynamic-values.md)
+### [Dynamic values](https://docs.kici.dev/user/dynamic-values/)
 
 Compute `environment`, `env`, and `concurrencyGroup` at runtime based on the incoming event payload. Instead of hardcoding static strings, pass a function that receives the webhook event and returns the resolved value.
 
-### [Secrets](secrets.md)
+### [Secrets](https://docs.kici.dev/user/secrets/)
 
 Access encrypted secrets in workflow steps via the explicit secrets API. Secrets are never auto-injected into `process.env` -- you must explicitly request each secret by name.
 
-### [GitHub App provider](providers/github.md)
+### [GitHub App provider](https://docs.kici.dev/user/providers/github/)
 
 The flagship source. Covers creating the GitHub App on GitHub's side (permissions, webhook URL, private key), registering it with the orchestrator via `kici-admin source add github`, routing keys (`github:<appId>`), global-workflow policy, enriched Check runs on pull requests, private-key and webhook-secret rotation, and troubleshooting.
 
-### [Universal-git provider](providers/universal-git.md)
+### [Universal-git provider](https://docs.kici.dev/user/providers/universal-git/)
 
 Connect a non-GitHub-App forge (Forgejo, Gitea, Gogs, GitLab, plain GitHub) to KiCI via its webhook. Covers preset selection, PAT and SSH credential wiring, credential rotation, global workflow policy against `generic:<orgId>:<sourceId>` routing keys, and troubleshooting.
 
-### [Global workflows](global-workflows.md)
+### [Global workflows](https://docs.kici.dev/user/global-workflows/)
 
 Cross-repo workflows that let a single workflow repo define jobs which run on events from many source repos in the same org. Covers the mental model (workflow repo vs. source repo, authoring axis vs. source axis), SDK syntax for declaring globals via `repos:` patterns, the dashboard opt-in flow and per-setting semantics (master toggle, author allow-list, source deny-list, elevated-access list), the security model, and troubleshooting skipped dispatches.
 
@@ -136,7 +136,7 @@ npx kici init --mjs
 
 This creates `.mjs` workflow files that run directly without a build step.
 
-After running `kici init`, jump straight to [Compile the workflow](#compile-the-workflow) below to compile and preview the scaffolded workflow.
+After running `kici init`, jump straight to [Compile the workflow](https://docs.kici.dev/user/getting-started/#compile-the-workflow) below to compile and preview the scaffolded workflow.
 
 ## Manual setup
 
@@ -215,7 +215,7 @@ This workflow:
 - Runs a `lint` job first
 - Runs a `test` job after lint succeeds (`needs: [lint]`)
 
-`runsOn` selects which agents may run a job. Every agent self-reports `kici:os:<platform>`, `kici:arch:<cpu>`, and `kici:host:<hostname>`, so `runsOn: 'kici:os:linux'` targets any connected Linux agent with zero configuration — `kici init` scaffolds workflows with exactly that. Use a custom label such as `'linux'` or `'gpu'` (defined in your scaler's `labelSet`) to target a specific pool instead. See the [runsOn forms](./sdk/core.md#runson-forms) reference for the full label model.
+`runsOn` selects which agents may run a job. Every agent self-reports `kici:os:<platform>`, `kici:arch:<cpu>`, and `kici:host:<hostname>`, so `runsOn: 'kici:os:linux'` targets any connected Linux agent with zero configuration — `kici init` scaffolds workflows with exactly that. Use a custom label such as `'linux'` or `'gpu'` (defined in your scaler's `labelSet`) to target a specific pool instead. See the [runsOn forms](https://docs.kici.dev/user/sdk/core/#runson-forms) reference for the full label model.
 
 **Single-step shortcut.** If a job only has one step, pass `run` directly to `job()` instead of building a `steps: [step(...)]` array:
 
@@ -229,7 +229,7 @@ const deploy = job('deploy', {
 });
 ```
 
-`run` and `steps` are mutually exclusive. The shorthand is ideal for deploy/notify/smoke-test jobs. See [Single-step job shorthand](sdk/core.md#single-step-job-shorthand) in the SDK reference for details (output access on the resulting `job.result` is flat -- no step-name nesting).
+`run` and `steps` are mutually exclusive. The shorthand is ideal for deploy/notify/smoke-test jobs. See [Single-step job shorthand](https://docs.kici.dev/user/sdk/core/#single-step-job-shorthand) in the SDK reference for details (output access on the resulting `job.result` is flat -- no step-name nesting).
 
 ## Compile the workflow
 
@@ -245,7 +245,7 @@ Expected output:
 ✓ Compiled workflows → .kici/kici.lock.json (1 workflow)
 ```
 
-The lock file (`kici.lock.json`) is a JSON representation of your workflow that the KiCI agent uses for execution. Commit this file alongside your workflow source. See [Lock file and workflow drift](lock-file-and-drift.md) for why and how to keep them in sync.
+The lock file (`kici.lock.json`) is a JSON representation of your workflow that the KiCI agent uses for execution. Commit this file alongside your workflow source. See [Lock file and workflow drift](https://docs.kici.dev/user/lock-file-and-drift/) for why and how to keep them in sync.
 
 ## Preview trigger matching
 
@@ -316,7 +316,7 @@ Every `.kici/` dependency must be resolvable from the **single cloned repository
 
 In practice:
 
-- **From a registry** — the common case. Pin a published version (a private registry works — see [Private registries](./private-registries.md)). Available for any package manager.
+- **From a registry** — the common case. Pin a published version (a private registry works — see [Private registries](https://docs.kici.dev/user/private-registries/)). Available for any package manager.
 - **From an in-repo workspace sibling** — if your `.kici/` is a member of a **pnpm workspace** or a **yarn berry workspace** (a `workspaces` array in the repo-root `package.json`), it can depend on a sibling package in the same repo via `workspace:*` (yarn berry also accepts `portal:`). The whole repo is cloned, so the sibling is present and resolves; the agent also builds your `.kici/` dependency closure after install, so a sibling's build output exists before the workflow that imports it loads. A `file:`/`link:`/`portal:` path is allowed only when it stays inside the repository.
 
 What fails fast (with an actionable error naming the dependency, not a raw package-manager error): a `workspace:` dependency in an **npm** project (npm has no workspace protocol — pin a published version or switch to pnpm), a `workspace:`/`portal:` dependency in a **yarn classic** project (v1 has neither — use a version range, pnpm, or yarn berry), a `workspace:` dependency in a **yarn berry** project whose repo-root `package.json` has no `workspaces` array, and any `file:`/`link:`/`portal:` path that points outside the cloned repo.
@@ -450,10 +450,10 @@ The compiler watches `.kici/workflows/*.ts` and recompiles on every save.
 
 ## Next steps
 
-- **[5-minute quickstart](quickstart.md)** -- ready to run your workflow on real infrastructure? Stand up an orchestrator + agent (Docker / Podman or bare metal)
-- **[SDK reference](sdk-reference.md)** -- complete API for workflows, jobs, steps, triggers, rules, and matrix
-- **[CLI reference](cli-reference.md)** -- all CLI commands with options and examples
-- **[Workflow patterns](workflow-patterns.md)** -- common patterns for real-world CI/CD workflows
+- **[5-minute quickstart](https://docs.kici.dev/user/quickstart/)** -- ready to run your workflow on real infrastructure? Stand up an orchestrator + agent (Docker / Podman or bare metal)
+- **[SDK reference](https://docs.kici.dev/user/sdk-reference/)** -- complete API for workflows, jobs, steps, triggers, rules, and matrix
+- **[CLI reference](https://docs.kici.dev/user/cli-reference/)** -- all CLI commands with options and examples
+- **[Workflow patterns](https://docs.kici.dev/user/workflow-patterns/)** -- common patterns for real-world CI/CD workflows
 
 ## How KiCI works
 
@@ -475,10 +475,10 @@ The lock file approach means the orchestrator stays git-agnostic -- it only need
 
 ## See also
 
-- [SDK reference](sdk-reference.md) -- complete API for workflows, jobs, steps, triggers, rules, and matrix
-- [CLI reference](cli-reference.md) -- all CLI commands with options and examples
-- [Workflow patterns](workflow-patterns.md) -- common patterns for real-world CI/CD workflows
-- [Architecture overview](../architecture/overview.md) -- how the three-tier runtime executes your workflows
+- [SDK reference](https://docs.kici.dev/user/sdk-reference/) -- complete API for workflows, jobs, steps, triggers, rules, and matrix
+- [CLI reference](https://docs.kici.dev/user/cli-reference/) -- all CLI commands with options and examples
+- [Workflow patterns](https://docs.kici.dev/user/workflow-patterns/) -- common patterns for real-world CI/CD workflows
+- [Architecture overview](https://docs.kici.dev/architecture/overview/) -- how the three-tier runtime executes your workflows
 
 ---
 
@@ -494,13 +494,13 @@ Each guide is split into two parts. **Part 1** gets you a green run against your
 
 Two containers brought up with `docker compose up -d` (orchestrator + PostgreSQL), plus one short-lived agent container spawned per job by the container scaler. Minimal host setup, perfect for a laptop, home server, or a tiny VM. No need to install PostgreSQL or any other system service.
 
-[Start with the Docker / Podman quickstart →](./quickstart/compose.md)
+[Start with the Docker / Podman quickstart →](https://docs.kici.dev/user/quickstart/compose/)
 
 ## Option B — Bare-metal install
 
 Native systemd services managed by `kici-admin orchestrator install` / `kici-admin agent install` — the orchestrator and agents run as native processes. The backing PostgreSQL runs as a single container by default (one `docker compose up -d`), or you can install it natively if you'd rather not run a container runtime at all. Best for a long-lived Linux host.
 
-[Start with the bare-metal quickstart →](./quickstart/bare-metal.md)
+[Start with the bare-metal quickstart →](https://docs.kici.dev/user/quickstart/bare-metal/)
 
 ## Which should I pick?
 
@@ -516,7 +516,7 @@ If you're not sure, pick Docker / Podman.
 
 ## Looking for the laptop-only path?
 
-Both quickstarts deploy a real orchestrator + agent. If you only want to write a workflow and dry-run it on your laptop with no infrastructure, [Getting started](./getting-started.md) covers `kici test` and `kici run local` instead.
+Both quickstarts deploy a real orchestrator + agent. If you only want to write a workflow and dry-run it on your laptop with no infrastructure, [Getting started](https://docs.kici.dev/user/getting-started/) covers `kici test` and `kici run local` instead.
 
 ---
 
@@ -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`)](https://docs.kici.dev/user/sdk/core/#job-dependencies-needs) in the SDK reference for the full matrix of `needs` forms (string, `Job` ref, `{ name, when }`, `dynamicGroup()`) and [needs-scheduler](https://docs.kici.dev/architecture/execution/needs-scheduler/) 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(...)]`:
 
@@ -597,7 +597,7 @@ export default workflow('smoke', {
 });
 ```
 
-`run` is mutually exclusive with `steps` (throws at compile time if both are set). Outputs are flat on `job.result` (no step-name nesting). See [Single-step job shorthand](../sdk/core.md#single-step-job-shorthand) in the SDK reference.
+`run` is mutually exclusive with `steps` (throws at compile time if both are set). Outputs are flat on `job.result` (no step-name nesting). See [Single-step job shorthand](https://docs.kici.dev/user/sdk/core/#single-step-job-shorthand) in the SDK reference.
 
 ## PR-only workflow with branch filters
 
@@ -744,7 +744,7 @@ npx kici compile           # regenerate .kici/kici.lock.json
 npx kici run local dispatch
 ```
 
-`kici run local` compiles the workflow, matches triggers against a simulated `dispatch` event, and executes the matched jobs directly on your machine with DAG-based scheduling. No webhook, no GitHub, no deployed orchestrator involved. See [`kici run local`](../cli-reference.md#kici-run-local) for options like `--job`, `--env`, `--json`, and `--junit`.
+`kici run local` compiles the workflow, matches triggers against a simulated `dispatch` event, and executes the matched jobs directly on your machine with DAG-based scheduling. No webhook, no GitHub, no deployed orchestrator involved. See [`kici run local`](https://docs.kici.dev/user/cli-reference/#kici-run-local) for options like `--job`, `--env`, `--json`, and `--junit`.
 
 ### Scoping to a single workflow
 
@@ -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/
@@ -1157,7 +1267,7 @@ export const postDeploy = workflow('post-deploy', {
 
 ### Same-run discovery → fan-out
 
-A result-aware [`dynamicJob(group, { needs, generate })`](../sdk/rules-matrix-dynamic.md#dynamicjob--result-aware-generation) is deferred until its declared upstreams complete, then runs with their frozen outputs as `ctx.needs` — so a discovery job can emit a list at runtime and the generator fans out one follow-up job per item, all in the same run:
+A result-aware [`dynamicJob(group, { needs, generate })`](https://docs.kici.dev/user/sdk/rules-matrix-dynamic/#dynamicjob--result-aware-generation) is deferred until its declared upstreams complete, then runs with their frozen outputs as `ctx.needs` — so a discovery job can emit a list at runtime and the generator fans out one follow-up job per item, all in the same run:
 
 ```typescript
 import { workflow, job, step, push, dynamicJob, z } from '@kici-dev/sdk';
@@ -1263,7 +1373,7 @@ export default workflow('on-argocd-deploy', {
 });
 ```
 
-See the [Operator guide: event routing](../../operator/event-routing.md) for how to set up generic webhook sources, verification methods, and trust relationships.
+See the [Operator guide: event routing](https://docs.kici.dev/operator/event-routing/) for how to set up generic webhook sources, verification methods, and trust relationships.
 
 ## Stripe webhook handler
 
@@ -1305,9 +1415,9 @@ export default workflow('stripe-invoice-handler', {
 
 **Prerequisites:**
 
-- An operator must create a generic webhook source named `stripe` via the admin API. See [Operator guide: creating a source](../../operator/event-routing.md#creating-a-source).
+- An operator must create a generic webhook source named `stripe` via the admin API. See [Operator guide: creating a source](https://docs.kici.dev/operator/event-routing/#creating-a-source).
 - The `stripe-signing-key` secret must contain your Stripe webhook signing secret.
-- This workflow uses the [registration model](../events.md#the-registration-model) -- it will not trigger until you push to your default branch.
+- This workflow uses the [registration model](https://docs.kici.dev/user/events/#the-registration-model) -- it will not trigger until you push to your default branch.
 
 ## Self-hosted git forge (Gogs, Forgejo, Gitea)
 
@@ -1356,7 +1466,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](../../architecture/webhooks/webhook-delivery.md#cross-source-delivery). The clone runs against the GitHub mirror using the GitHub App's token.
+- **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.
 - **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.
 
@@ -1390,7 +1500,7 @@ HTTPS with a forge PAT works the same way — store the token as a secret, `awai
 
 - An operator must create a generic webhook source via `kici-admin source add generic` (see above).
 - The forge's webhook secret must match the `--secret` value.
-- The workflow uses the [registration model](../events.md#the-registration-model) -- push to the default branch of a registered repo before the first webhook fires.
+- The workflow uses the [registration model](https://docs.kici.dev/user/events/#the-registration-model) -- push to the default branch of a registered repo before the first webhook fires.
 
 ## Plain GitHub repo webhooks (no GitHub App)
 
@@ -1452,12 +1562,12 @@ export default workflow('on-github-repo-push', {
 **What you lose compared to the GitHub App** (these are the same cloning / metadata caveats that apply to the Gogs/Forgejo pattern, plus GitHub-specific integrations):
 
 - No auto-clone — `packages/agent/src/checkout/git-clone.ts` uses GitHub App installation tokens to fetch the repo; a generic source has none. Either set `checkout: false` and clone yourself with a PAT/Deploy Key secret (same pattern as the Forgejo manual-clone example above), or keep the workflow self-contained.
-- No lock-file fetch — the orchestrator cannot fetch `.kici/kici.lock.json` at the pushed SHA via the GitHub API. The workflow must be pre-registered via the [registration model](../events.md#the-registration-model); ad-hoc per-commit workflow discovery that a GitHub App push gives you is not available.
+- No lock-file fetch — the orchestrator cannot fetch `.kici/kici.lock.json` at the pushed SHA via the GitHub API. The workflow must be pre-registered via the [registration model](https://docs.kici.dev/user/events/#the-registration-model); ad-hoc per-commit workflow discovery that a GitHub App push gives you is not available.
 - No changed-files enrichment — `event.changedFiles` is empty. Use JSONPath `match` on `rawPayload.commits[*].added/modified/removed` if you need path filters.
 - No check-run integration — KiCI cannot post Check Run results back to GitHub.
 - Workflow authors must use `genericWebhook()`, not `push()` / `pr()` / `webhook()` — the latter three only match events delivered through the native GitHub App provider.
 
-**When to use it anyway:** trigger-only workflows that don't need the cloned repo — posting Slack messages, kicking off external deploys, forwarding to downstream systems, or exposing GitHub repo events as `genericWebhook` for same-org [cross-source fan-out](../../architecture/webhooks/webhook-delivery.md#cross-source-delivery). For anything that compiles, tests, or checks code, install the GitHub App instead.
+**When to use it anyway:** trigger-only workflows that don't need the cloned repo — posting Slack messages, kicking off external deploys, forwarding to downstream systems, or exposing GitHub repo events as `genericWebhook` for same-org [cross-source fan-out](https://docs.kici.dev/architecture/webhooks/webhook-delivery/#cross-source-delivery). For anything that compiles, tests, or checks code, install the GitHub App instead.
 
 ## Nightly cron build
 
@@ -1590,7 +1700,7 @@ export default workflow('nightly-build', {
 **Notes:**
 
 - The `cron` field uses standard 5-field cron syntax. Use the `timezone` option (defaults to `'UTC'`) to control evaluation in a specific timezone: `schedule({ cron: '0 2 * * *', timezone: 'America/New_York' })`.
-- Schedule workflows use the [registration model](../events.md#the-registration-model) -- the cron will not start firing until you push to your default branch.
+- Schedule workflows use the [registration model](https://docs.kici.dev/user/events/#the-registration-model) -- the cron will not start firing until you push to your default branch.
 - In clustered orchestrator deployments, only the Raft leader evaluates cron schedules. If the leader changes, the new leader recovers missed schedules.
 
 **Timing precision and scaling:**
@@ -1654,7 +1764,7 @@ export const deploy = workflow('deploy-on-success', {
 
 - `workflowComplete()` is a system event trigger -- the orchestrator automatically emits these events when workflows finish. You do not need to call `ctx.emit()`.
 - The `status` filter accepts `'success'`, `'failed'`, and `'cancelled'`. Omit `status` to trigger on any completion.
-- The `deploy-on-success` workflow uses the [registration model](../events.md#the-registration-model) -- it will not trigger until you push to your default branch. The `build` workflow (using `push()`) works immediately.
+- The `deploy-on-success` workflow uses the [registration model](https://docs.kici.dev/user/events/#the-registration-model) -- it will not trigger until you push to your default branch. The `build` workflow (using `push()`) works immediately.
 - You can also use `jobComplete()` to trigger on individual job completions within a workflow.
 
 ## Custom event chaining
@@ -1726,8 +1836,8 @@ export const autoDeploy = workflow('auto-deploy', {
 - `defineEvent()` creates a typed contract using Zod. This is optional but recommended for documenting event payloads.
 - Custom events are delivered immediately when `ctx.emit()` is called (mid-workflow), not queued until the workflow completes.
 - Payload matching is available via the `match` option: `kiciEvent({ name: 'tests-passed', match: { '$.branch': 'main' } })`.
-- The `auto-deploy` workflow uses the [registration model](../events.md#the-registration-model) -- it will not trigger until you push to your default branch.
-- The [circuit breaker](../events.md#circuit-breaker) limits chain depth (default: 10) and rate (default: 100/min per workflow) to prevent infinite loops.
+- The `auto-deploy` workflow uses the [registration model](https://docs.kici.dev/user/events/#the-registration-model) -- it will not trigger until you push to your default branch.
+- The [circuit breaker](https://docs.kici.dev/user/events/#circuit-breaker) limits chain depth (default: 10) and rate (default: 100/min per workflow) to prevent infinite loops.
 
 ## Step context
 
@@ -1746,7 +1856,7 @@ Two surfaces drive the same cache:
 - **Declarative** — a `cache` field on a job or a step. The runtime restores before the work runs and saves after it succeeds, with no code in your step body.
 - **Imperative** — `ctx.cache.restore(spec)` / `ctx.cache.save(spec)` inside a step body, for fine-grained control over when restore and save happen.
 
-The cache is backed by the orchestrator's object storage. Entries are isolated per organization and per ref scope (see [Isolation](#isolation)); no other tenant can read your cache, and an untrusted/fork ref can never poison the cache a trusted branch reads.
+The cache is backed by the orchestrator's object storage. Entries are isolated per organization and per ref scope (see [Isolation](https://docs.kici.dev/user/sdk/caching/#isolation)); no other tenant can read your cache, and an untrusted/fork ref can never poison the cache a trusted branch reads.
 
 ## CacheSpec
 
@@ -1863,18 +1973,18 @@ Cache storage is bounded per organization. Two mechanisms keep it bounded:
 - **Quota** — when a save pushes the org over its byte quota (`KICI_USER_CACHE_QUOTA_BYTES`, default 5 GiB), the oldest entries are evicted until the org is back under quota.
 - **TTL** — entries unused for `KICI_USER_CACHE_TTL_MS` (default 7 days) expire. The TTL refreshes on read (touch-on-read), so an actively used cache stays warm.
 
-Both knobs are operator-configured on the orchestrator — see [orchestrator storage layout](../../operator/orchestrator/storage-layout.md).
+Both knobs are operator-configured on the orchestrator — see [orchestrator storage layout](https://docs.kici.dev/operator/orchestrator/storage-layout/).
 
 ## Observability
 
-Each cache restore and save surfaces in the run timeline as a `cache:restore` / `cache:save` pseudo-step, reporting the outcome (hit/miss/saved, the matched key, bytes). The same outcomes are recorded as `cache.restore` / `cache.save` run events. See [data flows](../../architecture/data-flows.md#user-facing-cache-flow) for the restore/save protocol.
+Each cache restore and save surfaces in the run timeline as a `cache:restore` / `cache:save` pseudo-step, reporting the outcome (hit/miss/saved, the matched key, bytes). The same outcomes are recorded as `cache.restore` / `cache.save` run events. See [data flows](https://docs.kici.dev/architecture/data-flows/#user-facing-cache-flow) for the restore/save protocol.
 
 ## See also
 
-- [Core](./core.md) -- `job()` / `step()` factories the `cache` field attaches to
-- [Runtime](./runtime.md) -- `StepContext`, where `ctx.cache` lives
-- [Orchestrator storage layout](../../operator/orchestrator/storage-layout.md) -- cache prefix, quota, TTL, and eviction
-- [Data flows](../../architecture/data-flows.md#user-facing-cache-flow) -- restore/save protocol and trust→scope mapping
+- [Core](https://docs.kici.dev/user/sdk/core/) -- `job()` / `step()` factories the `cache` field attaches to
+- [Runtime](https://docs.kici.dev/user/sdk/runtime/) -- `StepContext`, where `ctx.cache` lives
+- [Orchestrator storage layout](https://docs.kici.dev/operator/orchestrator/storage-layout/) -- cache prefix, quota, TTL, and eviction
+- [Data flows](https://docs.kici.dev/architecture/data-flows/#user-facing-cache-flow) -- restore/save protocol and trust→scope mapping
 
 ---
 
@@ -1908,8 +2018,8 @@ function workflow(name: string, options: WorkflowOptions): Workflow;
 | `options.cleanup`     | `HookInput`                                                            | no       | Always runs after the workflow (success, failure, or cancel)                                                                                                |
 | `options.onSuccess`   | `HookInput`                                                            | no       | Runs on workflow success                                                                                                                                    |
 | `options.onFailure`   | `HookInput`                                                            | no       | Runs on workflow failure                                                                                                                                    |
-| `options.concurrency` | `{ group: (ctx) => string; cancelInProgress?: boolean; max?: number }` | no       | Workflow-scoped concurrency. See [Concurrency](../concurrency.md).                                                                                          |
-| `options.timeout`     | `number`                                                               | no       | Whole-run wall-clock timeout in milliseconds across all jobs. On breach the orchestrator cancels the run and marks it timed out. See [Timeouts](#timeouts). |
+| `options.concurrency` | `{ group: (ctx) => string; cancelInProgress?: boolean; max?: number }` | no       | Workflow-scoped concurrency. See [Concurrency](https://docs.kici.dev/user/concurrency/).                                                                                          |
+| `options.timeout`     | `number`                                                               | no       | Whole-run wall-clock timeout in milliseconds across all jobs. On breach the orchestrator cancels the run and marks it timed out. See [Timeouts](https://docs.kici.dev/user/sdk/core/#timeouts). |
 
 **Returns:** `Workflow` -- an immutable workflow definition.
 
@@ -1922,7 +2032,7 @@ export default workflow('ci', {
 });
 ```
 
-Secret scoping happens at the job level via `environment` (see [job options](#jobname-options--joboptions) and [Secrets](../secrets.md)) — the workflow itself does not declare which secret environments it can read.
+Secret scoping happens at the job level via `environment` (see [job options](https://docs.kici.dev/user/sdk/core/#jobname-options--joboptions) and [Secrets](https://docs.kici.dev/user/secrets/)) — the workflow itself does not declare which secret environments it can read.
 
 ### job(name, options) / job(options)
 
@@ -1940,8 +2050,8 @@ function job(options: JobOptions): Job;
 | `name`                     | `string`                                                        | no                   | Job name (auto-generated UUID if omitted)                                                                                                                                                                |
 | `options.runsOn`           | `RunsOn`                                                        | yes                  | Runner label(s) and optional exclusions (see below)                                                                                                                                                      |
 | `options.steps`            | `StepInput[]`                                                   | yes (or use `run`)   | Steps to execute in order. Mutually exclusive with `run`.                                                                                                                                                |
-| `options.run`              | `(ctx) => Promise<unknown>`                                     | yes (or use `steps`) | Single-step shorthand -- see [Single-step job shorthand](#single-step-job-shorthand). Mutually exclusive with `steps`.                                                                                   |
-| `options.needs`            | `NeedsEntry[]`                                                  | no                   | Job dependencies (must complete first) -- see [Job dependencies (`needs`)](#job-dependencies-needs)                                                                                                      |
+| `options.run`              | `(ctx) => Promise<unknown>`                                     | yes (or use `steps`) | Single-step shorthand -- see [Single-step job shorthand](https://docs.kici.dev/user/sdk/core/#single-step-job-shorthand). Mutually exclusive with `steps`.                                                                                   |
+| `options.needs`            | `NeedsEntry[]`                                                  | no                   | Job dependencies (must complete first) -- see [Job dependencies (`needs`)](https://docs.kici.dev/user/sdk/core/#job-dependencies-needs)                                                                                                      |
 | `options.rules`            | `Rule[]`                                                        | no                   | Conditions for conditional execution                                                                                                                                                                     |
 | `options.description`      | `string`                                                        | no                   | Human-readable description                                                                                                                                                                               |
 | `options.matrix`           | `Matrix`                                                        | no                   | Matrix configuration for job expansion                                                                                                                                                                   |
@@ -1949,19 +2059,19 @@ function job(options: JobOptions): Job;
 | `options.exclude`          | `MatrixExclude[]`                                               | no                   | Matrix combinations to remove                                                                                                                                                                            |
 | `options.checkout`         | `boolean`                                                       | no (default: `true`) | When `false`, agent skips git clone. Useful for deploy/notify jobs.                                                                                                                                      |
 | `options.container`        | `string \| ContainerConfig`                                     | no                   | Docker image for job execution. String form is the image name; object form adds `env`. All steps run inside the container.                                                                               |
-| `options.environment`      | `string \| ((event) => string \| Promise<string>)`              | no                   | Deployment environment for this job. Static string or async/dynamic function -- see [Dynamic values](../dynamic-values.md).                                                                              |
-| `options.env`              | `Record<string, string> \| ((event) => Record<string, string>)` | no                   | Environment variables. Static object or async/dynamic function -- see [Dynamic values](../dynamic-values.md).                                                                                            |
-| `options.concurrencyGroup` | `string \| ((event) => string \| Promise<string>)`              | no                   | Concurrency group name (defaults to environment name) -- see [Concurrency](../concurrency.md).                                                                                                           |
+| `options.environment`      | `string \| ((event) => string \| Promise<string>)`              | no                   | Deployment environment for this job. Static string or async/dynamic function -- see [Dynamic values](https://docs.kici.dev/user/dynamic-values/).                                                                              |
+| `options.env`              | `Record<string, string> \| ((event) => Record<string, string>)` | no                   | Environment variables. Static object or async/dynamic function -- see [Dynamic values](https://docs.kici.dev/user/dynamic-values/).                                                                                            |
+| `options.concurrencyGroup` | `string \| ((event) => string \| Promise<string>)`              | no                   | Concurrency group name (defaults to environment name) -- see [Concurrency](https://docs.kici.dev/user/concurrency/).                                                                                                           |
 | `options.onCancel`         | `HookInput`                                                     | no                   | Hook that runs when the job is cancelled                                                                                                                                                                 |
 | `options.cleanup`          | `HookInput`                                                     | no                   | Hook that always runs after completion                                                                                                                                                                   |
 | `options.onSuccess`        | `HookInput`                                                     | no                   | Hook that runs when the job succeeds                                                                                                                                                                     |
 | `options.onFailure`        | `HookInput`                                                     | no                   | Hook that runs when the job fails                                                                                                                                                                        |
 | `options.beforeStep`       | `HookInput`                                                     | no                   | Hook that runs before each step                                                                                                                                                                          |
 | `options.afterStep`        | `HookInput`                                                     | no                   | Hook that runs after each step                                                                                                                                                                           |
-| `options.gracePeriod`      | `number`                                                        | no                   | Seconds before SIGKILL after SIGTERM during cancellation -- see [Hooks](../hooks.md#hook-timeout).                                                                                                       |
-| `options.timeout`          | `number`                                                        | no                   | Total job wall-clock timeout in milliseconds (init + all steps + hooks). On breach the job is aborted and reported timed out. See [Timeouts](#timeouts).                                                 |
-| `options.resources`        | `ResourceRequest`                                               | no                   | Per-job CPU / memory request and limit. See [Per-job resources](#per-job-resources) below.                                                                                                               |
-| `options.init`             | `InitConfig`                                                    | no                   | Per-job initialization run after clone, before steps -- provisions a toolchain. A generic config, a typed preset (`'mise'` / `{ mise }`), `'auto'`, or `false`. See [Per-job init](#per-job-init) below. |
+| `options.gracePeriod`      | `number`                                                        | no                   | Seconds before SIGKILL after SIGTERM during cancellation -- see [Hooks](https://docs.kici.dev/user/hooks/#hook-timeout).                                                                                                       |
+| `options.timeout`          | `number`                                                        | no                   | Total job wall-clock timeout in milliseconds (init + all steps + hooks). On breach the job is aborted and reported timed out. See [Timeouts](https://docs.kici.dev/user/sdk/core/#timeouts).                                                 |
+| `options.resources`        | `ResourceRequest`                                               | no                   | Per-job CPU / memory request and limit. See [Per-job resources](https://docs.kici.dev/user/sdk/core/#per-job-resources) below.                                                                                                               |
+| `options.init`             | `InitConfig`                                                    | no                   | Per-job initialization run after clone, before steps -- provisions a toolchain. A generic config, a typed preset (`'mise'` / `{ mise }`), `'auto'`, or `false`. See [Per-job init](https://docs.kici.dev/user/sdk/core/#per-job-init) below. |
 
 **Returns:** `Job` -- an immutable job definition.
 
@@ -1982,7 +2092,7 @@ const build = job({
 
 #### runsOn forms
 
-A job's `runsOn` selects which agents may run it. Every label listed must be present on the agent (a subset match). It accepts three forms, and each label can be an exact string, a glob, or a regular expression (see [Targeting by pattern](#targeting-by-pattern) below):
+A job's `runsOn` selects which agents may run it. Every label listed must be present on the agent (a subset match). It accepts three forms, and each label can be an exact string, a glob, or a regular expression (see [Targeting by pattern](https://docs.kici.dev/user/sdk/core/#targeting-by-pattern) below):
 
 ```typescript
 // 1. Simple string -- agent must have this label
@@ -2008,7 +2118,7 @@ runsOn: { labels: ['kici:os:linux'], exclude: ['kici:host:box-01'] }
 - **Required labels:** The agent must have every label in the `labels` array (or the string/array form).
 - **Excluded labels:** The agent must NOT have any label in the `exclude` array. This includes auto-derived labels like `kici:arch:arm64`, `kici:os:linux`, etc.
 - **Compile-time validation:** The compiler will error if any label appears in both `labels` and `exclude` (overlap detection).
-- **Operator-declared mandatory labels:** Operators may mark a scaler with `mandatoryLabels` (Kubernetes-taint-style opt-in). When a scaler declares a mandatory label, a job is only allowed to land on it if `runsOn.labels` includes that label. A workflow targeting such a scaler must explicitly list the mandatory label in `runsOn`. See the [auto-scaler mandatory labels](../../operator/orchestrator/auto-scaler/common-config.md#mandatory--exclude-labels) for details.
+- **Operator-declared mandatory labels:** Operators may mark a scaler with `mandatoryLabels` (Kubernetes-taint-style opt-in). When a scaler declares a mandatory label, a job is only allowed to land on it if `runsOn.labels` includes that label. A workflow targeting such a scaler must explicitly list the mandatory label in `runsOn`. See the [auto-scaler mandatory labels](https://docs.kici.dev/operator/orchestrator/auto-scaler/common-config/#mandatory--exclude-labels) for details.
 
 ```typescript
 // Route to any Linux agent that does NOT have the 'gpu' label
@@ -2024,6 +2134,33 @@ const deploy = job('deploy', {
 });
 ```
 
+#### Single-host selection: `pick`
+
+When more than one agent matches a `runsOn` selector, the object form's `pick`
+field controls **which** one runs the job:
+
+```typescript
+// Always the same host across re-runs (default — can be omitted)
+runsOn: { labels: ['role:db'], pick: 'deterministic' }
+
+// Any available host (load spread)
+runsOn: { labels: ['role:db'], pick: 'any' }
+```
+
+- **`'deterministic'` (the default)** — the orchestrator sorts the matching
+  agents by their agent id and picks the lowest. A job that must run exactly
+  once on one stable host — a database migration, a backup dump — lands on the
+  **same** host every run. The string and array shorthand forms
+  (`runsOn: 'role:db'`, `runsOn: ['role:db', 'linux']`) inherit this default.
+- **`'any'`** — pick any available matching agent. Use this for jobs that don't
+  need a stable host and benefit from spreading load across an equivalent pool.
+
+**Trade-off:** `'deterministic'` can hot-spot — if many jobs target the same
+label set, they all pin to the same lowest-id agent. Use `'any'` to spread those
+across the pool; keep `'deterministic'` when reproducibility matters more than
+balance. (`pick` selects among **single-agent** candidates; to fan a job out to
+**every** matching host, use [`runsOnAll`](https://docs.kici.dev/user/sdk/runs-on-all/) instead.)
+
 #### Targeting by pattern
 
 Every selector element — in `runsOn`, in `runsOnAll`, on both the include and the exclude side — can be a plain string, a glob pattern, or a regular expression. KiCI picks the matching mode from the value itself:
@@ -2128,7 +2265,7 @@ const configureNginx = step('configure-nginx', {
 ```
 
 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).
+drift, change nothing). See [Idempotent steps and check mode](https://docs.kici.dev/user/idempotent-steps/).
 
 ### Per-job resources
 
@@ -2211,7 +2348,7 @@ export const build = workflow('build', {
 | --------- | ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
 | `run`     | `string`                | yes      | Command run after clone, before steps. Runs in the job's sandbox at the clone root. Must be a non-empty command.                               |
 | `shell`   | `string`                | no       | Shell used to run `run`. Defaults to `bash`.                                                                                                   |
-| `cache`   | `CacheSpec`             | no       | Cache spec for binaries the command installs -- restored before the command, saved after on a key miss. See [Caching](./caching.md).           |
+| `cache`   | `CacheSpec`             | no       | Cache spec for binaries the command installs -- restored before the command, saved after on a key miss. See [Caching](https://docs.kici.dev/user/sdk/caching/).           |
 | `timeout` | `number`                | no       | Max wall-clock for this init command in milliseconds. Defaults to 10 minutes. On breach the init is aborted and the job is reported timed out. |
 | `env`     | `Record<string,string>` | no       | Static environment variables available to the command.                                                                                         |
 
@@ -2394,6 +2531,43 @@ export default workflow('ci', {
 
 Workflow and job timeouts surface with a distinct "timed out" reason so the dashboard labels the run or job as timed out rather than a generic failure or cancel.
 
+### Retries
+
+A step can declare a `retry` policy so a thrown attempt is re-run automatically instead of failing the job on the first error. Use it for genuinely transient failures — a flaky network call, an occasional 503, a dependency that is briefly not ready.
+
+```typescript
+step('publish', {
+  retry: 3, // shorthand for { maxAttempts: 3 } with the defaults below
+  run: async (ctx) => {
+    await ctx.$`pnpm publish`;
+  },
+});
+
+step('fetch-token', {
+  retry: {
+    maxAttempts: 5, // total attempts including the first; must be >= 1
+    delayMs: 500, // base delay between attempts (default 1000)
+    backoff: 'exponential', // 'exponential' (default) or 'fixed'
+    maxDelayMs: 30_000, // cap for exponential growth (default 30000)
+    retryIf: (err) => err instanceof TransientError, // default: retry on any throw
+  },
+  run: async (ctx) => {
+    await fetchToken();
+  },
+});
+```
+
+- **`retry: N`** is shorthand for `{ maxAttempts: N }` with all defaults applied.
+- **Defaults:** `delayMs: 1000`, `backoff: 'exponential'`, `maxDelayMs: 30000`, and "retry on any throw" when no `retryIf` is given.
+- **Backoff.** With `'exponential'`, the wait after the `n`-th attempt (1-based) is `min(delayMs * 2 ** (n - 1), maxDelayMs)` — 1s, 2s, 4s, … capped at `maxDelayMs`. With `'fixed'`, the wait is always `delayMs`.
+- **`retryIf(err)`** runs against the thrown error before each retry; return `false` to stop retrying immediately and let the failure stand.
+- **Timeout is per-attempt.** Each attempt gets the step's full `timeout` budget — a timed-out attempt counts as one failed attempt and is retried while attempts remain. The total wall-clock can therefore approach `maxAttempts * (timeout + delay)`, so keep `maxAttempts` and `maxDelayMs` sane (the job-level `timeout` still bounds the whole job).
+- **Retries exhaust before `continueOnError`.** A step with both retries first; only the _final_ failure is then softened to a warning by `continueOnError`.
+
+`retry` works identically under `kici run local` and on a remote agent, and applies to dynamically-generated job steps too. The `retryIf` predicate is an in-memory function: it is honored at execution time but never serialized into the lock file.
+
+> **Retry vs. wait-until-condition.** `retry` re-runs a step that _throws_. To poll until a condition becomes true (a port listening, a `/health` endpoint returning 200, a unit becoming active), use [`waitForStep`](https://docs.kici.dev/user/sdk/wait-for/) instead — it is purpose-built for declarative wait-for-condition with intervals, a timeout, and on-timeout handling.
+
 ### Output chaining
 
 Steps and jobs can access outputs from preceding steps/jobs using two patterns.
@@ -2476,7 +2650,7 @@ const deploy = job('deploy', {
 
 **Important:** `needs` must be declared explicitly. Output chaining does not auto-infer dependencies -- you must list job dependencies in `needs` even if you access their outputs via `.result`.
 
-Cross-job output chaining works in both local test mode (`kici test`) and remote pipeline execution. The orchestrator's needs-aware dispatch scheduler guarantees upstream jobs reach a terminal state before downstream jobs dispatch, and upstream outputs are transported to the downstream agent sandbox via the `upstreamJobOutputs` field on `job.dispatch`. See [needs-scheduler](../../architecture/execution/needs-scheduler.md) for the full dispatch semantics.
+Cross-job output chaining works in both local test mode (`kici test`) and remote pipeline execution. The orchestrator's needs-aware dispatch scheduler guarantees upstream jobs reach a terminal state before downstream jobs dispatch, and upstream outputs are transported to the downstream agent sandbox via the `upstreamJobOutputs` field on `job.dispatch`. See [needs-scheduler](https://docs.kici.dev/architecture/execution/needs-scheduler/) for the full dispatch semantics.
 
 ### Job dependencies (`needs`)
 
@@ -2489,9 +2663,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' }],
   ...
 });
 
@@ -2502,16 +2676,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.
 
-| 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. |
+| 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 |
 
-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).
+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`.
 
-**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.
+String and `Job`-reference entries default to `when: 'on-success'`. To override, use the object form (`{ name, when }` for static upstreams, `{ group, when }` for dynamic groups -- `dynamicGroup(name, { when: 'always' })` produces the latter).
+
+When an upstream's terminal status is **not** in the edge's set, the downstream transitions directly to `skipped`. Because a skipped job is itself terminal, this propagates transitively: each downstream's `when` set governs whether the skip cascades further.
+
+**Dispatch gate:** `needs` is a hard dispatch gate. A job dispatches only after every upstream in its `needs` array reaches a terminal status that satisfies that edge's `when` set. Root jobs (empty `needs`, no dynamic group refs) dispatch immediately. The scheduler is DB-backed and fully recovers across orchestrator restarts.
+
+**Reading an upstream's status in a step:** inside a running job, `ctx.needs.<job>.status` exposes each upstream's terminal status (`success`, `failed`, `skipped`, …) and `ctx.needs.<job>.result` its outputs. A group / matrix / `runsOnAll` fan-out upstream is an ordered array of `{ name, result, status }`, one per child. Use this to branch in TypeScript:
+
+```typescript
+job('report', {
+  needs: [{ name: 'probe', when: 'always' }],
+  run: async (ctx) => {
+    if (ctx.needs.probe.status === 'failed') await fileIncident(ctx.needs.probe.result);
+    else await publish(ctx.needs.probe.result);
+  },
+});
+```
+
+For an arbitrary outcome-based gate that prevents a job from dispatching at all, use a result-aware `dynamicJob` that returns `[]` or `[job]` based on `ctx.needs.<job>.status` — see [Dynamic jobs](https://docs.kici.dev/architecture/execution/dynamic-jobs/).
 
 **DAG validation:** three-layer cycle detection.
 
@@ -2524,7 +2718,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).
@@ -2553,7 +2750,7 @@ Tag a dynamic job generator function with a group name so other jobs can referen
 function dynamicJob(groupName: string, fn: DynamicJobFn): DynamicJobFn;
 ```
 
-The generator runs twice: once in the init phase (to register expected job names) and once inside the executing agent (to produce the actual jobs). Mismatches between the two evaluations are detected as determinism drift -- see [dynamic-jobs](../../architecture/execution/dynamic-jobs.md).
+The generator runs twice: once in the init phase (to register expected job names) and once inside the executing agent (to produce the actual jobs). Mismatches between the two evaluations are detected as determinism drift -- see [dynamic-jobs](https://docs.kici.dev/architecture/execution/dynamic-jobs/).
 
 ### Auto-generated IDs
 
@@ -2918,13 +3115,13 @@ The typed `payload` shapes above reference these partial GitHub object types. Ea
 
 Source: https://docs.kici.dev/user/sdk/idempotent/
 
-The SDK exposes two idempotency helpers — a generic function `idempotent()` and a step factory `idempotentStep()` — for the common case where a workflow step should:
+The SDK exposes three idempotency helpers — a generic function `idempotent()`, the step factory `idempotentStep()`, and its check-mode-aware sibling `checkStep()` — for the common case where a workflow step should:
 
 1. **Check** whether the desired state is already in place.
 2. **Apply** the change only when drift is detected.
 3. **Surface** the resource (or its identifier) on both branches, so downstream steps don't need to know whether work happened or was skipped.
 
-Both helpers wrap the same underlying runner, so they share semantics and return shape. Pick `idempotentStep()` when the operation is the whole job of a step; use `idempotent()` from anywhere — inside a multi-action step, a hook, or a bare async function.
+`idempotent()` and `idempotentStep()` wrap the same underlying runner and always apply on drift. Pick `idempotentStep()` when the operation is the whole job of a step; use `idempotent()` from anywhere — inside a multi-action step, a hook, or a bare async function. Pick `checkStep()` when the step should respect the run-level check mode — `kici run --check` previews the drift without applying it.
 
 ## `idempotent(options)`
 
@@ -3017,6 +3214,61 @@ 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`):
+
+| Factory          | Behavior under `kici run --check`         |
+| ---------------- | ----------------------------------------- |
+| `idempotentStep` | always applies on drift                   |
+| `checkStep`      | reports drift, applies only in apply mode |
+
+Use `checkStep()` for deploy-style steps where you want a dry-run preview of pending changes before committing them, and `idempotentStep()` for steps that must always converge (for example inside a hook). A `checkStep()` desugars to the first-class step check facet (`check` / `summarize` / `run(ctx, drift)` / `whenInSync`), so it participates in run-level check mode automatically: `kici run --check` reports the drift and skips `apply`, `kici run --check --fail-on-drift` exits non-zero when drift is detected, and apply mode applies the change.
+
+### Parameters
+
+| Name              | Type                                        | Required | Description                                                                                         |
+| ----------------- | ------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------- |
+| `name`            | `string`                                    | Yes      | Step name. Appears in the run timeline and in log lines.                                            |
+| `check`           | `(ctx) => Promise<TDrift \| null>`          | Yes      | Read-only inspection. Return `null` when the system is already in the desired state.                |
+| `apply`           | `(ctx, drift: TDrift) => Promise<TApplied>` | Yes      | Brings the system to the desired state. Runs only in apply mode (skipped under `kici run --check`). |
+| `summarize`       | `(drift: TDrift) => string`                 | Yes      | Human-readable summary of what `apply()` would do; shown in check-mode drift output.                |
+| `whenInSync`      | `(ctx) => Promise<TInSync>`                 | No       | Runs when `check()` returned `null` (already in sync).                                              |
+| `continueOnError` | `boolean`                                   | No       | When true, the job proceeds even if this step fails.                                                |
+| `timeout`         | `number`                                    | No       | Step-level timeout in milliseconds.                                                                 |
+
+The one signature difference from `idempotentStep`: `apply` and `whenInSync` receive `ctx` as their first argument, so the apply logic has access to `ctx.$`, `ctx.log`, and `ctx.secrets`.
+
+### Result
+
+`checkStep(...)` returns `Step<TApplied | TInSync>` — the output is whichever of `apply` / `whenInSync` ran.
+
+### Example
+
+```typescript
+import { checkStep, job } from '@kici-dev/sdk';
+
+const ensureDnsRecord = checkStep('ensure-dns-record', {
+  check: async (ctx) => {
+    const existing = await ctx.$`dig +short api.example.com`;
+    return existing.stdout.trim() ? null : { fqdn: 'api.example.com', target: '203.0.113.10' };
+  },
+  summarize: (drift) => `Create A record ${drift.fqdn} → ${drift.target}`,
+  apply: async (ctx, drift) => {
+    await ctx.$`dns-cli create ${drift.fqdn} ${drift.target}`;
+    return { created: true };
+  },
+  whenInSync: async () => ({ created: false }),
+});
+
+export const deploy = job('deploy', {
+  runsOn: 'linux',
+  steps: [ensureDnsRecord],
+});
+```
+
+Run `kici run --check` against this workflow to see the drift summary without touching DNS; run it without `--check` to apply.
+
 ## Worked example: create-if-missing returning a resource id
 
 The typical use case is **resource provisioning that should be safe to re-run**. The helper guarantees the same downstream typed shape whether the resource already existed or was just created:
@@ -3059,8 +3311,8 @@ The caller never has to branch on outcome — `result.result` is always a `Bucke
 
 ## See also
 
-- [Core SDK reference](./core.md) — the `step()`, `job()`, and `workflow()` factories that `idempotentStep()` builds on.
-- [Runtime types](./runtime.md) — `StepContext`, `Logger`, and other surface used inside the helpers.
+- [Core SDK reference](https://docs.kici.dev/user/sdk/core/) — the `step()`, `job()`, and `workflow()` factories that `idempotentStep()` builds on.
+- [Runtime types](https://docs.kici.dev/user/sdk/runtime/) — `StepContext`, `Logger`, and other surface used inside the helpers.
 
 ---
 
@@ -3187,7 +3439,7 @@ You can also narrow directly with `if (ctx.event.type === 'pull_request')` — T
 
 `EventPayload` is a discriminated union over the `type` field. Each variant provides typed access to the normalized event fields and the raw webhook payload.
 
-Every variant carries the shared `EventBase` fields — `type`, `action`, `targetBranch`, `sourceBranch`, `provider`, `isForkPR`, `baseBranch`, `senderUsername`, `sourceRepo`, `changedFiles`, and the raw `payload` — plus a per-type `payload` shape for the typed variants. The complete field-by-field schema, including every typed `payload` shape and the shared GitHub object types, is in the [event payload reference](./event-payloads.md).
+Every variant carries the shared `EventBase` fields — `type`, `action`, `targetBranch`, `sourceBranch`, `provider`, `isForkPR`, `baseBranch`, `senderUsername`, `sourceRepo`, `changedFiles`, and the raw `payload` — plus a per-type `payload` shape for the typed variants. The complete field-by-field schema, including every typed `payload` shape and the shared GitHub object types, is in the [event payload reference](https://docs.kici.dev/user/sdk/event-payloads/).
 
 **Typed variants** (with GitHub-specific payload fields): `pull_request`, `push`, `tag`, `comment`, `review`, `review_comment`, `release`, `dispatch`, `create`, `delete`, `status`, `workflow_run`, `fork`, `star`, `watch`.
 
@@ -3297,7 +3549,7 @@ interface MatrixValues {
 
 A matrix fan-out runs every combination at once by default. The fan-out-generic
 `maxParallel` and `failFast` job options bound it the same way they bound a
-[`runsOnAll`](./runs-on-all.md#rolling-rollout-maxparallel--failfast) host fan-out:
+[`runsOnAll`](https://docs.kici.dev/user/sdk/runs-on-all/#rolling-rollout-maxparallel--failfast) host fan-out:
 
 ```typescript
 const test = job('test', {
@@ -3445,12 +3697,12 @@ 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).
+`ctx.needs` is deterministic — a snapshot of upstream outputs frozen at first eval and replayed unchanged on re-eval, like `ctx.event`. Use result-aware generation for same-run fan-out from a prior job's result; use [`jobComplete()`](https://docs.kici.dev/user/sdk/triggers/) for cross-workflow reactions to a job finishing. See the architecture deep-dive in [dynamic jobs](https://docs.kici.dev/architecture/execution/dynamic-jobs/#result-aware-generation).
 
 ### JobOrFactory
 
@@ -3491,7 +3743,7 @@ roster that matches a label predicate — one pinned execution per host. Use it
 fleet-wide operations: patch every web tier, smoke-test every node, collect uptime
 from the fleet.
 
-`runsOnAll` is mutually exclusive with [`runsOn`](/user/sdk/core/): a job declares one
+`runsOnAll` is mutually exclusive with [`runsOn`](https://docs.kici.dev/user/sdk/core/): a job declares one
 or the other. Where `runsOn` picks a **single** agent that satisfies the labels,
 `runsOnAll` targets **all** matching hosts and runs the job once on each, pinned to
 that specific host.
@@ -3540,7 +3792,7 @@ const patch = job('patch', {
 #### Targeting by pattern
 
 Every entry in any of these forms — include or exclude — can be an exact string, a
-glob, or a regular expression, exactly like [`runsOn`](./core.md#targeting-by-pattern):
+glob, or a regular expression, exactly like [`runsOn`](https://docs.kici.dev/user/sdk/core/#targeting-by-pattern):
 
 - **Plain string → exact match** (`'role:web'`).
 - **String with glob metacharacters (`*`, `?`, `[]`, `{}`) → glob** (`'kici:host:web-*'`).
@@ -3592,6 +3844,66 @@ run: async (ctx) => {
 
 Both are `undefined` for jobs that do not use `runsOnAll`.
 
+### ctx.fanout — fan-out position
+
+Every fan-out child — a `runsOnAll` host **or** a matrix combination — also
+carries its **position** within the fan-out:
+
+```typescript
+ctx.fanout?: {
+  index: number;   // 0-based position in the deterministically-ordered fan-out
+  total: number;   // number of children in this fan-out
+  first: boolean;  // index === 0
+  last: boolean;   // index === total - 1
+};
+```
+
+The order is a **documented guarantee**: host fan-out is ordered by agent id,
+matrix fan-out by its combination label. So `ctx.fanout.first` is always the
+same (lowest-agent-id) host across re-runs, and `ctx.fanout.last` the same final
+one. `ctx.fanout` is `undefined` on a job that is not fanned out.
+
+### Run-once steps: onlyOnFirstHost / onlyOnLastHost / onlyOnFanoutIndex
+
+For ordered, stateful rollouts you often need a step that runs on exactly **one**
+host — enable a leader before the rest join, run a one-time migration, take a
+single dump. Three rule helpers express this by reading `ctx.fanout`:
+
+```typescript
+import { job, step, onlyOnFirstHost, onlyOnLastHost, onlyOnFanoutIndex } from '@kici-dev/sdk';
+
+const rollout = job('rollout', {
+  runsOnAll: 'role:db',
+  maxParallel: 1, // serial, so "first" runs before the rest
+  steps: [
+    // Runs only on the first (lowest-agent-id) host — KiCI's run-once primitive.
+    step('enable-sync-mode', { rules: [onlyOnFirstHost()] }, async (ctx) => {
+      /* configure the leader before standbys join */
+    }),
+    // Runs on every host.
+    step('apply', async (ctx) => {
+      /* ... */
+    }),
+    // Runs only on the last host.
+    step('finalize', { rules: [onlyOnLastHost()] }, async (ctx) => {
+      /* ... */
+    }),
+  ],
+});
+```
+
+- A step gated this way is **skipped** (not failed) on non-matching hosts — its
+  outputs exist only on the host where it ran.
+- `onlyOnFanoutIndex(n)` targets the host at a specific position.
+- **Non-fan-out safety:** on a job that is not fanned out, `ctx.fanout` is
+  `undefined` and these helpers treat the job as a single implicit child at
+  index 0 — so `onlyOnFirstHost()` runs normally there (there is one host, which
+  is the first). This means you can author a step with `onlyOnFirstHost()` and it
+  behaves correctly whether or not the job ends up fanning out.
+- The helpers are host-flavored by name (the dominant use case) but read
+  `ctx.fanout`, so they work for matrix fan-out too — `onlyOnFirstHost()` runs on
+  the first combination.
+
 ### byHost outputs
 
 A downstream that `needs:` a `runsOnAll` job receives a **byHost** envelope instead
@@ -3624,7 +3936,7 @@ to a single scalar: `summary.outputs[key]` is an array of every host's value, an
 ### onUnreachable: skip | fail | hold
 
 Resolution is backed by the **declared host roster** (see the operator
-[host roster](/operator/orchestrator/host-roster/) doc), not just the live registry.
+[host roster](https://docs.kici.dev/operator/orchestrator/host-roster/) doc), not just the live registry.
 This lets KiCI surface an expected-but-absent host instead of silently fanning out to a
 partial fleet. The `onUnreachable` policy controls what happens when a **durable**
 (static) host in the roster is matched but not currently connected:
@@ -3650,6 +3962,37 @@ independent of `onUnreachable` — a scaled-down node may never return. A `runsO
 that matches zero usable hosts fails the run rather than reporting a silent zero-child
 success.
 
+### includeUninitialized: converge a fresh fleet
+
+`onUnreachable` governs declared hosts that _had_ an agent and are momentarily absent.
+A **never-initialized** host — a freshly-provisioned box reachable over SSH but with no
+agent yet — is a different case: there is nothing to run on. Set
+`includeUninitialized: true` to widen the fan-out to those hosts and bring them up:
+
+```typescript
+const converge = job('converge', {
+  runsOnAll: 'kici:group:prod',
+  includeUninitialized: true,
+  steps: [partitionDisk, formatLuks, debootstrap, installAgent],
+});
+```
+
+For each un-agented declared host (one carrying SSH reach metadata), KiCI brings up a
+temporary init-runner over SSH and runs the **same steps** on it; hosts that already
+have a live agent run the steps on their own agent. One workflow converges the whole
+fleet — fresh boxes get built, live boxes run the same phases.
+
+Because the steps run on already-initialized hosts too, the bootstrap phases **must be
+idempotent [check-steps](https://docs.kici.dev/user/sdk/core/)**: each step's `check()` reports in-sync on a
+live box so the partition / format / install steps **skip** there and run only on fresh
+boxes. This is the safety guard — an OS or disk-format step must never re-run on a host
+that is already built. Re-running the workflow is a no-op everywhere. See the operator
+[fresh-box bootstrap](https://docs.kici.dev/operator/orchestrator/host-roster/) doc for the bring-up,
+capability gating, and lifecycle details.
+
+`includeUninitialized` is only meaningful alongside `runsOnAll`; it is ignored on a
+single-agent `runsOn` job.
+
 ### Rolling rollout: maxParallel + failFast
 
 By default a `runsOnAll` fan-out dispatches to every matched host at once — fine for
@@ -3685,6 +4028,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](https://docs.kici.dev/user/cli-reference/#host-narrowing-with---target)
+for the full flag behavior and the [`needs` gating model](https://docs.kici.dev/user/sdk/core/#job-dependencies-needs)
+for how a skipped upstream propagates.
+
 ### Limits (v0)
 
 - Per-host secret scoping is not yet available — all hosts receive the job's resolved
@@ -3716,9 +4085,9 @@ All types are exported from `@kici-dev/sdk` as type-only imports.
 | `OutputSchema`    | Record of Zod types for step outputs                                                                                                                                                                                                                                               |
 | `InferOutputs<T>` | Infer output type from output schema                                                                                                                                                                                                                                               |
 | `ContainerConfig` | Container config for job execution (`image`, `env?`)                                                                                                                                                                                                                               |
-| `RunsOn`          | Union of `runsOn` forms: `string \| RegExp \| (string \| RegExp)[] \| RunsOnSelector`. A plain string matches exactly, a string with glob metacharacters (`*?[]{}`) is a glob, and a `RegExp` is a regular expression. See [Targeting by pattern](./core.md#targeting-by-pattern). |
+| `RunsOn`          | Union of `runsOn` forms: `string \| RegExp \| (string \| RegExp)[] \| RunsOnSelector`. A plain string matches exactly, a string with glob metacharacters (`*?[]{}`) is a glob, and a `RegExp` is a regular expression. See [Targeting by pattern](https://docs.kici.dev/user/sdk/core/#targeting-by-pattern). |
 | `RunsOnSelector`  | Object form for `runsOn` with `labels` (required) and `exclude` (optional) properties. Each element accepts the exact / glob / regex forms on both sides.                                                                                                                          |
-| `RunsOnAllInput`  | Union of `runsOnAll` host fan-out forms: `string \| RegExp \| (string \| RegExp)[] \| { include: { all: (string \| RegExp)[] }[]; exclude?: (string \| RegExp)[] }`. Same exact / glob / regex semantics per element. See [runsOnAll](./runs-on-all.md#targeting-by-pattern).      |
+| `RunsOnAllInput`  | Union of `runsOnAll` host fan-out forms: `string \| RegExp \| (string \| RegExp)[] \| { include: { all: (string \| RegExp)[] }[]; exclude?: (string \| RegExp)[] }`. Same exact / glob / regex semantics per element. See [runsOnAll](https://docs.kici.dev/user/sdk/runs-on-all/#targeting-by-pattern).      |
 | `Fixture`         | Test fixture definition returned by `fixture()`                                                                                                                                                                                                                                    |
 | `FixtureOptions`  | Options for `fixture()` factory                                                                                                                                                                                                                                                    |
 | `Registry`        | Private npm registry declaration used in `WorkflowOptions.registries`                                                                                                                                                                                                              |
@@ -3905,7 +4274,7 @@ step('example', async ({ $, log, env, matrix, workflow, job }) => {
 - **Inside a dynamic `environment` / `env` / `concurrencyGroup` function** on a static job — captured to the `__init__` job's synthetic step-0 log, which appears in the timeline as "Init: _jobname_".
 - **Inside a `DynamicJobFn` body and the per-generated-job `environment` / `env` / `concurrencyGroup` / `matrix` functions** — captured to the `__dynamic__` job's synthetic step-0 log ("Evaluate: _jobname_" in the timeline). The `$` parameter in that context is a scoped zx shell, so `await $\`...\`` subprocess output is captured too.
 
-Use whichever style is convenient — you don't have to wrap `console.log` in the provided `log` parameter to make it visible. One limitation applies to in-process contexts only (init, build, dynamic-eval): direct `process.stdout.write` / `printf` is not captured there, because the agent's own logger uses that path and we don't want agent-internal output leaking into your step logs. Use `console.*` or the `log` parameter instead. See [Log streaming](../../architecture/execution/job-execution.md#log-streaming) for the full capture surface and limits (default 10 MB per step, backpressure behavior).
+Use whichever style is convenient — you don't have to wrap `console.log` in the provided `log` parameter to make it visible. One limitation applies to in-process contexts only (init, build, dynamic-eval): direct `process.stdout.write` / `printf` is not captured there, because the agent's own logger uses that path and we don't want agent-internal output leaking into your step logs. Use `console.*` or the `log` parameter instead. See [Log streaming](https://docs.kici.dev/architecture/execution/job-execution/#log-streaming) for the full capture surface and limits (default 10 MB per step, backpressure behavior).
 
 ### setEnv(key, value)
 
@@ -3930,7 +4299,7 @@ step('use', async (ctx) => {
 - Last-write-wins -- if multiple steps set the same key, the last value is used
 - Cannot override operator-injected secrets (the operator value takes precedence)
 - Changes take effect immediately in the current step and persist for all subsequent steps
-- Shell commands export the same way by appending to `$KICI_ENV` (see [Exporting env from shell commands](#exporting-env-from-shell-commands-kici_env--kici_path) below)
+- Shell commands export the same way by appending to `$KICI_ENV` (see [Exporting env from shell commands](https://docs.kici.dev/user/sdk/runtime/#exporting-env-from-shell-commands-kici_env--kici_path) below)
 
 ### addPath(dir)
 
@@ -4143,7 +4512,7 @@ const publish = job('publish', {
 - The returned `{ storageKey, subjectDigest, bundleMediaType }` identifies the stored bundle.
 - Only available inside a running job step; calling it outside one (for example, during local execution) rejects with a clear error.
 
-See the [build provenance guide](../provenance.md) for the end-to-end attest →
+See the [build provenance guide](https://docs.kici.dev/user/provenance/) for the end-to-end attest →
 verify → view journey, including how to verify a bundle with `kici verify-attestation`.
 
 ## Secrets
@@ -4238,7 +4607,7 @@ step('discover', async (ctx) => {
 
 ### File-mounted secrets (ctx.secrets.mountFile / exposeFile)
 
-Tools that require a file path on disk (sops `SOPS_AGE_KEY_FILE`, kubectl `KUBECONFIG`, gcloud `GOOGLE_APPLICATION_CREDENTIALS`) get a typed step-side API: `ctx.secrets.mountFile(opts)` writes the concatenation of one or more existing secrets to a per-step tmpfile and returns the path; `ctx.secrets.exposeFile(envVar, opts)` additionally sets `process.env[envVar] = path`. Files are removed and env vars are unset automatically when the step completes (success, failure, or timeout) — no manual cleanup. See [Mounting secrets as files](../secrets.md#mounting-secrets-as-files) for the full options table, lifecycle details, and the canonical sops example.
+Tools that require a file path on disk (sops `SOPS_AGE_KEY_FILE`, kubectl `KUBECONFIG`, gcloud `GOOGLE_APPLICATION_CREDENTIALS`) get a typed step-side API: `ctx.secrets.mountFile(opts)` writes the concatenation of one or more existing secrets to a per-step tmpfile and returns the path; `ctx.secrets.exposeFile(envVar, opts)` additionally sets `process.env[envVar] = path`. Files are removed and env vars are unset automatically when the step completes (success, failure, or timeout) — no manual cleanup. See [Mounting secrets as files](https://docs.kici.dev/user/secrets/#mounting-secrets-as-files) for the full options table, lifecycle details, and the canonical sops example.
 
 ### Local test mode secrets
 
@@ -4491,13 +4860,73 @@ Create a repository_dispatch trigger. Returns a frozen `DispatchTriggerConfig`.
 function dispatch(config?: DispatchConfigInput): DispatchTriggerConfig;
 ```
 
-**Config options:** `types` (string[]), `description`
+**Config options:** `types` (string[]), `description`, `inputs` (typed dispatch inputs map)
 
 ```typescript
 dispatch(); // Any dispatch
 dispatch({ types: ['deploy', 'rollback'] }); // Specific event types
 ```
 
+#### Typed dispatch inputs
+
+A `dispatch()` trigger can declare a typed `inputs` schema. Operators supply
+values with `kici run --input key=value`; KiCI validates, coerces, defaults, and
+exposes them to steps and rules as `ctx.dispatchInputs`. The values are validated
+on the orchestrator from the compiled lock file — a missing required input or a
+bad value is rejected before any agent runs, without cloning the repository.
+
+```typescript
+import { workflow, job, step, dispatch, defineDispatchInputs, z } from '@kici-dev/sdk';
+
+const inputs = defineDispatchInputs({
+  target: z.string().optional(),
+  skipCveScan: z.boolean().default(false),
+  skipCveScanReason: z.string().min(1).optional(),
+  mode: z.enum(['full', 'edge-only']).default('full'),
+  retries: z.number().int().min(0).max(10).default(3),
+});
+
+export default workflow('deploy-prod', {
+  on: dispatch({ types: ['deploy-prod'], inputs }),
+  jobs: [
+    job('gates', {
+      runsOn: 'kici:group:ops',
+      steps: [
+        step('cve-gate', async (ctx) => {
+          const i = inputs.from(ctx); // fully typed per declared key
+          if (i.skipCveScan) {
+            ctx.log.warn(`CVE gate skipped: ${i.skipCveScanReason ?? '(no reason)'}`);
+            return;
+          }
+          await ctx.$`pnpm scan:cve:gate`;
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+- **`defineDispatchInputs(map)`** is the single declaration site. It returns a
+  handle that `dispatch({ inputs })` accepts and exposes `inputs.from(ctx)` — a
+  typed reader over `ctx.dispatchInputs`, typed per declared key. `dispatch({ inputs })`
+  also accepts a bare `{ name: schema }` map directly when you don't need the reader.
+- **`ctx.dispatchInputs`** is always present (a validated map of
+  `string | number | boolean | null`), distinct from `ctx.inputs` (typed outputs
+  from `needs` dependencies). Rules see the same values via `ctx.dispatchInputs`,
+  so `skipUnless(ctx => !ctx.dispatchInputs.skipCveScan)` works.
+- **Defaults are applied once**, on the orchestrator (the authoritative side); the
+  CLI pre-validates `--input` for fast feedback and forwards the raw operator pairs.
+
+**Allowed input types (closed subset):** `z.string()`, `z.number()`,
+`z.boolean()`, `z.enum([...])`, `z.literal(v)`, with the modifiers `.optional()`,
+`.nullable()`, `.default(v)`, `.min(n)`, `.max(n)`, `.regex(re)`, `.int()`.
+Anything outside this set (`.refine()`, `.transform()`, `.pipe()`, `z.object()`,
+`z.array()`, `z.union()`, `z.record()`, `z.coerce.*`) is a **compile error** —
+the closed set is what guarantees the schema survives the trip to the
+orchestrator's lock file without silently dropping any validation. CLI strings
+are coerced for you (`--input retries=3` becomes the number `3`; booleans accept
+`true`/`false`/`1`/`0`/`yes`/`no`), so author your schema with clean types.
+
 ### create()
 
 Create a ref creation trigger (branches/tags). Returns a frozen `CreateTriggerConfig`.
@@ -4611,7 +5040,7 @@ Create a catch-all webhook trigger for any GitHub event. Returns a frozen `Webho
 function webhook(config: WebhookConfigInput): WebhookTriggerConfig;
 ```
 
-**Config options:** `events` (required string[]), `actions` (optional string[]), `repos` (optional cross-repo source patterns -- see [global workflows](../global-workflows.md)), `description`
+**Config options:** `events` (required string[]), `actions` (optional string[]), `repos` (optional cross-repo source patterns -- see [global workflows](https://docs.kici.dev/user/global-workflows/)), `description`
 
 ```typescript
 webhook({ events: ['deployment'] }); // Deployment events
@@ -4716,7 +5145,7 @@ jobComplete({ workflow: 'CI', job: 'build', status: ['success'] }); // Success o
 jobComplete({ workflow: 'CI', job: 'build', source: 'org/repo' }); // Cross-repo
 ```
 
-`jobComplete()` starts a **new** workflow run that reacts to another job finishing (gated on the prior job's status). For same-run fan-out — generating follow-up jobs from a prior job's _outputs_ within the same run — use a result-aware [`dynamicJob(group, { needs, generate })`](./rules-matrix-dynamic.md#dynamicjob--result-aware-generation) instead.
+`jobComplete()` starts a **new** workflow run that reacts to another job finishing (gated on the prior job's status). For same-run fan-out — generating follow-up jobs from a prior job's _outputs_ within the same run — use a result-aware [`dynamicJob(group, { needs, generate })`](https://docs.kici.dev/user/sdk/rules-matrix-dynamic/#dynamicjob--result-aware-generation) instead.
 
 ### genericWebhook()
 
@@ -5096,9 +5525,9 @@ If `check()` throws while polling, the error is logged and polling continues —
 
 ## See also
 
-- [Core SDK reference](./core.md) — the `step()`, `job()`, and `workflow()` factories that `waitForStep()` builds on.
-- [Idempotent helpers](./idempotent.md) — `idempotent()` and `idempotentStep()` for check / apply patterns.
-- [Runtime types](./runtime.md) — `StepContext`, `Logger`, and other surface used inside the helpers.
+- [Core SDK reference](https://docs.kici.dev/user/sdk/core/) — the `step()`, `job()`, and `workflow()` factories that `waitForStep()` builds on.
+- [Idempotent helpers](https://docs.kici.dev/user/sdk/idempotent/) — `idempotent()` and `idempotentStep()` for check / apply patterns.
+- [Runtime types](https://docs.kici.dev/user/sdk/runtime/) — `StepContext`, `Logger`, and other surface used inside the helpers.
 
 ---
 
@@ -5110,14 +5539,14 @@ Reference documentation for `@kici-dev/sdk`. The reference is split across five
 
 | Page                                                         | Covers                                                                                                                                                                                                                      |
 | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [Core](./sdk/core.md)                                        | `workflow()`, `job()`, `step()` factory functions and step / job authoring patterns (bare functions, output chaining, `needs`, dynamic groups).                                                                             |
-| [Triggers](./sdk/triggers.md)                                | All 22 trigger factories -- GitHub events (`pr`, `push`, `tag`, `comment`, ...), event triggers (`kiciEvent`, `workflowComplete`, `jobComplete`), `genericWebhook`, `schedule`, `lifecycle`, plus branch-pattern semantics. |
-| [Rules, matrix, dynamic jobs](./sdk/rules-matrix-dynamic.md) | `rule()`, `skip()`, matrix builds (static + dynamic), and `dynamicJob()` / `dynamicGroup()`.                                                                                                                                |
-| [Caching](./sdk/caching.md)                                  | `CacheSpec`, declarative `cache` on jobs/steps, imperative `ctx.cache.restore()` / `ctx.cache.save()`, immutable keys, `restoreKeys` prefix fallback, per-org + per-ref isolation.                                          |
-| [Validation & events](./sdk/validation-events.md)            | `validateDag()`, `defineEvent()`, event emission patterns.                                                                                                                                                                  |
-| [Runtime](./sdk/runtime.md)                                  | Types index, `StepContext`, secrets, and fixtures.                                                                                                                                                                          |
-| [Idempotent helpers](./sdk/idempotent.md)                    | `idempotent()` and `idempotentStep()` — check / apply pattern with typed results on both the skipped and applied branches.                                                                                                  |
-| [Wait-for helpers](./sdk/wait-for.md)                        | `waitFor()` and `waitForStep()` — poll a condition on an interval, run an optional success action, recover gracefully on timeout.                                                                                           |
+| [Core](https://docs.kici.dev/user/sdk/core/)                                        | `workflow()`, `job()`, `step()` factory functions and step / job authoring patterns (bare functions, output chaining, `needs`, dynamic groups).                                                                             |
+| [Triggers](https://docs.kici.dev/user/sdk/triggers/)                                | All 22 trigger factories -- GitHub events (`pr`, `push`, `tag`, `comment`, ...), event triggers (`kiciEvent`, `workflowComplete`, `jobComplete`), `genericWebhook`, `schedule`, `lifecycle`, plus branch-pattern semantics. |
+| [Rules, matrix, dynamic jobs](https://docs.kici.dev/user/sdk/rules-matrix-dynamic/) | `rule()`, `skip()`, matrix builds (static + dynamic), and `dynamicJob()` / `dynamicGroup()`.                                                                                                                                |
+| [Caching](https://docs.kici.dev/user/sdk/caching/)                                  | `CacheSpec`, declarative `cache` on jobs/steps, imperative `ctx.cache.restore()` / `ctx.cache.save()`, immutable keys, `restoreKeys` prefix fallback, per-org + per-ref isolation.                                          |
+| [Validation & events](https://docs.kici.dev/user/sdk/validation-events/)            | `validateDag()`, `defineEvent()`, event emission patterns.                                                                                                                                                                  |
+| [Runtime](https://docs.kici.dev/user/sdk/runtime/)                                  | Types index, `StepContext`, secrets, and fixtures.                                                                                                                                                                          |
+| [Idempotent helpers](https://docs.kici.dev/user/sdk/idempotent/)                    | `idempotent()`, `idempotentStep()`, and the check-mode-aware `checkStep()` — check / apply pattern with typed results on both the skipped and applied branches.                                                             |
+| [Wait-for helpers](https://docs.kici.dev/user/sdk/wait-for/)                        | `waitFor()` and `waitForStep()` — poll a condition on an interval, run an optional success action, recover gracefully on timeout.                                                                                           |
 
 The `@kici-dev/sdk` package re-exports the entire surface from a single entry point. Pick what you need:
 
@@ -5129,12 +5558,12 @@ For the complete list of every named export (factory functions, triggers, rules,
 
 ## See also
 
-- [Getting started](getting-started.md) -- install the SDK, write your first workflow, test locally
-- [CLI reference](cli-reference.md) -- compile, test, and manage workflows from the command line
-- [Workflow patterns](workflow-patterns.md) -- common patterns using the SDK features documented above
-- [Secrets management (operator)](../operator/security/secrets.md) -- configure encrypted secret storage and admin API
-- [Secrets architecture](../architecture/security/secrets.md) -- encryption model, multi-backend, and data flow
-- [State machine](../architecture/execution/state-machine.md) -- how execution states map to the lifecycle of jobs and steps
+- [Getting started](https://docs.kici.dev/user/getting-started/) -- install the SDK, write your first workflow, test locally
+- [CLI reference](https://docs.kici.dev/user/cli-reference/) -- compile, test, and manage workflows from the command line
+- [Workflow patterns](https://docs.kici.dev/user/workflow-patterns/) -- common patterns using the SDK features documented above
+- [Secrets management (operator)](https://docs.kici.dev/operator/security/secrets/) -- configure encrypted secret storage and admin API
+- [Secrets architecture](https://docs.kici.dev/architecture/security/secrets/) -- encryption model, multi-backend, and data flow
+- [State machine](https://docs.kici.dev/architecture/execution/state-machine/) -- how execution states map to the lifecycle of jobs and steps
 
 ---
 
@@ -5299,13 +5728,13 @@ Every request to `/api/v1/*` carries an `Authorization: Bearer <token>` header.
 | `kici_sa_`  | Service account key           | Dashboard → Settings → Service accounts | Org              |
 | (other)     | OIDC JWT or opaque OIDC token | OIDC login (browser SPA)                | User (cross-org) |
 
-JWT and opaque OIDC tokens are validated against the configured OIDC issuer (JWKS for JWTs, the issuer's UserInfo endpoint for opaque ones). All `kici_*` tokens are validated by SHA-256 hash lookup against the Platform DB. See [RBAC: authentication methods](../architecture/security/rbac.md#authentication-methods) for the full model.
+JWT and opaque OIDC tokens are validated against the configured OIDC issuer (JWKS for JWTs, the issuer's UserInfo endpoint for opaque ones). All `kici_*` tokens are validated by SHA-256 hash lookup against the Platform DB. See [RBAC: authentication methods](https://docs.kici.dev/architecture/security/rbac/#authentication-methods) for the full model.
 
 > **Note:** `kici_ok_` keys are **not** for the HTTP API — they authenticate orchestrator-to-Platform WebSocket connections only. Use `kici_sk_` (or `kici_pat_`) for HTTP calls.
 
 ### Permissions
 
-Tokens authenticate; RBAC authorizes. Every org-scoped route runs `orgContextMiddleware` (verifies you are a member of the target org) followed by `requirePermission(resource, level)`. The 15 resources and 5 levels are documented in [RBAC](../architecture/security/rbac.md#permission-model). User API keys carry their own permission matrix bounded above by the creator's effective permissions; PATs inherit the user's role permissions (or are capped further by their `scopes` field).
+Tokens authenticate; RBAC authorizes. Every org-scoped route runs `orgContextMiddleware` (verifies you are a member of the target org) followed by `requirePermission(resource, level)`. The 17 resources and 5 levels are documented in [RBAC](https://docs.kici.dev/architecture/security/rbac/#permission-model). User API keys carry their own permission matrix bounded above by the creator's effective permissions; PATs inherit the user's role permissions (or are capped further by their `scopes` field).
 
 ### Configurable surfaces
 
@@ -5350,7 +5779,7 @@ There is currently no per-token rate limit on `/api/v1/*`. A single global body-
 
 ### Audit trail
 
-Every `/api/v1/*` mutation that touches tenant-plane data is recorded in the upstream tenant-plane audit log, stamped with the actor (user, API key, service account, or upstream operator on a break-glass support read). Reads on customer data go through the orchestrator over the WebSocket proxy and land in the orchestrator's `access_log` table. See [Audit log](../operator/security/audit-log.md) for the orchestrator schema and the dashboard's "Activity" page for the federated view.
+Every `/api/v1/*` mutation that touches tenant-plane data is recorded in the upstream tenant-plane audit log, stamped with the actor (user, API key, service account, or upstream operator on a break-glass support read). Reads on customer data go through the orchestrator over the WebSocket proxy and land in the orchestrator's `access_log` table. See [Audit log](https://docs.kici.dev/operator/security/audit-log/) for the orchestrator schema and the dashboard's "Activity" page for the federated view.
 
 ## Token storage
 
@@ -5496,26 +5925,27 @@ kici run local [event] [options]
 
 **Options:**
 
-| Option              | Default   | Description                                                                                                                                                                                                       |
-| ------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `-p, --pick`        | `false`   | Interactively pick a workflow + trigger (see below)                                                                                                                                                               |
-| `--workflow <name>` | none      | Run only the specified workflow (mutex with `--pick`)                                                                                                                                                             |
-| `--job <name>`      | none      | Run only the specified job (and its dependencies)                                                                                                                                                                 |
-| `--branch <name>`   | detected  | Override detected git branch                                                                                                                                                                                      |
-| `--sha <hash>`      | detected  | Override detected git SHA                                                                                                                                                                                         |
-| `--payload <path>`  | none      | Path to explicit event payload JSON file                                                                                                                                                                          |
-| `--concurrency <n>` | CPU cores | Max parallel jobs **within one run** (job-level only). Cross-run [concurrency groups](concurrency.md) declared in `workflow({ concurrency: ... })` are enforced separately — see "Concurrency enforcement" below. |
-| `--keep-going`      | `false`   | Continue after job failure                                                                                                                                                                                        |
-| `--container`       | `false`   | Use Podman container isolation                                                                                                                                                                                    |
-| `--env <KEY=VALUE>` | none      | Environment variable override (repeatable)                                                                                                                                                                        |
-| `--files <path>`    | git diff  | Override changed file paths (repeatable, default: git diff)                                                                                                                                                       |
-| `--quiet`           | `false`   | Suppress streaming output (summary only)                                                                                                                                                                          |
-| `--json`            | `false`   | Output structured JSON result                                                                                                                                                                                     |
-| `--junit <path>`    | none      | Output JUnit XML result to file                                                                                                                                                                                   |
-| `--debug`           | `false`   | Verbose internals                                                                                                                                                                                                 |
-| `--kici-dir <path>` | `.kici`   | Path to .kici directory                                                                                                                                                                                           |
-| `--in-place`        | `false`   | Run against the real working directory instead of an isolated tmp checkout (see "Execution isolation" below)                                                                                                      |
-| `--keep`            | `false`   | Always retain the isolated tmp checkout (default: keep only on failure)                                                                                                                                           |
+| Option                | Default   | Description                                                                                                                                                                                                                            |
+| --------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `-p, --pick`          | `false`   | Interactively pick a workflow + trigger (see below)                                                                                                                                                                                    |
+| `--workflow <name>`   | none      | Run only the specified workflow (mutex with `--pick`)                                                                                                                                                                                  |
+| `--job <name>`        | none      | Run only the specified job (and its dependencies)                                                                                                                                                                                      |
+| `--branch <name>`     | detected  | Override detected git branch                                                                                                                                                                                                           |
+| `--sha <hash>`        | detected  | Override detected git SHA                                                                                                                                                                                                              |
+| `--payload <path>`    | none      | Path to explicit event payload JSON file                                                                                                                                                                                               |
+| `--concurrency <n>`   | CPU cores | Max parallel jobs **within one run** (job-level only). Cross-run [concurrency groups](https://docs.kici.dev/user/concurrency/) declared in `workflow({ concurrency: ... })` are enforced separately — see "Concurrency enforcement" below.                      |
+| `--keep-going`        | `false`   | Continue after job failure                                                                                                                                                                                                             |
+| `--container`         | `false`   | Use Podman container isolation                                                                                                                                                                                                         |
+| `--env <KEY=VALUE>`   | none      | Environment variable override (repeatable)                                                                                                                                                                                             |
+| `--input <KEY=VALUE>` | none      | Typed workflow-dispatch input (repeatable) — coerced + validated against the workflow's `dispatch({ inputs })` schema, exposed as `ctx.dispatchInputs` (see [triggers → typed dispatch inputs](https://docs.kici.dev/user/sdk/triggers/#typed-dispatch-inputs)) |
+| `--files <path>`      | git diff  | Override changed file paths (repeatable, default: git diff)                                                                                                                                                                            |
+| `--quiet`             | `false`   | Suppress streaming output (summary only)                                                                                                                                                                                               |
+| `--json`              | `false`   | Output structured JSON result                                                                                                                                                                                                          |
+| `--junit <path>`      | none      | Output JUnit XML result to file                                                                                                                                                                                                        |
+| `--debug`             | `false`   | Verbose internals                                                                                                                                                                                                                      |
+| `--kici-dir <path>`   | `.kici`   | Path to .kici directory                                                                                                                                                                                                                |
+| `--in-place`          | `false`   | Run against the real working directory instead of an isolated tmp checkout (see "Execution isolation" below)                                                                                                                           |
+| `--keep`              | `false`   | Always retain the isolated tmp checkout (default: keep only on failure)                                                                                                                                                                |
 
 **Interactive workflow selection (`--pick` / `-p`):**
 
@@ -5619,9 +6049,11 @@ kici run local push --keep-going
 
 Execute fixtures remotely through the full CI pipeline. Fixtures are defined in `.kici/tests/*.ts` using the `fixture()` factory function. Without arguments, lists available fixtures.
 
-Remote runs route through the Platform. Authenticate with a personal access token (`kici login`), then target an organization with `kici org use <org>` or the `--org` flag. The Platform relays the run to the org's orchestrator, while your working-tree overlay uploads directly to object storage — see [How the run is routed](#how-the-run-is-routed) and [The two planes](#the-two-planes) below.
+Remote runs route through the Platform. Authenticate with a personal access token (`kici login`), then target an organization with `kici org use <org>` or the `--org` flag. The Platform relays the run to the org's orchestrator, while your working-tree overlay uploads directly to object storage — see [How the run is routed](https://docs.kici.dev/user/cli-reference/#how-the-run-is-routed) and [The two planes](https://docs.kici.dev/user/cli-reference/#the-two-planes) below.
 
-The orchestrator must have **cache storage configured** (`KICI_STORAGE_TYPE` = `s3` or `filesystem`) with a dev-reachable upload endpoint so the CLI's direct upload succeeds; see the [testing guide](testing-guide.md) and [Storage layout](../operator/orchestrator/storage-layout.md) for setup.
+Like `kici run local`, `kici run remote` recompiles your workflows (`.kici/workflows` → `kici.lock.json`) before dispatching, so the orchestrator matches and dispatches against your current workflow definitions — a brand-new or edited workflow takes effect without a separate `kici compile`. A compile or validation error aborts the run before anything is uploaded.
+
+The orchestrator must have **cache storage configured** (`KICI_STORAGE_TYPE` = `s3` or `filesystem`) with a dev-reachable upload endpoint so the CLI's direct upload succeeds; see the [testing guide](https://docs.kici.dev/user/testing-guide/) and [Storage layout](https://docs.kici.dev/operator/orchestrator/storage-layout/) for setup.
 
 ```bash
 kici run remote [fixture] [options]
@@ -5635,22 +6067,26 @@ kici run remote [fixture] [options]
 
 **Options:**
 
-| Option                      | Default | Description                                                                                       |
-| --------------------------- | ------- | ------------------------------------------------------------------------------------------------- |
-| `--org <id>`                | active  | Target organization for this run (overrides `kici org use`)                                       |
-| `--orchestrator <name>`     | default | Target orchestrator cluster within the org (overrides the per-org default)                        |
-| `--all`                     | `false` | Run all fixtures                                                                                  |
-| `--workflow <name>`         | none    | Run a specific workflow directly (bypass triggers)                                                |
-| `--parallel`                | `false` | Run multiple fixtures concurrently                                                                |
-| `--no-wait`                 | -       | Fire and forget (print runIds, don't stream)                                                      |
-| `--quiet`                   | `false` | Minimal output (only final result)                                                                |
-| `--json`                    | `false` | Machine-readable JSON output                                                                      |
-| `--junit <path>`            | none    | JUnit XML output to file for CI integration                                                       |
-| `--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) |
-| `--debug`                   | `false` | Verbose internals                                                                                 |
-| `--kici-dir <path>`         | `.kici` | Path to .kici directory                                                                           |
+| Option                      | Default | Description                                                                                                                                                                                                                                |
+| --------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `--org <id>`                | active  | Target organization for this run (overrides `kici org use`)                                                                                                                                                                                |
+| `--orchestrator <name>`     | default | Target orchestrator cluster within the org (overrides the per-org default)                                                                                                                                                                 |
+| `--all`                     | `false` | Run all fixtures                                                                                                                                                                                                                           |
+| `-p, --pick`                | `false` | Interactively pick fixtures to run (multi-select; mutex with a fixture arg, `--all`, and `--workflow`)                                                                                                                                     |
+| `--workflow <name>`         | none    | Run a specific workflow directly (bypass triggers)                                                                                                                                                                                         |
+| `--parallel`                | `false` | Run multiple fixtures concurrently                                                                                                                                                                                                         |
+| `--no-wait`                 | -       | Fire and forget (print runIds, don't stream)                                                                                                                                                                                               |
+| `--quiet`                   | `false` | Minimal output (only final result)                                                                                                                                                                                                         |
+| `--json`                    | `false` | Machine-readable JSON output                                                                                                                                                                                                               |
+| `--junit <path>`            | none    | JUnit XML output to file for CI integration                                                                                                                                                                                                |
+| `--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](https://docs.kici.dev/user/testing-guide/)                                                                                                                                          |
+| `--input <KEY=VALUE>`       | none    | Typed workflow-dispatch input (repeatable) — validated + coerced + defaulted on the orchestrator from the lock descriptor, exposed as `ctx.dispatchInputs` (see [triggers → typed dispatch inputs](https://docs.kici.dev/user/sdk/triggers/#typed-dispatch-inputs)) |
+| `--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                                                                                                                                                                                                                    |
 
 **Examples:**
 
@@ -5687,8 +6123,59 @@ kici run remote push-main --no-wait
 
 # View recent test run history
 kici run remote --history
+
+# Interactively pick which fixtures to run (multi-select)
+kici run remote --pick
+
+# 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
 ```
 
+**Interactive fixture selection (`--pick` / `-p`):**
+
+Pass `--pick` (or `-p`) to open an interactive checkbox menu of the available
+fixtures. Toggle one or more with space, confirm with enter, and the selected
+fixtures run through the normal remote pipeline (honoring `--parallel`,
+`--no-wait`, and the other run flags). Notes:
+
+- `--pick` is mutually exclusive with a fixture argument, `--all`, and
+  `--workflow`. Passing any together exits with code 2.
+- When `stdin` is not a TTY, `--pick` prints the available fixtures and exits
+  without running anything — pass a fixture name (or `--all`) in scripts.
+
+#### 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](https://docs.kici.dev/user/sdk/core/#job-dependencies-needs)
+for the `when` gating model.
+
 **Exit codes:**
 
 | Code | Meaning                      |
@@ -5718,9 +6205,9 @@ When an org has more than one connected orchestrator cluster, the CLI picks the
 `kici run remote` uses two independent paths:
 
 - **Control plane** — run initiation, trigger, status, log retrieval, and cancellation flow from your machine through the Platform, which relays them over a WebSocket connection to the org's orchestrator. Logs are delivered by the CLI polling the Platform for log chunks (tracked by a monotonic line cursor) and run status until the run reaches a terminal state; there is no direct streaming socket to the orchestrator.
-- **Data plane** — your working-tree overlay tarball uploads **directly** from your machine to the orchestrator's object store via a presigned PUT URL. The overlay never passes through the Platform. This is why the orchestrator's object-store upload endpoint must be reachable from your machine; see [Storage layout](../operator/orchestrator/storage-layout.md).
+- **Data plane** — your working-tree overlay tarball uploads **directly** from your machine to the orchestrator's object store via a presigned PUT URL. The overlay never passes through the Platform. This is why the orchestrator's object-store upload endpoint must be reachable from your machine; see [Storage layout](https://docs.kici.dev/operator/orchestrator/storage-layout/).
 
-An orchestrator with no Platform connection cannot serve remote runs — the Platform is the service that offers them. For executing workflow steps on your own machine without an orchestrator (no scaler, agents, or environments), use [`kici run local`](#kici-run-local).
+An orchestrator with no Platform connection cannot serve remote runs — the Platform is the service that offers them. For executing workflow steps on your own machine without an orchestrator (no scaler, agents, or environments), use [`kici run local`](https://docs.kici.dev/user/cli-reference/#kici-run-local).
 
 #### Fresh repos (no GitHub remote)
 
@@ -5734,7 +6221,7 @@ An orchestrator with no Platform connection cannot serve remote runs — the Pla
 
 Destination routing is unchanged for fresh repos: the run still goes to your active org through the Platform.
 
-For a detailed guide on writing fixtures, configuring secrets, and understanding the upload flow, see [Testing guide](testing-guide.md).
+For a detailed guide on writing fixtures, configuring secrets, and understanding the upload flow, see [Testing guide](https://docs.kici.dev/user/testing-guide/).
 
 #### kici orchestrators
 
@@ -5829,18 +6316,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:**
 
@@ -5866,7 +6356,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
@@ -6115,7 +6606,7 @@ for `--quiet`.
 
 ### kici approve
 
-Approve a held [approval gate](approvals.md) so the run resumes. Identify the held element by run ID, optionally narrowed to a job and step.
+Approve a held [approval gate](https://docs.kici.dev/user/approvals/) so the run resumes. Identify the held element by run ID, optionally narrowed to a job and step.
 
 ```bash
 kici approve <run-id> [options]
@@ -6151,7 +6642,7 @@ You must be eligible for at least one unsatisfied clause (a member of a named te
 
 ### kici reject
 
-Reject a held [approval gate](approvals.md). A rejection fails the held element and the run. A reason is required.
+Reject a held [approval gate](https://docs.kici.dev/user/approvals/). A rejection fails the held element and the run. A reason is required.
 
 ```bash
 kici reject <run-id> --reason <text> [options]
@@ -6230,7 +6721,7 @@ After generating types, `ctx.secrets.get('MY_KEY')` and `ctx.secrets.expose('DB_
 
 **Git workflow:** Commit the generated `.kici/types/secrets.d.ts` so team members get type checking without needing orchestrator access. Run `kici types` to refresh when environments change.
 
-**Auto-regeneration:** `kici compile` automatically runs `kici types` after successful compilation when authenticated. See the [kici compile](#kici-compile) section for details.
+**Auto-regeneration:** `kici compile` automatically runs `kici types` after successful compilation when authenticated. See the [kici compile](https://docs.kici.dev/user/cli-reference/#kici-compile) section for details.
 
 **Escape hatch:** For dynamic keys not in the generated types, use a cast: `(ctx.secrets as any).DYNAMIC_KEY`.
 
@@ -6449,9 +6940,10 @@ Open the KiCI documentation site in the default browser. With the `llm` subcomma
 ```bash
 kici docs               # open https://kici.dev/docs/
 kici docs --no-open     # print the URL instead of opening a browser
-kici docs llm           # print llms-full.txt (the full bundle) to stdout
-kici docs llm --index   # print llms.txt (the curated link index) to stdout
-kici docs llm --out path/to/file.md   # write the bundle to a file
+kici docs llm           # print the llms.txt index (a router over the task bundles)
+kici docs llm sdk       # print the SDK task bundle
+kici docs llm full      # print llms-full.txt (every page in one file)
+kici docs llm sdk --out sdk-context.md   # write a bundle to a file
 ```
 
 **Examples:**
@@ -6460,14 +6952,14 @@ kici docs llm --out path/to/file.md   # write the bundle to a file
 # Open the docs site in your browser
 kici docs
 
-# Pipe the full LLM bundle into a coding agent
-kici docs llm | claude -- "Read this and help me author a deploy workflow"
+# Pipe just the SDK bundle into a coding agent (small, task-scoped context)
+kici docs llm sdk | claude -- "Read this and help me author a deploy workflow"
 
-# Save the curated index for offline reference
-kici docs llm --index --out kici-llms.txt
+# Save the router index for offline reference
+kici docs llm --out kici-llms-index.txt
 ```
 
-The bundle is regenerated from `docs/` every time `@kici-dev/compiler` is built, so it always matches your installed CLI version. The same content is available online at <https://kici.dev/llms.txt> and <https://kici.dev/llms-full.txt> following the [llms.txt convention](https://llmstxt.org/).
+Bundles are regenerated from `docs/` every time `@kici-dev/compiler` is built, so they always match your installed CLI version. The index lists each task bundle — `getting-started`, `sdk`, `cli`, `patterns`, `features`, `providers`, `architecture` — with its size and a one-line purpose; pass the bundle id as the topic. Every cross-reference link inside a bundle is an absolute `docs.kici.dev` URL. The same files are published online following the [llms.txt convention](https://llmstxt.org/).
 
 ### kici admin
 
@@ -6506,7 +6998,7 @@ kici admin drain-worker --url http://worker-2.internal:10143
 
 ### kici verify-attestation
 
-Verify a KiCI build-provenance attestation bundle offline. A bundle is the signed package a workflow step produces via `ctx.attestProvenance(...)`: a DSSE-wrapped SLSA in-toto statement, the ephemeral public key that signed it, and the KiCI identity token that anchors the build context. For the end-to-end attest → verify → view journey, see the [build provenance guide](./provenance.md). Verification establishes the full chain — the identity token verifies against the trusted issuer's JWKS, the DSSE signature verifies against the bundled key, and the statement's build context must match the token's claims (a mismatch is a hard failure). When an `[artifact]` is given, its SHA-256 digest is also matched against the attestation subject.
+Verify a KiCI build-provenance attestation bundle offline. A bundle is the signed package a workflow step produces via `ctx.attestProvenance(...)`: a DSSE-wrapped SLSA in-toto statement, the ephemeral public key that signed it, and the KiCI identity token that anchors the build context. For the end-to-end attest → verify → view journey, see the [build provenance guide](https://docs.kici.dev/user/provenance/). Verification establishes the full chain — the identity token verifies against the trusted issuer's JWKS, the DSSE signature verifies against the bundled key, and the statement's build context must match the token's claims (a mismatch is a hard failure). When an `[artifact]` is given, its SHA-256 digest is also matched against the attestation subject.
 
 ```bash
 kici verify-attestation [artifact] --bundle <path-or-url> --trust-root <url-or-file> [options]
@@ -6595,7 +7087,7 @@ The `kici compile` command produces `.kici/kici.lock.json` inside the `.kici` di
 - Should be committed to version control
 - Is regenerated on every `kici compile` run
 
-Use `kici compile --check` in CI to validate that workflows are correct without writing files. For the full story on drift, pre-commit/CI, and agent-side verification, see [Lock file and workflow drift](lock-file-and-drift.md).
+Use `kici compile --check` in CI to validate that workflows are correct without writing files. For the full story on drift, pre-commit/CI, and agent-side verification, see [Lock file and workflow drift](https://docs.kici.dev/user/lock-file-and-drift/).
 
 ## Exit codes
 
@@ -6633,10 +7125,10 @@ Set `KICI_DEBUG=true` for additional internal debug output across all commands.
 
 ## See also
 
-- [Getting started](getting-started.md) -- install the SDK and write your first workflow
-- [Testing guide](testing-guide.md) -- writing fixtures, remote test runs, secret contexts, and repo state transfer
-- [SDK reference](sdk-reference.md) -- complete API for the workflow definitions that the CLI compiles
-- [Workflow patterns](workflow-patterns.md) -- example workflows to compile and test with these commands
+- [Getting started](https://docs.kici.dev/user/getting-started/) -- install the SDK and write your first workflow
+- [Testing guide](https://docs.kici.dev/user/testing-guide/) -- writing fixtures, remote test runs, secret contexts, and repo state transfer
+- [SDK reference](https://docs.kici.dev/user/sdk-reference/) -- complete API for the workflow definitions that the CLI compiles
+- [Workflow patterns](https://docs.kici.dev/user/workflow-patterns/) -- example workflows to compile and test with these commands
 
 ---
 
@@ -6917,12 +7409,12 @@ Each workflow entry includes:
 | `jobs`                 | Job definitions with scheduling metadata (runsOn, needs, matrix, environment, concurrency, container, checkout, gracePeriod, label routing, dynamic fields, etc.).                                                                                                                                                                                                                                                                                              |
 | `rules`                | Workflow-level conditional rules (optional). Stored as dynamic references since rule functions cannot be serialized.                                                                                                                                                                                                                                                                                                                                            |
 | `description`          | Optional workflow description.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `hashFiles`            | Declared glob patterns for extra files included in the content hash (optional). See [extra files in the content hash](#extra-files-in-the-content-hash-hashfiles).                                                                                                                                                                                                                                                                                              |
+| `hashFiles`            | Declared glob patterns for extra files included in the content hash (optional). See [extra files in the content hash](https://docs.kici.dev/user/lock-file-and-drift/#extra-files-in-the-content-hash-hashfiles).                                                                                                                                                                                                                                                                                              |
 | `resolvedHashFiles`    | Resolved file paths from `hashFiles` at compile time (optional). Recorded so the agent can verify without re-discovering.                                                                                                                                                                                                                                                                                                                                       |
 | `contexts`             | Secret contexts declared by the workflow (optional). The orchestrator validates access to each context before dispatch.                                                                                                                                                                                                                                                                                                                                         |
-| `registries`           | Private npm registry declarations the agent authenticates against before install (optional): `url`, `scope`, `tokenSecret` reference, `alwaysAuth`. Resolved token bytes never appear in the lock file. See [private registries](private-registries.md).                                                                                                                                                                                                        |
-| `installEnv`           | Extra qualified secret refs (`<environment>:<secret-name>`) projected as env vars on the install subprocess for use with a committed `.kici/.npmrc` (optional). See [private registries](private-registries.md).                                                                                                                                                                                                                                                |
-| `concurrency`          | Workflow-level concurrency config: `hasGroup`, `cancelInProgress`, `max` (optional). See [concurrency groups](concurrency.md).                                                                                                                                                                                                                                                                                                                                  |
+| `registries`           | Private npm registry declarations the agent authenticates against before install (optional): `url`, `scope`, `tokenSecret` reference, `alwaysAuth`. Resolved token bytes never appear in the lock file. See [private registries](https://docs.kici.dev/user/private-registries/).                                                                                                                                                                                                        |
+| `installEnv`           | Extra qualified secret refs (`<environment>:<secret-name>`) projected as env vars on the install subprocess for use with a committed `.kici/.npmrc` (optional). See [private registries](https://docs.kici.dev/user/private-registries/).                                                                                                                                                                                                                                                |
+| `concurrency`          | Workflow-level concurrency config: `hasGroup`, `cancelInProgress`, `max` (optional). See [concurrency groups](https://docs.kici.dev/user/concurrency/).                                                                                                                                                                                                                                                                                                                                  |
 | `timeout`              | Whole-run wall-clock timeout in milliseconds (optional). The orchestrator reads this at run creation to set the run deadline.                                                                                                                                                                                                                                                                                                                                   |
 | Hook flags             | Boolean flags (`hasOnCancel`, `hasCleanup`, `hasOnSuccess`, `hasOnFailure`) indicating which lifecycle hooks are defined. Job entries additionally have `hasBeforeStep` and `hasAfterStep`.                                                                                                                                                                                                                                                                     |
 
@@ -6951,7 +7443,7 @@ Install a hook that compiles and stages the lock file before each commit:
 npx kici hook install
 ```
 
-This runs `kici compile && git add .kici/kici.lock.json` before each commit: if compilation fails the commit is blocked; if it succeeds the updated lock file is automatically staged. See [CLI Reference — kici hook](cli-reference.md#kici-hook) for options (husky, lefthook, pre-commit, prek, raw git).
+This runs `kici compile && git add .kici/kici.lock.json` before each commit: if compilation fails the commit is blocked; if it succeeds the updated lock file is automatically staged. See [CLI Reference — kici hook](https://docs.kici.dev/user/cli-reference/#kici-hook) for options (husky, lefthook, pre-commit, prek, raw git).
 
 ### CI check
 
@@ -7001,9 +7493,9 @@ So even without a pre-commit or CI check, a stale lock file will cause the run t
 
 ## See also
 
-- [Getting Started](getting-started.md) — compile and commit the lock file
-- [CLI Reference](cli-reference.md) — `kici compile`, `kici compile --check`, `kici hook`
-- [Architecture — Data flows](../architecture/data-flows.md) — how the lock file is used in the pipeline
+- [Getting Started](https://docs.kici.dev/user/getting-started/) — compile and commit the lock file
+- [CLI Reference](https://docs.kici.dev/user/cli-reference/) — `kici compile`, `kici compile --check`, `kici hook`
+- [Architecture — Data flows](https://docs.kici.dev/architecture/data-flows/) — how the lock file is used in the pipeline
 
 ---
 
@@ -7025,14 +7517,14 @@ Test your workflows remotely against the full CI pipeline from your local machin
 The command is remote-only -- all execution happens on the orchestrator and agent. For local-only trigger matching previews, use `kici test <event>`.
 
 :::note[Orchestrator prerequisite: cache storage]
-`kici run remote` uploads your working-tree overlay to the orchestrator's **cache storage** via a pre-signed URL, and the agent fetches it from there (see [Repo state transfer](#repo-state-transfer)). The target orchestrator must therefore have cache storage enabled (`KICI_STORAGE_TYPE` = `s3` or `filesystem`).
+`kici run remote` uploads your working-tree overlay to the orchestrator's **cache storage** via a pre-signed URL, and the agent fetches it from there (see [Repo state transfer](https://docs.kici.dev/user/testing-guide/#repo-state-transfer)). The target orchestrator must therefore have cache storage enabled (`KICI_STORAGE_TYPE` = `s3` or `filesystem`).
 
-- **Both quickstarts wire this up for you** — the [Docker / Podman quickstart](quickstart/compose.md) and the [bare-metal quickstart](quickstart/bare-metal.md) each ship a SeaweedFS object store and pre-fill the orchestrator's `KICI_STORAGE_*` block, so `kici run remote` works out of the box (see each guide's "run a workflow without pushing" step).
+- **Both quickstarts wire this up for you** — the [Docker / Podman quickstart](https://docs.kici.dev/user/quickstart/compose/) and the [bare-metal quickstart](https://docs.kici.dev/user/quickstart/bare-metal/) each ship a SeaweedFS object store and pre-fill the orchestrator's `KICI_STORAGE_*` block, so `kici run remote` works out of the box (see each guide's "run a workflow without pushing" step).
 - **A hand-rolled orchestrator deploy does not configure storage by default** — enable a backend before using `kici run remote`:
   - **`filesystem`** — simplest for a single-host orchestrator: set `KICI_STORAGE_TYPE=filesystem` and `KICI_STORAGE_FS_PATH=/var/lib/kici/cache`. No external service needed; blobs are served through the orchestrator's own HMAC-signed HTTP route.
   - **`s3`** — any S3-compatible bucket. **A non-public / self-hosted endpoint works**: set `KICI_STORAGE_TYPE=s3`, `KICI_STORAGE_BUCKET`, `KICI_STORAGE_ENDPOINT=https://your-endpoint` and (for most self-hosted services) `KICI_STORAGE_FORCE_PATH_STYLE=true`. If the developer machine running `kici run remote` reaches the bucket at a different address than the orchestrator, set `KICI_STORAGE_UPLOAD_ENDPOINT` to the developer-reachable address; if agents reach it at yet another address (e.g. agents in containers), set `KICI_STORAGE_EXTERNAL_ENDPOINT` to the agent-routable URL.
 
-See [Storage layout](../operator/orchestrator/storage-layout.md) for the full env-var reference.
+See [Storage layout](https://docs.kici.dev/operator/orchestrator/storage-layout/) for the full env-var reference.
 :::
 
 ## Getting started
@@ -7043,7 +7535,7 @@ See [Storage layout](../operator/orchestrator/storage-layout.md) for the full en
 kici login
 ```
 
-This opens your browser for OAuth authentication and stores a personal access token in `~/.kici/config`. For CI/CD pipelines or headless environments, use `kici login --token <your-api-key>` or `kici login --device` instead. See [CLI authentication](cli-auth.md) for details.
+This opens your browser for OAuth authentication and stores a personal access token in `~/.kici/config`. For CI/CD pipelines or headless environments, use `kici login --token <your-api-key>` or `kici login --device` instead. See [CLI authentication](https://docs.kici.dev/user/cli-auth/) for details.
 
 ### 2. Write a test fixture
 
@@ -7151,8 +7643,8 @@ This maps the `db` secret context to the `test-database` context, and `api` to `
 
 This mapping is honored by **both** `kici run local` and `kici run remote`:
 
-- For **`kici run local`** (see [`kici run local`](cli-reference.md#kici-run-local)), each named context is resolved from your local secret files (`.kici/.secrets`, `.env.local`, `secrets.yaml`, and `--env` flags).
-- For **`kici run remote`**, each named context maps to an orchestrator **environment**, and the orchestrator resolves that environment's secrets for the run. The target environment must be flagged `allowLocalExecution: true` — mapping a context to a missing or non-test environment rejects the run (see [Secret contexts for testing](#secret-contexts-for-testing) below).
+- For **`kici run local`** (see [`kici run local`](https://docs.kici.dev/user/cli-reference/#kici-run-local)), each named context is resolved from your local secret files (`.kici/.secrets`, `.env.local`, `secrets.yaml`, and `--env` flags).
+- For **`kici run remote`**, each named context maps to an orchestrator **environment**, and the orchestrator resolves that environment's secrets for the run. The target environment must be flagged `allowLocalExecution: true` — mapping a context to a missing or non-test environment rejects the run (see [Secret contexts for testing](https://docs.kici.dev/user/testing-guide/#secret-contexts-for-testing) below).
 
 ### Async fixtures
 
@@ -7307,7 +7799,7 @@ Because these values originate on your machine, they are the natural place to pu
 
 In addition to your uploaded values, the orchestrator resolves test-scoped secrets from its own store for a remote test run:
 
-- The job's own declared `environment` contributes its resolved secrets (flat). Static strings and **pure dynamic functions** both participate: a pure `environment:` function (see [Dynamic values](dynamic-values.md)) is evaluated against the fixture's simulated event, and the resolved name is gated and resolved like a static one. Impure dynamic functions (those requiring an init job) are not evaluated for test runs — use a fixture `secrets:` mapping (or `--context`) to supply such a job's secrets.
+- The job's own declared `environment` contributes its resolved secrets (flat). Static strings and **pure dynamic functions** both participate: a pure `environment:` function (see [Dynamic values](https://docs.kici.dev/user/dynamic-values/)) is evaluated against the fixture's simulated event, and the resolved name is gated and resolved like a static one. Impure dynamic functions (those requiring an init job) are not evaluated for test runs — use a fixture `secrets:` mapping (or `--context`) to supply such a job's secrets.
 - Each fixture `secrets: { ctx: envName }` mapping resolves the named environment's secrets under the namespaced context `ctx`.
 
 Both paths are restricted to environments flagged `allowLocalExecution: true`. A production environment left at the default `false` is never resolvable for a test run.
@@ -7352,7 +7844,7 @@ or via the dashboard's "Test runs" toggle on the environment detail page. `kici
 
 ### Local execution as an alternative
 
-`kici run local` resolves the same local secret files entirely on your machine and honors the fixture `secrets: { ... }` mapping to pick which local context backs each name (see [`kici run local`](cli-reference.md#kici-run-local)). Because the values never leave your machine, it's a good fit when you want to exercise secret-dependent steps without involving the orchestrator at all.
+`kici run local` resolves the same local secret files entirely on your machine and honors the fixture `secrets: { ... }` mapping to pick which local context backs each name (see [`kici run local`](https://docs.kici.dev/user/cli-reference/#kici-run-local)). Because the values never leave your machine, it's a good fit when you want to exercise secret-dependent steps without involving the orchestrator at all.
 
 ### Discovering available contexts
 
@@ -7429,9 +7921,9 @@ export const pushMain = fixture('push-main', {
 
 ## See also
 
-- [CLI reference](cli-reference.md) -- complete command reference for all `kici` commands
-- [SDK reference](sdk-reference.md) -- trigger functions, step context, and workflow API
-- [Workflow patterns](workflow-patterns.md) -- example workflows to test against
+- [CLI reference](https://docs.kici.dev/user/cli-reference/) -- complete command reference for all `kici` commands
+- [SDK reference](https://docs.kici.dev/user/sdk-reference/) -- trigger functions, step context, and workflow API
+- [Workflow patterns](https://docs.kici.dev/user/workflow-patterns/) -- example workflows to test against
 
 ---
 
@@ -7439,24 +7931,24 @@ export const pushMain = fixture('push-main', {
 
 Source: https://docs.kici.dev/user/workflow-patterns/
 
-Practical patterns for building real-world KiCI workflows in TypeScript. The patterns are organised across five pages -- start with [Basic CI](./patterns/basic.md) if you're new, or jump to [Integrations](./patterns/integrations.md) if you're wiring up a non-GitHub forge or a generic webhook.
+Practical patterns for building real-world KiCI workflows in TypeScript. The patterns are organised across five pages -- start with [Basic CI](https://docs.kici.dev/user/patterns/basic/) if you're new, or jump to [Integrations](https://docs.kici.dev/user/patterns/integrations/) if you're wiring up a non-GitHub forge or a generic webhook.
 
 | Page                                                       | Covers                                                                                                                                             |
 | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [Basic CI](./patterns/basic.md)                            | Single-job CI, PR-only / push-only filters, multiple triggers on one workflow, manual-only workflows.                                              |
-| [Conditionals & matrix](./patterns/conditionals-matrix.md) | Conditional execution with rules, matrix builds (static + dynamic), and dynamic job generation.                                                    |
-| [Integrations](./patterns/integrations.md)                 | Workflow chaining, generic webhooks, Stripe handlers, self-hosted git forges (Forgejo / Gitea / Gogs), plain GitHub repo webhooks (no GitHub App). |
-| [Scheduling & events](./patterns/scheduling-and-events.md) | Nightly cron, workflow-complete-triggered deploys, custom event chaining.                                                                          |
-| [Pattern reference](./patterns/reference.md)               | Step context, the examples repository, and GitHub check run output -- cross-cutting reference shared by every pattern above.                       |
+| [Basic CI](https://docs.kici.dev/user/patterns/basic/)                            | Single-job CI, PR-only / push-only filters, multiple triggers on one workflow, manual-only workflows.                                              |
+| [Conditionals & matrix](https://docs.kici.dev/user/patterns/conditionals-matrix/) | Conditional execution with rules, matrix builds (static + dynamic), and dynamic job generation.                                                    |
+| [Integrations](https://docs.kici.dev/user/patterns/integrations/)                 | Workflow chaining, generic webhooks, Stripe handlers, self-hosted git forges (Forgejo / Gitea / Gogs), plain GitHub repo webhooks (no GitHub App). |
+| [Scheduling & events](https://docs.kici.dev/user/patterns/scheduling-and-events/) | Nightly cron, workflow-complete-triggered deploys, custom event chaining.                                                                          |
+| [Pattern reference](https://docs.kici.dev/user/patterns/reference/)               | Step context, the examples repository, and GitHub check run output -- cross-cutting reference shared by every pattern above.                       |
 
 ## See also
 
-- [Event system](events.md) -- event model concepts, registration model, circuit breaker
-- [SDK reference](sdk-reference.md) -- complete API reference for all functions used in these patterns
-- [CLI reference](cli-reference.md) -- how to compile and test these workflows locally
-- [Getting started](getting-started.md) -- installation and first workflow setup
-- [Job execution lifecycle](../architecture/execution/job-execution.md) -- how agents execute the jobs defined in these patterns
-- [GitHub checks architecture](../architecture/webhooks/github-checks.md) -- deep dive into the check run system
+- [Event system](https://docs.kici.dev/user/events/) -- event model concepts, registration model, circuit breaker
+- [SDK reference](https://docs.kici.dev/user/sdk-reference/) -- complete API reference for all functions used in these patterns
+- [CLI reference](https://docs.kici.dev/user/cli-reference/) -- how to compile and test these workflows locally
+- [Getting started](https://docs.kici.dev/user/getting-started/) -- installation and first workflow setup
+- [Job execution lifecycle](https://docs.kici.dev/architecture/execution/job-execution/) -- how agents execute the jobs defined in these patterns
+- [GitHub checks architecture](https://docs.kici.dev/architecture/webhooks/github-checks/) -- deep dive into the check run system
 
 ---
 
@@ -7476,7 +7968,7 @@ your organizations, roles, and API keys stay attached to the same identity.
 Sign-in methods and passwords are managed in your **account console**, provided
 by the identity provider that handles single sign-on for KiCI. The dashboard's
 **Linked accounts** page does not control how you sign in — see
-[Linked accounts vs sign-in methods](#linked-accounts-vs-sign-in-methods) below.
+[Linked accounts vs sign-in methods](https://docs.kici.dev/user/account-and-login/#linked-accounts-vs-sign-in-methods) below.
 
 You can open the account console from the dashboard: go to your personal
 settings, open **Linked accounts**, and use the **Account console** link.
@@ -7520,13 +8012,15 @@ 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.
 
-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.
+A step-level gate can also fire **only when a check/apply step finds drift** — Terraform's plan→apply, per step. See [Drift gates](https://docs.kici.dev/user/approvals/#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)](https://docs.kici.dev/operator/approvals/) for how operators define teams, the approval queue, and expiry; see [the architecture overview](https://docs.kici.dev/architecture/approvals/) for how a hold is evaluated and resumed.
 
 ## Quick start
 
@@ -7540,37 +8034,37 @@ export default workflow('deploy', {
   jobs: [
     job('deploy-production', {
       runsOn: 'default',
-      requireApproval: [{ team: 'leads' }],
+      approval: [{ team: 'leads' }],
       steps: [step('deploy', async (ctx) => ctx.$`deploy --prod`)],
     }),
   ],
 });
 ```
 
-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.
+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`](https://docs.kici.dev/user/approvals/#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.
@@ -7582,27 +8076,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](https://docs.kici.dev/user/approvals/#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).
+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](https://docs.kici.dev/operator/approvals/#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
 
@@ -7611,7 +8107,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],
 });
 ```
@@ -7623,7 +8119,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: [
     /* ... */
   ],
@@ -7640,7 +8136,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`),
@@ -7650,11 +8146,41 @@ job('migrate-and-deploy', {
 
 Here `build-plan` runs, then the job pauses for a `dba` approval. On approval, `apply-migration` runs against the exact workspace `build-plan` produced, followed by `deploy`. A rejection or expiry fails the job.
 
-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).
+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](https://docs.kici.dev/operator/approvals/#agent-occupancy-during-step-level-holds).
+
+## Drift gates (`when: 'drift'`)
+
+A `when: 'drift'` gate is **step-scope only** and requires a [check/apply step](https://docs.kici.dev/user/idempotent-steps/). 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](https://docs.kici.dev/user/approvals/#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](https://docs.kici.dev/user/environments/#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
 
@@ -7674,15 +8200,28 @@ kici approve <run-id> --job migrate-and-deploy --step apply-migration
 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.
+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`](https://docs.kici.dev/user/cli-reference/#kici-approve) for the full command reference.
 
-You can also approve from the dashboard approval queue. See [Dashboard](dashboard/environments-and-secrets.md#approval-queue).
+### 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](https://docs.kici.dev/user/dashboard/environments-and-secrets/#approval-queue).
 
 ## See also
 
-- [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.
+- [Idempotent steps](https://docs.kici.dev/user/idempotent-steps/) — the check/apply step facet that drift gates build on.
+- [Environments](https://docs.kici.dev/user/environments/) — operator-required reviewers on protected environments.
+- [Approval gates (operator guide)](https://docs.kici.dev/operator/approvals/) — teams, the approval queue, expiry, and self-approval.
+- [Approval gates (architecture)](https://docs.kici.dev/architecture/approvals/) — the unified hold model and the step-level round-trip.
 
 ---
 
@@ -7742,7 +8281,7 @@ group: () => 'deploy';
 group: (ctx) => `deploy-${ctx.event.targetBranch ?? 'default'}`;
 ```
 
-The workflow-level group function is always evaluated **agent-side** at runtime -- the lock file records only that a group function exists (`hasGroup: true`), not the function itself. The agent loads the workflow source, calls the group function with `{ branch, event }`, and reports the evaluated key back to the orchestrator before step execution begins. This differs from job-level `concurrencyGroup` (see [Environments](environments.md#concurrency-groups)), where the compiler performs purity analysis and can inline pure functions for orchestrator-side evaluation.
+The workflow-level group function is always evaluated **agent-side** at runtime -- the lock file records only that a group function exists (`hasGroup: true`), not the function itself. The agent loads the workflow source, calls the group function with `{ branch, event }`, and reports the evaluated key back to the orchestrator before step execution begins. This differs from job-level `concurrencyGroup` (see [Environments](https://docs.kici.dev/user/environments/#concurrency-groups)), where the compiler performs purity analysis and can inline pure functions for orchestrator-side evaluation.
 
 ## cancelInProgress mode
 
@@ -7893,7 +8432,7 @@ Queued runs can be cancelled before they start executing. The cancel request rem
 
 ## Job-level concurrency groups
 
-In addition to workflow-level concurrency, individual jobs can define their own concurrency group via the `concurrencyGroup` property. This controls concurrent execution at the job level rather than the workflow level. See [Environments — concurrency groups](environments.md#concurrency-groups) for details.
+In addition to workflow-level concurrency, individual jobs can define their own concurrency group via the `concurrencyGroup` property. This controls concurrent execution at the job level rather than the workflow level. See [Environments — concurrency groups](https://docs.kici.dev/user/environments/#concurrency-groups) for details.
 
 ## Local execution
 
@@ -7901,7 +8440,7 @@ In addition to workflow-level concurrency, individual jobs can define their own
 
 Coordination is local only. Running the same workflow on two different machines does not serialize across them — that requires the orchestrator. For full cross-host enforcement (queueing across agents, dashboard visibility, `max > 1`), use `kici run remote` against a deployed orchestrator.
 
-Lock files live under `$XDG_RUNTIME_DIR/kici-local-locks/` on Linux, falling back to `os.tmpdir()/kici-local-locks-<uid>/`. A workflow whose `group` callback throws aborts the run with a clear error rather than running unprotected. See [`kici run local` — Concurrency enforcement](cli-reference.md#concurrency-enforcement) for the `KICI_LOCAL_LOCK_KILL_GRACE_MS` override and the diagnostic output emitted while contending on a busy lock.
+Lock files live under `$XDG_RUNTIME_DIR/kici-local-locks/` on Linux, falling back to `os.tmpdir()/kici-local-locks-<uid>/`. A workflow whose `group` callback throws aborts the run with a clear error rather than running unprotected. See [`kici run local` — Concurrency enforcement](https://docs.kici.dev/user/cli-reference/#concurrency-enforcement) for the `KICI_LOCAL_LOCK_KILL_GRACE_MS` override and the diagnostic output emitted while contending on a busy lock.
 
 The `kici run local --concurrency <n>` flag is a separate concept — it caps **job-level** parallelism within a single run (how many jobs from one workflow run at once), not cross-run serialization.
 
@@ -7921,14 +8460,14 @@ This guide is split across the following pages:
 
 | Page                                                                                  | Covers                                                                  |
 | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
-| [Getting started](./dashboard/getting-started.md)                                     | Onboarding checklist and your organizations list                        |
-| [Navigation and layout](./dashboard/navigation.md)                                    | Sidebar, mobile nav, theme, time display, shortcuts, error pages        |
-| [Runs and logs](./dashboard/runs.md)                                                  | Run list, run detail, the log viewer                                    |
-| [Settings](./dashboard/settings.md)                                                   | Members, roles, teams, keys, sources, billing, security, support access |
-| [Workflows, diagnostics, and orchestrators](./dashboard/workflows-and-diagnostics.md) | Registered workflows, infra health, per-cluster views                   |
-| [Environments, secrets, and approvals](./dashboard/environments-and-secrets.md)       | Environments, secret scopes, approval queue                             |
-| [Activity and DLQ](./dashboard/activity-and-dlq.md)                                   | Forensic activity log and dead-letter queue                             |
-| [Account](./dashboard/account.md)                                                     | Personal account settings                                               |
+| [Getting started](https://docs.kici.dev/user/dashboard/getting-started/)                                     | Onboarding checklist and your organizations list                        |
+| [Navigation and layout](https://docs.kici.dev/user/dashboard/navigation/)                                    | Sidebar, mobile nav, theme, time display, shortcuts, error pages        |
+| [Runs and logs](https://docs.kici.dev/user/dashboard/runs/)                                                  | Run list, run detail, the log viewer                                    |
+| [Settings](https://docs.kici.dev/user/dashboard/settings/)                                                   | Members, roles, teams, keys, sources, billing, security, support access |
+| [Workflows, diagnostics, and orchestrators](https://docs.kici.dev/user/dashboard/workflows-and-diagnostics/) | Registered workflows, infra health, per-cluster views                   |
+| [Environments, secrets, and approvals](https://docs.kici.dev/user/dashboard/environments-and-secrets/)       | Environments, secret scopes, approval queue                             |
+| [Activity and DLQ](https://docs.kici.dev/user/dashboard/activity-and-dlq/)                                   | Forensic activity log and dead-letter queue                             |
+| [Account](https://docs.kici.dev/user/dashboard/account/)                                                     | Personal account settings                                               |
 
 ---
 
@@ -8046,7 +8585,7 @@ env: async (event) => {
 - **Write pure functions whenever possible** to avoid the init-job delay. Most environment and env computations only need the event payload data.
 - **Check compiler warnings** -- the compiler tells you when a function is classified as impure and explains why.
 - **Runtime errors in inline expressions cause immediate job failure.** There is no fallback to the init-job path. If your pure function throws at runtime (e.g., accessing a property on `undefined`), the job fails immediately.
-- **The event parameter is the normalized event envelope** — the same shape rules receive as `ctx.event`: `{ type, action, targetBranch, sourceBranch, changedFiles, payload, … }` (see the [event payload reference](./sdk/event-payloads.md) for the complete schema). Narrow on `event.type` (`'push'`, `'pull_request'`, `'tag'`, …) to branch per trigger kind. The raw provider webhook body is nested at `event.payload` (for GitHub pushes: `payload.ref`, `payload.after`, `payload.repository`, …).
+- **The event parameter is the normalized event envelope** — the same shape rules receive as `ctx.event`: `{ type, action, targetBranch, sourceBranch, changedFiles, payload, … }` (see the [event payload reference](https://docs.kici.dev/user/sdk/event-payloads/) for the complete schema). Narrow on `event.type` (`'push'`, `'pull_request'`, `'tag'`, …) to branch per trigger kind. The raw provider webhook body is nested at `event.payload` (for GitHub pushes: `payload.ref`, `payload.after`, `payload.repository`, …).
 
 ---
 
@@ -8213,7 +8752,7 @@ job('deploy-review', {
 });
 ```
 
-A pure function like the one above (see [Dynamic values](dynamic-values.md)) is evaluated inline at dispatch with no init-job overhead. Dynamic environments that match a glob pattern (e.g., `review/*`) inherit the pattern's configuration, variables, and protection rules.
+A pure function like the one above (see [Dynamic values](https://docs.kici.dev/user/dynamic-values/)) is evaluated inline at dispatch with no init-job overhead. Dynamic environments that match a glob pattern (e.g., `review/*`) inherit the pattern's configuration, variables, and protection rules.
 
 ### Job-level environment variables
 
@@ -8237,7 +8776,7 @@ job('deploy', {
 
 ### Concurrency groups
 
-Jobs can define their own concurrency groups to control concurrent execution within an environment. For workflow-level concurrency (which applies to all jobs in a workflow), see [Concurrency groups](concurrency.md).
+Jobs can define their own concurrency groups to control concurrent execution within an environment. For workflow-level concurrency (which applies to all jobs in a workflow), see [Concurrency groups](https://docs.kici.dev/user/concurrency/).
 
 Control concurrent deployments to the same environment:
 
@@ -8286,7 +8825,7 @@ When a job targets an environment, variables are merged in this order (last wins
 6. **Job env** -- from the `env` property in the SDK
 7. **`setEnv()` calls** -- runtime modifications within steps
 
-> **Note:** Secrets are NOT part of the environment variable merge. They are delivered to the step context via IPC and accessed through `ctx.secrets`, not through `process.env`. See the [step context](#step-context) section above.
+> **Note:** Secrets are NOT part of the environment variable merge. They are delivered to the step context via IPC and accessed through `ctx.secrets`, not through `process.env`. See the [step context](https://docs.kici.dev/user/environments/#step-context) section above.
 
 ## Protection rules
 
@@ -8310,9 +8849,9 @@ Require manual approval before a job can proceed:
 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.
+When reviewers are required, the job enters a "held" state. Reviewers can approve or reject via the dashboard, the [`kici approve`](https://docs.kici.dev/user/cli-reference/#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](https://docs.kici.dev/user/approvals/). Both forms use the same held-element mechanism and the same queue.
 
 ### Wait timer
 
@@ -8347,7 +8886,7 @@ Trust tier is determined by the contributor's identity link and CI trust RBAC le
 
 The trust tier also affects which lock file is used for PR-triggered runs: trusted contributors use the PR head lock file, while known and unknown contributors use the base branch lock file. This prevents untrusted workflow modifications from affecting execution.
 
-See the [CI security architecture docs](../architecture/security/ci-security.md) for the full trust resolution flow.
+See the [CI security architecture docs](https://docs.kici.dev/architecture/security/ci-security/) for the full trust resolution flow.
 
 ### Security approval queue
 
@@ -8381,7 +8920,7 @@ Navigate to **Settings > Environments** in the dashboard. Click **New environmen
 - **Fixed** -- applies to jobs that declare exactly this environment name, like `staging` or `production`
 - **Glob** -- applies to any environment name a job declares that matches the pattern, e.g. `review/*` matches a job with `environment: 'review/PR-123'`
 
-The environments list shows each environment's type, whether test runs may use it (the `allowLocalExecution` flag -- see the [testing guide](./testing-guide.md)), and whether it is enabled.
+The environments list shows each environment's type, whether test runs may use it (the `allowLocalExecution` flag -- see the [testing guide](https://docs.kici.dev/user/testing-guide/)), and whether it is enabled.
 
 ### Environment detail page
 
@@ -8540,7 +9079,7 @@ genericWebhook({
 
 **Config options:** `source` (required), `events`, `match`, `not`, `auth`, `path`, `description`.
 
-The `source` field MUST match the `--name` that an operator passed to `kici-admin source add generic --name <name>` when the source was created — that string is the source's identifier in the orchestrator. Generic webhook sources must be created by an operator before events can be received; see [Operator guide: event routing](../operator/event-routing.md) for setup instructions.
+The `source` field MUST match the `--name` that an operator passed to `kici-admin source add generic --name <name>` when the source was created — that string is the source's identifier in the orchestrator. Generic webhook sources must be created by an operator before events can be received; see [Operator guide: event routing](https://docs.kici.dev/operator/event-routing/) for setup instructions.
 
 ### Schedule events
 
@@ -8650,7 +9189,7 @@ This lookup is fast because the registration index is held in memory and refresh
 
 ### Cross-source webhook delivery
 
-The catch-all `webhook()` trigger (see [SDK reference: webhook()](sdk/triggers.md#webhook)) participates in this same registration lookup, but with one twist: it fires for matching events arriving via **any** inbound webhook source in the same org, not just the source the workflow's repo is bound to. The orchestrator maintains a `(customerId, eventName)` index over webhook trigger registrations and consults it on every inbound generic webhook.
+The catch-all `webhook()` trigger (see [SDK reference: webhook()](https://docs.kici.dev/user/sdk/triggers/#webhook)) participates in this same registration lookup, but with one twist: it fires for matching events arriving via **any** inbound webhook source in the same org, not just the source the workflow's repo is bound to. The orchestrator maintains a `(customerId, eventName)` index over webhook trigger registrations and consults it on every inbound generic webhook.
 
 The lookup is structurally org-isolated — a generic webhook delivered to org A can never reach a workflow registered against org B, because foreign-org rows live in a different bucket of the index. When a webhook fires across sources, the runtime clone token, repo URL, and check-status posting all come from the **registration's** source bundle, not the inbound source. The inbound source contributes only the event payload.
 
@@ -8787,15 +9326,15 @@ export default workflow('post-deploy', {
 });
 ```
 
-Custom events are delivered immediately when emitted (mid-workflow, not queued until workflow completion). See the [SDK reference: emitting events](sdk/validation-events.md#emitting-events) section for the full `ctx.emit()` API.
+Custom events are delivered immediately when emitted (mid-workflow, not queued until workflow completion). See the [SDK reference: emitting events](https://docs.kici.dev/user/sdk/validation-events/#emitting-events) section for the full `ctx.emit()` API.
 
 ## See also
 
-- [SDK reference: event triggers](sdk/triggers.md#event-triggers) -- complete API signatures for all trigger builders
-- [SDK reference: emitting events](sdk/validation-events.md#emitting-events) -- `ctx.emit()` and `defineEvent()` API
-- [Workflow patterns: workflow chaining](patterns/integrations.md#workflow-chaining) -- examples of event-driven workflow chains
-- [Operator guide: event routing](../operator/event-routing.md) -- configuring generic webhook sources, trust relationships, and event routing
-- [Architecture: event system](../architecture/webhooks/event-system.md) -- internal event routing design, registration model, cluster synchronization
+- [SDK reference: event triggers](https://docs.kici.dev/user/sdk/triggers/#event-triggers) -- complete API signatures for all trigger builders
+- [SDK reference: emitting events](https://docs.kici.dev/user/sdk/validation-events/#emitting-events) -- `ctx.emit()` and `defineEvent()` API
+- [Workflow patterns: workflow chaining](https://docs.kici.dev/user/patterns/integrations/#workflow-chaining) -- examples of event-driven workflow chains
+- [Operator guide: event routing](https://docs.kici.dev/operator/event-routing/) -- configuring generic webhook sources, trust relationships, and event routing
+- [Architecture: event system](https://docs.kici.dev/architecture/webhooks/event-system/) -- internal event routing design, registration model, cluster synchronization
 
 ---
 
@@ -8915,9 +9454,9 @@ Non-push triggers work too — `pr()`, `tag()`, `comment()`, `release()`, `workf
 
 ## See also
 
-- [Architecture — global workflows](../architecture/global-workflows.md) — dual-query dispatch flow, cross-provider auth, security model, lock-file schema.
-- [Universal-git provider](providers/universal-git.md#global-workflows) — how global workflows interact with `generic:<orgId>:<sourceId>` routing keys.
-- [SDK reference](sdk-reference.md) — the full set of triggers that accept `repos:`.
+- [Architecture — global workflows](https://docs.kici.dev/architecture/global-workflows/) — dual-query dispatch flow, cross-provider auth, security model, lock-file schema.
+- [Universal-git provider](https://docs.kici.dev/user/providers/universal-git/#global-workflows) — how global workflows interact with `generic:<orgId>:<sourceId>` routing keys.
+- [SDK reference](https://docs.kici.dev/user/sdk-reference/) — the full set of triggers that accept `repos:`.
 
 ---
 
@@ -8987,7 +9526,7 @@ const configureNginx = step('configure-nginx', {
 `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`,
-`requireApproval`, `onCancel`, `cleanup`, `outputs`) composes unchanged.
+`approval`, `onCancel`, `cleanup`, `outputs`) composes unchanged.
 
 A plain `step()` without `check` keeps its exact current behavior — the check
 facet is fully optional.
@@ -9044,9 +9583,9 @@ 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.
+- [Idempotent SDK helpers](https://docs.kici.dev/user/sdk/idempotent/) — the `idempotent()` / `idempotentStep()` convenience wrappers (always apply on drift), plus `checkStep()`, the clean-shape sibling that respects the run-level check mode.
+- [Core SDK reference](https://docs.kici.dev/user/sdk/core/) — the `step()`, `job()`, and `workflow()` factories the check facet extends.
+- [Lock file and drift](https://docs.kici.dev/user/lock-file-and-drift/) — how the lock file carries step capability flags.
 
 ---
 
@@ -9099,7 +9638,7 @@ export default workflow('build', {
 
 Per-field rules:
 
-- **`url`** — Must be HTTPS. HTTP is permitted only for `localhost` / `127.0.0.0/8` / `::1` / `*.local` hosts, or when an operator has flipped the org-level `allow_http_npm_registries` toggle (see [`kici-admin org-settings allow-http-npm`](/operator/kici-admin-cli#allow-http-npm--permit-non-https-private-npm-registries)).
+- **`url`** — Must be HTTPS. HTTP is permitted only for `localhost` / `127.0.0.0/8` / `::1` / `*.local` hosts, or when an operator has flipped the org-level `allow_http_npm_registries` toggle (see [`kici-admin org-settings allow-http-npm`](https://docs.kici.dev/operator/kici-admin-cli#allow-http-npm--permit-non-https-private-npm-registries)).
 - **`scope`** — Optional. When present, the registry serves only that scope (`@my-org`). When absent, this entry becomes the **default** registry — at most one entry may omit `scope`.
 - **`tokenSecret`** — Mandatory `<environment>:<secret-name>`. The orchestrator looks up the secret in the named environment via the per-environment secret resolver. The bare name **must not** contain a colon.
 - **`alwaysAuth`** — Defaults to `true`. Forces npm to send the token on every request (even GETs), which is what most managed-registry providers require.
@@ -9264,7 +9803,7 @@ registries: [
 
 ## Security model
 
-- **Per-environment scoping.** Every `tokenSecret` and `installEnv` entry is qualified with an environment name. The orchestrator runs the same protection-rule pipeline (branch / trust / concurrency / reviewer / wait-timer) against each named environment **before** resolving any secret, so a workflow that wants a `production` token from a feature branch is rejected exactly like a job that tries to deploy to `production` from a feature branch. A reviewer-gated install environment **pauses** the whole workflow dispatch as a workflow-scoped held run instead of resolving the token — see [Reviewer-gated installs](#reviewer-gated-installs) below.
+- **Per-environment scoping.** Every `tokenSecret` and `installEnv` entry is qualified with an environment name. The orchestrator runs the same protection-rule pipeline (branch / trust / concurrency / reviewer / wait-timer) against each named environment **before** resolving any secret, so a workflow that wants a `production` token from a feature branch is rejected exactly like a job that tries to deploy to `production` from a feature branch. A reviewer-gated install environment **pauses** the whole workflow dispatch as a workflow-scoped held run instead of resolving the token — see [Reviewer-gated installs](https://docs.kici.dev/user/private-registries/#reviewer-gated-installs) below.
 - **Untrusted contributors get no tokens.** When a fork PR is dispatched and the contributor-trust resolution returns anything other than `trusted`, the orchestrator strips both `npmRegistries` and `installEnvSecrets` out of the dispatch. The install runs without auth and fails naturally on the first private dep — fork PRs cannot ever observe a registry token, even if a misconfigured environment lacks an explicit `requiredTrustTier`.
 - **Lifecycle scripts disabled.** Whenever a private registry is in scope, the agent runs the install with `--ignore-scripts` (npm or pnpm alike). A malicious `preinstall` / `postinstall` hook in committed `package.json` cannot read the synthesized token env vars, even though they exist in the install subprocess. For a pnpm workspace, the agent builds your in-repo dependency closure as a separate step **after** the install's auth is torn down, so build scripts never see the tokens either.
 - **Stderr is redacted.** If the install fails, the agent masks every token literal out of the surfaced stderr / stdout chunks before logging.
@@ -9300,9 +9839,9 @@ The dashboard JSON lives at `infra/terraform/modules/grafana/dashboards/install-
 
 ## See also
 
-- [Secrets](secrets.md) — how to seed the `<environment>:<secret-name>` values referenced by `tokenSecret` / `installEnv`.
-- [Environments](environments.md) — protection rules (`branch_restrictions`, `requires_review`, `minimum_trust`) that the install gate inherits.
-- [Operator: `kici-admin org-settings`](/operator/kici-admin-cli#org-settings----org-level-security-policy) — the `allow_http_npm_registries` toggle and other org-scoped knobs.
+- [Secrets](https://docs.kici.dev/user/secrets/) — how to seed the `<environment>:<secret-name>` values referenced by `tokenSecret` / `installEnv`.
+- [Environments](https://docs.kici.dev/user/environments/) — protection rules (`branch_restrictions`, `requires_review`, `minimum_trust`) that the install gate inherits.
+- [Operator: `kici-admin org-settings`](https://docs.kici.dev/operator/kici-admin-cli#org-settings----org-level-security-policy) — the `allow_http_npm_registries` toggle and other org-scoped knobs.
 
 ---
 
@@ -9461,7 +10000,7 @@ kici verify-attestation ./dist/app.tgz \
   --trust-root ./kici-trust-root.json
 ```
 
-The full flag reference is in the [CLI reference](./cli-reference.md#kici-verify-attestation).
+The full flag reference is in the [CLI reference](https://docs.kici.dev/user/cli-reference/#kici-verify-attestation).
 
 ## Viewing attestations in the dashboard
 
@@ -9491,9 +10030,9 @@ attestations shows an empty state.
 
 ## See also
 
-- [SDK runtime reference](./sdk/runtime.md) — the `ctx.attestProvenance` and
+- [SDK runtime reference](https://docs.kici.dev/user/sdk/runtime/) — the `ctx.attestProvenance` and
   `ctx.kici.oidc.token` step APIs in full.
-- [CLI reference](./cli-reference.md#kici-verify-attestation) — every
+- [CLI reference](https://docs.kici.dev/user/cli-reference/#kici-verify-attestation) — every
   `kici verify-attestation` flag and exit code.
 
 ---
@@ -9506,7 +10045,7 @@ KiCI provides an explicit secrets API that gives workflow steps controlled acces
 
 ## Overview
 
-Secrets are managed per-environment in the orchestrator (see [operator docs](/operator/orchestrator/configuration) for setup). When a job runs with an `environment` binding, the agent receives the secret keys available for that environment but does **not** inject their values into the step's process environment. Instead, steps access secrets through the `ctx.secrets` API.
+Secrets are managed per-environment in the orchestrator (see [operator docs](https://docs.kici.dev/operator/orchestrator/configuration) for setup). When a job runs with an `environment` binding, the agent receives the secret keys available for that environment but does **not** inject their values into the step's process environment. Instead, steps access secrets through the `ctx.secrets` API.
 
 This design prevents accidental secret leakage through child processes, log output, or error messages. Only secrets you explicitly request are loaded into memory.
 
@@ -9525,7 +10064,7 @@ Use whichever fits the workflow — most small teams stay on the dashboard; ops
 
 ### When the operator has disabled dashboard writes
 
-The orchestrator operator can flip `secrets.set` (and `variables.set`) to **CLI-only** as part of the [dashboard-write policy](/operator/security/dashboard-write-policy). When that flip is on:
+The orchestrator operator can flip `secrets.set` (and `variables.set`) to **CLI-only** as part of the [dashboard-write policy](https://docs.kici.dev/operator/security/dashboard-write-policy). When that flip is on:
 
 - The dashboard's "Add secret" / "Edit value" controls render with a lock icon. Clicking them shows a tooltip with the exact `kici-admin secret set` invocation needed.
 - The dashboard's secrets page still lists secret **names**, scopes, and bindings — only the value-entry path moves to the CLI.
@@ -9562,7 +10101,7 @@ Two cross-cutting flags help every mode:
 
 `kici-admin variable set` uses the same flags for non-encrypted variables, plus `--locked` to mark a variable as immutable from subsequent dashboard writes.
 
-A full reference of input modes — including the default-mode resolution rules and the security trade-offs of each — lives in [Dashboard-write policy → CLI input modes](/operator/security/dashboard-write-policy#cli-input-modes-for-the-plaintext-path).
+A full reference of input modes — including the default-mode resolution rules and the security trade-offs of each — lives in [Dashboard-write policy → CLI input modes](https://docs.kici.dev/operator/security/dashboard-write-policy#cli-input-modes-for-the-plaintext-path).
 
 ## Accessing secrets
 
@@ -9720,7 +10259,7 @@ export default workflow('deploy', {
 
 ### Injecting decrypted sops values into the environment
 
-KiCI does **not** scan your repository for `*.enc.yaml` files and auto-decrypt them into the environment at job init — nothing in a job runs `sops` on your behalf, and resolved secrets are never auto-injected as environment variables (see [Security notes](./sdk/runtime.md#security-notes)). Decryption is always something your workflow does explicitly: provision the age (or other) decryption key as a KiCI secret, expose it for the step, run `sops -d`, and decide what to do with the output.
+KiCI does **not** scan your repository for `*.enc.yaml` files and auto-decrypt them into the environment at job init — nothing in a job runs `sops` on your behalf, and resolved secrets are never auto-injected as environment variables (see [Security notes](https://docs.kici.dev/user/sdk/runtime/#security-notes)). Decryption is always something your workflow does explicitly: provision the age (or other) decryption key as a KiCI secret, expose it for the step, run `sops -d`, and decide what to do with the output.
 
 When you want the decrypted values available as environment variables — not just written to a file — decrypt early and export the values through `$KICI_ENV` (or `ctx.setEnv`). Anything appended to `$KICI_ENV` becomes an environment variable for every later step in the same job, so a single decrypt step can populate the environment for the whole job:
 
@@ -9753,9 +10292,9 @@ export default workflow('deploy', {
 });
 ```
 
-Decrypted values exported this way follow the same rules as any other `$KICI_ENV` / `ctx.setEnv` export: last-write-wins on a repeated key, and a key that collides with an operator-injected secret is ignored (the operator value wins). See [Exporting env from shell commands](./sdk/runtime.md#exporting-env-from-shell-commands-kici_env--kici_path) for the full `$KICI_ENV` contract.
+Decrypted values exported this way follow the same rules as any other `$KICI_ENV` / `ctx.setEnv` export: last-write-wins on a repeated key, and a key that collides with an operator-injected secret is ignored (the operator value wins). See [Exporting env from shell commands](https://docs.kici.dev/user/sdk/runtime/#exporting-env-from-shell-commands-kici_env--kici_path) for the full `$KICI_ENV` contract.
 
-If you only need the decrypted material as a file on disk (the common `kubectl` / `gcloud` case), skip the env hop and redirect to a file instead — see the [canonical sops example](#canonical-sops-example) above.
+If you only need the decrypted material as a file on disk (the common `kubectl` / `gcloud` case), skip the env hop and redirect to a file instead — see the [canonical sops example](https://docs.kici.dev/user/secrets/#canonical-sops-example) above.
 
 ## API reference
 
@@ -9797,7 +10336,7 @@ Note that `get()` is async -- you must `await` the result.
 
 When you run `kici types`, the compiler generates a `.kici/secrets.d.ts` file that provides type-safe autocompletion for your secret keys. The generated types augment the `StepSecrets` interface so that `ctx.secrets.get('...')` and `ctx.secrets.has('...')` offer suggestions for known keys.
 
-See [CLI reference](/user/cli) for the `kici types` command.
+See [CLI reference](https://docs.kici.dev/user/cli) for the `kici types` command.
 
 ---
 
@@ -9812,11 +10351,11 @@ The **GitHub App** is KiCI's flagship source. A single App:
 1. receives `push`, `pull_request`, and related events from every repo it's installed on,
 2. clones repos with a short-lived installation token (no deploy key to manage),
 3. posts workflow / job / step Check runs back to the pull request (see
-   [GitHub checks architecture](../../architecture/webhooks/github-checks.md)).
+   [GitHub checks architecture](https://docs.kici.dev/architecture/webhooks/github-checks/)).
 
 You don't need an App for every scenario — if you only care about `push`
 events, don't want to install an App, or are using a non-GitHub forge,
-use the [universal-git provider](universal-git.md) instead.
+use the [universal-git provider](https://docs.kici.dev/user/providers/universal-git/) instead.
 
 ## GitHub App vs. `github-repo` preset
 
@@ -9886,11 +10425,12 @@ GitHub App "my-org" is live.
 
 **Flags:**
 
-| Flag                  | Effect                                                                                                                                                                                                              |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--name <name>`       | The App name on GitHub (required).                                                                                                                                                                                  |
-| `--github-org <slug>` | Create the App under a GitHub organization instead of your personal account.                                                                                                                                        |
-| `--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. |
+| 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](https://docs.kici.dev/user/providers/github/#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](https://docs.kici.dev/user/providers/github/#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
@@ -9952,7 +10492,7 @@ the manifest flow — follow these steps.
 
    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](../../architecture/security/ci-security.md)
+   you use [CI trust tiers](https://docs.kici.dev/architecture/security/ci-security/)
    on an org-level install — see the event note below.
 
 6. **Subscribe to events.** At minimum: `push`, `pull_request`,
@@ -9964,7 +10504,7 @@ the manifest flow — follow these steps.
    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](../../architecture/security/ci-security.md)). These
+   [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
@@ -10035,7 +10575,7 @@ kici-admin source get-webhook-secret github:12345  # Fetch the secret (for debug
 ```
 
 For the full CLI reference see the `source` section of the
-[kici-admin CLI reference](../../operator/orchestrator/kici-admin-cli.md).
+[kici-admin CLI reference](https://docs.kici.dev/operator/orchestrator/kici-admin-cli/).
 
 ## Routing keys
 
@@ -10054,6 +10594,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
@@ -10083,7 +10670,7 @@ kici-admin org-settings global-workflows deny-add 'my-org/contrib/*' \
 Global workflows authored in a GitHub App repo can dispatch against
 events from universal-git sources in the same org, and vice versa,
 with each clone using its own source's credentials. See
-[Global workflows](../../architecture/global-workflows.md) for the
+[Global workflows](https://docs.kici.dev/architecture/global-workflows/) for the
 policy model and cross-source dispatch contract.
 
 ## Check runs
@@ -10101,7 +10688,7 @@ configuration is required beyond installing the App with the
 `checks: write` permission.
 
 For architecture details see
-[GitHub checks architecture](../../architecture/webhooks/github-checks.md).
+[GitHub checks architecture](https://docs.kici.dev/architecture/webhooks/github-checks/).
 
 ## Rotation
 
@@ -10184,12 +10771,12 @@ and confirm the App is installed on that repo.
 
 ## See also
 
-- [Universal-git provider](universal-git.md) — for Forgejo / Gitea /
+- [Universal-git provider](https://docs.kici.dev/user/providers/universal-git/) — for Forgejo / Gitea /
   Gogs / GitLab, and for plain-GitHub repos without an App
-- [GitHub checks architecture](../../architecture/webhooks/github-checks.md)
-- [Global workflows](../../architecture/global-workflows.md)
-- [kici-admin CLI reference](../../operator/orchestrator/kici-admin-cli.md)
-- [Event routing](../../operator/event-routing.md) — operator-level
+- [GitHub checks architecture](https://docs.kici.dev/architecture/webhooks/github-checks/)
+- [Global workflows](https://docs.kici.dev/architecture/global-workflows/)
+- [kici-admin CLI reference](https://docs.kici.dev/operator/orchestrator/kici-admin-cli/)
+- [Event routing](https://docs.kici.dev/operator/event-routing/) — operator-level
   routing-key mechanics
 
 ---
@@ -10208,8 +10795,8 @@ from GitHub or GitLab; the operator drives runs explicitly with the
 > globally-registered or policy workflows the operator controls — a vendored
 > repo baked into an agent image, a repo synced onto a host out-of-band, a
 > golden internal pipeline. For ordinary per-developer CI driven by pull
-> requests and pushes, use the [GitHub App provider](./github.md) or the
-> [universal-git provider](./universal-git.md) against a real forge.
+> requests and pushes, use the [GitHub App provider](https://docs.kici.dev/user/providers/github/) or the
+> [universal-git provider](https://docs.kici.dev/user/providers/universal-git/) against a real forge.
 
 ## Trust caveat (read first)
 
@@ -10304,9 +10891,9 @@ the run is created and then fails, rather than being silently dropped.
 
 ## See also
 
-- [Universal-git provider](./universal-git.md) — for a remote forge (or any
+- [Universal-git provider](https://docs.kici.dev/user/providers/universal-git/) — for a remote forge (or any
   `http://` git server) when there is no shared filesystem.
-- [GitHub App provider](./github.md) — the flagship source for pull-request
+- [GitHub App provider](https://docs.kici.dev/user/providers/github/) — the flagship source for pull-request
   CI with Checks.
 
 ---
@@ -10321,7 +10908,7 @@ Gitea, Gogs, GitLab, plain GitHub (without the App), and any custom
 webhook-driven forge you can describe in JSONPath.
 
 > **Want Check runs on pull requests?** Use the [GitHub App
-> provider](github.md) instead — it clones via short-lived installation
+> provider](https://docs.kici.dev/user/providers/github/) instead — it clones via short-lived installation
 > tokens and drives KiCI's enriched Checks UI out of the box. The
 > universal-git `github-repo` preset is the right fallback when you
 > can't install an App.
@@ -10341,7 +10928,7 @@ that back the GitHub App source also serve universal-git sources.
 > the right choice for the **remote-agent** case — point it at an `http://`
 > git server and the agent clones over the network. When the repo instead
 > lives on the agent's own filesystem (a vendored / operator-curated repo),
-> use a [local `file://` source](./local-file.md) and drive it with the
+> use a [local `file://` source](https://docs.kici.dev/user/providers/local-file/) and drive it with the
 > `kici-admin` CLI.
 
 ## Which preset do I need?
@@ -10515,7 +11102,7 @@ kici-admin org-settings global-workflows deny-add \
   --source "generic:<orgId>:<sourceId>"
 ```
 
-See [Global workflows](../../architecture/global-workflows.md) for the
+See [Global workflows](https://docs.kici.dev/architecture/global-workflows/) for the
 policy model (`isWorkflowRepoAllowed` + `isSourceRepoAllowed` +
 `isElevatedAccessAllowed`) and the cross-provider dispatch contract.
 
@@ -10559,6 +11146,374 @@ with the right PEM.
 
 # Architecture overview
 
+## Configuration architecture
+
+Source: https://docs.kici.dev/architecture/configuration/
+
+This document describes the internal design of the orchestrator's configuration management system. For operator-facing documentation, see [Configuration Reference](https://docs.kici.dev/operator/orchestrator/configuration/) and [Config Management Guide](https://docs.kici.dev/operator/orchestrator/config-management/).
+
+## Config type system
+
+The configuration is modeled as three distinct types that merge into a final application config:
+
+### LocalConfig
+
+Per-orchestrator settings loaded from a YAML file. These are instance-specific and never shared:
+
+```typescript
+interface LocalConfig {
+  database: { url: string };
+  instance?: { id?: string; mode?: 'platform' | 'hybrid' | 'independent' };
+  server?: { port?: number; basePath?: string; logLevel?: string };
+  scaler?: { configPath?: string; configDir?: string };
+}
+```
+
+**Key property:** Every field except `database.url` is optional. An orchestrator can run entirely from env vars with no YAML file.
+
+### SharedConfig
+
+Shared settings stored in the PostgreSQL `config_versions` table. Defined once, shared across all instances:
+
+```typescript
+interface SharedConfig {
+  platform?: { url?: string; token?: string };
+  storage?: { type?: 's3'; bucket?: string; ... };
+  agentAuth?: 'token' | 'none';
+  agentTokenTtlMs?: number;
+  queue?: { maxDepth?: number; timeoutMs?: number };
+  lockfileCache?: { max?: number; ttlMs?: number };
+  staleDetector?: { scanIntervalMs?: number; ... };
+  secrets?: { key?: string; keyFile?: string; bootstrapAdminToken?: string };
+  pgCustomerSecrets?: boolean;
+  cluster?: { joinToken?: string; raftElectionTimeoutMinMs?: number; ... };
+  // ... tuning fields
+}
+```
+
+**Key property:** All top-level fields are optional. The DB may store a partial config.
+
+### AppConfig
+
+The merged result type used throughout the codebase. Combines `LocalConfig` + `SharedConfig` with resolved defaults:
+
+```typescript
+interface AppConfig {
+  instanceId: string; // From local config or auto-generated
+  mode: 'platform' | 'hybrid' | 'independent';
+  databaseUrl: string; // Flattened from database.url
+  port: number; // Flattened from server.port
+  basePath: string;
+  platformUrl?: string; // Flattened from platform.url
+  platformToken?: string;
+  agentAuth: 'token' | 'none'; // With defaults applied
+  queueMaxDepth: number; // Flattened from queue.maxDepth
+  cluster: { instanceId: string; credentialFile: string; autoRotateCredentials: boolean; peers: string[]; ... };
+  // ... all other fields with defaults
+}
+```
+
+**Key property:** `AppConfig` uses flat field names (e.g., `databaseUrl` instead of `database.url`) for backward compatibility with the existing codebase. A `flattenToAppConfig()` function handles the mapping.
+
+### How they merge
+
+```
+defaults (getDefaults())
+    |
+    v
+SharedConfig (from DB)        ──deepMerge──>  merged layer 1+2
+    |
+    v
+LocalConfig (from YAML)       ──deepMerge──>  merged layer 1+2+3
+    |
+    v
+Env var overrides              ──apply──>      merged layer 1+2+3+4
+    |
+    v
+flattenToAppConfig()           ──flatten──>    flat AppConfig shape
+    |
+    v
+appConfigSchema.safeParse()    ──validate──>   typed AppConfig
+```
+
+The `deepMerge` function merges objects recursively, replaces arrays (does not merge item-by-item), and skips `undefined`/`null` source values (they do not override existing values).
+
+## Resolution chain
+
+### Two-phase design
+
+```
+Phase 1 (local-only):
+  YAML file + KICI_ env vars
+      |
+      v
+  resolveLocalConfig() -> { databaseUrl, instanceId, port, mode }
+      |
+      v
+  Connect to PostgreSQL
+      |
+      v
+Phase 2 (full merge):
+  defaults -> DB -> YAML -> env
+      |
+      v
+  resolveFullConfig() -> AppConfig
+```
+
+**Why two phases?** The database URL must come from local config (YAML or env var) because we need it to connect to PostgreSQL. But the shared config is stored in PostgreSQL. This circular dependency is broken by resolving local config first (Phase 1), connecting to the DB, then doing the full merge (Phase 2).
+
+### Env var processing
+
+Environment variables are processed in two stages:
+
+1. **Direct mappings:** `KICI_DATABASE_URL` -> `database.url`, etc. A lookup table in `env-overlay.ts` maps known env var suffixes to config path arrays.
+
+2. **Multi-app GitHub provider:** `KICI_PROVIDERS_GITHUB_<APP_NAME>_<FIELD>` is parsed by stripping the `PROVIDERS_GITHUB_` prefix, finding the field suffix (`APP_ID`, `PRIVATE_KEY`, `WEBHOOK_SECRET`), and deriving the app name from the middle segment. App names are lowercased with underscores converted to hyphens (`MAIN_ORG` -> `main-org`).
+
+Type coercion is applied based on known field types: numeric fields are parsed as numbers, boolean fields are compared against `"true"`, all others remain strings.
+
+## Two-phase bootstrap
+
+```
+┌─────────────────┐
+│  Process Start   │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  Load YAML +    │  resolveLocalConfig()
+│  Env Overrides  │  -> databaseUrl, instanceId, port, mode
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  Connect to     │  PostgreSQL
+│  Database       │  Run migrations
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  Load Shared    │  SharedConfigStore.getLatest()
+│  Config from DB │  -> decrypt -> SharedConfig
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  Full Merge     │  resolveFullConfig(local, db, env)
+│  + Validate     │  -> AppConfig
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  Start Server   │  HTTP, WS, scaler, cluster
+└─────────────────┘
+```
+
+## DB schema
+
+### config_versions table
+
+```sql
+CREATE TABLE config_versions (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  version SERIAL NOT NULL UNIQUE,
+  config JSONB NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  created_by TEXT NOT NULL,
+  description TEXT,
+  encrypted_paths TEXT[] NOT NULL DEFAULT '{}'
+);
+
+CREATE INDEX idx_config_versions_version ON config_versions(version DESC);
+CREATE INDEX idx_config_versions_created_at ON config_versions(created_at DESC);
+```
+
+**Design choices:**
+
+- **SERIAL version:** Auto-incrementing integer provides a total ordering of config changes. Simple to compare in heartbeats.
+- **JSONB config:** Stores the full shared config document. JSONB allows future querying/indexing if needed, though we always read the full document.
+- **Immutable rows:** Each change creates a new version. Old versions are never modified, providing a full audit trail.
+- **encrypted_paths:** Array of concrete dot-separated paths (e.g., `platform.token`, `cluster.joinToken`) that contain encrypted values. Stored alongside the config so the system knows exactly which fields to decrypt without runtime path list dependency.
+- **created_by:** Identifies the source of the change (e.g., `cli:seed`, `api:set`, `api:rollback`).
+
+### Versioning strategy
+
+- Version numbers are auto-incrementing integers managed by PostgreSQL SERIAL
+- Rollback creates a new version (copy of target) rather than reverting to the old version number
+- Example: versions 1, 2, 3 exist. Rollback to 1 creates version 4 with the content of version 1
+- This preserves the audit trail: version 4 records when and why the rollback happened
+
+## Encryption
+
+### Algorithm
+
+AES-256-GCM via the existing `secrets/crypto.ts` module:
+
+- **Key:** 32-byte AES-256 key derived from the master key (`KICI_SECRET_KEY`)
+- **IV:** Random 12-byte initialization vector per encryption
+- **Auth tag:** 16-byte GCM authentication tag
+- **AAD:** `config-field:<path>` (e.g., `config-field:platform.token`) -- binds ciphertext to its specific location
+- **Wire format:** base64(IV || AuthTag || Ciphertext)
+- **Key version:** Integer stamp for the master-key generation that sealed the row. Every new row is written under the active generation (hydrated from `MAX(key_version)` at startup). `kici-admin rotate-key` bumps the stamp atomically — the decrypt path accepts the current generation, and during the grace window also the previous one (`KICI_SECRET_KEY_OLD`), so historical rows and rollbacks continue to work seamlessly across rotations.
+
+### Sensitive field paths
+
+The following glob patterns define sensitive fields:
+
+```typescript
+const SENSITIVE_FIELD_PATHS = [
+  'platform.token',
+  'secrets.key',
+  'secrets.bootstrapAdminToken',
+  'cluster.joinToken',
+] as const;
+```
+
+### Encryption flow
+
+```
+Save:
+  config -> resolveGlobPaths(SENSITIVE_FIELD_PATHS)
+         -> for each concrete path: encrypt(value, key, "config-field:<path>")
+         -> store { encrypted_config, encrypted_paths[] }
+
+Load:
+  row -> for each path in encrypted_paths: decrypt(value, key, "config-field:<path>")
+      -> SharedConfig
+
+Export (redacted):
+  row -> decrypt (if master key available) -> replace encrypted_paths values with "***REDACTED***"
+```
+
+### Rollback optimization
+
+When rolling back, the target version's encrypted config is copied as-is to the new version. No re-encryption is needed because:
+
+- The same master key applies (all orchestrators share the same key)
+- The same AAD applies (paths are identical)
+- The `encrypted_paths` array is preserved from the target version
+
+## Hot-Reload
+
+### ConfigReloader design
+
+The `ConfigReloader` class manages the full reload lifecycle:
+
+```mermaid
+flowchart TD
+    SIGHUP["SIGHUP (signal)"] --> trigger
+    HTTP["HTTP POST /reload"] --> trigger
+    Cluster["Cluster auto-fix"] --> trigger["triggerReload()<br/>500ms debounce"]
+
+    trigger --> execute["executeReload()<br/>boolean mutex"]
+
+    execute --> resolveLocal["resolveLocalConfig()"]
+    execute --> getLatest["getLatest (DB)"]
+    execute --> resolveFull["resolveFullConfig()<br/>(merge + validate)"]
+
+    resolveLocal --> check["Check restart-required fields"]
+    getLatest --> check
+    resolveFull --> check
+
+    check --> swap["Atomic swap<br/>onConfigApplied()"]
+
+    swap --> onProvider["onProviderChange (if changed)"]
+    swap --> onScaler["onScalerReload (always)"]
+    swap --> onPlatform["onPlatformReconnect (if changed)"]
+```
+
+### Safety guarantees
+
+- **Mutex:** Boolean flag prevents concurrent reloads. Second reload returns `{ success: false, errors: ["Reload already in progress"] }`.
+- **Debounce:** Rapid triggers (e.g., multiple SIGHUP signals) are collapsed into a single reload with a 500ms window.
+- **Validation before swap:** The new config must pass full schema validation. On failure, the old config is preserved and an error is logged.
+- **Restart-required detection:** Fields like `databaseUrl`, `port`, `instanceId` are compared. If changed, the old values are preserved in the applied config and a warning is logged.
+- **No crash on failure:** The orchestrator always keeps running with the old config if anything goes wrong during reload.
+
+### Subsystem callbacks
+
+The `ConfigReloader` uses a dependency injection pattern with callbacks for subsystem re-initialization:
+
+| Callback              | When Called                   | Purpose                                                                                      |
+| --------------------- | ----------------------------- | -------------------------------------------------------------------------------------------- |
+| `onProviderChange`    | Provider config changed       | Reserved callback (providers are now DB-managed via sources table; currently always a no-op) |
+| `onScalerReload`      | Always on successful reload   | Reload scaler YAML config                                                                    |
+| `onPlatformReconnect` | Platform URL or token changed | Reconnect WS to Platform relay                                                               |
+| `onConfigApplied`     | Always on successful reload   | Atomic config reference swap, increment local config version                                 |
+
+### Prometheus metrics
+
+| Metric                          | Type    | Labels                                                                  | Description                           |
+| ------------------------------- | ------- | ----------------------------------------------------------------------- | ------------------------------------- |
+| `kici_orch_config_reload_total` | Counter | `result` (attempted/success/failed), `source` (sighup/http/cluster/cli) | Config reload attempts and outcomes   |
+| `kici_orch_config_version`      | Gauge   | --                                                                      | Current shared config version from DB |
+
+## Multi-Provider
+
+### ProviderRegistry
+
+The `ProviderRegistry` maps routing keys to provider bundles. Each routing key (e.g., `github:12345`) is associated with a `ProviderBundle` containing:
+
+- `WebhookNormalizer` -- normalizes incoming webhooks to a standard format
+- `LockFileFetcher` -- fetches lock files from the repository
+- `ChangedFilesFetcher` -- determines which files changed
+- `CloneTokenProvider` -- generates clone tokens for agents
+- `RepoUrlBuilder` -- builds clone URLs and raw file URLs
+- `ContributorResolver` -- resolves contributor permissions for trust-tier gating
+- `CheckStatusPoster` -- posts check statuses (approval/hold) to the git provider
+
+Provider registrations are managed via the `sources` database table, not via `SharedConfig`. When the orchestrator connects to the Platform relay, it reads source records from the DB and sends `source.register` messages. Changes to sources (add/remove) are detected via PostgreSQL LISTEN/NOTIFY on the `sources_change` channel and pushed to the Platform via `source.secrets` and `source.register`/`source.deregister`.
+
+### Per-App Credentials
+
+Each source record contains its own `appId` and `privateKey` (stored as scoped secrets). When processing a webhook, the orchestrator looks up the routing key to find the matching source and uses its credentials for JWT generation, clone tokens, and check run updates.
+
+## Cluster sync
+
+### Heartbeat config version
+
+In clustered deployments, each orchestrator includes its current config version in Raft heartbeat metadata via the `configVersion` optional field on the `peerHeartbeatSchema`.
+
+When the `PeerRegistry` processes a heartbeat:
+
+1. Compare `localConfigVersion` with `peer.configVersion`
+2. If `peer.configVersion > localConfigVersion` AND both are > 0:
+   - Invoke the `onConfigVersionBehind` callback
+   - This triggers a config reload from the database
+
+### Auto-remediation flow
+
+```
+Orchestrator A (version 5)          Orchestrator B (version 3)
+         │                                     │
+         │──── heartbeat(configVersion=5) ────>│
+         │                                     │
+         │                           compare: 5 > 3
+         │                           trigger reload from DB
+         │                                     │
+         │                           resolveFullConfig()
+         │                           -> version 5
+         │                                     │
+         │<── heartbeat(configVersion=5) ──────│
+         │                                     │
+         │   both at version 5 ✓               │
+```
+
+### Guard conditions
+
+- Version comparison only triggers when **both** local and peer versions are > 0
+- This prevents false triggers from:
+  - Legacy orchestrators that do not report `configVersion` (field is optional, defaults to 0)
+  - Newly started orchestrators before their first config load
+- The `localConfigVersion` is a monotonically incrementing local counter (incremented on each successful reload)
+
+## See also
+
+- [Configuration Reference](https://docs.kici.dev/operator/orchestrator/configuration/) -- operator guide
+- [Config Management Guide](https://docs.kici.dev/operator/orchestrator/config-management/) -- CLI and API guide
+
+---
+
 ## Data flows
 
 Source: https://docs.kici.dev/architecture/data-flows/
@@ -10596,7 +11551,7 @@ GitHub  -->  Platform Relay  -->  Orchestrator  -->  Agent
 15. **Orchestrator matches triggers** against lock file using `matchAllWorkflows()` from `@kici-dev/engine`.
 16. **Orchestrator checks caches** for source tarballs and dependency tarballs.
 17. **Orchestrator dispatches jobs** to agents via the job queue and WebSocket.
-18. **Orchestrator persists a delivery row** keyed by `(org_id, delivery_id)` to its own `event_log`, including a pointer to the gzipped payload in object storage. The orchestrator's delivery log is surfaced in the dashboard's Settings → Event log tab. See [`webhook-delivery.md`](./webhooks/webhook-delivery.md#delivery-log).
+18. **Orchestrator persists a delivery row** keyed by `(org_id, delivery_id)` to its own `event_log`, including a pointer to the gzipped payload in object storage. The orchestrator's delivery log is surfaced in the dashboard's Settings → Event log tab. See [`webhook-delivery.md`](https://docs.kici.dev/architecture/webhooks/webhook-delivery/#delivery-log).
 
 ## Job execution flow
 
@@ -10624,7 +11579,7 @@ Orchestrator                         Agent                    Sandbox (child pro
 
 ### Agent pipeline
 
-The agent delegates job execution to an `ExecutionSandbox` (container, bare-metal, or firecracker). The sandbox runs customer code in an isolated child process -- never in the agent's V8 isolate. Four job types are handled: execution jobs (sandbox), build-only jobs (in-process, cache population), init-only jobs (in-process, dynamic field resolution), and DynamicJobFn evaluation jobs (in-process, runtime job generation). See [Job execution lifecycle](./execution/job-execution.md) for details.
+The agent delegates job execution to an `ExecutionSandbox` (container, bare-metal, or firecracker). The sandbox runs customer code in an isolated child process -- never in the agent's V8 isolate. Four job types are handled: execution jobs (sandbox), build-only jobs (in-process, cache population), init-only jobs (in-process, dynamic field resolution), and DynamicJobFn evaluation jobs (in-process, runtime job generation). See [Job execution lifecycle](https://docs.kici.dev/architecture/execution/job-execution/) for details.
 
 1. **Report running** -- Send `job.status: running` immediately upon accepting the dispatch
 2. **Sandbox selection** -- Determine execution mode (container, bare-metal, firecracker) from job config and environment
@@ -10662,7 +11617,7 @@ Run initiation (`upload-init`), the trigger, status polling, log retrieval, and
 
 ### Data plane
 
-The working-tree overlay tarball uploads **directly** from the developer machine to the orchestrator's object store via a pre-signed PUT URL minted during `upload-init`. The overlay bytes never pass through the Platform. Because of this split, only the object store needs to be reachable from the developer machine — the orchestrator can sit behind a private network. See [Storage layout](../operator/orchestrator/storage-layout.md) for the upload-endpoint configuration.
+The working-tree overlay tarball uploads **directly** from the developer machine to the orchestrator's object store via a pre-signed PUT URL minted during `upload-init`. The overlay bytes never pass through the Platform. Because of this split, only the object store needs to be reachable from the developer machine — the orchestrator can sit behind a private network. See [Storage layout](https://docs.kici.dev/operator/orchestrator/storage-layout/) for the upload-endpoint configuration.
 
 ### Org anchor
 
@@ -10785,7 +11740,7 @@ If cache storage is unavailable or a download fails:
 - **Source tarball download failure:** Hard failure today — the agent does not fall back to `git clone` on the execution path. (The build path is where cloning happens.) In practice this is rare because the same orchestrator that issued the pre-signed URL controls the cache backend.
 - **Dep tarball download failure:** Agent falls back to running `npm ci` / `npm install` inline.
 - **Dep tarball hash mismatch:** Agent retries the download twice (3 total attempts), then fails the job (no fallback for integrity failures).
-- **Source tarball drift (extracted `contentHash` ≠ lock file):** Hard failure with "Lock file is out of date: workflow source changed without regenerating kici.lock.json" — see [Lock file and drift](../user/lock-file-and-drift.md).
+- **Source tarball drift (extracted `contentHash` ≠ lock file):** Hard failure with "Lock file is out of date: workflow source changed without regenerating kici.lock.json" — see [Lock file and drift](https://docs.kici.dev/user/lock-file-and-drift/).
 - **Build failure:** Execution is skipped entirely with a "Build failed" check status. Workflows that contain dynamic job entries (DynamicJobFn) are allowed to proceed with their dynamic eval jobs since those compile from source.
 - **No cache configured:** Agent runs inline install for every job (pre-caching behavior).
 
@@ -10817,9 +11772,9 @@ The orchestrator derives the target platform/arch for dep cache lookups by probi
 
 ### TTL and eviction (touch-on-read)
 
-Both caches refresh TTL on read via `touch-on-read`. An entry's lifetime is reset every time an orchestrator issues a pre-signed GET URL for it. Default TTL is `KICI_CACHE_TTL_DAYS=30`; entries unused for 30 days expire at the storage level. Actively used sources and deps stay in cache indefinitely as long as they continue to be referenced by inbound webhooks or reruns. See [`docs/operator/dependency-caching.md`](../operator/dependency-caching.md#cache-behavior) for configuration.
+Both caches refresh TTL on read via `touch-on-read`. An entry's lifetime is reset every time an orchestrator issues a pre-signed GET URL for it. Default TTL is `KICI_CACHE_TTL_DAYS=30`; entries unused for 30 days expire at the storage level. Actively used sources and deps stay in cache indefinitely as long as they continue to be referenced by inbound webhooks or reruns. See [`docs/operator/dependency-caching.md`](https://docs.kici.dev/operator/dependency-caching/#cache-behavior) for configuration.
 
-For the full per-package bucket and prefix inventory — cache, logs, cold-store, and the observability sidecar buckets — see [orchestrator storage layout](../operator/orchestrator/storage-layout.md).
+For the full per-package bucket and prefix inventory — cache, logs, cold-store, and the observability sidecar buckets — see [orchestrator storage layout](https://docs.kici.dev/operator/orchestrator/storage-layout/).
 
 ### Pre-signed URL upload flow
 
@@ -10857,7 +11812,7 @@ Agents receive pre-signed S3 GET URLs (15-minute expiry) directly in `job.dispat
 
 ## User-facing cache flow
 
-The source/dep cache above is internal: the orchestrator owns its keys and decides when to hit or build. The **user-facing cache** is driven by the workflow author — the declarative `cache: { key, paths, restoreKeys? }` on a job/step, or the imperative `ctx.cache.restore()` / `ctx.cache.save()` API (see [SDK caching reference](../user/sdk/caching.md)). It reuses the same object-storage backend and the same direct-to-storage presigned-URL transport, but the agent — not the orchestrator — initiates each restore and save over WebSocket.
+The source/dep cache above is internal: the orchestrator owns its keys and decides when to hit or build. The **user-facing cache** is driven by the workflow author — the declarative `cache: { key, paths, restoreKeys? }` on a job/step, or the imperative `ctx.cache.restore()` / `ctx.cache.save()` API (see [SDK caching reference](https://docs.kici.dev/user/sdk/caching/)). It reuses the same object-storage backend and the same direct-to-storage presigned-URL transport, but the agent — not the orchestrator — initiates each restore and save over WebSocket.
 
 The agent's cache module archives `paths` into a gzipped tarball (computing a SHA-256 over the bytes) and streams downloads back through a checksum-verified extract pipeline. The orchestrator's `UserCache` owns the `cache/<orgId>/<repoId>/<scope>/<key>` namespacing, the immutable first-save check, the `restoreKeys` prefix scan, the two-phase atomic save, and per-org quota/TTL eviction.
 
@@ -10911,7 +11866,7 @@ The save is **immutable** and **atomic**. The orchestrator declines (`skip: true
 
 ### Trust → scope mapping
 
-The orchestrator threads a `cacheRefScope` onto each `job.dispatch`. A **trusted** ref (the repo's own branches, default branch) maps to the `shared` write scope; any other ref (a fork PR) maps to `isolated`, writing to a per-run `iso/<runId>/` scope. This is the cache-isolation model: a fork can restore from the trusted `shared/` cache but can never write into it, so it cannot poison the entries a trusted branch later restores. The org segment of the key namespace (`cache/<orgId>/`) is the per-tenant boundary — no tenant can read another tenant's cache. See [orchestrator storage layout](../operator/orchestrator/storage-layout.md#user-cache) for the full prefix map and quota/TTL knobs.
+The orchestrator threads a `cacheRefScope` onto each `job.dispatch`. A **trusted** ref (the repo's own branches, default branch) maps to the `shared` write scope; any other ref (a fork PR) maps to `isolated`, writing to a per-run `iso/<runId>/` scope. This is the cache-isolation model: a fork can restore from the trusted `shared/` cache but can never write into it, so it cannot poison the entries a trusted branch later restores. The org segment of the key namespace (`cache/<orgId>/`) is the per-tenant boundary — no tenant can read another tenant's cache. See [orchestrator storage layout](https://docs.kici.dev/operator/orchestrator/storage-layout/#user-cache) for the full prefix map and quota/TTL knobs.
 
 ## Internal event routing flow
 
@@ -11405,15 +12360,15 @@ The Platform tier exposes a `/ws/browser` WebSocket endpoint for dashboard clien
 
 ## See also
 
-- [Architecture overview](overview.md) -- three-tier model and component responsibilities
-- [Protocol messages](protocol-messages.md) -- WebSocket message schemas
-- [Event system internals](./webhooks/event-system.md) -- event router, registration model, cron scheduler
-- [State machine](./execution/state-machine.md) -- job execution state transitions
-- [Webhook delivery](./webhooks/webhook-delivery.md) -- detailed webhook processing pipeline
-- [Operator: dependency caching](../operator/dependency-caching.md) -- configuration guide
-- [Operator: monitoring & tracing](../operator/observability/monitoring.md) -- trace fields and Loki queries
-- [Operator: event routing & generic webhooks](../operator/event-routing.md) -- generic source setup and trust management
-- [SDK reference: output chaining](../user/sdk/core.md#output-chaining) -- user-facing output chaining API
+- [Architecture overview](https://docs.kici.dev/architecture/overview/) -- three-tier model and component responsibilities
+- [Protocol messages](https://docs.kici.dev/architecture/protocol-messages/) -- WebSocket message schemas
+- [Event system internals](https://docs.kici.dev/architecture/webhooks/event-system/) -- event router, registration model, cron scheduler
+- [State machine](https://docs.kici.dev/architecture/execution/state-machine/) -- job execution state transitions
+- [Webhook delivery](https://docs.kici.dev/architecture/webhooks/webhook-delivery/) -- detailed webhook processing pipeline
+- [Operator: dependency caching](https://docs.kici.dev/operator/dependency-caching/) -- configuration guide
+- [Operator: monitoring & tracing](https://docs.kici.dev/operator/observability/monitoring/) -- trace fields and Loki queries
+- [Operator: event routing & generic webhooks](https://docs.kici.dev/operator/event-routing/) -- generic source setup and trust management
+- [SDK reference: output chaining](https://docs.kici.dev/user/sdk/core/#output-chaining) -- user-facing output chaining API
 
 ---
 
@@ -11468,7 +12423,7 @@ The orchestrator is the execution brain. It decides what to run and dispatches w
 - **Agent registry** -- Tracks connected agents with label-based routing for job dispatch.
 - **Job queue** -- PostgreSQL-backed FIFO queue for reliable dispatch.
 - **Webhook pipeline** -- Dedup, event mapping, lock file fetch, trigger matching, and job dispatch in a single pipeline.
-- **Multi-orchestrator clustering** -- Optional peer-to-peer coordination via direct WebSocket connections. Enables cross-architecture job routing (e.g., x64 coordinator reroutes arm64 jobs to a peer), high availability, and dedicated coordinator topologies. Uses Raft consensus for leader election (orphan recovery). See [Multi-Orchestrator Architecture](./clustering/multi-orchestrator.md).
+- **Multi-orchestrator clustering** -- Optional peer-to-peer coordination via direct WebSocket connections. Enables cross-architecture job routing (e.g., x64 coordinator reroutes arm64 jobs to a peer), high availability, and dedicated coordinator topologies. Uses Raft consensus for leader election (orphan recovery). See [Multi-Orchestrator Architecture](https://docs.kici.dev/architecture/clustering/multi-orchestrator/).
 - **Auto-scaler** -- Optional pluggable module for ephemeral agent provisioning. Supports containers (Docker/Podman), bare-metal processes, and Firecracker microVMs as backends. Spawns agents on demand when no matching agent is connected, with label-based routing, two-level capacity limits (global + per-backend), warm pools, YAML configuration (`scalers.d/` directory support), and SIGHUP reload. Disabled by default -- orchestrator works without it.
 - **Independent database** -- Has its own PostgreSQL database separate from the Platform. Stores execution runs/jobs/steps, dispatch queue, webhook secrets, dedup cache, and scaler state. The orchestrator's `execution_runs` and `execution_jobs` are the authoritative source of truth. The Platform receives execution status updates via WebSocket messages (`execution.status`, `job.status.forward`).
 
@@ -11607,13 +12562,13 @@ The orchestrator connects outbound to the Platform WebSocket endpoint. After aut
 
 When multiple orchestrators are deployed, they establish direct WebSocket connections to each other on the `/ws/peer` endpoint. Peers are discovered via the Platform matchmaker (Platform/hybrid modes) or static configuration (`KICI_CLUSTER_PEERS` env var, independent mode). Connections are authenticated with a mutual pre-shared key (PSK). Traffic includes agent inventory heartbeats, job rerouting, progress reporting, cancel propagation, and Raft leader election. These messages never transit the Platform tier.
 
-> See [Multi-Orchestrator Architecture](./clustering/multi-orchestrator.md) for clustering details and [Protocol Messages](protocol/dashboard.md#orchestrator-orchestrator-messages-peer-to-peer) for message schemas.
+> See [Multi-Orchestrator Architecture](https://docs.kici.dev/architecture/clustering/multi-orchestrator/) for clustering details and [Protocol Messages](https://docs.kici.dev/architecture/protocol/dashboard/#orchestrator-orchestrator-messages-peer-to-peer) for message schemas.
 
 ### Orchestrator ↔ Agent
 
 The agent connects outbound to the orchestrator WebSocket endpoint. After registration (agent ID, labels, concurrency), the connection is used for job dispatch, status reporting, and log streaming.
 
-> See [Protocol Messages](protocol-messages.md) and [Webhook Delivery](./webhooks/webhook-delivery.md) for detailed message flows and schemas.
+> See [Protocol Messages](https://docs.kici.dev/architecture/protocol-messages/) and [Webhook Delivery](https://docs.kici.dev/architecture/webhooks/webhook-delivery/) for detailed message flows and schemas.
 
 ## Authentication and multi-tenancy
 
@@ -11621,9 +12576,9 @@ KiCI uses application-level tenant isolation. The Platform dashboard API accepts
 
 ## See also
 
-- [Multi-Orchestrator Architecture](./clustering/multi-orchestrator.md) -- P2P clustering, Raft consensus, job rerouting
-- [State Machine](./execution/state-machine.md) -- execution lifecycle tracking across all tiers
-- [Protocol Messages](protocol-messages.md) -- WebSocket message schemas for all three layers
-- [Webhook Delivery](./webhooks/webhook-delivery.md) -- end-to-end trace of a webhook through all three tiers
+- [Multi-Orchestrator Architecture](https://docs.kici.dev/architecture/clustering/multi-orchestrator/) -- P2P clustering, Raft consensus, job rerouting
+- [State Machine](https://docs.kici.dev/architecture/execution/state-machine/) -- execution lifecycle tracking across all tiers
+- [Protocol Messages](https://docs.kici.dev/architecture/protocol-messages/) -- WebSocket message schemas for all three layers
+- [Webhook Delivery](https://docs.kici.dev/architecture/webhooks/webhook-delivery/) -- end-to-end trace of a webhook through all three tiers
 
 ---