@kici-dev/compiler 0.1.14 → 0.1.16

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

@@ -12,7 +12,7 @@ Documentation for workflow authors -- people writing CI/CD pipelines in TypeScri
 
 ## Pages
 
-### [Getting started](getting-started.md)
+### [Getting started with KiCI](getting-started.md)
 
 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.
 
@@ -86,7 +86,7 @@ Cross-repo workflows that let a single workflow repo define jobs which run on ev
 
 ---
 
-## Getting started with KiCI
+## Getting started with workflows
 
 Source: https://docs.kici.dev/user/getting-started/
 
@@ -179,7 +179,7 @@ Create `.kici/workflows/ci.ts`:
 import { workflow, job, step, pr } from '@kici-dev/sdk';
 
 const lint = job('lint', {
-  runsOn: 'ubuntu-latest',
+  runsOn: 'linux',
   steps: [
     step('install', async ({ $ }) => {
       await $`pnpm install --frozen-lockfile`;
@@ -191,7 +191,7 @@ const lint = job('lint', {
 });
 
 const test = job('test', {
-  runsOn: 'ubuntu-latest',
+  runsOn: 'linux',
   needs: [lint],
   steps: [
     step('install', async ({ $ }) => {
@@ -264,9 +264,9 @@ Workflow: ci
   ✓ Matched trigger 1
   Jobs (2):
     lint
-      runs-on: ubuntu-latest
+      runs-on: linux
     test
-      runs-on: ubuntu-latest
+      runs-on: linux
 
 Decision Summary:
 
@@ -310,7 +310,7 @@ This updates `.kici/package.json` and generates (or updates) `package-lock.json`
 
 ### Dependency resolution contract
 
-Every `.kici/` dependency must be resolvable from the **single cloned repository**. When a job runs, the agent clones only this repository and installs `.kici/` dependencies with your repo's package manager (npm or pnpm — yarn is not yet supported and is rejected with an actionable error). A dependency that points outside the cloned repo cannot be resolved.
+Every `.kici/` dependency must be resolvable from the **single cloned repository**. When a job runs, the agent clones only this repository and installs `.kici/` dependencies with your repo's package manager (npm or pnpm; yarn is not supported — the agent rejects it with an actionable error). A dependency that points outside the cloned repo cannot be resolved.
 
 In practice:
 
@@ -525,7 +525,7 @@ A standard lint-then-test pipeline using job dependencies (`needs`):
 import { workflow, job, step, pr } from '@kici-dev/sdk';
 
 const lint = job('lint', {
-  runsOn: 'ubuntu-latest',
+  runsOn: 'linux',
   steps: [
     step('install', async ({ $ }) => {
       await $`pnpm install --frozen-lockfile`;
@@ -538,7 +538,7 @@ const lint = job('lint', {
 });
 
 const test = job('test', {
-  runsOn: 'ubuntu-latest',
+  runsOn: 'linux',
   needs: [lint],
   steps: [
     step('install', async ({ $ }) => {
@@ -551,7 +551,7 @@ const test = job('test', {
 });
 
 const typecheck = job('typecheck', {
-  runsOn: 'ubuntu-latest',
+  runsOn: 'linux',
   needs: [lint],
   steps: [
     step('install', async ({ $ }) => {
@@ -608,7 +608,7 @@ const trigger = pr({
 });
 
 const build = job('build', {
-  runsOn: 'ubuntu-latest',
+  runsOn: 'linux',
   steps: [
     step('build', async ({ $ }) => {
       await $`pnpm build`;
@@ -643,7 +643,7 @@ import { workflow, job, step, push } from '@kici-dev/sdk';
 
 // Deploy on pushes to main
 const deploy = job('deploy', {
-  runsOn: 'ubuntu-latest',
+  runsOn: 'linux',
   steps: [
     step('deploy', async ({ $ }) => {
       await $`pnpm build`;
@@ -687,7 +687,7 @@ A workflow can respond to multiple trigger types:
 import { workflow, job, step, pr, push } from '@kici-dev/sdk';
 
 const test = job('test', {
-  runsOn: 'ubuntu-latest',
+  runsOn: 'linux',
   steps: [
     step('test', async ({ $ }) => {
       await $`pnpm test`;
@@ -719,7 +719,7 @@ export default workflow('hello-world', {
   on: dispatch(),
   jobs: [
     job('greet', {
-      runsOn: 'ubuntu-latest',
+      runsOn: 'linux',
       steps: [
         step('say-hello', async ({ $ }) => {
           await $`echo "Hello, World!"`;
@@ -777,7 +777,7 @@ Rules control whether a workflow or job runs. Use `rule()` for conditions that m
 import { workflow, job, step, pr, rule } from '@kici-dev/sdk';
 
 const test = job('test', {
-  runsOn: 'ubuntu-latest',
+  runsOn: 'linux',
   steps: [
     step('test', async ({ $ }) => {
       await $`pnpm test`;
@@ -802,7 +802,7 @@ export default workflow('ci', {
 import { workflow, job, step, pr, rule, skip } from '@kici-dev/sdk';
 
 const unitTests = job('unit-tests', {
-  runsOn: 'ubuntu-latest',
+  runsOn: 'linux',
   steps: [
     step('test', async ({ $ }) => {
       await $`pnpm test:unit`;
@@ -811,7 +811,7 @@ const unitTests = job('unit-tests', {
 });
 
 const e2eTests = job('e2e-tests', {
-  runsOn: 'ubuntu-latest',
+  runsOn: 'linux',
   rules: [
     // Skip E2E when only docs change
     skip('docs only', async (ctx) => {
@@ -862,7 +862,7 @@ Run a job for each value in an array:
 import { workflow, job, step, push } from '@kici-dev/sdk';
 
 const test = job('test', {
-  runsOn: 'ubuntu-latest',
+  runsOn: 'linux',
   matrix: ['18', '20', '22'],
   steps: [
     step('test', async ({ $, matrix }) => {
@@ -886,14 +886,14 @@ Use an object to define multiple dimensions. KiCI expands all combinations (capp
 
 ```typescript
 const test = job('test', {
-  runsOn: 'ubuntu-latest',
+  runsOn: ['linux', 'kici:agent:container'],
   matrix: {
-    os: ['ubuntu-latest', 'macos-latest'],
+    os: ['linux', 'arm64'],
     node: ['18', '20', '22'],
   },
   steps: [
     step('test', async ({ $, matrix }) => {
-      // matrix.os = 'ubuntu-latest' | 'macos-latest'
+      // matrix.os = 'linux' | 'arm64'
       // matrix.node = '18' | '20' | '22'
       await $`echo "Testing on ${matrix!.os} with Node ${matrix!.node}"`;
       await $`pnpm test`;
@@ -904,21 +904,27 @@ const test = job('test', {
 
 This creates 6 job instances (2 OS x 3 Node versions).
 
+> **Labels are customer-defined.** `runsOn` values such as `linux` or `arm64` are scaler
+> labels **you** define in your orchestrator's `labelSets` — they are matched by subset
+> semantics, not by a hosted-runner name. You can also target reserved auto-injected labels
+> in the `kici:` namespace (e.g. `kici:agent:firecracker`, `kici:agent:container`) to pin a
+> job to a specific backend type.
+
 ### Include and exclude
 
 Fine-tune matrix combinations:
 
 ```typescript
 const test = job('test', {
-  runsOn: 'ubuntu-latest',
+  runsOn: 'linux',
   matrix: {
-    os: ['ubuntu-latest', 'macos-latest', 'windows-latest'],
+    os: ['linux', 'arm64', 'windows'],
     node: ['18', '20', '22'],
   },
   // Remove specific combination
-  exclude: [{ os: 'windows-latest', node: '18' }],
+  exclude: [{ os: 'windows', node: '18' }],
   // Add specific combination not in the matrix
-  include: [{ os: 'ubuntu-latest', node: '23' }],
+  include: [{ os: 'linux', node: '23' }],
   steps: [
     step('test', async ({ $ }) => {
       await $`pnpm test`;
@@ -935,7 +941,7 @@ Compute matrix values at runtime using an async function:
 
 ```typescript
 const test = job('test', {
-  runsOn: 'ubuntu-latest',
+  runsOn: 'linux',
   matrix: async ({ $ }) => {
     // Discover packages in a monorepo
     const result = await $`ls packages/`;
@@ -984,7 +990,7 @@ const discoverAndTest: DynamicJobFn = async ({ $ }) => {
 
   return packages.map((pkg) =>
     job(`test-${pkg}`, {
-      runsOn: 'ubuntu-latest',
+      runsOn: 'linux',
       steps: [
         step('test', async ({ $ }) => {
           await $`cd packages/${pkg} && pnpm test`;
@@ -1006,7 +1012,7 @@ The `jobs` array accepts both static `Job` objects and `DynamicJobFn` functions:
 
 ```typescript
 const lint = job('lint', {
-  runsOn: 'ubuntu-latest',
+  runsOn: 'linux',
   steps: [
     step('lint', async ({ $ }) => {
       await $`pnpm lint`;
@@ -1036,7 +1042,7 @@ const prTrigger = pr({ target: 'main', paths: ['src/**', 'packages/**', '!**/*.m
 const pushTrigger = push({ branches: 'main' });
 
 const lint = job('lint', {
-  runsOn: 'ubuntu-latest',
+  runsOn: 'linux',
   steps: [
     step('install', async ({ $ }) => {
       await $`pnpm install --frozen-lockfile`;
@@ -1048,7 +1054,7 @@ const lint = job('lint', {
 });
 
 const test = job('test', {
-  runsOn: 'ubuntu-latest',
+  runsOn: 'linux',
   needs: [lint],
   matrix: { node: ['18', '20', '22'] },
   steps: [
@@ -1059,7 +1065,7 @@ const test = job('test', {
 });
 
 const deploy = job('deploy', {
-  runsOn: 'ubuntu-latest',
+  runsOn: 'linux',
   needs: [test],
   rules: [
     // Only deploy from push events (not PRs)
@@ -1114,7 +1120,7 @@ export const deploy = workflow('deploy', {
   on: push({ branches: 'main' }),
   jobs: [
     job('deploy', {
-      runsOn: 'ubuntu-latest',
+      runsOn: 'linux',
       steps: [
         step('deploy', async ({ $ }) => {
           await $`./scripts/deploy.sh`;
@@ -1129,7 +1135,7 @@ export const postDeploy = workflow('post-deploy', {
   on: workflowComplete({ name: 'deploy', status: ['success'] }),
   jobs: [
     job('notify', {
-      runsOn: 'ubuntu-latest',
+      runsOn: 'linux',
       steps: [
         step('slack', async ({ $ }) => {
           await $`./scripts/notify-slack.sh "Deploy succeeded"`;
@@ -1152,7 +1158,7 @@ export const deploy = workflow('deploy', {
   on: push({ branches: 'main' }),
   jobs: [
     job('deploy', {
-      runsOn: 'ubuntu-latest',
+      runsOn: 'linux',
       steps: [
         step('deploy', async ({ $ }) => {
           await $`./scripts/deploy.sh`;
@@ -1173,7 +1179,7 @@ export const postDeploy = workflow('post-deploy', {
   on: kiciEvent({ name: 'deploy-complete', match: { '$.env': 'prod' } }),
   jobs: [
     job('smoke-test', {
-      runsOn: 'ubuntu-latest',
+      runsOn: 'linux',
       steps: [
         step('test', async ({ $ }) => {
           await $`./scripts/smoke-test.sh`;
@@ -1198,7 +1204,7 @@ export default workflow('on-argocd-deploy', {
   on: genericWebhook({ source: 'argocd', events: ['deploy.success'] }),
   jobs: [
     job('post-deploy', {
-      runsOn: 'ubuntu-latest',
+      runsOn: 'linux',
       steps: [
         step('verify', async ({ $, rawPayload }) => {
           // rawPayload contains the full webhook body from ArgoCD
@@ -1232,7 +1238,7 @@ export default workflow('stripe-invoice-handler', {
   }),
   jobs: [
     job('process-invoice', {
-      runsOn: 'ubuntu-latest',
+      runsOn: 'linux',
       steps: [
         step('extract-customer', async ({ $, log }) => {
           log.info('Processing paid invoice from Stripe');
@@ -1289,7 +1295,7 @@ export default workflow('on-forgejo-push', {
   }),
   jobs: [
     job('react-to-push', {
-      runsOn: 'ubuntu-latest',
+      runsOn: 'linux',
       steps: [
         step('log', async ({ rawPayload, log }) => {
           const ref = (rawPayload as { ref?: string }).ref;
@@ -1311,7 +1317,7 @@ Manual-clone example (pattern 2) using an SSH deploy key:
 
 ```typescript
 job('forgejo-ci', {
-  runsOn: 'ubuntu-latest',
+  runsOn: 'linux',
   checkout: false, // skip framework clone
   steps: [
     step('clone', async ({ $, ctx, rawPayload }) => {
@@ -1356,7 +1362,7 @@ kici-admin source add generic \
   --rate-limit 120
 
 # Patch the verificationConfig to use GitHub's signature header
-# (the CLI does not expose --signature-header yet; use the admin REST API):
+# (the CLI has no --signature-header flag; use the admin REST API):
 curl -X PATCH https://<orchestrator>/api/v1/admin/generic-sources/<sourceId> \
   -H "Authorization: Bearer <admin-token>" \
   -H "Content-Type: application/json" \
@@ -1383,7 +1389,7 @@ export default workflow('on-github-repo-push', {
   }),
   jobs: [
     job('notify', {
-      runsOn: 'ubuntu-latest',
+      runsOn: 'linux',
       checkout: false, // no App token -> skip auto-clone
       steps: [
         step('log', async ({ rawPayload, log }) => {
@@ -1502,7 +1508,7 @@ const install = step('install', async ({ $ }) => {
 });
 
 const fullTest = job('full-test', {
-  runsOn: 'ubuntu-latest',
+  runsOn: 'linux',
   steps: [
     install,
     step('test', async ({ $ }) => {
@@ -1515,7 +1521,7 @@ const fullTest = job('full-test', {
 });
 
 const publish = job('publish-nightly', {
-  runsOn: 'ubuntu-latest',
+  runsOn: 'linux',
   needs: [fullTest],
   steps: [
     install,
@@ -1559,7 +1565,7 @@ export const build = workflow('build', {
   on: push({ branches: 'main' }),
   jobs: [
     job('test', {
-      runsOn: 'ubuntu-latest',
+      runsOn: 'linux',
       steps: [
         step('install', async ({ $ }) => {
           await $`pnpm install --frozen-lockfile`;
@@ -1580,7 +1586,7 @@ export const deploy = workflow('deploy-on-success', {
   on: workflowComplete({ name: 'build', status: ['success'] }),
   jobs: [
     job('deploy', {
-      runsOn: 'ubuntu-latest',
+      runsOn: 'linux',
       steps: [
         step('deploy-staging', async ({ $ }) => {
           await $`./scripts/deploy.sh staging`;
@@ -1627,7 +1633,7 @@ export const testSuite = workflow('test-suite', {
   on: push({ branches: 'main' }),
   jobs: [
     job('test', {
-      runsOn: 'ubuntu-latest',
+      runsOn: 'linux',
       steps: [
         step('install', async ({ $ }) => {
           await $`pnpm install --frozen-lockfile`;
@@ -1653,7 +1659,7 @@ export const autoDeploy = workflow('auto-deploy', {
   on: kiciEvent({ name: 'tests-passed' }),
   jobs: [
     job('deploy', {
-      runsOn: 'ubuntu-latest',
+      runsOn: 'linux',
       steps: [
         step('deploy', async ({ $ }) => {
           await $`./scripts/deploy.sh`;
@@ -1682,6 +1688,149 @@ export const autoDeploy = workflow('auto-deploy', {
 
 # SDK reference
 
+## Caching
+
+Source: https://docs.kici.dev/user/sdk/caching/
+
+KiCI ships a general-purpose cache for any files or directories your workflow produces — compiled artifacts, downloaded toolchains, package manager stores, build outputs. A cache entry is keyed, immutable once written, and shared across runs of the same repository so a later run can restore what an earlier run produced instead of recomputing it.
+
+Two surfaces drive the same cache:
+
+- **Declarative** — a `cache` field on a job or a step. The runtime restores before the work runs and saves after it succeeds, with no code in your step body.
+- **Imperative** — `ctx.cache.restore(spec)` / `ctx.cache.save(spec)` inside a step body, for fine-grained control over when restore and save happen.
+
+The cache is backed by the orchestrator's object storage. Entries are isolated per organization and per ref scope (see [Isolation](#isolation)); no other tenant can read your cache, and an untrusted/fork ref can never poison the cache a trusted branch reads.
+
+## CacheSpec
+
+Both surfaces take the same shape:
+
+```typescript
+interface CacheSpec {
+  /** Exact cache key. First save wins; re-saving an existing key is a no-op. */
+  key: string;
+  /** Files/directories to cache. Repo-root-relative or `~`-prefixed. */
+  paths: string[];
+  /** Ordered prefix fallbacks for partial restore; newest matching entry wins. */
+  restoreKeys?: string[];
+}
+```
+
+- **`key`** is the exact cache key. It is **immutable** — the first save under a given key wins, and any later save under the same exact key is a no-op (the existing entry is never overwritten). Build keys from inputs that change when the cached content should change, e.g. a hash of your lockfile: `` key: `deps-${await ctx.$`sha256sum pnpm-lock.yaml`}` ``.
+- **`paths`** are the files and directories to archive, repo-root-relative or `~`-prefixed (the agent expands `~` to the workspace home). At least one path is required.
+- **`restoreKeys`** are ordered **prefix** fallbacks tried only when the exact `key` misses on restore. Each prefix is matched against existing entries; the **newest** matching entry wins. This lets a run that changed its lockfile still restore the closest previous cache and rebuild incrementally.
+
+## Declarative cache
+
+Add a `cache` field to a job or a step. It accepts one `CacheSpec` or an array of them. The runtime restores every spec before the job/step runs (surfaced as a `cache:restore` pseudo-step) and saves every spec after it completes successfully (surfaced as a `cache:save` pseudo-step):
+
+```typescript
+import { job } from '@kici-dev/sdk';
+
+job('build', {
+  runsOn: 'linux-x64',
+  cache: {
+    key: 'mise-tools-v1',
+    paths: ['~/.local/share/mise'],
+  },
+  steps: [
+    step('install-tools', async (ctx) => {
+      await ctx.$`mise install`;
+    }),
+    step('build', async (ctx) => {
+      await ctx.$`mise exec -- pnpm build`;
+    }),
+  ],
+});
+```
+
+Step-level cache scopes the restore/save to a single step:
+
+```typescript
+step('deps', {
+  cache: { key: `npm-${lockfileHash}`, paths: ['node_modules'], restoreKeys: ['npm-'] },
+  run: async (ctx) => {
+    await ctx.$`pnpm install --frozen-lockfile`;
+  },
+});
+```
+
+On a cache **hit**, the archived paths are restored before the step body runs, so `pnpm install` sees a warm `node_modules`. On a **miss**, the step runs cold and the resulting paths are saved under the exact key for the next run.
+
+## Imperative cache (`ctx.cache`)
+
+When you need to decide at runtime whether to restore or save — for example, save only when a build actually changed something — use the imperative API on the step context:
+
+```typescript
+step('build', async (ctx) => {
+  const result = await ctx.cache.restore({
+    key: `build-${sourceHash}`,
+    paths: ['dist'],
+    restoreKeys: ['build-'],
+  });
+
+  if (result.hit) {
+    ctx.log.info(`restored cache (matched ${result.matchedKey})`);
+  }
+
+  await ctx.$`pnpm build`;
+
+  await ctx.cache.save({ key: `build-${sourceHash}`, paths: ['dist'] });
+});
+```
+
+`restore(spec)` returns `{ hit, matchedKey? }`:
+
+- `hit` is `true` when the exact `key` matched **or** a `restoreKeys` prefix matched.
+- `matchedKey` is the full key that actually matched — the exact key on a direct hit, or the full key of the matched prefix entry on a fallback hit.
+
+`save(spec)` archives `spec.paths` under `spec.key`. Like the declarative surface, it is immutable: the first save under an exact key wins, and re-saving the same key is a no-op.
+
+## Restore semantics
+
+A restore resolves in this order:
+
+1. **Exact key.** If an entry exists under the exact `key`, it is restored and `matchedKey === key`.
+2. **restoreKeys prefix fallback.** Each `restoreKeys` prefix is tried in order. Within a prefix, the **newest** matching entry wins; `matchedKey` is that entry's full key.
+3. **Miss.** If nothing matches, `hit` is `false` and no paths are restored.
+
+This mirrors the familiar lockfile-hash pattern: key the entry on the exact lockfile hash, and add a `restoreKeys` prefix so a changed lockfile still restores the most recent prior cache to rebuild from.
+
+## Immutability
+
+Cache keys are write-once. The **first** save under an exact key wins; every subsequent save under that same exact key is a no-op and the original bytes are preserved. To publish new content, use a new key (typically by including a content hash in the key). Immutability is what makes a cache hit safe to trust — the bytes behind a given key never change after they are first written.
+
+## Isolation
+
+Each cache entry is scoped to your organization and to the ref's trust level:
+
+- **Trusted refs** (your repository's own branches, default branch) read and write a **shared** scope visible to the whole org for that repository.
+- **Untrusted / fork refs** read the shared scope as a fallback but write to an **isolated** per-run scope. A fork build can therefore benefit from a warm cache the trusted branch produced, but can never write into the shared scope — so a malicious fork cannot poison the cache a trusted branch later restores.
+
+No tenant can read another tenant's cache; the org boundary is enforced in the cache key namespace.
+
+## Eviction
+
+Cache storage is bounded per organization. Two mechanisms keep it bounded:
+
+- **Quota** — when a save pushes the org over its byte quota (`KICI_USER_CACHE_QUOTA_BYTES`, default 5 GiB), the oldest entries are evicted until the org is back under quota.
+- **TTL** — entries unused for `KICI_USER_CACHE_TTL_MS` (default 7 days) expire. The TTL refreshes on read (touch-on-read), so an actively used cache stays warm.
+
+Both knobs are operator-configured on the orchestrator — see [orchestrator storage layout](../../operator/orchestrator/storage-layout.md).
+
+## 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.
+
+## 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
+
+---
+
 ## SDK reference: core
 
 Source: https://docs.kici.dev/user/sdk/core/
@@ -1698,21 +1847,22 @@ function workflow(name: string, options: WorkflowOptions): Workflow;
 
 **Parameters:**
 
-| Parameter             | Type                                                                   | Required | Description                                                                                                                                     |
-| --------------------- | ---------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `name`                | `string`                                                               | yes      | Unique workflow name                                                                                                                            |
-| `options.jobs`        | `JobOrFactory[]`                                                       | yes      | Static jobs and/or dynamic job generators                                                                                                       |
-| `options.on`          | `Trigger \| Trigger[]`                                                 | no       | When the workflow should trigger                                                                                                                |
-| `options.rules`       | `Rule[]`                                                               | no       | Conditions that must pass for execution                                                                                                         |
-| `options.description` | `string`                                                               | no       | Human-readable description                                                                                                                      |
-| `options.hashFiles`   | `string[]`                                                             | no       | Extra repo-relative paths or globs mixed into the workflow content hash. Changes invalidate the source cache.                                   |
-| `options.registries`  | `Registry[]`                                                           | no       | Private npm registries the agent authenticates against before `npm install`. Each `tokenSecret` uses qualified `<environment>:<secret>` syntax. |
-| `options.installEnv`  | `string[]`                                                             | no       | Qualified `<environment>:<secret>` refs projected as env vars onto the install subprocess (used with a customer-committed `.kici/.npmrc`).      |
-| `options.onCancel`    | `HookInput`                                                            | no       | Runs when the workflow is cancelled                                                                                                             |
-| `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).                                                                              |
+| Parameter             | Type                                                                   | Required | Description                                                                                                                                                 |
+| --------------------- | ---------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`                | `string`                                                               | yes      | Unique workflow name                                                                                                                                        |
+| `options.jobs`        | `JobOrFactory[]`                                                       | yes      | Static jobs and/or dynamic job generators                                                                                                                   |
+| `options.on`          | `Trigger \| Trigger[]`                                                 | no       | When the workflow should trigger                                                                                                                            |
+| `options.rules`       | `Rule[]`                                                               | no       | Conditions that must pass for execution                                                                                                                     |
+| `options.description` | `string`                                                               | no       | Human-readable description                                                                                                                                  |
+| `options.hashFiles`   | `string[]`                                                             | no       | Extra repo-relative paths or globs mixed into the workflow content hash. Changes invalidate the source cache.                                               |
+| `options.registries`  | `Registry[]`                                                           | no       | Private npm registries the agent authenticates against before `npm install`. Each `tokenSecret` uses qualified `<environment>:<secret>` syntax.             |
+| `options.installEnv`  | `string[]`                                                             | no       | Qualified `<environment>:<secret>` refs projected as env vars onto the install subprocess (used with a customer-committed `.kici/.npmrc`).                  |
+| `options.onCancel`    | `HookInput`                                                            | no       | Runs when the workflow is cancelled                                                                                                                         |
+| `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). |
 
 **Returns:** `Workflow` -- an immutable workflow definition.
 
@@ -1738,45 +1888,47 @@ function job(options: JobOptions): Job;
 
 **Parameters:**
 
-| Parameter                  | Type                                                            | Required             | Description                                                                                                                 |
-| -------------------------- | --------------------------------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `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.rules`            | `Rule[]`                                                        | no                   | Conditions for conditional execution                                                                                        |
-| `options.description`      | `string`                                                        | no                   | Human-readable description                                                                                                  |
-| `options.matrix`           | `Matrix`                                                        | no                   | Matrix configuration for job expansion                                                                                      |
-| `options.include`          | `MatrixInclude[]`                                               | no                   | Additional matrix combinations                                                                                              |
-| `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.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.resources`        | `ResourceRequest`                                               | no                   | Per-job CPU / memory request and limit. See [Per-job resources](#per-job-resources) below.                                  |
+| Parameter                  | Type                                                            | Required             | Description                                                                                                                                              |
+| -------------------------- | --------------------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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.rules`            | `Rule[]`                                                        | no                   | Conditions for conditional execution                                                                                                                     |
+| `options.description`      | `string`                                                        | no                   | Human-readable description                                                                                                                               |
+| `options.matrix`           | `Matrix`                                                        | no                   | Matrix configuration for job expansion                                                                                                                   |
+| `options.include`          | `MatrixInclude[]`                                               | no                   | Additional matrix combinations                                                                                                                           |
+| `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.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`             | `GenericInitConfig \| GenericInitConfig[] \| false`             | no                   | Per-job initialization run after clone, before steps -- provisions a toolchain. See [Per-job init](#per-job-init) below.                                 |
 
 **Returns:** `Job` -- an immutable job definition.
 
 ```typescript
 // Named job
 const build = job('build', {
-  runsOn: 'ubuntu-latest',
+  runsOn: 'linux',
   steps: [checkout, install, compile],
   needs: [lint],
 });
 
 // Anonymous job (auto-generated UUID name)
 const build = job({
-  runsOn: 'ubuntu-latest',
+  runsOn: 'linux',
   steps: [checkout, install],
 });
 ```
@@ -1802,7 +1954,7 @@ runsOn: { labels: ['linux', 'docker'], exclude: ['gpu'] }
 - **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 operator guide](/operator/orchestrator/auto-scaler/overview-and-config/#mandatory-labels-k8s-style-opt-in-gate) 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](../../operator/orchestrator/auto-scaler/common-config.md#mandatory--exclude-labels) for details.
 
 ```typescript
 // Route to any Linux agent that does NOT have the 'gpu' label
@@ -1899,6 +2051,65 @@ Per-backend kernel enforcement of `limits`:
 - **Firecracker backend:** always enforced. Fractional CPU rounds up to the nearest integer vCPU.
 - **Bare-metal backend:** advisory by default — the scaler caps still apply, but no cgroup is created. Operators can opt in to kernel enforcement via `enforceCgroups: true` on the scaler entry.
 
+### Per-job init
+
+`options.init` declares a hand-written command that runs **after the repo is cloned and before the job's steps execute**. Its purpose is to provision a repo-declared toolchain (a `mise` toolchain, a custom setup script, a language runtime) and put it on the environment every subsequent step sees.
+
+```typescript
+import { workflow, job, step, push } from '@kici-dev/sdk';
+
+export const build = workflow('build', {
+  on: [push()],
+  jobs: [
+    job('build', {
+      runsOn: 'linux',
+      init: {
+        run: `
+          set -euo pipefail
+          command -v mise >/dev/null || curl -fsSL https://mise.run | sh
+          export PATH="$HOME/.local/bin:$PATH"
+          mise install
+          mise env -s bash | sed -n 's/^export //p' >> "$KICI_ENV"
+          echo "$HOME/.local/share/mise/shims" >> "$KICI_PATH"
+        `,
+        cache: { key: 'mise-jq-1.7.1', paths: ['~/.local/share/mise'] },
+        timeout: 600_000,
+      },
+      steps: [
+        step('show-jq-version', async (ctx) => {
+          // jq is on PATH because the init phase appended the mise shims dir to $KICI_PATH.
+          const { stdout } = await ctx.$`jq --version`;
+          ctx.log.info(`jq version: ${stdout.trim()}`);
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+**`GenericInitConfig` shape:**
+
+| Field     | Type                    | Required | Description                                                                                                                                    |
+| --------- | ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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).           |
+| `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.                                                                                         |
+
+**The `$KICI_ENV` / `$KICI_PATH` handoff.** The init command does not mutate the step environment directly. Instead it writes what it wants visible to later steps to two files the agent allocates and exposes as environment variables:
+
+- **`$KICI_ENV`** -- append one `KEY=value` line per environment variable. The agent reads the file after the command and makes each variable available to every subsequent step.
+- **`$KICI_PATH`** -- append one directory per line. The agent prepends each directory to `PATH` for every subsequent step.
+
+The agent reads both files after the command succeeds, applies the delta, and the resulting environment is visible to all steps that follow (and to any later init command).
+
+**Failure before steps.** If the init command exits non-zero or exceeds its `timeout`, the job **fails before any step runs** -- the init surfaces as a failed `init:<n>` pseudo-step in the run timeline (alongside the step list), its logs are attached, and the step loop never executes. This makes a broken toolchain a clear, early failure rather than a confusing mid-run error.
+
+**Arrays run in order.** Passing `GenericInitConfig[]` runs the inits sequentially; each one's `$KICI_ENV` / `$KICI_PATH` delta is applied before the next runs, so a later init sees an earlier init's tools on `PATH`. The first init to fail stops the sequence and fails the job.
+
+**`init: false`** is an explicit opt-out (reserved for a future auto-detect layer); it behaves the same as omitting `init`.
+
 ## Step & job authoring patterns
 
 KiCI supports several authoring patterns for steps and jobs to reduce boilerplate and improve developer experience.
@@ -1997,6 +2208,44 @@ const deploy = job('deploy', {
 
 The `run` function is stored as the job's only step with an auto-generated name (`step-1`). `run` and `steps` are mutually exclusive -- providing both throws an error.
 
+### Timeouts
+
+`timeout` (milliseconds) can be set at three levels. Each level caps **its own scope** independently — a workflow or job timeout is a separate wall-clock cap, **not** a default that flows down to steps.
+
+| Level        | Field                        | Caps                                                   | Enforced by      | On breach                                                         |
+| ------------ | ---------------------------- | ------------------------------------------------------ | ---------------- | ----------------------------------------------------------------- |
+| **step**     | `step(..., { timeout })`     | A single step's wall-clock.                            | the agent        | The step fails; falls back to the 30-minute default when unset.   |
+| **job**      | `job(..., { timeout })`      | The job's total wall-clock (init + all steps + hooks). | the agent        | The job is aborted and reported failed with a "timed out" reason. |
+| **workflow** | `workflow(..., { timeout })` | The whole run's wall-clock across all jobs.            | the orchestrator | The run is cancelled with a "timed out" reason.                   |
+
+```typescript
+export default workflow('ci', {
+  timeout: 1_800_000, // whole run must finish within 30 minutes
+  jobs: [
+    job('build', {
+      runsOn: 'linux',
+      timeout: 600_000, // this job (init + steps + hooks) within 10 minutes
+      steps: [
+        step('compile', {
+          timeout: 120_000, // this single step within 2 minutes
+          run: async (ctx) => {
+            await ctx.$`make build`;
+          },
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+**Precedence — each scope caps its own scope.** The three timeouts are independent caps, not a fallback chain:
+
+- A **step** with no `timeout` falls back to the 30-minute agent default, regardless of the job or workflow timeout. A job timeout never becomes a step's default.
+- A **job** `timeout` bounds the job's total wall-clock (its init, every step including their own per-step timeouts, and its hooks). It does not change any step's individual cap.
+- A **workflow** `timeout` is a run-level deadline. The orchestrator records it when the run starts and cancels the run if its wall-clock exceeds the timeout, even when individual jobs and steps are still within their own caps.
+
+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.
+
 ### Output chaining
 
 Steps and jobs can access outputs from preceding steps/jobs using two patterns.
@@ -2169,6 +2418,354 @@ These IDs are stable as long as the order of unnamed entries does not change. Ad
 
 ---
 
+## Event payload reference
+
+Source: https://docs.kici.dev/user/sdk/event-payloads/
+
+<!-- Generated by scripts/docs-gen-event-payloads.ts — do not edit by hand. Regenerate: pnpm docs:gen:events -->
+
+## The envelope
+
+The normalized event envelope is the single event contract in KiCI. Rules receive it as `ctx.event`, and every dynamic function — `environment:`, `env:`, and `concurrencyGroup:` resolvers, generated jobs, and a workflow's `concurrency.group` — receives the same envelope as its argument.
+
+Narrow on the `type` field to branch per trigger kind (`if (event.type === 'push')`). The raw provider webhook body is nested at `payload`; the typed variants below describe its shape per event type.
+
+These fields are present on every envelope (the `EventBase` shape):
+
+| Field             | Type                      | Description                                                                     |
+| ----------------- | ------------------------- | ------------------------------------------------------------------------------- |
+| `type`            | `string`                  | Normalized event type discriminant.                                             |
+| `action?`         | `string`                  | Sub-action (e.g. 'opened', 'created', 'submitted').                             |
+| `targetBranch?`   | `string`                  | Target branch (push target, PR base, or default branch).                        |
+| `sourceBranch?`   | `string`                  | Source branch (PR head branch). Only set for PR-like events.                    |
+| `provider?`       | `string`                  | Provider that originated this event.                                            |
+| `isForkPR?`       | `boolean`                 | Whether this PR comes from a fork. Only set for PR-like events.                 |
+| `baseBranch?`     | `string`                  | Base branch ref for PR events.                                                  |
+| `senderUsername?` | `string`                  | Sender username from the webhook payload.                                       |
+| `sourceRepo?`     | `string`                  | Repository identifier (e.g. "owner/repo").                                      |
+| `changedFiles?`   | `string[]`                | Files changed in this event (for path filtering).                               |
+| `payload?`        | `Record<string, unknown>` | Raw webhook payload from the provider. May be absent in flattened event forms.  |
+| `[key: string]`   | `unknown`                 | Index signature for backward compatibility — untyped fields resolve to unknown. |
+
+## Event types
+
+One section per member of the `EventPayload` union. The heading is the `type` literal; the table lists the fields of that event's `payload` property when it declares a typed shape.
+
+### `pull_request`
+
+Carried by `PullRequestEventPayload`. The `payload` property has the following shape:
+
+| Field           | Type                | Description |
+| --------------- | ------------------- | ----------- |
+| `action`        | `string`            |             |
+| `number`        | `number`            |             |
+| `pull_request`  | `GitHubPullRequest` |             |
+| `repository`    | `GitHubRepository`  |             |
+| `sender`        | `GitHubUser`        |             |
+| `[key: string]` | `unknown`           |             |
+
+### `push`
+
+Carried by `PushEventPayload`. The `payload` property has the following shape:
+
+| Field           | Type               | Description |
+| --------------- | ------------------ | ----------- |
+| `ref`           | `string`           |             |
+| `after`         | `string`           |             |
+| `before`        | `string`           |             |
+| `head_commit?`  | `GitHubCommit`     |             |
+| `commits?`      | `GitHubCommit[]`   |             |
+| `repository`    | `GitHubRepository` |             |
+| `sender?`       | `GitHubUser`       |             |
+| `forced?`       | `boolean`          |             |
+| `[key: string]` | `unknown`          |             |
+
+### `tag`
+
+Carried by `TagEventPayload`. The `payload` property has the following shape:
+
+| Field           | Type               | Description |
+| --------------- | ------------------ | ----------- |
+| `ref`           | `string`           |             |
+| `after`         | `string`           |             |
+| `repository`    | `GitHubRepository` |             |
+| `sender?`       | `GitHubUser`       |             |
+| `[key: string]` | `unknown`          |             |
+
+### `comment`
+
+Carried by `CommentEventPayload`. The `payload` property has the following shape:
+
+| Field           | Type                                                                                 | Description |
+| --------------- | ------------------------------------------------------------------------------------ | ----------- |
+| `action`        | `string`                                                                             |             |
+| `comment`       | `GitHubComment`                                                                      |             |
+| `issue?`        | `{ number: number; title?: string; pull_request?: unknown; [key: string]: unknown }` |             |
+| `repository`    | `GitHubRepository`                                                                   |             |
+| `sender`        | `GitHubUser`                                                                         |             |
+| `[key: string]` | `unknown`                                                                            |             |
+
+### `review`
+
+Carried by `ReviewEventPayload`. The `payload` property has the following shape:
+
+| Field           | Type                | Description |
+| --------------- | ------------------- | ----------- |
+| `action`        | `string`            |             |
+| `review`        | `GitHubReview`      |             |
+| `pull_request`  | `GitHubPullRequest` |             |
+| `repository`    | `GitHubRepository`  |             |
+| `sender`        | `GitHubUser`        |             |
+| `[key: string]` | `unknown`           |             |
+
+### `review_comment`
+
+Carried by `ReviewCommentEventPayload`. The `payload` property has the following shape:
+
+| Field           | Type                | Description |
+| --------------- | ------------------- | ----------- |
+| `action`        | `string`            |             |
+| `comment`       | `GitHubComment`     |             |
+| `pull_request`  | `GitHubPullRequest` |             |
+| `repository`    | `GitHubRepository`  |             |
+| `sender`        | `GitHubUser`        |             |
+| `[key: string]` | `unknown`           |             |
+
+### `release`
+
+Carried by `ReleaseEventPayload`. The `payload` property has the following shape:
+
+| Field           | Type               | Description |
+| --------------- | ------------------ | ----------- |
+| `action`        | `string`           |             |
+| `release`       | `GitHubRelease`    |             |
+| `repository`    | `GitHubRepository` |             |
+| `sender`        | `GitHubUser`       |             |
+| `[key: string]` | `unknown`          |             |
+
+### `dispatch`
+
+Carried by `DispatchEventPayload`. The `payload` property has the following shape:
+
+| Field             | Type                      | Description |
+| ----------------- | ------------------------- | ----------- |
+| `action`          | `string`                  |             |
+| `client_payload?` | `Record<string, unknown>` |             |
+| `repository`      | `GitHubRepository`        |             |
+| `sender?`         | `GitHubUser`              |             |
+| `[key: string]`   | `unknown`                 |             |
+
+### `create`
+
+Carried by `CreateEventPayload`. The `payload` property has the following shape:
+
+| Field           | Type               | Description |
+| --------------- | ------------------ | ----------- |
+| `ref`           | `string`           |             |
+| `ref_type`      | `string`           |             |
+| `repository`    | `GitHubRepository` |             |
+| `sender`        | `GitHubUser`       |             |
+| `[key: string]` | `unknown`          |             |
+
+### `delete`
+
+Carried by `DeleteEventPayload`. The `payload` property has the following shape:
+
+| Field           | Type               | Description |
+| --------------- | ------------------ | ----------- |
+| `ref`           | `string`           |             |
+| `ref_type`      | `string`           |             |
+| `repository`    | `GitHubRepository` |             |
+| `sender`        | `GitHubUser`       |             |
+| `[key: string]` | `unknown`          |             |
+
+### `status`
+
+Carried by `StatusEventPayload`. The `payload` property has the following shape:
+
+| Field           | Type                                              | Description |
+| --------------- | ------------------------------------------------- | ----------- |
+| `state`         | `string`                                          |             |
+| `sha`           | `string`                                          |             |
+| `context`       | `string`                                          |             |
+| `description?`  | `string`                                          |             |
+| `target_url?`   | `string`                                          |             |
+| `branches?`     | `Array<{ name: string; [key: string]: unknown }>` |             |
+| `repository`    | `GitHubRepository`                                |             |
+| `sender`        | `GitHubUser`                                      |             |
+| `[key: string]` | `unknown`                                         |             |
+
+### `workflow_run`
+
+Carried by `WorkflowRunEventPayload`. The `payload` property has the following shape:
+
+| Field           | Type                                                                                                   | Description |
+| --------------- | ------------------------------------------------------------------------------------------------------ | ----------- |
+| `action`        | `string`                                                                                               |             |
+| `workflow_run`  | `{ head_branch: string; name: string; conclusion?: string; status?: string; [key: string]: unknown; }` |             |
+| `repository`    | `GitHubRepository`                                                                                     |             |
+| `sender`        | `GitHubUser`                                                                                           |             |
+| `[key: string]` | `unknown`                                                                                              |             |
+
+### `fork`
+
+Carried by `ForkEventPayload`. The `payload` property has the following shape:
+
+| Field           | Type                                            | Description |
+| --------------- | ----------------------------------------------- | ----------- |
+| `forkee`        | `{ full_name: string; [key: string]: unknown }` |             |
+| `repository`    | `GitHubRepository`                              |             |
+| `sender`        | `GitHubUser`                                    |             |
+| `[key: string]` | `unknown`                                       |             |
+
+### `star`
+
+Carried by `StarEventPayload`. The `payload` property has the following shape:
+
+| Field           | Type               | Description |
+| --------------- | ------------------ | ----------- |
+| `action`        | `string`           |             |
+| `repository`    | `GitHubRepository` |             |
+| `sender`        | `GitHubUser`       |             |
+| `[key: string]` | `unknown`          |             |
+
+### `watch`
+
+Carried by `WatchEventPayload`. The `payload` property has the following shape:
+
+| Field           | Type               | Description |
+| --------------- | ------------------ | ----------- |
+| `action`        | `string`           |             |
+| `repository`    | `GitHubRepository` |             |
+| `sender`        | `GitHubUser`       |             |
+| `[key: string]` | `unknown`          |             |
+
+### `webhook`
+
+Carried by `WebhookEventPayload`. Adds no typed fields beyond the shared envelope; `payload` is the raw provider body (`Record<string, unknown>`).
+
+### `kici_event`
+
+Carried by `KiciEventPayload`. Adds no typed fields beyond the shared envelope; `payload` is the raw provider body (`Record<string, unknown>`).
+
+### `workflow_complete`
+
+Carried by `WorkflowCompleteEventPayload`. Adds no typed fields beyond the shared envelope; `payload` is the raw provider body (`Record<string, unknown>`).
+
+### `job_complete`
+
+Carried by `JobCompleteEventPayload`. Adds no typed fields beyond the shared envelope; `payload` is the raw provider body (`Record<string, unknown>`).
+
+### `generic_webhook`
+
+Carried by `GenericWebhookEventPayload`. Adds no typed fields beyond the shared envelope; `payload` is the raw provider body (`Record<string, unknown>`).
+
+### `schedule`
+
+Carried by `ScheduleEventPayload`. Adds no typed fields beyond the shared envelope; `payload` is the raw provider body (`Record<string, unknown>`).
+
+### `lifecycle`
+
+Carried by `LifecycleEventPayload`. Adds no typed fields beyond the shared envelope; `payload` is the raw provider body (`Record<string, unknown>`).
+
+### `rerun`
+
+Carried by `RerunEventPayload`. Adds no typed fields beyond the shared envelope; `payload` is the raw provider body (`Record<string, unknown>`).
+
+### `manual_schedule`
+
+Carried by `ManualScheduleEventPayload`. Adds no typed fields beyond the shared envelope; `payload` is the raw provider body (`Record<string, unknown>`).
+
+### `unknown`
+
+Carried by `UnknownEventPayload`. Adds no typed fields beyond the shared envelope; `payload` is the raw provider body (`Record<string, unknown>`).
+
+## Shared GitHub object shapes
+
+The typed `payload` shapes above reference these partial GitHub object types. Each lists only the commonly accessed fields; the index signature on every shape resolves any other field to `unknown`.
+
+### `GitHubRepository`
+
+| Field            | Type                                        | Description |
+| ---------------- | ------------------------------------------- | ----------- |
+| `full_name`      | `string`                                    |             |
+| `default_branch` | `string`                                    |             |
+| `name?`          | `string`                                    |             |
+| `owner?`         | `{ login: string; [key: string]: unknown }` |             |
+| `private?`       | `boolean`                                   |             |
+| `[key: string]`  | `unknown`                                   |             |
+
+### `GitHubUser`
+
+| Field           | Type      | Description |
+| --------------- | --------- | ----------- |
+| `login`         | `string`  |             |
+| `id?`           | `number`  |             |
+| `[key: string]` | `unknown` |             |
+
+### `GitHubPullRequest`
+
+| Field           | Type                                                                                                          | Description |
+| --------------- | ------------------------------------------------------------------------------------------------------------- | ----------- |
+| `number`        | `number`                                                                                                      |             |
+| `draft?`        | `boolean`                                                                                                     |             |
+| `title?`        | `string`                                                                                                      |             |
+| `body?`         | `string`                                                                                                      |             |
+| `state?`        | `string`                                                                                                      |             |
+| `merged?`       | `boolean`                                                                                                     |             |
+| `head`          | `{ ref: string; sha: string; repo?: { full_name: string; [key: string]: unknown }; [key: string]: unknown; }` |             |
+| `base`          | `{ ref: string; repo?: { full_name: string; [key: string]: unknown }; [key: string]: unknown; }`              |             |
+| `user?`         | `GitHubUser`                                                                                                  |             |
+| `labels?`       | `Array<{ name: string; [key: string]: unknown }>`                                                             |             |
+| `[key: string]` | `unknown`                                                                                                     |             |
+
+### `GitHubCommit`
+
+| Field           | Type                                                                           | Description |
+| --------------- | ------------------------------------------------------------------------------ | ----------- |
+| `id`            | `string`                                                                       |             |
+| `message`       | `string`                                                                       |             |
+| `author?`       | `{ name?: string; email?: string; username?: string; [key: string]: unknown }` |             |
+| `timestamp?`    | `string`                                                                       |             |
+| `added?`        | `string[]`                                                                     |             |
+| `removed?`      | `string[]`                                                                     |             |
+| `modified?`     | `string[]`                                                                     |             |
+| `[key: string]` | `unknown`                                                                      |             |
+
+### `GitHubComment`
+
+| Field           | Type         | Description |
+| --------------- | ------------ | ----------- |
+| `id`            | `number`     |             |
+| `body`          | `string`     |             |
+| `user`          | `GitHubUser` |             |
+| `[key: string]` | `unknown`    |             |
+
+### `GitHubReview`
+
+| Field           | Type         | Description |
+| --------------- | ------------ | ----------- |
+| `id`            | `number`     |             |
+| `state`         | `string`     |             |
+| `body?`         | `string`     |             |
+| `user`          | `GitHubUser` |             |
+| `[key: string]` | `unknown`    |             |
+
+### `GitHubRelease`
+
+| Field               | Type      | Description |
+| ------------------- | --------- | ----------- |
+| `id`                | `number`  |             |
+| `tag_name`          | `string`  |             |
+| `name?`             | `string`  |             |
+| `body?`             | `string`  |             |
+| `draft?`            | `boolean` |             |
+| `prerelease?`       | `boolean` |             |
+| `target_commitish?` | `string`  |             |
+| `[key: string]`     | `unknown` |             |
+
+---
+
 ## SDK reference: idempotent
 
 Source: https://docs.kici.dev/user/sdk/idempotent/
@@ -2442,17 +3039,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.
 
-**Common fields** (on all variants via `EventBase`):
-
-| Field            | Type                           | Description                             |
-| ---------------- | ------------------------------ | --------------------------------------- |
-| `type`           | `string` (literal per variant) | Event type discriminant                 |
-| `action`         | `string \| undefined`          | Sub-action (e.g. 'opened', 'created')   |
-| `targetBranch`   | `string \| undefined`          | Target branch (push target, PR base)    |
-| `sourceBranch`   | `string \| undefined`          | Source branch (PR head)                 |
-| `provider`       | `string \| undefined`          | Provider name (e.g. 'github')           |
-| `senderUsername` | `string \| undefined`          | Webhook sender username                 |
-| `payload`        | `Record<string, unknown>`      | Raw webhook payload (typed per variant) |
+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).
 
 **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`.
 
@@ -2480,16 +3067,16 @@ step('test', async ({ $, matrix }) => {
 
 ```typescript
 matrix: {
-  os: ['ubuntu-latest', 'macos-latest'],
+  os: ['linux', 'arm64'],
   node: ['18', '20'],
 }
 ```
 
-Creates 4 job instances (2 x 2). In steps, values are named properties:
+Creates 4 job instances (2 x 2). The `os` values (`linux`, `arm64`) are **customer-defined scaler labels** matched by subset semantics against the labels your orchestrator advertises in its scaler `labelSets` — not hosted-runner names. In steps, values are named properties:
 
 ```typescript
 step('test', async ({ $, matrix }) => {
-  console.log(matrix!.os); // 'ubuntu-latest' or 'macos-latest'
+  console.log(matrix!.os); // 'linux' or 'arm64'
   console.log(matrix!.node); // '18' or '20'
 });
 ```
@@ -2522,14 +3109,14 @@ Fine-tune matrix combinations on multi-dimensional matrices:
 
 ```typescript
 matrix: {
-  os: ['ubuntu-latest', 'macos-latest', 'windows-latest'],
+  os: ['linux', 'arm64', 'windows'],
   node: ['18', '20', '22'],
 },
 exclude: [
-  { os: 'windows-latest', node: '18' },
+  { os: 'windows', node: '18' },
 ],
 include: [
-  { os: 'ubuntu-latest', node: '23' },
+  { os: 'linux', node: '23' },
 ],
 ```
 
@@ -2599,7 +3186,7 @@ const discoverJobs: DynamicJobFn = async ({ $ }) => {
   const packages = result.stdout.trim().split('\n');
   return packages.map((pkg) =>
     job(`test-${pkg}`, {
-      runsOn: 'ubuntu-latest',
+      runsOn: 'linux',
       steps: [
         step('test', async ({ $ }) => {
           await $`cd packages/${pkg} && pnpm test`;
@@ -2858,7 +3445,7 @@ Use whichever style is convenient — you don't have to wrap `console.log` in th
 
 ### setEnv(key, value)
 
-Set an environment variable that is visible to the current step and all subsequent steps in the same job. This is the equivalent of `echo "KEY=VALUE" >> $GITHUB_ENV` in GitHub Actions.
+Export an environment variable to later steps in the same job. This is the canonical way to hand a value computed in one step to the steps that follow — the equivalent of `echo "KEY=VALUE" >> $GITHUB_ENV` in GitHub Actions. The value is visible to the current step and all subsequent steps in the job.
 
 ```typescript
 step('setup', async (ctx) => {
@@ -2879,6 +3466,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)
 
 ### addPath(dir)
 
@@ -2896,6 +3484,40 @@ step('build', async (ctx) => {
 });
 ```
 
+### Exporting env from shell commands ($KICI_ENV / $KICI_PATH)
+
+`setEnv` and `addPath` are the TypeScript form of "export env to later steps". A shell command — including a non-JS toolchain installer — exports env the same way by appending to two files the agent points at before every step:
+
+- **`$KICI_ENV`** — append `KEY=value` lines. Each becomes an environment variable visible to subsequent steps, exactly like `ctx.setEnv('KEY', 'value')`.
+- **`$KICI_PATH`** — append one directory per line. Each is prepended to `PATH` for subsequent steps, exactly like `ctx.addPath(dir)`. The first directory appended ends up first on `PATH`.
+
+```typescript
+step('install-tool', async (ctx) => {
+  await ctx.$`./install-mytool.sh`; // installs to /opt/mytool
+  // Export from the shell, no JS round-trip needed:
+  await ctx.$`echo "MYTOOL_HOME=/opt/mytool" >> "$KICI_ENV"`;
+  await ctx.$`echo "/opt/mytool/bin" >> "$KICI_PATH"`;
+});
+
+step('build', async (ctx) => {
+  // MYTOOL_HOME is set and /opt/mytool/bin is on PATH here.
+  await ctx.$`mytool build`;
+});
+```
+
+**Format (v1):**
+
+- One `KEY=value` per line in `$KICI_ENV`. The split is on the first `=`, so the value may contain `=`. Blank lines and lines without a `=` are ignored.
+- One directory per line in `$KICI_PATH`. Blank lines are ignored.
+- Values must be single-line — embedded newlines are not supported in v1.
+
+**Behavior (shared with `setEnv` / `addPath`):**
+
+- Applied after the step completes and visible to every later step in the job.
+- Last-write-wins on a repeated key.
+- Cannot override an operator-injected secret — a collision is ignored and logged, and the operator value is preserved.
+- The files are reset before each step, so each step sees only its own appended lines.
+
 ### setSecretOutput(key, value)
 
 Publish an encrypted secret output from this job. Downstream jobs that list this job in their `needs` array receive the value merged into `ctx.secrets`.
@@ -2944,7 +3566,7 @@ Each job picks its secret environment via the `environment` option on `job()`. T
 
 ```typescript
 const deploy = job('deploy', {
-  runsOn: 'ubuntu-latest',
+  runsOn: 'linux',
   environment: 'production',
   steps: [
     /* ... */
@@ -2983,7 +3605,7 @@ step('deploy', async ({ secrets }) => {
 import { workflow, job, step, push } from '@kici-dev/sdk';
 
 const deploy = job('deploy', {
-  runsOn: 'ubuntu-latest',
+  runsOn: 'linux',
   environment: 'production',
   steps: [
     step('deploy', async (ctx) => {
@@ -3899,6 +4521,7 @@ Reference documentation for `@kici-dev/sdk`. The reference is split across five
 | [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.                                                                                                  |
@@ -4089,7 +4712,7 @@ JWT and opaque OIDC tokens are validated against the configured OIDC issuer (JWK
 
 ### 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 14 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 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).
 
 ### Configurable surfaces
 
@@ -4346,6 +4969,7 @@ Cleanup policy:
 - On a fully successful run, the isolated checkout is removed.
 - On failure, it is retained and its path is logged so you can inspect the failed state.
 - `--keep` always retains it, even on success.
+- Retained checkouts are garbage-collected after 72 hours by the next `kici run local` invocation — copy a checkout elsewhere if you need it longer.
 
 Set the `KICI_RUN_DIR` environment variable to place the isolated checkout under a base directory other than the system temp directory.
 
@@ -4402,6 +5026,8 @@ 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.
 
+Requires `kici login` (an authenticated session) and a target orchestrator that has **cache storage configured** (`KICI_STORAGE_TYPE` = `s3` or `filesystem`) — the command uploads your working-tree overlay to that storage for the agent to fetch. The quickstart orchestrators do not enable storage by default; see the [testing guide](testing-guide.md) for setup (including non-public / self-hosted S3 endpoints).
+
 ```bash
 kici run remote [fixture] [options]
 ```
@@ -4414,21 +5040,21 @@ kici run remote [fixture] [options]
 
 **Options:**
 
-| Option                      | Default | Description                                        |
-| --------------------------- | ------- | -------------------------------------------------- |
-| `--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                     |
-| `--routing-key <key>`       | none    | Override routing key for this run                  |
-| `--secret <key=value>`      | none    | Inject flat secret (repeatable)                    |
-| `--context <ctx.key=value>` | none    | Inject context secret (repeatable)                 |
-| `--debug`                   | `false` | Verbose internals                                  |
-| `--kici-dir <path>`         | `.kici` | Path to .kici directory                            |
+| Option                      | Default | Description                                                                                                           |
+| --------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
+| `--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                                                                                        |
+| `--routing-key <key>`       | none    | Override routing key for this run                                                                                     |
+| `--context <ctx.key=value>` | none    | Inject a namespaced context secret, uploaded encrypted to the orchestrator (repeatable)                               |
+| `--env <KEY=VALUE>`         | none    | Provide a per-run secret, uploaded encrypted to the orchestrator (repeatable) — see [testing guide](testing-guide.md) |
+| `--debug`                   | `false` | Verbose internals                                                                                                     |
+| `--kici-dir <path>`         | `.kici` | Path to .kici directory                                                                                               |
 
 **Examples:**
 
@@ -4561,14 +5187,14 @@ kici login [options]
 
 **Environment variables:**
 
-| Variable              | Default                   | Description                                                            |
-| --------------------- | ------------------------- | ---------------------------------------------------------------------- |
-| `KICI_PLATFORM_URL`   | none (required for OAuth) | Platform API base URL                                                  |
-| `KICI_OIDC_ISSUER`    | none (required for OAuth) | OIDC issuer URL                                                        |
-| `KICI_OIDC_CLIENT_ID` | none (required for OAuth) | OIDC client ID                                                         |
-| `KICI_BROWSER_CMD`    | uses `open` package       | Custom browser command with `{url}` placeholder, or `none` to suppress |
-| `KICI_CALLBACK_PORT`  | random                    | Fixed port for OAuth PKCE callback server                              |
-| `KICI_CONFIG_DIR`     | `~/.kici`                 | Override config directory                                              |
+| Variable              | Default                                      | Description                                                            |
+| --------------------- | -------------------------------------------- | ---------------------------------------------------------------------- |
+| `KICI_PLATFORM_URL`   | `https://api.kici.dev`                       | Platform API base URL (override for a self-hosted Platform)            |
+| `KICI_OIDC_ISSUER`    | `https://auth.kici.dev/realms/kici-internal` | OIDC issuer URL (override for a self-hosted Platform)                  |
+| `KICI_OIDC_CLIENT_ID` | `kici-cli`                                   | OIDC client ID (override for a self-hosted Platform)                   |
+| `KICI_BROWSER_CMD`    | uses `open` package                          | Custom browser command with `{url}` placeholder, or `none` to suppress |
+| `KICI_CALLBACK_PORT`  | random                                       | Fixed port for OAuth PKCE callback server                              |
+| `KICI_CONFIG_DIR`     | `~/.kici`                                    | Override config directory                                              |
 
 **Examples:**
 
@@ -4751,6 +5377,72 @@ kici cancel abc123 --force
 kici cancel --branch feature/wip
 ```
 
+### 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.
+
+```bash
+kici approve <run-id> [options]
+```
+
+**Arguments:**
+
+| Argument | Required | Description                        |
+| -------- | -------- | ---------------------------------- |
+| `run-id` | yes      | Run ID holding the gate to approve |
+
+**Options:**
+
+| Option            | Default | Description                                         |
+| ----------------- | ------- | --------------------------------------------------- |
+| `--job <name>`    | none    | Approve a held job (omit for a workflow-level hold) |
+| `--step <name>`   | none    | Approve a held step (used with `--job`)             |
+| `--reason <text>` | none    | Optional note recorded with the approval            |
+
+**Examples:**
+
+```bash
+# Approve a workflow-level hold
+kici approve abc123
+
+# Approve a held job
+kici approve abc123 --job deploy-production
+
+# Approve a held step
+kici approve abc123 --job migrate-and-deploy --step apply-migration
+```
+
+You must be eligible for at least one unsatisfied clause (a member of a named team, or a named user) and hold the `environments:write` or `ci_trust:write` permission. The command reports whether the element was released, how many clauses remain, or that it was rejected.
+
+### kici reject
+
+Reject a held [approval gate](approvals.md). A rejection fails the held element and the run. A reason is required.
+
+```bash
+kici reject <run-id> --reason <text> [options]
+```
+
+**Arguments:**
+
+| Argument | Required | Description                       |
+| -------- | -------- | --------------------------------- |
+| `run-id` | yes      | Run ID holding the gate to reject |
+
+**Options:**
+
+| Option            | Default | Description                                        |
+| ----------------- | ------- | -------------------------------------------------- |
+| `--reason <text>` | none    | Required. Reason recorded with the rejection       |
+| `--job <name>`    | none    | Reject a held job (omit for a workflow-level hold) |
+| `--step <name>`   | none    | Reject a held step (used with `--job`)             |
+
+**Examples:**
+
+```bash
+# Reject a held job with a reason
+kici reject abc123 --job deploy-production --reason "Wrong release branch"
+```
+
 ### kici secrets list
 
 List secret contexts available for test runs. Shows context names and key names (not values).
@@ -5416,13 +6108,13 @@ If you change a workflow file (`.ts`) but do **not** regenerate and commit the l
 
 The lock file (`kici.lock.json`) is a JSON file with the following top-level fields:
 
-| Field           | Description                                                                                                         |
-| --------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `schemaVersion` | Lock file schema version (currently 12). 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 `.kici/package-lock.json`, used as the dependency cache key. Omitted when no package lock file exists.   |
-| `workflows`     | Array of workflow entries, each with its own `contentHash`, `compileSchemaVersion`, triggers, and jobs.             |
+| Field           | Description                                                                                                                                                                                                                                                                                                                                           |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `schemaVersion` | Lock file schema version (currently 15). 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. |
+| `workflows`     | Array of workflow entries, each with its own `contentHash`, `compileSchemaVersion`, triggers, and jobs.                                                                                                                                                                                                                                               |
 
 Each workflow entry includes:
 
@@ -5438,7 +6130,11 @@ Each workflow entry includes:
 | `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).                                                                                                                                                                                                                                                                                              |
 | `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).                                                                                                                                                                                                                                                                                                                                  |
+| `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`.                                                                                                                                                                                                                                                                     |
 
 ## Rule: commit both together
@@ -5534,11 +6230,22 @@ Test your workflows remotely against the full CI pipeline from your local machin
 
 - Run any workflow against your current working tree (including unstaged changes)
 - Get real-time log output streamed back to your terminal
-- Use test-specific secret contexts that are isolated from production
+- 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>`.
 
+:::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`).
+
+- **The [Docker / Podman quickstart](quickstart/compose.md) wires this up for you** — it ships a SeaweedFS service, so `kici run remote` works there out of the box (see its "run a workflow without pushing" step).
+- **The [bare-metal quickstart](quickstart/bare-metal.md) 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.
+:::
+
 ## Getting started
 
 ### 1. Authenticate
@@ -5637,7 +6344,7 @@ When not specified, these default to values detected from your local git repo (c
 
 ### Secret context mappings
 
-Map test secret contexts to your fixture:
+Map secret contexts to your fixture:
 
 ```typescript
 export const pushWithSecrets = fixture('push-with-secrets', {
@@ -5649,7 +6356,12 @@ export const pushWithSecrets = fixture('push-with-secrets', {
 });
 ```
 
-This maps the `db` secret context to the `test-database` context on the orchestrator, and `api` to `test-api-keys`. Only environments with `allowLocalExecution: true` are accessible. See [Secret contexts for testing](#secret-contexts-for-testing) below.
+This maps the `db` secret context to the `test-database` context, and `api` to `test-api-keys`.
+
+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).
 
 ### Async fixtures
 
@@ -5780,39 +6492,76 @@ The CLI always shows a pre-upload summary before transferring:
 
 ## Secret contexts for testing
 
-Test runs can only access secret contexts that have been explicitly marked as test-accessible.
+The goal of the test-secret model is to let test runs reach **test-only credentials** while keeping production credentials out of reach. `kici run remote` combines two sources of secrets for a test run, then merges them with a clear precedence and a fail-closed gate.
+
+### CLI-uploaded local secrets
+
+`kici run remote` collects the same local secret values that `kici run local` reads — `.kici/.secrets`, `.kici/.env.local`, `.kici/secrets.yaml`, and any `--env KEY=VALUE` flags — and uploads them **encrypted** to the orchestrator alongside the run. The orchestrator decrypts them only to inject them into the agent for that run; the control plane never sees the values.
+
+```bash
+# Provide an ad-hoc test value for a single remote run
+kici run remote push-main --env KICI_DATABASE_URL=postgresql://localhost/test
+```
+
+`--env` provides a **flat** per-run override; `--context <ctx>.<KEY>=<value>` is its sibling for a **namespaced** per-run override, placing the value under the named context `ctx`. Both are uploaded **encrypted** and follow the same precedence rule below — a CLI-supplied value wins over the orchestrator test-environment secret on a key collision.
 
-### Operator configuration
+```bash
+# Provide a namespaced per-run value under the 'db' context
+kici run remote push-db --context db.KICI_DATABASE_URL=postgresql://localhost/test
+```
 
-Test-run access to a secret context is gated by a single flag on the environment that owns the bound secrets:
+Because these values originate on your machine, they are the natural place to put throwaway test credentials without touching any orchestrator-stored secret.
 
-- **`allowLocalExecution`** -- When `true`, CLI-initiated test runs (`kici run remote`) may resolve secrets through this environment. Production environments should leave this `false` so test runs cannot reach production credentials.
+### Orchestrator test-environment secrets
 
-### Fixture secret mappings
+In addition to your uploaded values, the orchestrator resolves test-scoped secrets from its own store for a remote test run:
 
-In your fixture, map local names to remote context names:
+- 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.
+- 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.
 
 ```typescript
 export const pushWithDb = fixture('push-db', {
   event: push({ branches: ['main'] }),
-  secrets: { db: 'test-database' },
+  secrets: { db: 'test-database' }, // 'test-database' must be allowLocalExecution: true
 });
 ```
 
-In your workflow, access secrets normally via `ctx.secrets` or `ctx.contexts`:
-
 ```typescript
 step('migrate', async (ctx) => {
-  const dbUrl = ctx.secrets.KICI_DATABASE_URL;
+  const dbUrl = await ctx.secrets.get('KICI_DATABASE_URL');
   await ctx.$`npx prisma migrate deploy`;
 });
 ```
 
-During a test run, the `KICI_DATABASE_URL` secret is resolved from the `test-database` context instead of the production context.
+### Precedence: CLI values win
+
+When a key exists in both sources, the **CLI-uploaded local value wins** over the orchestrator test-environment value. This makes a local override a per-run knob: set `--env KICI_DATABASE_URL=...` (or put it in `.kici/.secrets`) to shadow the test environment's value for just that run, without changing anything on the orchestrator.
+
+### Fail-closed on non-test environments
+
+Test-run secret resolution is fail-closed:
+
+- If a fixture maps a context to an environment that does not exist, the run is **rejected**.
+- If a fixture maps a context to an environment whose `allowLocalExecution` is `false`, the run is **rejected**.
+- The `allowLocalExecution` gate applies to **all** remote test runs: a run whose matched workflow targets an environment with the flag off is rejected, so a test run can never resolve production secrets.
+
+### The `allowLocalExecution` environment flag
+
+Each environment carries an `allowLocalExecution` flag (default `false`) that controls test-run access to that environment and to its secrets. Production environments should leave it at `false`; create a dedicated test environment with `allowLocalExecution: true` that binds only test-only secret scopes for the contexts you want test runs to use.
+
+The flag is set by the orchestrator operator, either via the CLI:
+
+```bash
+kici-admin environment set-policy --env test-database --allow-local-execution true
+```
+
+or via the dashboard's "Test runs" toggle on the environment detail page. `kici secrets list` only surfaces contexts whose owning environment has `allowLocalExecution: true`, so production environments are never advertised as test-accessible.
 
-### Fail-closed behavior
+### Local execution as an alternative
 
-If a workflow accesses a secret context that has no test-allowed equivalent, the run fails immediately. This prevents accidental use of production secrets in test runs.
+`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.
 
 ### Discovering available contexts
 
@@ -5922,6 +6671,58 @@ Practical patterns for building real-world KiCI workflows in TypeScript. The pat
 
 # Workflow features
 
+## Account and sign-in
+
+Source: https://docs.kici.dev/user/account-and-login/
+
+Your KiCI account is a single identity. It stays the same no matter how you
+sign in — whether you signed up with GitHub or with an email and password.
+Changing your sign-in method does not create a new account or move your data;
+your organizations, roles, and API keys stay attached to the same identity.
+
+## Where sign-in methods are managed
+
+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.
+
+You can open the account console from the dashboard: go to your personal
+settings, open **Linked accounts**, and use the **Account console** link.
+
+## Adding a password to a GitHub-created account
+
+If you registered by signing in with GitHub and now want to sign in with an
+email and password as well:
+
+1. Open your account console.
+2. Add a password (and, if prompted, confirm your email).
+
+After this, you can sign in either with GitHub or with your email and password —
+it is the same account.
+
+## Removing GitHub as a sign-in method
+
+To stop using GitHub to sign in:
+
+1. First add a password (see above). The identity provider will not let you
+   remove your only sign-in method, so you must have another one first.
+2. In your account console, remove the GitHub sign-in method.
+
+Your account, organizations, and data are unaffected — you simply sign in a
+different way afterward.
+
+## Linked accounts vs sign-in methods
+
+The dashboard's **Linked accounts** page controls **run-attribution metadata**
+only — for example, showing your GitHub username on the runs you trigger and
+determining your contributor trust level. Unlinking a provider there removes
+that display link; it does **not** remove the provider as a way to sign in.
+
+To actually change how you sign in, use your account console as described above.
+
+---
+
 ## Concurrency groups
 
 Source: https://docs.kici.dev/user/concurrency/
@@ -5974,8 +6775,8 @@ group: (ctx) => `deploy-${ctx.branch}`;
 // Global concurrency (across all branches)
 group: () => 'deploy';
 
-// Per-environment concurrency
-group: (ctx) => `deploy-${ctx.event.environment ?? 'default'}`;
+// Per-target-branch concurrency
+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.
@@ -6172,7 +6973,7 @@ The six steps are:
 
 1. **Install the kici CLI** -- `npm install -g kici`.
 2. **Create a workflow** -- `kici init` scaffolds a `.kici/` directory in your repository.
-3. **Run a workflow locally** -- `kici test pr:open --dry-run` executes a workflow on your machine with no orchestrator required.
+3. **Run a workflow locally** -- `kici run local pr:open` executes a workflow on your machine with no orchestrator required.
 4. **Connect an orchestrator** -- deploy an orchestrator and connect it with a join token from **Settings → Orchestrator keys**.
 5. **Add a webhook source** -- register a source under **Settings → Sources** so pushes and pull requests trigger runs.
 6. **Trigger your first run** -- push to your repository to produce your first run through the relay.
@@ -6462,7 +7263,7 @@ The job tree supports keyboard navigation:
 The content area has the following tabs:
 
 - **Logs** (default) -- shows log output for the selected job or step
-- **Payload** -- webhook payload viewer showing the raw event payload that triggered the run
+- **Payload** -- webhook payload viewer showing the raw event payload that triggered the run. This tab appears only for runs triggered by a webhook event (and re-runs of those, which copy the original payload); runs started by a schedule, manual schedule, lifecycle event, or another run carry no payload, so the tab is hidden for them
 - **Timeline** -- CSS Gantt chart showing the execution timeline of all jobs, with percentage-based bars and striped animation for running jobs. A **Provisioning** milestones section between the dispatch and execution phases plots scaler lifecycle events for the run — including a **Provisioning failed** marker when the scaler could not bring an agent up
 - **Summary** -- contextual overview scoped to the current selection (run-level trigger/repo/timing info, or job-level execution context with environment variables, runtime info, and sandbox details)
 
@@ -6577,18 +7378,30 @@ Each member's linked provider accounts (e.g. GitHub) are also visible here.
 
 <!-- help:settings-roles#settings -->
 
-Roles define granular permissions across 14 resource categories (runs, secrets, members, etc.) with 5 access levels: `none`, `read`, `read_payload`, `write`, `admin`.
+Roles define granular permissions across 15 resource categories (runs, secrets, members, etc.) with 5 access levels: `none`, `read`, `read_payload`, `write`, `admin`.
 
 Create custom roles to restrict what team members can do, or use the built-in **Owner** role for full access.
 
 <!-- /help:settings-roles -->
 
+<!-- help:settings-teams#settings -->
+
+Teams are named groups of organization members. A role granted to a team is inherited by every member, so you can manage permissions for a whole group in one place.
+
+Team names can also be referenced in workflow approval gates (`requireApproval: [{ team: 'leads' }]`) — any member of the named team can satisfy that gate.
+
+Managing teams (create / rename / delete, membership, role grants) requires the **Teams** permission at `admin`; `read` shows a view-only list.
+
+<!-- /help:settings-teams -->
+
 <!-- help:settings-api-keys#settings -->
 
 API keys allow programmatic access to the KiCI API for automation, scripts, and CI integrations.
 
 Each key is scoped to this organization with a custom permission matrix and an optional expiry date. Keys can be revoked individually.
 
+Use a key's clone button to open the creation modal prefilled with that key's name, expiry, and permissions — handy for recreating an expired key or deriving a new key from an existing one.
+
 <!-- /help:settings-api-keys -->
 
 <!-- help:settings-orchestrator-keys#orchestrator-keys -->
@@ -6597,6 +7410,8 @@ Orchestrator keys authenticate the WebSocket connection between your orchestrato
 
 Create a key here and set it as the `KICI_PLATFORM_TOKEN` environment variable in your orchestrator configuration. Keys can optionally be restricted to specific routing patterns.
 
+Use a key's clone button to open the creation modal prefilled with that key's name and description.
+
 <!-- /help:settings-orchestrator-keys -->
 
 <!-- help:settings-sources#sources -->
@@ -6649,6 +7464,8 @@ The relayed-webhooks counter only includes webhooks delivered through the KiCI P
 
 Webhooks pointed directly at your orchestrator's public ingest endpoint never reach the Platform, so they're invisible to this counter and uncapped on every Hosted tier. If you have a public orchestrator ingress, you can mix-and-match: use the relay for sources you can't expose publicly, and point GitHub (or any provider / generic webhook) straight at your orchestrator for the rest.
 
+Every webhook the relay forwards counts — **including ones your workflows ultimately ignore**. Trigger matching runs on your orchestrator, not on the Platform, so the relay forwards each signature-verified webhook before any trigger is evaluated. A source that sends many events you filter down to a handful of runs still consumes one relayed webhook per event. If a high-volume source mostly produces no run, point it directly at your orchestrator (see above) to keep it off this counter entirely.
+
 When you hit the cap, new relayed webhooks are rejected with `429 Plan limit reached`. Upgrade in the Stripe Billing Portal to lift the cap immediately; usage resets monthly on your billing anniversary.
 
 <!-- /help:settings-billing-relayed-webhooks -->
@@ -6818,6 +7635,20 @@ The summary strip at the top shows total / enabled / disabled counts plus whethe
 
 <!-- /help:settings-security-dashboard-policy -->
 
+<!-- help:settings-support-access#settings -->
+
+Controls whether KiCI support staff may open read-only support sessions against your organization. Sessions are **off by default** — nobody outside your org can read your data until you opt in here.
+
+When enabled:
+
+- KiCI staff can open time-boxed, read-only sessions to investigate an issue.
+- Every read they perform is recorded in your audit trail with the support reason.
+- No writes are ever possible during a session.
+
+Disabling the toggle immediately ends any in-progress support session. Only users with the `support:admin` permission (owners by default) can change this setting.
+
+<!-- /help:settings-support-access -->
+
 <!-- help:settings-webhooks-delivery-log#settings -->
 
 The delivery log shows recent webhook deliveries for an endpoint, including the HTTP status code, number of retry attempts, and the event payload.
@@ -6874,11 +7705,26 @@ The settings page (`/orgs/:customerId/settings`) uses a tabbed layout:
 10. **Webhooks** -- outbound webhook endpoint management with delivery logs and test ping
 11. **Event log** -- inbound webhook delivery log (visible with `event_log:read` permission)
 12. **Security** -- read-only view of the orchestrator's dashboard-write policy matrix (visible with `org_settings:read` permission)
+13. **Support access** -- opt-in switch that controls whether KiCI support staff may open read-only support sessions against your org (visible with `support:read`; toggled with `support:admin`)
 
 Audit-log-style entries are no longer a settings tab; they live on the dedicated **Activity** page accessible from the sidebar.
 
 Tab selection syncs with the URL path (`/settings/members`, `/settings/api-keys`, etc.), making tabs bookmarkable.
 
+### Support access
+
+The Support access tab controls whether KiCI support staff may open a read-only **support session** against your organization to help diagnose an issue. The setting is **off by default** -- until you opt in here, no one outside your org can read your data.
+
+When support access is enabled:
+
+- A KiCI operator can open a time-boxed (30-minute, renewable), read-only support session scoped to a stated reason.
+- A support session is **runs-only**: the operator can browse your run list and, by confirming each run individually, view that run's detail and step logs. Nothing else is visible, and no write is ever possible.
+- Every run an operator opens is recorded in your [Activity](#activity) audit trail, attributed to the operator with the support reason -- so you can see exactly what was looked at and why.
+
+**Disabling immediately ends any active session.** Toggling the switch off closes every in-progress support session for your org at once. Enabling and disabling the setting is itself audited, attributed to the user who changed it.
+
+Viewing the setting requires the `support:read` permission; changing it requires `support:admin` (granted to owners by default).
+
 ### Orchestrator keys
 
 The orchestrator keys tab manages API keys used to authenticate orchestrator-to-Platform WebSocket connections. These are separate from user API keys (which grant dashboard/API access).
@@ -6955,11 +7801,15 @@ Personal access tokens (PATs) are long-lived credentials for programmatic API ac
 
 Create a PAT to authenticate CLI tools or scripts without going through the OIDC login flow. Tokens can be revoked at any time.
 
+Use a token's clone button to open the creation modal prefilled with that token's name, expiry, and permissions.
+
 <!-- /help:personal-pats -->
 
 <!-- help:personal-linked-accounts#account -->
 
-Linked accounts connect your external provider identities (like GitHub) to your KiCI account. Linking enables features like showing your provider username in run metadata and associating your commits with your KiCI identity.
+Linked accounts connect your external provider identities (like GitHub) to your KiCI account. Linking shows your provider username in run metadata and sets your contributor trust level.
+
+**Unlinking here removes the display link only** — it does not remove a sign-in method. To change how you sign in (add a password, remove GitHub login), use the **Account console** link, or see [Account and sign-in](./account-and-login.md).
 
 <!-- /help:personal-linked-accounts -->
 
@@ -7053,7 +7903,7 @@ The policy state is visible at three layers in the UI:
 - A **lock-icon prefix** on every disabled control, with a per-control CLI hint.
 - A **per-page banner** on any page containing at least one disabled operation, listing every disabled op on that page and its CLI equivalent.
 
-The Security policy page (Settings → Security → Dashboard policy) renders the full 23-row read-only matrix with the current state and the `kici-admin` command for each row. The policy itself cannot be changed from the dashboard — the orchestrator operator manages it via `kici-admin org-settings dashboard-writes`. See [Dashboard-write policy](/operator/security/dashboard-write-policy) for the operator-side details.
+The Security policy page (Settings → Security → Dashboard policy) renders the full 24-row read-only matrix with the current state and the `kici-admin` command for each row. The policy itself cannot be changed from the dashboard — the orchestrator operator manages it via `kici-admin org-settings dashboard-writes`. See [Dashboard-write policy](/operator/security/dashboard-write-policy) for the operator-side details.
 
 ## Approval queue
 
@@ -7067,6 +7917,8 @@ The standalone account page (`/account`) provides access to personal settings ou
 - **Personal access tokens** -- create and revoke PATs for programmatic API access
 - **Linked accounts** -- connect external provider identities (e.g. GitHub) to your KiCI account
 
+Linked accounts control run-attribution metadata only — unlinking a provider here does not remove it as a way to sign in. To change how you sign in, see [Account and sign-in](./account-and-login.md).
+
 This page is also accessible within an org context via the user menu in the sidebar (`/orgs/:customerId/account`).
 
 ## Admin section
@@ -7133,14 +7985,25 @@ The dashboard shows informative error pages instead of blank screens:
 
 Source: https://docs.kici.dev/user/dynamic-values/
 
-Dynamic values let you compute `environment`, `env`, and `concurrencyGroup` at runtime based on the incoming event. Instead of hardcoding static strings, you pass a function that receives the webhook event payload and returns the resolved value.
+Dynamic values let you compute `environment`, `env`, and `concurrencyGroup` at runtime based on the incoming event. Instead of hardcoding static strings, you pass a function that receives the normalized event envelope and returns the resolved value.
 
 ```typescript
 job('deploy', {
   runsOn: ['default'],
-  environment: (event) => event.ref.split('/').pop(),
-  env: (event) => ({ BRANCH: event.ref.split('/').pop() }),
-  concurrencyGroup: (event) => `deploy-${event.ref.split('/').pop()}`,
+  environment: (event) => event.targetBranch,
+  env: (event) => ({ BRANCH: event.targetBranch }),
+  concurrencyGroup: (event) => `deploy-${event.targetBranch}`,
+  steps: [
+    /* ... */
+  ],
+});
+```
+
+```typescript
+job('deploy', {
+  runsOn: 'default',
+  // One shape everywhere: branch on the normalized event type.
+  environment: (event) => (event.type === 'pull_request' ? 'preview' : 'production'),
   steps: [
     /* ... */
   ],
@@ -7167,21 +8030,21 @@ When the compiler detects a pure function, it serializes the function source dir
 **Examples of pure functions:**
 
 ```typescript
-// Simple branch extraction from ref
-environment: (event) => event.ref.split('/').pop();
+// Simple branch extraction
+environment: (event) => event.targetBranch;
 
 // Object literal with string operations
-env: ({ ref }) => ({ BRANCH: ref.split('/').pop() });
+env: (event) => ({ BRANCH: event.targetBranch });
 
 // Concatenation with event data
-concurrencyGroup: (event) => `deploy-${event.ref.split('/').pop()}`;
+concurrencyGroup: (event) => `deploy-${event.targetBranch}`;
 
 // Using safe globals
-env: (event) => ({ UPPER: String(event.ref).toUpperCase() });
+env: (event) => ({ UPPER: String(event.targetBranch).toUpperCase() });
 
 // Local variables are fine
 environment: (event) => {
-  const parts = event.ref.split('/');
+  const parts = event.targetBranch.split('/');
   return parts[parts.length - 1];
 };
 ```
@@ -7201,7 +8064,7 @@ This adds approximately 5-10 seconds of overhead for cloning and evaluation.
 
 ```typescript
 // Async functions cannot be inlined
-environment: async (event) => await lookupEnv(event.ref);
+environment: async (event) => await lookupEnv(event.targetBranch);
 
 // External module references
 env: (event) => {
@@ -7221,18 +8084,18 @@ env: async (event) => {
 
 ## Performance comparison
 
-| Evaluation path                      | Overhead | When used                                                  |
-| ------------------------------------ | -------- | ---------------------------------------------------------- |
-| Static value (string/object literal) | ~0ms     | `environment: 'staging'`                                   |
-| Inline expression (pure function)    | ~0ms     | `environment: (event) => event.ref.split('/').pop()`       |
-| Init job (impure function)           | ~5-10s   | `environment: async (event) => await lookupEnv(event.ref)` |
+| Evaluation path                      | Overhead | When used                                                           |
+| ------------------------------------ | -------- | ------------------------------------------------------------------- |
+| Static value (string/object literal) | ~0ms     | `environment: 'staging'`                                            |
+| Inline expression (pure function)    | ~0ms     | `environment: (event) => event.targetBranch`                        |
+| Init job (impure function)           | ~5-10s   | `environment: async (event) => await lookupEnv(event.targetBranch)` |
 
 ## Tips
 
 - **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** contains the normalized webhook payload. For push events this includes `ref`, `repository`, `sender`, etc. For PR events it includes `pull_request`, `action`, etc.
+- **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`, …).
 
 ---
 
@@ -7240,16 +8103,16 @@ env: async (event) => {
 
 Source: https://docs.kici.dev/user/env-vars/
 
-The KiCI CLI reads the following environment variables to customize its behavior. OAuth login (`kici login` without `--token`) requires `KICI_PLATFORM_URL`, `KICI_OIDC_ISSUER`, and `KICI_OIDC_CLIENT_ID` to be set — the CLI does not ship defaults for them.
+The KiCI CLI reads the following environment variables to customize its behavior. OAuth login (`kici login` without `--token`) defaults `KICI_PLATFORM_URL`, `KICI_OIDC_ISSUER`, and `KICI_OIDC_CLIENT_ID` to the hosted KiCI Platform, so `kici login` works with no configuration. Set them only to target a self-hosted Platform or a testing environment.
 
 ## Authentication
 
-| Variable              | Description                                                 | Default            |
-| --------------------- | ----------------------------------------------------------- | ------------------ |
-| `KICI_OIDC_ISSUER`    | OIDC issuer URL for authentication (required for OAuth)     | none — must be set |
-| `KICI_OIDC_CLIENT_ID` | OIDC client ID for the CLI application (required for OAuth) | none — must be set |
-| `KICI_PLATFORM_URL`   | Platform API base URL (required for OAuth)                  | none — must be set |
-| `KICI_CONFIG_DIR`     | Override the KiCI config directory                          | `~/.kici`          |
+| Variable              | Description                            | Default                                      |
+| --------------------- | -------------------------------------- | -------------------------------------------- |
+| `KICI_OIDC_ISSUER`    | OIDC issuer URL for authentication     | `https://auth.kici.dev/realms/kici-internal` |
+| `KICI_OIDC_CLIENT_ID` | OIDC client ID for the CLI application | `kici-cli`                                   |
+| `KICI_PLATFORM_URL`   | Platform API base URL                  | `https://api.kici.dev`                       |
+| `KICI_CONFIG_DIR`     | Override the KiCI config directory     | `~/.kici`                                    |
 
 ## Browser behavior
 
@@ -7275,9 +8138,9 @@ Authenticate with a pre-existing API key (no browser needed):
 kici login --token <<< "$KICI_API_KEY"
 ```
 
-### Custom OIDC provider
+### Self-hosted Platform or custom OIDC provider
 
-Point the CLI to a self-hosted or testing OIDC provider:
+`kici login` targets the hosted KiCI Platform by default. To point the CLI at a self-hosted Platform or a testing OIDC provider, override the defaults:
 
 ```bash
 export KICI_OIDC_ISSUER=https://your-idp.example.com
@@ -7384,12 +8247,12 @@ export default workflow('deploy', {
 
 ### Dynamic environments
 
-The environment name can be a string or a function (sync or async) for dynamic environments (e.g., per-PR review environments):
+The environment name can be a string or a function (sync or async) for dynamic environments (e.g., per-PR review environments). The function receives the normalized event envelope, with the raw provider body nested at `event.payload`:
 
 ```typescript
 job('deploy-review', {
   runsOn: 'default',
-  environment: async (event) => `review/PR-${event.pull_request.number}`,
+  environment: (event) => `review/PR-${event.payload.pull_request.number}`,
   steps: [
     step('deploy', async (ctx) => {
       // ctx.environment is 'review/PR-123' (resolved at runtime)
@@ -7399,7 +8262,7 @@ job('deploy-review', {
 });
 ```
 
-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](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.
 
 ### Job-level environment variables
 
@@ -7411,7 +8274,7 @@ job('deploy', {
   environment: 'production',
   env: { DEPLOY_TARGET: 'us-east-1' },
   // Or dynamic:
-  // env: async (event) => ({ DEPLOY_SHA: event.after?.slice(0, 7) }),
+  // env: (event) => ({ DEPLOY_SHA: event.payload.after?.slice(0, 7) }),
   steps: [
     step('deploy', async (ctx) => {
       // DEPLOY_TARGET is available in ctx.env
@@ -7433,7 +8296,7 @@ job('deploy', {
   environment: 'production',
   concurrencyGroup: 'production-api',
   // Or dynamic:
-  // concurrencyGroup: async (event) => `review-${event.pull_request.number}`,
+  // concurrencyGroup: (event) => `review-${event.payload.pull_request.number}`,
   steps: [
     /* ... */
   ],
@@ -7496,7 +8359,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 or API. Held runs expire after a configurable timeout (default: 1 hour).
+When reviewers are required, the job enters a "held" state. Reviewers can approve or reject via the dashboard, the [`kici approve`](cli-reference.md#kici-approve) command, or the API. Held runs expire after a configurable timeout.
+
+This operator-set rule is the **mandatory** form of an approval gate. Workflow authors can also declare gates in code with `requireApproval` at step, job, or workflow level — see [Approval gates](approvals.md). Both forms use the same held-element mechanism and the same queue.
 
 ### Wait timer
 
@@ -7560,10 +8425,12 @@ Strategy: queue (or cancel-pending)
 
 ### Creating environments
 
-Navigate to **Settings > Environments** in the dashboard. Click **+ New** to create an inline row with the environment name and type (Fixed or Glob).
+Navigate to **Settings > Environments** in the dashboard. Click **New environment** to choose the environment name and type (Fixed or Glob).
+
+- **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'`
 
-- **Fixed** -- a named environment like `staging` or `production`
-- **Glob** -- a pattern like `review/*` that matches dynamic environment names
+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.
 
 ### Environment detail page
 
@@ -7804,7 +8671,7 @@ export default workflow('nightly-build', {
   on: schedule({ cron: '0 2 * * *' }),
   jobs: [
     job('build', {
-      runsOn: 'ubuntu-latest',
+      runsOn: 'linux',
       steps: [
         step('build', async ({ $ }) => {
           await $`pnpm build`;
@@ -7903,7 +8770,7 @@ export default workflow('build', {
   on: push({ branches: 'main' }),
   jobs: [
     job('build', {
-      runsOn: 'ubuntu-latest',
+      runsOn: 'linux',
       steps: [
         step('build', async ({ $ }) => {
           await $`pnpm build`;
@@ -7958,7 +8825,7 @@ export default workflow('post-deploy', {
   on: kiciEvent({ name: 'deploy-complete', match: { '$.env': 'prod' } }),
   jobs: [
     job('smoke-test', {
-      runsOn: 'ubuntu-latest',
+      runsOn: 'linux',
       steps: [
         step('test', async ({ $ }) => {
           await $`./scripts/smoke-test.sh`;
@@ -8246,7 +9113,7 @@ export default workflow('build', {
 });
 ```
 
-The same pattern works for GCP Artifact Registry — replace the `aws codeartifact` call with `gcloud auth print-access-token`. A typed `RegistryProvider` for these short-lived flows is on the roadmap; the manual setup-step is the supported path until then.
+The same pattern works for GCP Artifact Registry — replace the `aws codeartifact` call with `gcloud auth print-access-token`. The manual setup-step shown here is the supported path for these short-lived flows.
 
 ## Provider-specific examples
 
@@ -8774,7 +9641,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/kici-admin-cli.md).
+[kici-admin CLI reference](../../operator/orchestrator/kici-admin-cli.md).
 
 ## Routing keys
 
@@ -8927,7 +9794,7 @@ and confirm the App is installed on that repo.
   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/kici-admin-cli.md)
+- [kici-admin CLI reference](../../operator/orchestrator/kici-admin-cli.md)
 - [Event routing](../../operator/event-routing.md) — operator-level
   routing-key mechanics
 
@@ -9180,7 +10047,7 @@ Source: https://docs.kici.dev/architecture/data-flows/
 
 This document describes the key data flows through the KiCI architecture: webhook delivery, job execution, 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 12, which adds `registries` and `installEnv` fields for private registry support on top of 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 15, which adds per-job init config on top of v14's declarative cache specs, v11's `LockInlineValue` for pure function inline evaluation, v10's simplified negative patterns (! prefix in repos/paths arrays), v9's global workflow repos matching, and v8's runsOn polymorphic type support.
 
 ## Webhook delivery flow
 
@@ -9206,7 +10073,7 @@ GitHub  -->  Platform Relay  -->  Orchestrator  -->  Agent
 10. **Orchestrator fetches lock file** via the provider's `LockFileFetcher` (cached with LRU). For untrusted PR events, fetches both base and head lock files in parallel; for trusted PRs and pushes, fetches from head SHA.
 11. **Orchestrator detects workflow modifications** for untrusted PR events by comparing base and head lock files via `detectWorkflowModifications()`, applying security holds when non-trusted contributors modify workflow files.
 12. **Orchestrator extracts registrations** on default-branch pushes: persists registerable workflows (event, schedule, lifecycle triggers) for cluster-wide event matching.
-13. **Orchestrator registers event subscriptions** from lock file (if event routing is active) via `eventRouter.registerSubscriptions()`.
+13. **Orchestrator notifies the event router** on default-branch pushes: after the registrations are persisted, emits a `registration.updated` event via `eventRouter.emit()` (if event routing is active). Workflow event subscriptions are the persisted registrations themselves, matched at emit time through the registration index.
 14. **Orchestrator fetches changed files** via the provider's `ChangedFilesFetcher` for path-based trigger filtering (skipped when no workflow uses path filters).
 15. **Orchestrator matches triggers** against lock file using `matchAllWorkflows()` from `@kici-dev/engine`.
 16. **Orchestrator checks caches** for source tarballs and dependency tarballs.
@@ -9349,9 +10216,9 @@ The source cache and dep cache are independent. Four combinations are possible:
 
 Dep cache misses alone do **not** trigger a build job. Deps are platform-specific (`deps/{platform}-{arch}/{hash}.tar.gz`) so a build job would need a builder agent matching the target platform, which may not exist (e.g., an arm64 builder when only x64 builders are available). When the source cache misses, the dispatched build job piggy-backs dep packing if deps are also missing. A single build job handles both artifacts when both miss, avoiding duplicate builds.
 
-### Legacy / cross-source / no-contentHash workflows
+### 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 12 (see [Design decisions](design-decisions.md#lock-file-schema-versioning)).
+- **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 15.
 - **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
@@ -9435,6 +10302,64 @@ The two-phase metadata approach (`upload via PUT` then `initMeta via CopyObject`
 
 Agents receive pre-signed S3 GET URLs (15-minute expiry) directly in `job.dispatch` messages. Agents download artifacts from S3, bypassing the orchestrator for all data transfer.
 
+## 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 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.
+
+### Restore flow
+
+```
+Agent                              Orchestrator (UserCache)          Object storage
+  |                                      |                                |
+  |-- cache.user.restore.request ------->|                                |
+  |   { key, restoreKeys? }              |-- exact key in read prefixes ->|
+  |                                      |   (isolated: iso/<runId>/      |
+  |                                      |    then shared/; trusted:      |
+  |                                      |    shared/ only)               |
+  |                                      |-- restoreKeys prefix scan ---->|
+  |                                      |   (newest match wins)          |
+  |                                      |-- getUrl(matched) + touch ---->|
+  |<-- cache.user.restore.response ------|                                |
+  |   { hit, matchedKey?,                |                                |
+  |     downloadUrl?, tarHash? }         |                                |
+  |                                      |                                |
+  |-- HTTP GET (tarball body) -------------------------------------->|
+  |   (direct download; verify tarHash, extract paths)                |
+```
+
+The restore resolves the exact `key` across the ref's read prefixes first, then each `restoreKeys` prefix in order (newest matching entry wins). A trusted ref reads only `shared/`; an untrusted/fork ref reads its own `iso/<runId>/` scope and then falls back to `shared/`. On a hit the response carries a presigned GET URL plus the tarball's `tarHash`, which the agent verifies before extracting.
+
+### Save flow (two-phase atomic)
+
+```
+Agent                              Orchestrator (UserCache)          Object storage
+  |                                      |                                |
+  |-- cache.user.save.request --------->|                                |
+  |   { key }                            |-- has(final key)? ------------>|
+  |                                      |   (immutable: skip if exists)  |
+  |                                      |-- getUploadUrl(.tmp-<uuid>) -->|
+  |<-- cache.user.save.response ---------|                                |
+  |   { uploadUrl?, skip }               |                                |
+  |                                      |                                |
+  |-- HTTP PUT (tarball body) ----------------------------------->|
+  |   (direct upload to temp object)                              |
+  |                                      |                                |
+  |-- cache.user.save.complete -------->|                                |
+  |   { key, tarHash, sizeBytes }        |-- copy(temp -> final) -------->|
+  |                                      |-- delete(temp) --------------->|
+  |                                      |-- initMeta(final) ------------>|
+  |                                      |-- put(.hash) + put(.size) ---->|
+  |                                      |-- enforce per-org quota ------>|
+```
+
+The save is **immutable** and **atomic**. The orchestrator declines (`skip: true`) up front if the exact key already exists. Otherwise the agent uploads to a `.tmp-<uuid>` object via a presigned PUT, then `cache.user.save.complete` triggers a server-side copy temp→final, a delete of the temp, an `initMeta` to stamp TTL metadata, and `.hash` / `.size` companion writes. Because the final key only appears after the copy, a crashed upload never leaves a corrupt committed entry. The committing save then enforces the per-org byte quota, evicting oldest entries until the org is back under `KICI_USER_CACHE_QUOTA_BYTES`.
+
+### 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.
+
 ## Internal event routing flow
 
 Internal events (custom events from `ctx.emit()` and system events from workflow/job completion) flow through the event router for fan-out delivery to matching workflows.
@@ -9467,11 +10392,11 @@ EventRouter.onNotification(eventId) [private]
   |      increments attempts and records claimed_at/claimed_by atomically)
   |-- If lease acquired:
   |     |-- processSubscriptions(event):
-  |     |     |-- If RegistrationIndex available (new path):
+  |     |     |-- If RegistrationIndex available:
   |     |     |     Look up registrations by trigger type
   |     |     |     TrustStore.isTrusted() (for cross-repo events)
   |     |     |     matchAllWorkflows() against registered workflows
-  |     |     |-- Else (legacy fallback):
+  |     |     |-- Else (no RegistrationIndex):
   |     |     |     TrustStore.isTrusted() (for cross-routing-key events)
   |     |     |     matchAllWorkflows() against in-memory lock file subscriptions
   |     |     |-- For each match: onEventMatched(event, lockFile, matchedWorkflows)
@@ -9503,7 +10428,7 @@ Two invariants keep events from being silently lost:
   event lands in the DLQ (`dlq_at` set, `dlq_reason='exhausted_retries'`)
   and is surfaced via Prometheus (`kici_orch_event_dlq_*`), Grafana
   (`event-delivery` dashboard), and the kici-admin CLI
-  (`kici-admin event-dlq {list,retry,discard}`).
+  (`kici-admin event-dlq {list,count,retry,discard}`).
 - **Crash detection:** when a node crashes mid-dispatch, its lease ages out
   after `leaseDurationMs` (default 60 s). The leader's
   `EventRetryScanner` releases the expired lease and re-publishes
@@ -9939,141 +10864,6 @@ The Platform tier exposes a `/ws/browser` WebSocket endpoint for dashboard clien
 
 ---
 
-## Design decisions
-
-Source: https://docs.kici.dev/architecture/design-decisions/
-
-This page explains the rationale behind KiCI's major architectural choices. Each section describes the decision, why it was made, and what alternatives were considered.
-
-## TypeScript over YAML
-
-**Decision:** Workflows are defined in TypeScript, not YAML.
-
-TypeScript provides full language power -- type checking, IDE autocomplete, refactoring tools, conditional logic, and composability. Workflows are regular TypeScript code that can be tested, imported, and reused like any other module. YAML-based CI systems (GitHub Actions, CircleCI) limit expressiveness to what the YAML schema supports, requiring workarounds for anything beyond basic conditionals.
-
-**Alternative:** YAML workflow definitions (industry standard). Rejected because YAML constrains what users can express and makes workflows harder to test and refactor.
-
-## Lock file approach
-
-**Decision:** The compiler generates a `kici.lock.json` file that separates workflow definitions from runtime execution.
-
-The lock file is a JSON snapshot of workflow definitions with static triggers pre-evaluated at compile time. This enables the orchestrator to match triggers without cloning code -- it fetches only the lock file via the GitHub API. Dynamic elements (dynamic jobs, dynamic matrices, rules) are represented as source references in the lock file and evaluated at runtime by the agent.
-
-**Alternative:** Runtime evaluation of TypeScript at the routing tier. Rejected because it would require the orchestrator to clone repositories for trigger matching, adding latency and complexity to the dispatch path.
-
-> See `packages/compiler/src/` for the compiler that generates lock files.
-
-## Three-tier relay model
-
-**Decision:** The system is split into three deployment tiers: Platform (webhook router), orchestrator (execution brain), and agent (execution worker).
-
-This architecture separates trust boundaries. Customer code never leaves customer infrastructure -- the Platform tier handles only webhook verification and routing, with no access to customer code or secrets. The orchestrator matches triggers without cloning code. Only the agent, running on customer infrastructure, clones repositories and executes steps. The three-tier model also enables fully self-hosted deployment where all tiers run on customer infrastructure.
-
-**Alternative:** Monolithic Platform that runs everything (customer code on KiCI servers). Rejected because it requires customers to trust a third party with their source code and secrets.
-
-> See [Architecture Overview](overview.md) for the full three-tier diagram.
-
-## Synchronous webhook relay
-
-**Decision:** The Platform tier relays webhooks synchronously over WebSocket: verify signature, route to orchestrator, wait for ACK, respond to GitHub.
-
-Synchronous relay is simpler, lower latency, and eliminates infrastructure dependencies. GitHub's built-in webhook retry mechanism handles the failure case -- if the Platform tier cannot relay (no orchestrator connected), it returns an error and GitHub retries automatically. This approach removed the need for a separate broker and an async job queue.
-
-**Alternative:** Async queue (store webhook in a queue, process later). Rejected because it added infrastructure complexity (a separate broker and queue layer) without meaningful benefit -- GitHub already provides reliable retry behavior.
-
-## Per-source webhook secrets
-
-**Decision:** Each webhook source has its own webhook secret stored on the orchestrator side, dynamically registered by orchestrators via the `source.register` protocol message.
-
-Per-source secrets enable multi-tenant Platform with proper isolation. Each customer's webhook source (e.g., a GitHub App) has a unique webhook secret, and signature verification uses the correct secret for each incoming webhook based on the routing key derived from the `X-GitHub-Hook-Installation-Target-ID` header.
-
-**Alternative:** A single shared webhook secret via environment variable. Rejected because it cannot support multiple tenants and provides no isolation between customers.
-
-## Routing key routing
-
-**Decision:** Webhooks are routed by provider-scoped routing key (e.g., `github:12345`) derived from the `X-GitHub-Hook-Installation-Target-ID` header. One routing key maps to one orchestrator connection.
-
-App ID routing provides a clean 1:1 mapping between a customer's GitHub App and their orchestrator. The orchestrator extracts the `installation_id` from the webhook payload body for GitHub API calls (fetching lock files, posting check runs).
-
-**Alternative:** Route by Installation ID (more granular, one App can have many installations). Rejected because it adds complexity without clear benefit -- most customers use one App with one or a few installations, and the orchestrator can handle multiple installations internally.
-
-## PostgreSQL as the orchestrator's only data store
-
-**Decision:** The customer-deployable orchestrator depends on a single PostgreSQL database — no separate broker, cache, or pub/sub system. PostgreSQL is the primary data store on the Platform tier as well (the two tiers run independent databases).
-
-PostgreSQL backs the orchestrator's durable job queue (delayed and recurring jobs, retries, dead-letter handling), workflow runs, dispatched jobs, sources, secrets, and event registrations. All DB access goes through a typed SQL query layer. Cross-instance coordination inside an orchestrator cluster (peer announcements, run cancellation, secret invalidation) uses PostgreSQL LISTEN/NOTIFY, so adding orchestrator replicas does not introduce a new infrastructure dependency.
-
-**Alternative:** A separate broker / queue / pub-sub system alongside PostgreSQL. Rejected for the customer-deployable orchestrator because PostgreSQL covers durable jobs, transactional state changes, and cross-instance coordination in a single dependency — adding a broker would multiply operator surface area without buying customers a capability they don't already have.
-
-## Pure-function state machine
-
-**Decision:** The state machine uses pure functions: `transition(state, event) -> newState` with no internal state, no classes, and no mutation.
-
-Pure functions are trivially testable (input/output, no setup), serializable (state is a string), and usable across all tiers without instantiation. The transition table is a plain `Record` for type-safe dispatch. The state machine tracks workflow runs, jobs, and steps using 11 states and 16 events.
-
-**Alternative:** Class-based state machine with internal state (e.g., `machine.apply(event)`). Rejected because it is harder to test (requires instantiation and lifecycle management), harder to serialize (class instances), and adds unnecessary complexity for a simple state transition problem.
-
-> See `packages/engine/src/state-machine/machine.ts` for the implementation and [State Machine](./execution/state-machine.md) for full documentation.
-
-## Single agent binary with label-based routing
-
-**Decision:** One agent binary, configured with labels via the `KICI_LABELS` environment variable (e.g., `linux,docker,gpu`). The orchestrator routes jobs by matching `runsOn` labels against registered agent labels.
-
-A single binary simplifies deployment and maintenance. Labels provide flexible routing without requiring separate agent builds or deployments per platform. New capabilities are added by deploying the same binary with different labels and environment configuration.
-
-**Alternative:** Separate agent binaries per platform (e.g., `kici-agent-linux`, `kici-agent-docker`). Rejected because it multiplies build and deployment complexity without meaningful benefit.
-
-> See `packages/agent/src/config.ts` for label configuration.
-
-## Lock file schema versioning
-
-**Decision:** The lock file includes a `schemaVersion` field that tracks breaking changes to the trigger format.
-
-| Version | Description                                                                                                                                                                                                                                                                                                                                              |
-| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 12      | Current schema. Covers everything in v11 plus per-workflow `registries` and `installEnv` fields for private-package authentication. Token bytes never appear in the lock file — only qualified `<environment>:<secret-name>` references that the orchestrator resolves at dispatch time through the per-environment secret resolver.                     |
-| 11      | Covers the full trigger taxonomy (git events, internal events, schedule, lifecycle, generic webhooks), the `_type` discriminator on each trigger entry, polymorphic `runsOn` matching with `excludeLabels`, hook and concurrency flags on `LockJob`, repo-pattern matching with `!` negation, and `LockInlineValue` for pure-function inline evaluation. |
-
-The `_type` field on each lock file trigger entry identifies the trigger type for the matcher's exhaustive switch dispatch. Users must recompile workflows with `pnpm kici compile` after upgrading to get the latest trigger types in their lock files.
-
-**`SimulatedEvent.type`** is an open `string` type, allowing the `kici test` CLI to simulate any event type without requiring engine changes for each new event.
-
-## Two-phase evaluation
-
-**Decision:** Trigger matching happens in two phases: fast reject at the orchestrator (no clone needed) and full evaluation at the agent (clone and run TypeScript).
-
-The orchestrator evaluates static triggers from the lock file -- branch patterns, path patterns, and event types. This is fast and requires only a small JSON file fetched via the GitHub API. The agent handles everything that requires code: rule evaluation (arbitrary TypeScript functions), dynamic job generation, and dynamic matrix expansion. This separation keeps the orchestrator fast and git-agnostic.
-
-**Alternative:** Full evaluation at the orchestrator (clone repo, run TypeScript, then dispatch). Rejected because it would make the orchestrator slow, require git access at the routing tier, and blur the trust boundary between routing and execution.
-
-## Registration model for event-triggered workflows
-
-**Decision:** Workflows with non-Git triggers (schedule, kiciEvent, genericWebhook, workflowComplete, jobComplete, lifecycle) are extracted from the lock file on default-branch push and stored in a registration database. The orchestrator matches incoming events against these registrations without fetching the lock file each time.
-
-**Why:** Git-based triggers (push, PR) work with per-event lock file fetching because the webhook itself provides the repo and ref. Internal events (cron fires, custom events, workflow completions) do not carry repo/ref information -- the orchestrator needs to know which workflows to evaluate before the event arrives. The registration model solves this by pre-populating the orchestrator's knowledge of event-triggered workflows.
-
-**Alternative:** Fetch all lock files from all known repos on every internal event. Rejected because it would be O(repos \* events) API calls, adding unacceptable latency and GitHub API rate limit pressure.
-
-> See `packages/orchestrator/src/registration/` for the implementation.
-
-## Event trigger matching via registration index
-
-**Decision:** The event router matches events exclusively against the DB-backed `RegistrationIndex`. A previous legacy in-memory subscription fallback was removed since the registration index is always available and is the sole authoritative source for trigger matching.
-
-**Why:** A single code path eliminates drift risk between dual paths, halves the test surface, and avoids confusing future contributors about which path is authoritative. The project's pre-release "no backward compatibility" rule means deferred cleanup shouldn't accumulate.
-
-> See `packages/orchestrator/src/events/event-router.ts` and `packages/orchestrator/src/registration/` for the implementation.
-
-## See also
-
-- [Architecture Overview](overview.md) -- the three-tier model and package structure
-- [State Machine](./execution/state-machine.md) -- details of the pure-function state machine
-- [Webhook Delivery](./webhooks/webhook-delivery.md) -- synchronous relay in action
-- [Reconnection](./clustering/reconnection.md) -- WebSocket resilience patterns
-- [Event System Internals](./webhooks/event-system.md) -- event router, registration model, cron scheduler
-
----
-
 ## Architecture overview
 
 Source: https://docs.kici.dev/architecture/overview/
@@ -10233,14 +11023,17 @@ flowchart TD
     PLATFORM --> SHARED
     ORCH --> ENGINE
     ORCH --> SHARED
+    ORCH -.->|dev| AGENT
     AGENT --> ENGINE
     AGENT --> SDK
     AGENT --> SHARED
+    AGENT --> CORE
     KICI["kici (wrapper)"]
     KICI --> COMPILER
     KICI --> CORE
     KICIADMIN["kici-admin (admin CLI)"]
     KICIADMIN --> ORCH
+    KICIADMIN --> AGENT
 ```
 
 **Leaf packages** (no `@kici` dependencies): `@kici-dev/core` and `@kici-dev/engine`. These can be tested and built independently. `@kici-dev/shared` builds on `@kici-dev/core` and re-exports it. The dashboard depends on `@kici-dev/engine` for shared types (protocol schemas, state machine) and imports the Platform's API type definitions as a dev dependency, but communicates with backend services at runtime via HTTP/WebSocket, not at compile time.
@@ -10277,6 +11070,5 @@ KiCI uses application-level tenant isolation. The Platform dashboard API accepts
 - [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
-- [Design Decisions](design-decisions.md) -- rationale behind the three-tier model and other architectural choices
 
 ---