@kici-dev/compiler 0.1.22 → 0.1.24

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.
+All CLI commands provided by `@kici-dev/compiler`: `kici compile` (with watch mode and check mode), `kici run` (local and remote execution), `kici preview` (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,14 +245,14 @@ 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
 
-Use `kici test` to preview which workflows match a trigger event (dry-run, no execution):
+Use `kici preview` to preview which workflows match a trigger event (dry-run, no execution):
 
 ```bash
-npx kici test pr:open
+npx kici preview pr:open
 ```
 
 Expected output (simplified):
@@ -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.
@@ -418,14 +418,14 @@ Or add the flag to your root `package.json`:
 
 ## Authoring KiCI workflows with LLM coding agents
 
-KiCI is LLM-ready by design. Because workflows are real, typed TypeScript, coding agents reason over the SDK's `.d.ts` signatures instead of guessing a bespoke YAML DSL — and they verify their own pipelines with the same `kici test` and `kici run local` loop you use, so there's no push-to-find-out round-trip. First-class agent context ships in the box, so an agent is briefed the moment it opens the project.
+KiCI is LLM-ready by design. Because workflows are real, typed TypeScript, coding agents reason over the SDK's `.d.ts` signatures instead of guessing a bespoke YAML DSL — and they verify their own pipelines with the same `kici preview` and `kici run local` loop you use, so there's no push-to-find-out round-trip. First-class agent context ships in the box, so an agent is briefed the moment it opens the project.
 
 KiCI ships first-class context for LLM coding agents (Claude Code, Cursor, Aider, etc.). When you scaffold a project with `kici init`, the CLI writes `.kici/AGENTS.md`, a one-page briefing that tells the agent:
 
 - where the SDK type declarations live (`node_modules/@kici-dev/sdk/dist/index.d.ts`)
 - the five canonical authoring patterns with runnable examples
 - the anti-patterns that catch agents off-guard (no YAML, no `/dist/...` imports, no top-level `await`)
-- the local commands the agent should drive (`kici compile --check`, `kici test`, `kici run local`, `kici docs llm`)
+- the local commands the agent should drive (`kici compile --check`, `kici preview`, `kici run local`, `kici docs llm`)
 
 If you don't want the file, pass `--no-agents-md` to `kici init`, or delete the file afterwards — KiCI never reads it at runtime.
 
@@ -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 preview` 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 status that satisfies the edge. If an upstream fails, downstream jobs skip by default (override per-edge with `when: 'always'`). See [Job dependencies (`needs`)](../sdk/core.md#job-dependencies-needs) in the SDK reference for the full matrix of `needs` forms (string, `Job` ref, `{ name, when }`, `dynamicGroup()`) and [needs-scheduler](../../architecture/execution/needs-scheduler.md) for the dispatch semantics.
+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
 
@@ -1267,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';
@@ -1373,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
 
@@ -1415,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)
 
@@ -1466,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.
 
@@ -1500,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)
 
@@ -1562,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
 
@@ -1700,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:**
@@ -1764,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
@@ -1836,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
 
@@ -1856,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
 
@@ -1973,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
 
 ---
 
@@ -2018,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.
 
@@ -2032,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)
 
@@ -2050,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                                                                                                                                                                   |
@@ -2059,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.
 
@@ -2092,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
@@ -2118,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
@@ -2134,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:
@@ -2238,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
 
@@ -2321,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.                                                                                         |
 
@@ -2504,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.
@@ -2586,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 execution (`kici run local`) 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`)
 
@@ -2641,7 +2705,7 @@ job('report', {
 });
 ```
 
-For an arbitrary outcome-based gate that prevents a job from dispatching at all, use a result-aware `dynamicJob` that returns `[]` or `[job]` based on `ctx.needs.<job>.status` — see [Dynamic jobs](../../architecture/execution/dynamic-jobs.md).
+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.
 
@@ -2686,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
 
@@ -3051,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)`
 
@@ -3150,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:
@@ -3192,8 +3311,90 @@ 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.
+
+---
+
+## SDK reference: parallel
+
+Source: https://docs.kici.dev/user/sdk/parallel/
+
+`parallel([...steps], opts?)` runs a group of independent steps **concurrently**
+within one job, behind a join barrier: execution continues past the group only
+once every child has settled. Each child is its own observable step — it gets its
+own logs, status, timing, and retry — instead of being hidden inside one step's
+`Promise.all`.
+
+```ts
+import { workflow, job, step, parallel, push } from '@kici-dev/sdk';
+
+export default workflow('ci', {
+  on: push(),
+  jobs: [
+    job('checks', {
+      runsOn: 'kici:os:linux',
+      steps: [
+        checkout,
+        // lint, typecheck, and the unit tests have no ordering between them,
+        // so they run together — the job's wall-clock is the slowest child,
+        // not the sum of all three.
+        parallel([lint, typecheck, unitTests], { failFast: true }),
+        deploy,
+      ],
+    }),
+  ],
+});
+```
+
+`parallel(...)` returns a `ParallelGroup` that sits in the ordinary flat
+`steps: [...]` array — there is no new `job` field. A group's children are
+**sequential steps only**; groups cannot be nested.
+
+## Options
+
+`parallel(steps, opts?)` accepts:
+
+- **`failFast?: boolean`** — default `true`. When a child fails, the in-flight
+  siblings are cancelled immediately and the job fails. With `failFast: false`
+  every child runs to completion first, then the job fails if any child failed.
+- **`maxParallel?: number`** — default unlimited. Caps how many children run at
+  once; children waiting for a slot report a `pending` status until they launch.
+- **`name?: string`** — a label for the group's dashboard band.
+
+A child marked `continueOnError: true` never trips fail-fast and never fails the
+job — it still shows a `failed` status badge, but the group treats it as
+non-fatal.
+
+## Statuses
+
+Parallel steps introduce two step statuses:
+
+- **`pending`** — a child queued behind `maxParallel`, not yet launched.
+- **`cancelled`** — a sibling aborted by fail-fast. A cancelled step is **not** a
+  failure: only the child that actually failed fails the job; the cancelled
+  siblings render in gray (distinct from the red failing step) on the dashboard.
+
+Children may also complete **out of order** — the fastest child finishes first
+regardless of array position. A later sequential step can read a parallel child's
+`.result` after the barrier; children within a group cannot read each other's
+results (there is no ordering inside the group).
+
+## Scope: nests inside job-level fan-out
+
+`parallel()`'s `failFast` / `maxParallel` are **step-group** scopes — they govern
+only the steps inside the group. They are a different layer from the **job-level**
+`failFast` / `maxParallel` on a matrix / `runsOnAll` fan-out, which govern how a
+job's child _jobs_ spread across the matrix or host roster. A `parallel()` group
+inside a fan-out job nests its concurrency inside each fan-out child.
+
+## Local vs remote execution
+
+Run remotely (the orchestrator + agent), parallel children execute concurrently
+and each surfaces as its own dashboard step. `kici run local` executes the same
+children in array order in its single-process model — the results are identical,
+only the wall-clock and the live fail-fast cancellation differ. Use a remote run
+to observe the concurrent timeline.
 
 ---
 
@@ -3320,7 +3521,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`.
 
@@ -3430,7 +3631,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', {
@@ -3583,7 +3784,7 @@ export default workflow('discovery-fan-out', { jobs: [discover, reports] });
 | `'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
 
@@ -3624,7 +3825,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.
@@ -3673,7 +3874,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-*'`).
@@ -3725,6 +3926,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
@@ -3757,7 +4018,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:
@@ -3783,6 +4044,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
@@ -3840,8 +4132,8 @@ When `--target` narrows a `runsOnAll` job to zero hosts, the run **fails** by de
 (a mistyped selector should be loud, not silently no-op). Pass `--target-allow-empty`
 to **skip** the zeroed job instead — it records a `skipped` status, and downstream jobs
 gated with `when: 'on-skip'` (or `when: 'always'`) still run, exactly as for an
-`onUnreachable: 'skip'` zero-host fan-out. See the [CLI reference](/user/cli-reference/#host-narrowing-with---target)
-for the full flag behavior and the [`needs` gating model](./core.md#job-dependencies-needs)
+`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)
@@ -3875,9 +4167,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`                                                                                                                                                                                                              |
@@ -4004,7 +4296,7 @@ interface StepContext<TInputs = Record<string, unknown>> {
   rawPayload?: Record<string, unknown>;
   /** Which git provider triggered this workflow (e.g. 'github', 'gitlab') */
   provider?: string;
-  /** Whether this execution was triggered by `kici test` (remote test run) */
+  /** Whether this execution was triggered by `kici run remote` (developer-initiated remote run) */
   isTestRun: boolean;
   /** The resolved deployment environment name for this job (undefined without environment) */
   environment?: string;
@@ -4064,7 +4356,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)
 
@@ -4089,7 +4381,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)
 
@@ -4302,7 +4594,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
@@ -4397,11 +4689,11 @@ 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
 
-When running `kici test`, you can provide secrets locally without an orchestrator.
+When running `kici preview`, you can provide secrets locally without an orchestrator.
 
 #### .kici/.secrets file
 
@@ -4429,10 +4721,10 @@ Override or supplement file-based secrets with CLI flags:
 
 ```bash
 # Inject flat secrets (repeatable)
-kici test push --secret DEPLOY_TOKEN=my-token --secret API_KEY=my-key
+kici preview push --secret DEPLOY_TOKEN=my-token --secret API_KEY=my-key
 
 # Inject context-scoped secrets (repeatable)
-kici test push --context production.DB_PASSWORD=prod-secret --context npm-publish.NPM_TOKEN=abc123
+kici preview push --context production.DB_PASSWORD=prod-secret --context npm-publish.NPM_TOKEN=abc123
 ```
 
 **Precedence:** CLI flags override `.kici/.secrets` file values. Context secrets are auto-flattened into `ctx.secrets` using the same merge logic as production (last context wins).
@@ -4650,13 +4942,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`.
@@ -4770,7 +5122,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
@@ -4875,7 +5227,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()
 
@@ -4927,6 +5279,7 @@ interface ScheduleConfigInput {
   cron: string; // Required: cron expression (5-field)
   timezone?: string; // Timezone for cron evaluation (default: 'UTC')
   description?: string; // Human-readable description of the schedule
+  inputs?: DispatchInputsMap; // Optional: defaults-only typed inputs (see below)
 }
 ```
 
@@ -4937,6 +5290,41 @@ schedule({ cron: '0 9 * * 1', timezone: 'America/New_York' }); // Monday 9am ET
 schedule({ cron: '*/15 * * * *', description: 'health check every 15 min' });
 ```
 
+#### Schedule inputs (defaults-only)
+
+A `schedule()` trigger may declare typed `inputs`. A cron or dashboard
+"run now" fire carries **no operator-supplied values**, so each input resolves
+from its declared **default** and is exposed to steps and rules as
+`ctx.dispatchInputs` — the same surface as [typed dispatch inputs](https://docs.kici.dev/user/sdk/triggers/#typed-dispatch-inputs).
+
+Because there is no operator to supply a value, every schedule input must
+declare a `.default()` **or** be `.optional()`. An input that is neither is
+rejected at `kici compile` time.
+
+```typescript
+import { workflow, job, schedule, z } from '@kici-dev/sdk';
+
+export default workflow('nightly', {
+  on: schedule({
+    cron: '0 3 * * *',
+    inputs: { mode: z.enum(['full', 'quick']).default('full') },
+  }),
+  jobs: [
+    job('build', {
+      runsOn: 'default',
+      run: async (ctx) => {
+        ctx.log(`mode = ${ctx.dispatchInputs.mode}`); // "full" on every fire
+      },
+    }),
+  ],
+});
+```
+
+You can also share a typed handle via `defineDispatchInputs(...)` and read it
+back with `.from(ctx)`, exactly as with `dispatch()`. The allowed input types
+are the same closed subset documented under
+[typed dispatch inputs](https://docs.kici.dev/user/sdk/triggers/#typed-dispatch-inputs).
+
 ### lifecycle()
 
 Create a lifecycle trigger for cross-workflow orchestration events. Returns a frozen `LifecycleTriggerConfig`.
@@ -5255,9 +5643,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.
 
 ---
 
@@ -5265,18 +5653,19 @@ If `check()` throws while polling, the error is logged and polling continues —
 
 Source: https://docs.kici.dev/user/sdk-reference/
 
-Reference documentation for `@kici-dev/sdk`. The reference is split across five pages by topic.
+Reference documentation for `@kici-dev/sdk`. The reference is split across the per-topic pages below.
 
 | 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.                                                                                           |
+| [Parallel steps](https://docs.kici.dev/user/sdk/parallel/)                          | `parallel()` — run independent steps concurrently within one job behind a join barrier, each as its own observable step, with `failFast` and `maxParallel` controls.                                                        |
 
 The `@kici-dev/sdk` package re-exports the entire surface from a single entry point. Pick what you need:
 
@@ -5288,17 +5677,110 @@ 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
 
 ---
 
 # CLI and authoring
 
+## Drive KiCI from your coding agent
+
+Source: https://docs.kici.dev/user/ai-agents/
+
+KiCI ships a hosted **MCP server** so a coding agent (Claude Code, or any MCP
+client) can drive your CI directly: trigger runs, read a structured result,
+fetch the failing step's logs, cancel, and re-run — all under your own identity,
+org-scoped, and audited. There are no per-tool tokens to configure: point the
+agent at one URL with one credential and it's done.
+
+The MCP exposes only what you can already do yourself through the `kici` CLI and
+the dashboard. It is not a new privileged surface — every tool maps to an
+existing user-facing operation and is gated by the same permissions your role
+grants.
+
+## 1. Mint an agent token
+
+The MCP accepts **only** an agent-kind personal access token (PAT). Mint one with
+the `kici` CLI (log in first with `kici login`):
+
+```bash
+kici pat create --agent --name "claude-code"
+```
+
+The `--name` value is the **agent label**. It is recorded on every action the
+agent takes, so your audit log shows exactly which agent did what (and on whose
+behalf). The token is printed once — save it now; it cannot be retrieved later.
+
+An agent PAT inherits your permissions unchanged — it carries provenance, not
+extra authority. Powerful operator capabilities (secret rotation, agent and peer
+management, draining) are intentionally **not** exposed here.
+
+## 2. Point your coding agent at the MCP server
+
+Configure your MCP client with the KiCI MCP endpoint and the agent PAT as a
+Bearer credential. The endpoint is the hosted Platform URL plus `/api/v1/mcp`.
+
+For Claude Code, add a remote MCP server whose URL is your KiCI Platform's
+`/api/v1/mcp` and whose `Authorization` header is `Bearer <your-agent-pat>`.
+
+That's the entire setup. The agent can now call the tools below.
+
+## 3. What the agent can do
+
+**Read**
+
+- `list_runs` — recent runs in your organization.
+- `get_run` — the structured, provenance-tagged result of a run: the typed job
+  graph, per-step statuses and exit codes, durations, and a derived failure
+  category.
+- `get_step_logs` — the log lines for a specific step.
+- `list_workflows` — your registered workflows.
+
+**Drive**
+
+- `trigger_run` — run a registered workflow ("run now").
+- `rerun_run` — re-run a completed run.
+- `cancel_run` — cancel an in-progress run.
+
+If you belong to a single organization, the org is resolved automatically. If
+you belong to several, pass an `orgId` argument to any tool.
+
+## 4. Why the structured result is agent-safe
+
+`get_run` and `get_step_logs` return a machine-first shape designed for an agent
+to reason over without being misled by repository content. Every field that
+comes from your repo, a contributor, or a process's output — workflow and job
+names, refs, error messages, log lines, job outputs — is wrapped in an
+`{ untrusted: true, value: … }` envelope. KiCI-generated values (ids, statuses,
+exit codes, durations, the derived failure category) are left plain. An agent can
+keep user-controlled content out of its instruction channel by refusing to act
+on anything tagged `untrusted`.
+
+Secret values are never returned — only the names of the secret keys a step
+accessed.
+
+## 5. The audit guarantee
+
+Because the MCP accepts only an agent-kind PAT, **every action that flows through
+it is agent-attributed by construction** — there is no path that produces an
+untagged, human-looking action. Each read and each drive operation is recorded in
+your orchestrator's access log under your identity plus the agent label, so you
+always have a complete trail of what your agent did.
+
+Inspect that trail with `kici-admin access-log list --json` (or
+`kici-admin access-log show <id>` for one entry). An agent-attributed row keeps
+`actor_type` as `user` and `actor_id` as your own identity — the agent provenance
+rides in the row's actor metadata as `agentLabel` (the `--name` you minted the
+PAT with) and `agentPatId` (the token that acted). The label is also stored in a
+dedicated `agent_label` column on every such row.
+
+---
+
 ## CLI authentication
 
 Source: https://docs.kici.dev/user/cli-auth/
@@ -5458,13 +5940,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
 
@@ -5509,7 +5991,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
 
@@ -5581,7 +6063,7 @@ Run commands with `npx kici` or add scripts to your `package.json`:
 {
   "scripts": {
     "kici:compile": "kici compile",
-    "kici:test": "kici test"
+    "kici:preview": "kici preview"
   }
 }
 ```
@@ -5655,26 +6137,29 @@ 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)                                                                                                                                                                |
+| `--check`             | `false`   | Run in [check mode](https://docs.kici.dev/user/idempotent-steps/): each step reports drift instead of applying; the run still exits 0                                                                                                                           |
+| `--fail-on-drift`     | `false`   | In check mode, exit non-zero if any step reports drift (no effect without `--check`)                                                                                                                                                   |
 
 **Interactive workflow selection (`--pick` / `-p`):**
 
@@ -5778,9 +6263,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.
+
+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](testing-guide.md) and [Storage layout](../operator/orchestrator/storage-layout.md) for setup.
+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]
@@ -5794,24 +6281,30 @@ 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) |
-| `--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                                                                           |
+| 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                                                                                                                                                                                                                    |
+| `--routing-key <key>`       | none    | Override the routing key for this run (advanced; selecting the org normally suffices — see [How the run is routed](https://docs.kici.dev/user/cli-reference/#how-the-run-is-routed))                                                                                                |
+| `--check`                   | `false` | Run in [check mode](https://docs.kici.dev/user/idempotent-steps/): each step reports drift instead of applying                                                                                                                                                      |
+| `--fail-on-drift`           | `false` | In check mode, fail the run if any step reports drift (no effect without `--check`)                                                                                                                                                        |
+| `--approve-all, --yes`      | `false` | Auto-approve every [approval gate](https://docs.kici.dev/user/approvals/) this run holds on (run-scoped; eligibility still enforced)                                                                                                                                |
 
 **Examples:**
 
@@ -5849,6 +6342,9 @@ 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
 
@@ -5859,6 +6355,18 @@ kici run remote deploy --target role:web --target dc:eu
 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
@@ -5883,7 +6391,7 @@ When `--target` narrows a `runsOnAll` job to zero hosts, the default is to **fai
 the run (fail-loud — a typo in the selector shouldn't silently skip work). Pass
 `--target-allow-empty` to **skip** the zeroed job instead; the job records a
 `skipped` status, and any downstream job that needs it with `when: 'on-skip'` (or
-`when: 'always'`) still runs. See [Job dependencies](./sdk/core.md#job-dependencies-needs)
+`when: 'always'`) still runs. See [Job dependencies](https://docs.kici.dev/user/sdk/core/#job-dependencies-needs)
 for the `when` gating model.
 
 **Exit codes:**
@@ -5915,9 +6423,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)
 
@@ -5931,7 +6439,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
 
@@ -5962,12 +6470,12 @@ kici orchestrators use us-east
 kici orchestrators use us-east --org xyz789ghi012
 ```
 
-### kici test
+### kici preview
 
 Preview which workflows match a trigger event (dry-run, no execution). Useful for verifying trigger configurations during development.
 
 ```bash
-kici test [event] [options]
+kici preview [event] [options]
 ```
 
 **Arguments:**
@@ -5994,19 +6502,19 @@ kici test [event] [options]
 
 ```bash
 # Preview which workflows match a push event
-kici test push
+kici preview push
 
 # Preview PR trigger matching
-kici test pr:open
+kici preview pr:open
 
 # Preview with branch override
-kici test push --branch develop
+kici preview push --branch develop
 
 # Filter to specific workflow
-kici test push --workflow ci
+kici preview push --workflow ci
 
 # Simulate changed files for path-filtered triggers
-kici test push --files src/index.ts --files README.md
+kici preview push --files src/index.ts --files README.md
 ```
 
 **Exit codes:**
@@ -6016,7 +6524,7 @@ kici test push --files src/index.ts --files README.md
 | 0    | Preview completed (including zero matches) |
 | 1    | Error                                      |
 
-**Migration from old `kici test <fixture>`:** If you were using `kici test <fixture-name>` for remote fixture execution, use `kici run remote <fixture-name>` instead. For local workflow execution, use `kici run local <event>`.
+**Migration from the old `test` command:** The dry-run preview command was renamed from `test` to `preview`. If you were using the old `test` command with a fixture name for remote fixture execution, use `kici run remote <fixture-name>` instead. For local workflow execution, use `kici run local <event>`.
 
 ### kici login
 
@@ -6316,7 +6824,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]
@@ -6352,7 +6860,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]
@@ -6393,6 +6901,27 @@ Only key names are shown — secret values are never returned over this endpoint
 
 **Prerequisites:** authenticate via `kici login` and select an active organization with `kici org use <name>`.
 
+### kici pat create
+
+Mint a personal access token under your own identity. Pass `--agent` to mint an
+**agent-kind** PAT — the credential a coding agent points the KiCI MCP server at.
+
+```bash
+kici pat create --agent --name "claude-code"
+```
+
+- `--agent` marks the token as agent-kind. An agent PAT inherits your
+  permissions unchanged (it carries provenance, not extra authority) and is the
+  **only** credential the MCP server accepts.
+- `--name <label>` sets the token name. For an agent PAT this is the **agent
+  label** recorded on every action the agent takes — required with `--agent`.
+- `--expires-in-days <n>` overrides the default expiry.
+
+The token is printed once — save it immediately; it cannot be retrieved later.
+See [Drive KiCI from your coding agent](https://docs.kici.dev/user/ai-agents/) for the full setup.
+
+**Prerequisites:** authenticate via `kici login` first.
+
 ### kici types
 
 Generate TypeScript declaration files from orchestrator environment metadata. The generated `.d.ts` file augments the SDK's `KnownSecretKeys` and `EnvironmentSecrets` interfaces, providing compile-time autocomplete and type checking for secret key names.
@@ -6431,7 +6960,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`.
 
@@ -6650,9 +7179,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:**
@@ -6661,14 +7191,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
 
@@ -6707,10 +7237,10 @@ 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]
+kici verify-attestation [artifact] --bundle <path-or-url> [--trust-root <url-or-file>] [options]
 ```
 
 **Arguments:**
@@ -6721,14 +7251,14 @@ kici verify-attestation [artifact] --bundle <path-or-url> --trust-root <url-or-f
 
 **Options:**
 
-| Option                       | Required | Description                                                                               |
-| ---------------------------- | -------- | ----------------------------------------------------------------------------------------- |
-| `--bundle <path-or-url>`     | yes      | Path or `http(s)` URL to the attestation bundle JSON.                                     |
-| `--trust-root <url-or-file>` | yes      | Trusted issuer (see below). The token issuer is pinned to it, never taken from the token. |
-| `--audience <aud>`           | no       | Expected token audience (defaults to the KiCI provenance audience).                       |
-| `--json`                     | no       | Print the structured verification result as JSON instead of human-readable output.        |
+| Option                       | Required | Description                                                                                                                     |
+| ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `--bundle <path-or-url>`     | yes      | Path or `http(s)` URL to the attestation bundle JSON.                                                                           |
+| `--trust-root <url-or-file>` | no       | Trusted issuer (see below). Defaults to the hosted KiCI platform. The token issuer is pinned to it, never taken from the token. |
+| `--audience <aud>`           | no       | Expected token audience (defaults to the KiCI provenance audience).                                                             |
+| `--json`                     | no       | Print the structured verification result as JSON instead of human-readable output.                                              |
 
-**Trust root:** the verifier never trusts the issuer named inside the token — you supply the trusted issuer out-of-band via `--trust-root`, in one of two forms:
+**Trust root:** `--trust-root` defaults to the hosted KiCI platform's provenance issuer — the same platform you `kici login` against (see [Which trust root do I use?](https://docs.kici.dev/user/provenance/#which-trust-root-do-i-use)), so the common case needs no flag. The verifier never trusts the issuer named inside the token; supplying it out-of-band is what prevents a forged bundle from self-attesting. To override the default, pass `--trust-root` in one of two forms:
 
 - **Online — an HTTPS issuer URL.** The verifier fetches `<url>/.well-known/openid-configuration`, reads its `issuer` and `jwks_uri`, and fetches the JWKS. The token's `iss` is pinned to the discovery document's `issuer`.
 - **Offline — a self-contained trust-root file.** A local JSON file with the issuer and JWKS inlined, so no network access is needed (air-gapped verification):
@@ -6747,7 +7277,10 @@ kici verify-attestation [artifact] --bundle <path-or-url> --trust-root <url-or-f
 **Examples:**
 
 ```bash
-# Online: verify a bundle against a deployed issuer, digest-checking the artifact
+# Default: verify against the hosted KiCI platform (no --trust-root needed)
+kici verify-attestation ./dist/app.tgz --bundle ./app.tgz.kici.json
+
+# Override: verify a bundle against a specific issuer, digest-checking the artifact
 kici verify-attestation ./dist/app.tgz \
   --bundle ./app.tgz.kici.json \
   --trust-root https://platform.example/issuer
@@ -6764,10 +7297,10 @@ kici verify-attestation --bundle ./app.tgz.kici.json \
 
 **Exit codes:**
 
-| Code | Meaning                                                                             |
-| ---- | ----------------------------------------------------------------------------------- |
-| 0    | Verified — signature, identity, build context (and digest, if checked) all pass     |
-| 1    | Not verified, or an error (missing flag, unreadable bundle, unreachable trust root) |
+| Code | Meaning                                                                                   |
+| ---- | ----------------------------------------------------------------------------------------- |
+| 0    | Verified — signature, identity, build context (and digest, if checked) all pass           |
+| 1    | Not verified, or an error (missing `--bundle`, unreadable bundle, unreachable trust root) |
 
 ## Workflow discovery
 
@@ -6796,7 +7329,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
 
@@ -6809,7 +7342,7 @@ All commands follow a consistent exit code convention:
 
 ## Debug output
 
-Use `--debug` (on `kici run local`, `kici run remote`, `kici test`) or `--verbose` (on `kici compile`) for detailed output:
+Use `--debug` (on `kici run local`, `kici run remote`, `kici preview`) or `--verbose` (on `kici compile`) for detailed output:
 
 ```bash
 # Shows trigger matching, rule evaluation, decision traces
@@ -6819,7 +7352,7 @@ kici run local push --debug
 kici compile --verbose
 
 # Shows trigger matching preview
-kici test pr:open --debug
+kici preview pr:open --debug
 ```
 
 Set `KICI_DEBUG=true` for additional internal debug output across all commands.
@@ -6834,10 +7367,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
 
 ---
 
@@ -7100,7 +7633,7 @@ The lock file (`kici.lock.json`) is a JSON file with the following top-level fie
 
 | Field           | Description                                                                                                                                                                                                                                                                                                                                           |
 | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `schemaVersion` | Lock file schema version (currently 20). Incremented on breaking format changes.                                                                                                                                                                                                                                                                      |
+| `schemaVersion` | Lock file schema version (currently 29). Incremented on breaking format changes.                                                                                                                                                                                                                                                                      |
 | `source`        | Reference to the source file and export (e.g., `{ file: “.kici/workflows/ci.ts”, export: “#default” }`).                                                                                                                                                                                                                                              |
 | `contentHash`   | SHA-256 of the serialized lock file content (excluding itself). Changes when any workflow, trigger, or job changes.                                                                                                                                                                                                                                   |
 | `lockfileHash`  | SHA-256 of the detected package manager's lockfile, used as the dependency cache key. The lockfile is `.kici/package-lock.json` for npm, or the repo-root `pnpm-lock.yaml` / `yarn.lock` for a pnpm/yarn workspace; the hash input is prefixed with the manager name so a manager change is a guaranteed cache miss. Omitted when no lockfile exists. |
@@ -7118,12 +7651,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`.                                                                                                                                                                                                                                                                     |
 
@@ -7152,7 +7685,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
 
@@ -7202,9 +7735,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
 
 ---
 
@@ -7223,17 +7756,17 @@ Test your workflows remotely against the full CI pipeline from your local machin
 - Give test runs test-scoped secrets — your local secret files and `--env` values (uploaded encrypted) plus any environment flagged `allowLocalExecution: true` — while production environments stay unreachable
 - Detect test mode in workflow code via `ctx.isTestRun`
 
-The command is remote-only -- all execution happens on the orchestrator and agent. For local-only trigger matching previews, use `kici test <event>`.
+The command is remote-only -- all execution happens on the orchestrator and agent. For local-only trigger matching previews, use `kici preview <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
@@ -7244,7 +7777,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
 
@@ -7352,8 +7885,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
 
@@ -7508,7 +8041,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.
@@ -7553,7 +8086,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
 
@@ -7630,9 +8163,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
 
 ---
 
@@ -7640,24 +8173,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
 
 ---
 
@@ -7677,7 +8210,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.
@@ -7727,9 +8260,9 @@ You declare a gate in your workflow with `approval`. It is available at three le
 - **Job** — hold the job before any of its steps run.
 - **Workflow** — hold the whole run before any job is dispatched.
 
-A step-level gate can also fire **only when a check/apply step finds drift** — Terraform's plan→apply, per step. See [Drift gates](#drift-gates-whendrift) below.
+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)](../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.
+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
 
@@ -7750,7 +8283,7 @@ export default workflow('deploy', {
 });
 ```
 
-When the run reaches this job, it is held instead of dispatched. The held run appears in the dashboard approval queue and can be released from there or with the [`kici approve`](#approving-from-the-cli) command. Once a member of `leads` approves, the job dispatches normally.
+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 `approval` field
 
@@ -7798,12 +8331,12 @@ approval: {
 
 | Field       | Type                  | Description                                                                                                                                                                 |
 | ----------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `when`      | `'always' \| 'drift'` | When the gate fires. `'always'` (default) gates before the element; `'drift'` gates a check/apply step only when it finds drift. See [Drift gates](#drift-gates-whendrift). |
+| `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
 
@@ -7855,13 +8388,13 @@ 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](idempotent-steps.md). Instead of pausing unconditionally, it fires **between the step's `check` and `run`, only when `check` finds drift in apply mode** — exactly Terraform's plan→apply, scoped to one step. When the step is already in sync (no drift), nothing pauses and the step skips.
+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](#approving-from-the-cli) show the actual diff the operator is approving — not a static reason string.
+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', {
@@ -7889,7 +8422,7 @@ A `when: 'drift'` gate on a step without a `check` facet, or at job/workflow sco
 
 ## Mandatory vs. explicit gates
 
-`approval` is the **explicit** gate — a deliberate "pause for a human here" written by the workflow author. It composes with the **mandatory** gate an operator can attach to a protected environment via required reviewers (see [Environments](environments.md#required-reviewers)). When both apply to the same job, all clauses from both sources must be satisfied before the job is released. The two funnel into one held-element mechanism, so the dashboard queue and `kici approve` work the same way regardless of which source held the element.
+`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
 
@@ -7909,7 +8442,7 @@ 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.
 
 ### Inline approval and `--approve-all` in `kici run remote`
 
@@ -7923,14 +8456,14 @@ kici run remote deploy-prod --approve-all
 
 `--approve-all` is **run-scoped** — it only auto-approves holds belonging to the run this invocation dispatched; there is no fleet-wide or account-wide auto-approve. Eligibility is still enforced per hold: if you are not eligible for a gate, that gate still blocks. Each auto-approved gate prints its payload before resolving and is recorded distinctly in the audit trail (`held_run.auto_approve`).
 
-You can also approve from the dashboard approval queue. See [Dashboard](dashboard/environments-and-secrets.md#approval-queue).
+You can also approve from the dashboard approval queue. See [Dashboard](https://docs.kici.dev/user/dashboard/environments-and-secrets/#approval-queue).
 
 ## See also
 
-- [Idempotent steps](idempotent-steps.md) — the check/apply step facet that drift gates build on.
-- [Environments](environments.md) — operator-required reviewers on protected environments.
-- [Approval gates (operator guide)](../operator/approvals.md) — teams, the approval queue, expiry, and self-approval.
-- [Approval gates (architecture)](../architecture/approvals.md) — the unified hold model and the step-level round-trip.
+- [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.
 
 ---
 
@@ -7990,7 +8523,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
 
@@ -8141,7 +8674,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
 
@@ -8149,7 +8682,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.
 
@@ -8169,14 +8702,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                                               |
 
 ---
 
@@ -8294,7 +8827,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`, …).
 
 ---
 
@@ -8461,7 +8994,37 @@ 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.
+
+### Multiple environments per job
+
+A job can bind more than one environment with `environments`, an ordered array. This lets a single job draw secrets and variables from several environments at once — for example a shared `staging` environment plus a `my-testing` environment that carries test-only variables:
+
+```typescript
+job('deploy', {
+  runsOn: 'default',
+  environments: ['staging', 'my-testing'],
+  steps: [
+    step('deploy', async (ctx) => {
+      // ctx.secrets and ctx.env carry the merged set from both environments
+      const dbUrl = await ctx.secrets.get('DB_URL');
+    }),
+  ],
+});
+```
+
+- `environment` (singular) and `environments` (array) are mutually exclusive — setting both is a compile error. `environment: 'staging'` is exactly equivalent to `environments: ['staging']`.
+- Each array entry is a static name or a function of the event, resolved per element exactly like a single dynamic environment.
+
+**Merge order — last wins.** All bound environments are resolved on every dispatch (webhook, scheduled, and test runs alike) and merged in array order. When the same secret or variable key is defined in more than one environment, the later entry in the array wins. With `environments: ['staging', 'my-testing']`, a key defined in both resolves to `my-testing`'s value; keys defined in only one are preserved. The longest-scope-path-wins rule still applies _within_ each environment.
+
+**Protection rules combine all-must-pass.** A job must satisfy **every** bound environment's gates — adding an environment can never loosen access. Branch restrictions, trigger-type filters, and repo patterns must pass for all environments; the minimum trust tier is the most restrictive across them; required reviewers are the union of all environments' reviewers; the wait timer is the longest; and the hold expiry is the shortest. If a run is gated out, the rejection names which environment and which rule rejected it (visible via `kici status` and the run's rejection reason), so a mutually-exclusive set of rules surfaces as a clear failure rather than a silent perpetual rejection.
+
+**Skip-on-test.** On a test or local run (`kici run remote`, `kici run local`), any bound environment that disallows local execution is skipped — its variables and secrets are omitted from the merge and its gates are not evaluated. This makes the test-only-variables pattern work: with `environments: ['staging', 'my-testing']` where only `my-testing` allows local execution, a test run resolves just `my-testing`'s variables. If every bound environment disallows test runs, the job runs with no environment variables and a clear warning.
+
+**Unconfigured environments contribute nothing at dispatch.** At dispatch time a bound environment name with no matching configured environment (and no matching glob environment) simply adds no variables, secrets, or protection rules — the job still runs, exactly as a single dynamic environment resolving to an as-yet-unconfigured name does today.
+
+**Registration rejects a provably-unsatisfiable binding.** When a workflow is registered, KiCI statically checks every multi-environment binding: a bound environment that does not exist, a disabled one, or two environments with mutually-exclusive fixed branch / trigger-type / repository restrictions (no value can satisfy both) makes the binding provably unsatisfiable, and the registration is rejected with a precise message naming the job, the environments, and the rule — for example `unsatisfiable environment binding: job 'deploy' binds environments [staging, my-testing] with mutually exclusive branch restrictions (no value satisfies all bound environments)`. Bindings whose restrictions use globs are undecidable at registration and fall through to the dispatch-time gate check instead.
 
 ### Job-level environment variables
 
@@ -8485,7 +9048,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:
 
@@ -8502,7 +9065,7 @@ job('deploy', {
 });
 ```
 
-If no `concurrencyGroup` is specified, the environment name is used as the default concurrency group.
+If no `concurrencyGroup` is specified, the environment name is used as the default concurrency group. For a job bound to multiple environments, the default is the **first** bound environment's name.
 
 ### Step context
 
@@ -8534,7 +9097,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
 
@@ -8558,9 +9121,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 `approval` 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
 
@@ -8595,7 +9158,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
 
@@ -8629,7 +9192,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
 
@@ -8643,6 +9206,12 @@ Each environment has four tabs:
 
 4. **History** -- view filtered runs targeting this environment.
 
+### Bound environments on runs
+
+A job's bound deployment environments are shown as chips on the run detail page (in the job metadata panel) in the order the job declared them, and the distinct set across a run's jobs appears as compact chips on the run list. For a multi-environment job the chips read left-to-right in merge order — later environments override earlier ones on key collisions. A `(dynamic)` chip marks an environment whose name is computed at runtime; it resolves to the real name once the run starts. A job that binds a single environment shows one chip; a job that binds none shows no chip.
+
+If a multi-environment binding is gated out, the run's failure banner names which environment and which rule rejected it (the same all-must-pass detail surfaced by `kici status`).
+
 ### Secrets management
 
 Secrets are individual encrypted values organized by scope paths (e.g., `aws/prod`, `databases/postgres`). Scopes are bound to environments via bindings:
@@ -8788,7 +9357,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
 
@@ -8898,7 +9467,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.
 
@@ -9035,15 +9604,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
 
 ---
 
@@ -9163,9 +9732,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:`.
 
 ---
 
@@ -9292,9 +9861,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.
 
 ---
 
@@ -9347,7 +9916,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.
@@ -9512,7 +10081,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.
@@ -9548,9 +10117,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.
 
 ---
 
@@ -9666,11 +10235,34 @@ statement's build context must match the token's identity claims (a mismatch is
 a hard failure).
 
 ```bash
-kici verify-attestation [artifact] --bundle <path-or-url> --trust-root <url-or-file>
+kici verify-attestation [artifact] --bundle <path-or-url> [--trust-root <url-or-file>]
 ```
 
-You supply the trusted issuer out-of-band via `--trust-root` — the verifier
-never trusts the issuer named inside the token. There are two forms:
+### Which trust root do I use?
+
+The trust root is the **KiCI platform's provenance issuer** — the same hosted
+KiCI platform you `kici login` against. KiCI attestations are issued by, and
+verified against, that one issuer; there are no competing "roots" to choose
+between. So the answer to "shouldn't I just use KiCI as the trust root?" is yes
+— and that's the **default**: omit `--trust-root` and the verifier checks the
+bundle against the hosted KiCI platform automatically. You only pass
+`--trust-root` to verify against a different environment or, more commonly, an
+offline `{ issuer, jwks }` file for air-gapped checks.
+
+### Why you supply it out-of-band
+
+Given there's a single issuer, why pass it at all instead of letting the
+verifier read it from the token? Because the issuer named **inside** a token
+cannot be trusted: a forged bundle could carry a token that names
+`iss: https://attacker.example` _and_ bundle a key set that "verifies" it,
+making the whole signature chain circular and self-attesting. The verifier
+therefore pins to an issuer you supply out-of-band and checks the token against
+_that_ — the bundle is verified against a key set you trust, not one it shipped
+with. Naming the trust root is a security requirement, not a multiple-choice
+question.
+
+To override the default, supply the trusted issuer via `--trust-root`, in one of
+two forms:
 
 - **Online — an HTTPS issuer URL.** The verifier fetches
   `<url>/.well-known/openid-configuration`, reads its `issuer` and `jwks_uri`,
@@ -9698,7 +10290,10 @@ when it does not (or on an error such as a missing flag or unreachable trust
 root).
 
 ```bash
-# Verify a bundle against a deployed issuer, digest-checking the artifact:
+# Default: verify against the hosted KiCI platform (no --trust-root needed):
+kici verify-attestation ./dist/app.tgz --bundle ./app.tgz.kici.json
+
+# Override the trust root to verify against a specific issuer:
 kici verify-attestation ./dist/app.tgz \
   --bundle ./app.tgz.kici.json \
   --trust-root https://platform.example/issuer
@@ -9709,7 +10304,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
 
@@ -9737,11 +10332,49 @@ attestations shows an empty state.
 
 <!-- /help:run-attestations -->
 
+## Browsing attestations across runs
+
+The **Attestations** page (in the org sidebar) lists every build-provenance
+attestation your organization has produced — not just one run's. It is the
+supply-chain audit surface: look up "who built `sha256:…`?" by digest, or browse
+and filter every attestation across all runs.
+
+<!-- help:attestations-list#browsing-attestations-across-runs -->
+
+The **Attestations** page lists every build-provenance attestation your organization has produced.
+
+- **Search** by artifact digest (exact `sha256:…`) or name to trace a specific artifact.
+- **Filter** by verification status, repository, workflow, job, or date.
+- Each row's **status badge** is the verdict KiCI recorded when the attestation was produced (`verified`, `failed`, `unverifiable`, or `pending`).
+
+Open a row for the parsed provenance statement and a live re-verification.
+
+<!-- /help:attestations-list -->
+
+The status badge here is the **server-side verdict**, computed once when the
+attestation was recorded (verify-at-ingest) — so the list stays fast at any
+size. `verified` means the signature, build identity, and build context all
+checked out against the provenance issuer; `failed` means verification ran and
+the bundle did not pass; `unverifiable` means no verdict could be computed (no
+provenance issuer configured, or its keys could not be read — not a forgery
+signal); `pending` means the verdict has not been computed yet.
+
+Opening a row leads to the **attestation detail page**:
+
+<!-- help:attestation-detail#browsing-attestations-across-runs -->
+
+This page shows the parsed provenance for one attestation.
+
+- **Builder identity, source, and build type** come from the signed SLSA statement.
+- The **stored badge** is the verdict recorded at build time; **Re-verify** runs the check live in your browser against the current signing keys.
+- **Download** exports the signed bundle for offline verification with `kici verify-attestation`.
+<!-- /help:attestation-detail -->
+
 ## 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.
 
 ---
@@ -9754,10 +10387,12 @@ 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.
 
+A job can bind several environments with `environments: ['staging', 'my-testing']`; the secret keys from all bound environments are merged in array order, with a later environment's value winning on a key collision. See [Multiple environments per job](https://docs.kici.dev/user/environments/#multiple-environments-per-job).
+
 ## Where secret values come from
 
 Secret values are written either through the dashboard or through `kici-admin` running against the orchestrator. The orchestrator operator decides — per organization — which surface accepts secret writes. From the workflow author's perspective, the resolution path at run time is identical either way; the difference is where you (or your ops team) **enter** the value.
@@ -9773,7 +10408,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.
@@ -9810,7 +10445,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
 
@@ -9968,7 +10603,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:
 
@@ -10001,9 +10636,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
 
@@ -10045,7 +10680,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.
 
 ---
 
@@ -10060,11 +10695,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
 
@@ -10136,9 +10771,9 @@ GitHub App "my-org" is live.
 
 | Flag                  | Effect                                                                                                                                                                                                                                                                                |
 | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--name <name>`       | The App name you _request_ on GitHub (required). GitHub assigns the final name + slug; the stored, displayed name always comes from GitHub (see [Display name and slug](#display-name-and-slug)).                                                                                     |
+| `--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](#self-hosted-webhook-url-override). |
+| `--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
@@ -10201,7 +10836,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`,
@@ -10213,7 +10848,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
@@ -10284,7 +10919,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
 
@@ -10379,7 +11014,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
@@ -10397,7 +11032,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
 
@@ -10480,12 +11115,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
 
 ---
@@ -10504,8 +11139,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)
 
@@ -10600,9 +11235,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.
 
 ---
@@ -10617,7 +11252,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.
@@ -10637,7 +11272,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?
@@ -10811,7 +11446,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.
 
@@ -10855,13 +11490,381 @@ 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/
 
 This document describes the key data flows through the KiCI architecture: webhook delivery, job execution, developer-initiated remote runs, dependency caching, re-run and cancel, trace ID propagation, internal event routing, and generic webhook ingestion.
 
-> **Lock file schema version:** The lock file uses schema version 21, which adds the `CheckMode` / `CheckStepOutcome` enums for check-mode step execution on top of v20's `LabelMatcher` (exact/regex) selectors for `runsOn`/`runsOnAll`/`excludeLabels`, v19's `maxParallel`/`failFast` fan-out concurrency, v18's `runsOnAll` host fan-out predicate and `onUnreachable` policy, v17's typed init presets (`mise` / `{ mise }`) and `auto` detection, v16's normalized approval config, v15's per-job init config, v14's declarative cache specs, v11's `LockInlineValue` for pure function inline evaluation, v10's simplified negative patterns (! prefix in repos/paths arrays), v9's global workflow repos matching, and v8's runsOn polymorphic type support.
+> **Lock file schema version:** The lock file uses schema version 29. The orchestrator rejects any fetched lock whose `schemaVersion` does not exactly match the engine version it was built against, so a stale lock must be recompiled with `kici compile` and pushed again after any SDK upgrade that bumps the schema.
 
 ## Webhook delivery flow
 
@@ -10892,7 +11895,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
 
@@ -10920,7 +11923,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
@@ -10958,7 +11961,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
 
@@ -11067,7 +12070,7 @@ Dep cache misses alone do **not** trigger a build job. Deps are platform-specifi
 
 ### Cross-source / no-contentHash workflows
 
-- **Lock files without `contentHash`** (schema v1) skip the source cache entirely; agents compile from source. Regenerate lock files with `kici compile` to enable caching. The current lock file schema version is 21.
+- **Lock files without `contentHash`** (schema v1) skip the source cache entirely; agents compile from source. Regenerate lock files with `kici compile` to enable caching. The current lock file schema version is 29.
 - **Cross-source / global-workflow dispatch** (a workflow registered against source A fired by a webhook on source B) bypasses both caches. The registration's lock file entry still carries `contentHash`, but the cross-source path always clone-and-installs — the eval temp dir doesn't ship `@kici-dev/sdk`. The execution agent still verifies `contentHash` against the cloned source for drift detection.
 
 ### Build deduplication
@@ -11081,7 +12084,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).
 
@@ -11113,9 +12116,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
 
@@ -11153,7 +12156,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.
 
@@ -11207,7 +12210,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
 
@@ -11635,7 +12638,7 @@ The compiler processes the workflow definition:
 
 ### Execution time (local test runner)
 
-When `kici test` runs a workflow:
+When `kici run local` runs a workflow:
 
 1. **SDK module resolution:** The runner resolves `setStepOutputsMap` / `setJobOutputsMap` from the same `@kici-dev/sdk` module instance that the workflow uses (ensures the proxy reads from the same map)
 2. **Map injection:** Fresh `OutputsMap` and `StepRefMap` are created and injected via `setStepOutputsMap()` / `setStepRefMap()` before each job
@@ -11701,15 +12704,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
 
 ---
 
@@ -11764,7 +12767,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`).
 
@@ -11903,13 +12906,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
 
@@ -11917,9 +12920,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
 
 ---