@kici-dev/compiler 0.6.1 → 0.8.0

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

@@ -48,7 +48,7 @@ The lock file is the seam. Everything left of it is decided once at compile time
 
 `kici compile` loads your `.kici/workflows/*.ts`, validates dependencies (no cycles, no missing `needs`), assigns compile-time step IDs (unnamed steps become `step-1`, `step-2`, …), and writes `kici.lock.json`.
 
-The compiler runs your module's **top-level code** to build the workflow object — but that execution's side effects and in-memory state do not travel. Only the resulting workflow structure lands in the lock. Anything your top-level code computes that isn't part of the returned workflow object simply doesn't exist past this point.
+The compiler runs your module's **top-level code** to build the workflow object — but that execution's side effects and in-memory state do not travel. Only the resulting workflow structure lands in the lock. Anything your top-level code computes that isn't part of the returned workflow object doesn't exist past this point.
 
 See [compile the workflow](https://docs.kici.dev/user/getting-started/#compile-the-workflow) for the command in context.
 
@@ -204,7 +204,7 @@ kici runs logs <run-id>
 When you cannot resolve it yourself, gather a diagnostic bundle:
 
 ```bash
-kici report --run <run-id> --message "what you expected, and what happened"
+kici report --run <run-id>
 ```
 
 The command writes a ZIP and prints its path and `sha256`. It sends nothing.
@@ -311,7 +311,7 @@ npx kici init
 This will:
 
 1. Create `.kici/` directory with `workflows/`, `tests/`, `types/`, `package.json`, and `tsconfig.json`. The `types/` folder holds a local development aid — TypeScript declarations that `kici types` (and an authenticated `kici compile`) generate from your orchestrator's secret contexts. Its content is a snapshot of one org's secret keys, so it is not committed.
-2. Create a `.kiciignore` file with sensible defaults
+2. Create two `.kiciignore` files with sensible defaults: one at the repo root, which selects the working-tree files a remote run uploads, and one inside `.kici/`, which declares the paths the per-workflow content hash skips
 3. Let you choose from starter workflow templates (hello-world, pr-checks)
 4. Install dependencies using the package manager detected for your repo (npm, pnpm, or yarn)
 5. Update `.gitignore` to exclude `.kici/node_modules/`, and write `.kici/.gitignore` to keep the generated `types/` declarations untracked (`kici.lock.json` stays tracked — the orchestrator fetches it from your repo)
@@ -590,7 +590,7 @@ Point to a local SDK checkout for IDE autocompletion:
 {
   "name": "my-project-kici",
   "devDependencies": {
-    "@kici-dev/sdk": ">=0.0.1-0"
+    "@kici-dev/sdk": "latest"
   },
   "kici": {
     "sdkPath": "../../packages/sdk"
@@ -602,7 +602,7 @@ The `sdkPath` field tells the compiler where to resolve TypeScript path mappings
 
 ### KICI_DEV environment variable
 
-Set `KICI_DEV=true` to use a prerelease-compatible version range (`>=0.0.1-0`) in generated files, which resolves prerelease builds from a local Verdaccio registry:
+Set `KICI_DEV=true` to pin the SDK to the `latest` dist-tag in generated files, which resolves prerelease builds from a local Verdaccio registry:
 
 ```bash
 KICI_DEV=true npx kici init
@@ -1781,6 +1781,74 @@ For a **minted app token**, prefer re-deriving over transporting — those expir
 after an hour, so one minted in an earlier job is often already dead by the time
 a later job reads it. Have the later job name the same secret, or mint its own.
 
+## What a job may ask for
+
+A credential is authorized against the workflow you wrote, not against the code
+running in the job. Three things must all hold before the orchestrator resolves
+one:
+
+1. **The job declared it.** The orchestrator records the job's `gitCredentials`
+   map when it dispatches the job, and compares every request against that
+   record. A request naming a credential the job did not declare is refused.
+   This is why you pass `credential: 'forge'` — a name — rather than building a
+   credential reference in step code.
+2. **The named context admits the run.** A `prod:` reference runs the `prod`
+   context's own protection rules first: its branch restrictions, its
+   `minimumTrust`, its approval requirement. A credential named from a branch
+   the context does not allow is refused, and the git operation fails. The rule
+   that refused it is named in your orchestrator's log, not in the run — the
+   orchestrator returns a fixed error to the job rather than describing its own
+   configuration to code it does not trust.
+3. **The contributor is trusted.** A run from an untrusted ref — a fork pull
+   request — gets no declared credential at all. It still clones with the
+   source credential, so the build runs; only the declared credentials are
+   withheld. The reduced-privilege note on the run says so.
+
+The context in a reference does **not** have to appear in the job's `contexts:`
+list. The reference names its own context, and that context's rules are what
+authorize it.
+
+## Generated jobs
+
+A job produced by a `dynamicJob` generator has no entry in the lock file, so it
+cannot declare credentials of its own. The **generator** declares them, and every
+job it produces inherits that map:
+
+```typescript
+dynamicJob('shards', {
+  gitCredentials: {
+    forge: { kind: 'token', tokenSecret: 'ci:FORGE_PAT' },
+  },
+  generate: async ({ ctx }) =>
+    ctx.event.payload.targets.map((target) =>
+      job(`publish-${target}`, {
+        runsOn: 'linux',
+        run: async ({ $, repo }) => {
+          await repo.withWrite(
+            { permissions: { contents: 'write' }, credential: 'forge' },
+            async () => {
+              await $`git push origin HEAD`;
+            },
+          );
+        },
+      }),
+    ),
+});
+```
+
+Three points follow from where the declaration lives:
+
+- **All generated jobs share one map.** The generator is granted one ceiling, and
+  every job it produces gets exactly that ceiling. Use a second generator when
+  two sets of jobs need different credentials.
+- **A `gitCredentials` map on a generated job is ignored.** The generator's
+  declaration is committed source that KiCI reads from the lock file. A generated
+  job's own declaration would come from the code that produced it, which is what
+  the authorization check above exists to be independent of.
+- **The options form is required.** `dynamicJob('shards', async () => …)` — the
+  bare function form — has nowhere to put the declaration. Pass
+  `{ generate, gitCredentials }` instead; `needs` stays optional.
+
 ## How it works, and why long jobs still push
 
 An app token expires an hour after it is issued, and cannot be renewed. Rather
@@ -1797,6 +1865,10 @@ does at the start, and no credential is ever written into `.git/config`, into
   unaffected.
 - **The reserved `needs:` context is not resolvable yet** on a deployed
   orchestrator; naming it produces a clear error rather than a wrong credential.
+- **A credential reference built in step code is refused.** The SDK takes a
+  credential _name_; there is no way to pass a reference. Code that constructs
+  one and sends it directly is rejected by the agent and, if it reaches the
+  orchestrator, by the declaration check above.
 - **A write window is bounded by the repository and the callback, not the step.**
   Steps running concurrently in the same job can push to the same repository
   while it is open. They cannot reach a different one.
@@ -2131,8 +2203,10 @@ KiCI has no native provider for Gogs, Forgejo, or Gitea, but these forges send H
 ```bash
 # Forgejo / Gitea send event name in X-Gitea-Event and signature in X-Gitea-Signature.
 # Gogs uses X-Gogs-Event and X-Gogs-Signature (same HMAC-SHA256 hex-digest format).
+# --org must be your Platform organization id: a generic source's routing key
+# embeds it, and the Platform refuses to register a key naming another org.
 kici-admin source add generic \
-  --org my-org \
+  --org <platform-org-id> \
   --name forgejo-main \
   --verification hmac_sha256 \
   --secret @/path/to/webhook-secret.txt \
@@ -2140,7 +2214,7 @@ kici-admin source add generic \
   --rate-limit 120
 ```
 
-Note the returned source ID, then register a webhook in the forge pointing at `https://<platform>/webhooks/<orgId>/generic/<sourceId>` (or the orchestrator's direct URL). Set content type to `application/json` and paste the same secret.
+Note the returned source ID, then register a webhook in the forge pointing at `https://<platform>/webhook/<orgId>/generic/<sourceId>` (or the orchestrator's direct URL, which takes the source **name** in place of the id). Set content type to `application/json` and paste the same secret.
 
 **Workflow:**
 
@@ -2207,14 +2281,16 @@ HTTPS with a forge PAT works the same way — store the token as a secret, `awai
 
 ## Plain GitHub repo webhooks (no GitHub App)
 
-The Gogs/Forgejo/Gitea pattern above also applies when you want to trigger workflows from a GitHub repository **without installing the KiCI GitHub App** — for example because you lack org-admin rights, you're on a restricted GitHub Enterprise tenant, or you simply don't want an App installation. Model the repo-level webhook as a generic source, accepting the same `genericWebhook()`-only ergonomics.
+The Gogs/Forgejo/Gitea pattern above also applies when you want to trigger workflows from a GitHub repository **without installing the KiCI GitHub App**. You may lack org-admin rights, sit on a restricted GitHub Enterprise tenant, or not want an App installation. Model the repo-level webhook as a generic source, accepting the same `genericWebhook()`-only ergonomics.
 
 **Operator setup:**
 
 ```bash
 # GitHub sends event name in X-GitHub-Event and HMAC-SHA256 signature in X-Hub-Signature-256.
+# --org must be your Platform organization id: a generic source's routing key
+# embeds it, and the Platform refuses to register a key naming another org.
 kici-admin source add generic \
-  --org my-org \
+  --org <platform-org-id> \
   --name gh-repo-foo \
   --verification hmac_sha256 \
   --secret @/path/to/webhook-secret.txt \
@@ -2231,7 +2307,7 @@ curl -X PATCH https://<orchestrator>/api/v1/admin/generic-sources/<sourceId> \
 
 Then in the GitHub repo, go to **Settings → Webhooks → Add webhook**, set:
 
-- **Payload URL:** `https://<platform>/webhooks/<orgId>/generic/<sourceId>` (or the orchestrator's direct URL)
+- **Payload URL:** `https://<platform>/webhook/<orgId>/generic/<sourceId>` (or the orchestrator's direct URL, which takes the source **name** in place of the id)
 - **Content type:** `application/json`
 - **Secret:** the same secret
 - **Events:** pick what you care about (e.g., `push`, `pull_request`)
@@ -2688,6 +2764,7 @@ runsOn: { labels: ['kici:os:linux'], exclude: ['kici:host:box-01'] }
 
 - **Required labels:** The agent must have every label in the `labels` array (or the string/array form).
 - **Excluded labels:** The agent must NOT have any label in the `exclude` array. This includes auto-derived labels like `kici:arch:arm64`, `kici:os:linux`, etc.
+- **Case:** Label matching is **case-insensitive** at every step. `runsOn: 'gpu'` matches an agent that reports `GPU`, and a pool declaring `["Docker"]` serves a `runsOn: ["docker"]` job (see [auto-scaler matching rules](https://docs.kici.dev/operator/orchestrator/auto-scaler/operations/#matching-rules)). KiCI stores and displays every label in lowercase, so the dashboard, `kici-admin agent list`, and `ctx.kici.inventory[…].labels` report the folded form. Compare against a lowercase value when you read a label back in workflow code: `h.labels.includes('gpu')`, not `h.labels.includes('GPU')`.
 - **Compile-time validation:** The compiler will error if any label appears in both `labels` and `exclude` (overlap detection).
 - **Operator-declared mandatory labels:** Operators may mark a scaler with `mandatoryLabels` (Kubernetes-taint-style opt-in). When a scaler declares a mandatory label, a job is only allowed to land on it if `runsOn.labels` includes that label. A workflow targeting such a scaler must explicitly list the mandatory label in `runsOn`. See the [auto-scaler mandatory labels](https://docs.kici.dev/operator/orchestrator/auto-scaler/common-config/#mandatory--exclude-labels) for details.
 
@@ -2740,6 +2817,12 @@ Every selector element — in `runsOn`, in `runsOnAll`, on both the include and
 - **String with glob metacharacters (`*`, `?`, `[]`, `{}`) → glob.** `'kici:host:web-*'` matches every host label starting with `kici:host:web-`. `'kici:host:box-0[1-3]'` matches `box-01`, `box-02`, `box-03`.
 - **`RegExp` literal → regular expression.** `/kici:host:box-0[1-3]/` matches any label the expression matches.
 
+All three forms match case-insensitively. `'GPU'`, `'kici:host:Web-*'` and `/kici:host:BOX-0[1-3]/` each match a label of any case, and a `RegExp` you write with the `i` flag behaves the same. The `g` and `y` flags are dropped — a selector asks one question per label, so a sticky match would resume part-way through the next one.
+
+`kici:host:` carries the machine's hostname folded to lowercase. A host that calls itself `Build-Box-01` advertises `kici:host:build-box-01`, and both `runsOn: 'kici:host:build-box-01'` and `runsOn: 'kici:host:Build-Box-01'` match it.
+
+Case folding covers labels and hostnames only. An **agent ID** stays an opaque identifier and compares exactly, which is what keeps a per-host secret binding on `prod-01` away from an agent named `PROD-01` — see [per-host secret scoping](https://docs.kici.dev/operator/security/secrets/#per-host-secret-scoping).
+
 Both the required (include) side and the excluded side accept all three forms:
 
 ```typescript
@@ -3398,11 +3481,19 @@ Tag a dynamic job generator with a group name so other jobs can reference it via
 ```typescript
 function dynamicJob(
   groupName: string,
-  fnOrConfig: DynamicJobFn | { needs: DynamicJobNeed[]; generate: DynamicJobFn },
+  fnOrConfig:
+    | DynamicJobFn
+    | {
+        needs?: DynamicJobNeed[];
+        generate: DynamicJobFn;
+        gitCredentials?: GitCredentialMap;
+      },
 ): TaggedDynamicJobFn;
 ```
 
-The second argument is either a plain generator (event-only, evaluated at webhook time) or a result-aware `{ needs, generate }` config, which defers the generator until its declared upstreams complete and exposes their frozen outputs as `ctx.needs`. See [Rules, matrix, dynamic jobs](https://docs.kici.dev/user/sdk/rules-matrix-dynamic/#dynamicjob--result-aware-generation) for the result-aware form.
+The second argument is either a plain generator (event-only, evaluated at webhook time) or an options config. An options config that declares `needs` is result-aware: it defers the generator until those upstreams complete and exposes their frozen outputs as `ctx.needs`. See [Rules, matrix, dynamic jobs](https://docs.kici.dev/user/sdk/rules-matrix-dynamic/#dynamicjob--result-aware-generation) for the result-aware form.
+
+`needs` is optional. An options config without it is evaluated at webhook time, like the plain generator form. Use that form to declare `gitCredentials` on an event-only generator: every job the generator produces inherits the map, which is the only way a generated job gets named credentials. See [Git credentials](https://docs.kici.dev/user/patterns/git-credentials/#generated-jobs).
 
 The generator runs twice: once in the init phase (to register expected job names) and once inside the executing agent (to produce the actual jobs). Mismatches between the two evaluations are detected as determinism drift -- see [dynamic-jobs](https://docs.kici.dev/architecture/execution/dynamic-jobs/).
 
@@ -3581,6 +3672,11 @@ The throw is a `ChangedFilesUnavailableError` (exported from `@kici-dev/sdk`, ca
 
 ### evaluateRules(rules, context, label, onRuleResult?)
 
+The agent calls this on your behalf. A workflow does not call it. It lives on
+`@kici-dev/sdk/internal`, outside semver, and stays exported from the root barrel as
+`@deprecated` until v1.0.0 — see [deprecations](https://docs.kici.dev/user/deprecations/). It is described here
+because its return shape is what a rule's outcome looks like in the run log.
+
 Evaluate an array of rules sequentially with fail-fast behavior. Stops on the first failure.
 
 ```typescript
@@ -3648,7 +3744,7 @@ Every variant carries the shared `EventBase` fields — `type`, `action`, `targe
 
 Matrix configurations expand a single job into multiple instances, one per parameter combination. Maximum 256 combinations.
 
-Combinations must be **unique**. Two combinations that would produce the same instance name — most simply, the same value listed twice — fail the job instead of quietly running it twice.
+Combinations must be **unique**. Two combinations that would produce the same instance name — in the simplest case, the same value listed twice — fail the job instead of quietly running it twice.
 
 Expansion happens at **dispatch time**: the orchestrator materializes the matrix into N execution jobs — one per combination, each dispatched to its own agent — before any job runs. Each instance receives its combination as `ctx.matrix`. This is identical whether the workflow runs via `kici run <event> --local` or remotely through a webhook trigger, and the dashboard groups the N instances under one parent node.
 
@@ -3831,8 +3927,13 @@ isDynamicFunction(matrix); // true if async function
 
 ### Matrix expansion utilities
 
+The agent expands a matrix for you. A workflow does not call these. They live on
+`@kici-dev/sdk/internal`, outside semver, and stay exported from the root barrel as
+`@deprecated` until v1.0.0 — see [deprecations](https://docs.kici.dev/user/deprecations/). They are described
+here because they define the combinations a matrix job actually produces.
+
 ```typescript
-import { expandMatrix, applyIncludeExclude } from '@kici-dev/sdk';
+import { expandMatrix, applyIncludeExclude } from '@kici-dev/sdk/internal';
 ```
 
 `expandMatrix(matrix)` takes a string array or an object of string arrays and returns all combinations as `MatrixValues[]`. For a single-dimension array, each value becomes `{ value: '...' }`. For multi-dimensional objects, it produces the Cartesian product. Anything else throws a `MatrixShapeError` naming the expected shape; numbers and booleans inside the values are accepted and converted to strings.
@@ -3890,7 +3991,8 @@ export default workflow('ci', {
 `dynamicJob(group, fnOrConfig)` tags a generator with a group name (so static jobs can depend on it via `needs: [dynamicGroup('group')]`). It is polymorphic:
 
 - **Function form** — event-only, dispatched at webhook time: `dynamicJob('shards', async ({ ctx }) => [...])`.
-- **Options-object form** — result-aware, deferred until its declared `needs` complete, then run with the upstreams' frozen outputs as `ctx.needs`: `dynamicJob('reports', { needs, generate })`.
+- **Options-object form** — `dynamicJob('reports', { needs, generate })`. With `needs`, it is result-aware: deferred until those upstreams complete, then run with their frozen outputs as `ctx.needs`.
+  - `needs` is optional. Without it the generator is dispatched at webhook time, like the function form. That form is how a generator declares `gitCredentials`, which every job it produces inherits — see [Git credentials](https://docs.kici.dev/user/patterns/git-credentials/#generated-jobs).
 
 ```typescript
 import { workflow, job, step, dynamicJob, dynamicGroup, z } from '@kici-dev/sdk';
@@ -4063,7 +4165,7 @@ those files contain**. It is a declarative filter on the `pr()`, `push()`, and
 at the event's commit. The orchestrator evaluates it as pure data before
 dispatching — it reads only the referenced files, never clones the whole
 repository, and never runs any of your workflow code. A workflow whose `requires`
-does not pass is simply not dispatched.
+does not pass is not dispatched.
 
 Each entry is a `ContentRequirement`:
 
@@ -4328,7 +4430,7 @@ dispatch({ types: ['deploy', 'rollback'] }); // Specific event types
 #### Typed dispatch inputs
 
 A `dispatch()` trigger can declare a typed `inputs` schema. Operators supply
-values with `kici run --input key=value`; KiCI validates, coerces, defaults, and
+values with `kici run remote --input key=value`; KiCI validates, coerces, defaults, and
 exposes them to steps and rules as `ctx.dispatchInputs`. The values are validated
 on the orchestrator from the compiled lock file — a missing required input or a
 bad value is rejected before any agent runs, without cloning the repository.
@@ -5043,6 +5145,20 @@ import { workflow, job, step, pr, push, rule, defineEvent } from '@kici-dev/sdk'
 
 For the complete list of every named export (factory functions, triggers, rules, validation, hook factories, types), see the per-topic pages above.
 
+## `@kici-dev/sdk/internal` is not a supported surface
+
+The package also publishes an `@kici-dev/sdk/internal` subpath. It carries the runtime
+contract between the SDK and the KiCI agent. Those are the functions that install the maps
+a `.result` proxy reads, build the step context your workflow body receives, evaluate its
+rules, and expand its matrix. The agent drives all of it on your behalf.
+
+It is **not covered by semver** and may change shape in any release. Do not import it from
+a workflow. Everything a workflow author needs is on the root entry point above.
+
+Those same symbols are also still exported from the root barrel, marked `@deprecated`, so
+an older SDK in a repository keeps working. They are removed from the root at v1.0.0 — see
+[deprecations](https://docs.kici.dev/user/deprecations/).
+
 ## See also
 
 - [Getting started](https://docs.kici.dev/user/getting-started/) -- install the SDK, write your first workflow, test locally
@@ -5671,7 +5787,7 @@ The SDK exposes three idempotency helpers — a generic function `idempotent()`,
 2. **Apply** the change only when drift is detected.
 3. **Surface** the resource (or its identifier) on both branches, so downstream steps don't need to know whether work happened or was skipped.
 
-`idempotent()` and `idempotentStep()` wrap the same underlying runner and always apply on drift. Pick `idempotentStep()` when the operation is the whole job of a step; use `idempotent()` from anywhere — inside a multi-action step, a hook, or a bare async function. Pick `checkStep()` when the step should respect the run-level check mode — `kici run --check` previews the drift without applying it.
+`idempotent()` and `idempotentStep()` wrap the same underlying runner and always apply on drift. Pick `idempotentStep()` when the operation is the whole job of a step; use `idempotent()` from anywhere — inside a multi-action step, a hook, or a bare async function. Pick `checkStep()` when the step should respect the run-level check mode — `kici run remote --check` previews the drift without applying it.
 
 ## `idempotent(options)`
 
@@ -5766,30 +5882,30 @@ export const setup = job('setup', {
 
 ## `checkStep(name, options)`
 
-The check-mode-aware sibling of `idempotentStep()`. It takes a closely related option shape, but behaves differently when a run is started in check mode (`kici run --check`):
+The check-mode-aware sibling of `idempotentStep()`. It takes a closely related option shape, but behaves differently when a run is started in check mode (`kici run remote --check`):
 
-| Factory          | Behavior under `kici run --check`         |
+| Factory          | Behavior under `kici run remote --check`  |
 | ---------------- | ----------------------------------------- |
 | `idempotentStep` | always applies on drift                   |
 | `checkStep`      | reports drift, applies only in apply mode |
 
-Use `checkStep()` for deploy-style steps where you want a dry-run preview of pending changes before committing them, and `idempotentStep()` for steps that must always converge (for example inside a hook). A `checkStep()` desugars to the first-class step check facet (`check` / `summarize` / `run(ctx, drift)` / `whenInSync`), so it participates in run-level check mode automatically: `kici run --check` reports the drift and skips `apply`, `kici run --check --fail-on-drift` exits non-zero when drift is detected, and apply mode applies the change.
+Use `checkStep()` for deploy-style steps where you want a dry-run preview of pending changes before committing them, and `idempotentStep()` for steps that must always converge (for example inside a hook). A `checkStep()` desugars to the first-class step check facet (`check` / `summarize` / `run(ctx, drift)` / `whenInSync`), so it participates in run-level check mode automatically: `kici run remote --check` reports the drift and skips `apply`, `kici run remote --check --fail-on-drift` exits non-zero when drift is detected, and apply mode applies the change.
 
 ### Parameters
 
-| Name              | Type                                        | Required | Description                                                                                         |
-| ----------------- | ------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------- |
-| `name`            | `string`                                    | Yes      | Step name. Appears in the run timeline and in log lines.                                            |
-| `check`           | `(ctx) => Promise<TDrift \| null>`          | Yes      | Read-only inspection. Return `null` when the system is already in the desired state.                |
-| `apply`           | `(ctx, drift: TDrift) => Promise<TApplied>` | Yes      | Brings the system to the desired state. Runs only in apply mode (skipped under `kici run --check`). |
-| `summarize`       | `(drift: TDrift) => string`                 | Yes      | Human-readable summary of what `apply()` would do; shown in check-mode drift output.                |
-| `whenInSync`      | `(ctx) => Promise<TInSync>`                 | No       | Runs when `check()` returned `null` (already in sync).                                              |
-| `outputs`         | `OutputSchema`                              | No       | Zod schema validating the step's outputs at runtime.                                                |
-| `continueOnError` | `boolean`                                   | No       | When true, the job proceeds even if this step fails.                                                |
-| `timeout`         | `number`                                    | No       | Step-level timeout in milliseconds.                                                                 |
-| `retry`           | `number \| RetryConfig`                     | No       | Retry policy for the step; `retry: N` is shorthand for `{ maxAttempts: N }`.                        |
-| `cache`           | `CacheInput`                                | No       | Declarative cache restored before the step and saved after it succeeds.                             |
-| `rules`           | `Rule[]`                                    | No       | Step-level conditional rules, evaluated agent-side.                                                 |
+| Name              | Type                                        | Required | Description                                                                                                |
+| ----------------- | ------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------- |
+| `name`            | `string`                                    | Yes      | Step name. Appears in the run timeline and in log lines.                                                   |
+| `check`           | `(ctx) => Promise<TDrift \| null>`          | Yes      | Read-only inspection. Return `null` when the system is already in the desired state.                       |
+| `apply`           | `(ctx, drift: TDrift) => Promise<TApplied>` | Yes      | Brings the system to the desired state. Runs only in apply mode (skipped under `kici run remote --check`). |
+| `summarize`       | `(drift: TDrift) => string`                 | Yes      | Human-readable summary of what `apply()` would do; shown in check-mode drift output.                       |
+| `whenInSync`      | `(ctx) => Promise<TInSync>`                 | No       | Runs when `check()` returned `null` (already in sync).                                                     |
+| `outputs`         | `OutputSchema`                              | No       | Zod schema validating the step's outputs at runtime.                                                       |
+| `continueOnError` | `boolean`                                   | No       | When true, the job proceeds even if this step fails.                                                       |
+| `timeout`         | `number`                                    | No       | Step-level timeout in milliseconds.                                                                        |
+| `retry`           | `number \| RetryConfig`                     | No       | Retry policy for the step; `retry: N` is shorthand for `{ maxAttempts: N }`.                               |
+| `cache`           | `CacheInput`                                | No       | Declarative cache restored before the step and saved after it succeeds.                                    |
+| `rules`           | `Rule[]`                                    | No       | Step-level conditional rules, evaluated agent-side.                                                        |
 
 Everything from `outputs` down is a plain [`step()` option](https://docs.kici.dev/user/sdk/core/) forwarded to the underlying step. The three step options `checkStep` does **not** accept are `onCancel`, `cleanup`, and `approval`.
 
@@ -5823,7 +5939,7 @@ export const deploy = job('deploy', {
 });
 ```
 
-Run `kici run --check` against this workflow to see the drift summary without touching DNS; run it without `--check` to apply.
+Run `kici run remote --check` against this workflow to see the drift summary without touching DNS; run it without `--check` to apply.
 
 ## Worked example: create-if-missing returning a resource id
 
@@ -6386,6 +6502,17 @@ interface StepContext<TInputs = Record<string, unknown>> {
   provider?: string;
   /** Whether this execution was triggered by `kici run remote` (developer-initiated remote run) */
   isTestRun: boolean;
+  /** The job's own checked-out repository (present for every job that checks out); `withWrite` opens a write window for it — see [Git credentials](https://docs.kici.dev/user/patterns/git-credentials/) */
+  repo?: {
+    identifier: string;
+    path: string;
+    ref?: string;
+    sha?: string;
+    withWrite(
+      opts: { permissions?: Record<string, string>; credential?: string },
+      fn: () => Promise<void>,
+    ): Promise<void>;
+  };
   /** Registering repo of a global workflow (undefined for non-global workflows) */
   workflowRepo?: RepoInfo;
   /** Repo where the triggering event occurred (undefined for non-global workflows) */
@@ -6586,6 +6713,8 @@ const deploy = job('deploy', {
 
 Request a short-lived OIDC ID token for the current job, bound to an `audience`. The token is a signed JWT whose identity claims (`repository`, `ref`, `sha`, `kici_run_id`, `kici_job_id`) are derived by your orchestrator from the run context — a step cannot spoof them. Use it to authenticate the build to an external service that trusts the orchestrator's OIDC issuer (for example, when generating build provenance).
 
+The token also carries the event context a cloud trust policy needs to tell a fork pull request from a trusted push — `is_fork`, `head_repository`, `trust_tier`, `event_name`, and a pull-request-specific `sub`. See [ID-token claims and cloud trust policies](https://docs.kici.dev/user/provenance/#id-token-claims-and-cloud-trust-policies) for the full claim table and a worked AWS policy.
+
 ```typescript
 const publish = job('publish', {
   steps: [
@@ -6625,6 +6754,8 @@ interface HostInventoryEntry {
 
 Two dimensions describe a host. **Labels** are flat strings used for grouping and targeting (the same labels `runsOn` / `runsOnAll` match). **Properties** are typed host-vars (`string | number | boolean`) — the place for facts like `region`, `cores`, or `gpu`. A host reports its own properties via the agent's `KICI_PROPERTIES` config, and an operator can pre-declare them with `kici-admin host declare --prop key=value`; the two are shallow-merged (agent-reported keys win).
 
+`labels` and `hostname` come back lowercase — KiCI folds both, so a pool declaring `Docker` reports `docker`. Compare against a lowercase value: `h.labels.includes('gpu')`, not `h.labels.includes('GPU')`. A label selector passed to `query()` folds too, so `{ include: [['GPU']] }` matches. `agentId` and `properties` keep their case.
+
 ```typescript
 // All hosts:
 const all = await ctx.kici.inventory.query();
@@ -7320,7 +7451,7 @@ triggered, or the repo had no lock file at that commit.
    source-registration mismatch).
 2. **Did anything match?** Run `kici preview push --branch <your-branch>`
    against your workflow. If it reports no matching workflow, your triggers don't
-   cover that event/branch — the push was delivered and simply matched nothing.
+   cover that event/branch — the push was delivered and matched nothing.
 3. **Was there a lock file?** A repository with **no** `kici.lock.json` at the
    pushed commit produces no run and is not an error. Confirm the lock file is
    committed and current (see [Lock-file drift](https://docs.kici.dev/user/common-failures/#lock-file-drift)).
@@ -7639,7 +7770,7 @@ KiCI uses a **two-artifact model**: TypeScript workflows are the source of truth
 ## Why the lock file matters
 
 - **Orchestrator** fetches the lock file at the commit SHA and uses it to evaluate triggers and to look up the cached `.kici/` source tarball + `node_modules` tarball. It never runs your TypeScript.
-- **Agents** download the cached source tarball (or, on cold cache, the build agent clones + packs it), register the shared TypeScript loader hook, and dynamic-`import()` the workflow `.ts` directly. The lock file's per-workflow `contentHash` identifies the expected raw-source bytes and is verified against the extracted source before any step runs.
+- **Agents** download the cached source tarball (or, on cold cache, the build agent clones + packs it), register the shared TypeScript loader hook, and dynamic-`import()` the workflow `.ts` directly. The lock file's per-workflow `contentHash` identifies the expected contents of the whole `.kici/` directory and is verified against the extracted source before any step runs. The tarball's own bytes are verified against the digest the orchestrator dispatched, and the restored tree **replaces** `.kici/` rather than being unpacked over it, so a file you deleted does not survive a cache hit.
 
 If you change a workflow file (`.ts`) but do **not** regenerate and commit the lock file, the repo at that commit has **drift**: the lock file no longer matches the source. Triggers and cache keys can be wrong, and runs can fail with a clear “stale lock file” error once the agent verifies the hash.
 
@@ -7647,37 +7778,38 @@ 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, stamped by the compiler that produced the lock. Incremented on every format change. The orchestrator accepts a range of versions — see [schema compatibility window](https://docs.kici.dev/user/lock-file-and-drift/#schema-compatibility-window) — rather than requiring an exact match.                                                                                  |
-| `minReaderVersion` | The oldest orchestrator schema version that can read this lock (the newest breaking version at compile time). An orchestrator whose own schema is below this rejects the lock and asks you to upgrade it. Omitted on locks compiled before the compatibility window existed. See [schema compatibility window](https://docs.kici.dev/user/lock-file-and-drift/#schema-compatibility-window).         |
-| `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.                                                                                                                                                                                                                                               |
+| Field              | Description                                                                                                                                                                                                                                                                                                                                                        |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `schemaVersion`    | Lock file schema version, stamped by the compiler that produced the lock. Incremented on every format change. The orchestrator accepts a range of versions — see [schema compatibility window](https://docs.kici.dev/user/lock-file-and-drift/#schema-compatibility-window) — rather than requiring an exact match.                                                                                               |
+| `minReaderVersion` | The oldest orchestrator schema version that can read this lock (the newest breaking version at compile time). An orchestrator whose own schema is below this rejects the lock and asks you to upgrade it. Omitted on locks compiled before the compatibility window existed. See [schema compatibility window](https://docs.kici.dev/user/lock-file-and-drift/#schema-compatibility-window).                      |
+| `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.              |
+| `siblingsDigest`   | SHA-256 over the git-tracked source of every in-repo `workspace:` / `file:` / `link:` / `portal:` sibling package `.kici` depends on, transitively. Part of the dependency cache key alongside `lockfileHash`, because editing a sibling's source moves no package manager lockfile. Omitted when `.kici` depends on no in-repo package, which is the common case. |
+| `workflows`        | Array of workflow entries, each with its own `contentHash`, `compileSchemaVersion`, triggers, and jobs.                                                                                                                                                                                                                                                            |
 
 Each workflow entry includes:
 
-| Field                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `name`                 | Workflow name.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `source`               | Per-workflow source file and export reference.                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `contentHash`          | SHA-256 of the raw workflow source mixed with `compileSchemaVersion` (and an `assetDigest` of declared `hashFiles` when present): `SHA-256(compileSchemaVersion + ":" + rawSource [+ "\0" + assetDigest])`. The orchestrator uses this as the source-tarball cache key and the agent re-computes it against the extracted source to detect drift.                                                                                                               |
-| `compileSchemaVersion` | Compiler schema version used when computing `contentHash` (currently `5`). The hash input is line-ending-normalized (CRLF → LF) so a lock file produced on Linux matches the agent's hash on Windows where Git's `core.autocrlf=true` rewrites checked-out text to CRLF. Bumping the schema version invalidates every existing source cache entry even if source is unchanged, which is the correct behavior when the compile-time or runtime contract changes. |
-| `triggers`             | Trigger definitions extracted from the workflow (used by the orchestrator for event matching).                                                                                                                                                                                                                                                                                                                                                                  |
-| `jobs`                 | Job definitions with scheduling metadata (runsOn, needs, matrix, contexts, concurrency, container, checkout, gracePeriod, label routing, dynamic fields, etc.).                                                                                                                                                                                                                                                                                                 |
-| `rules`                | Workflow-level conditional rules (optional). Stored as dynamic references since rule functions cannot be serialized.                                                                                                                                                                                                                                                                                                                                            |
-| `description`          | Optional workflow description.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `hashFiles`            | Declared glob patterns for extra files included in the content hash (optional). See [extra files in the content hash](https://docs.kici.dev/user/lock-file-and-drift/#extra-files-in-the-content-hash-hashfiles).                                                                                                                                                                                                                                                                                              |
-| `resolvedHashFiles`    | Resolved file paths from `hashFiles` at compile time (optional). Recorded so the agent can verify without re-discovering.                                                                                                                                                                                                                                                                                                                                       |
-| `contexts`             | Secret contexts declared by the workflow (optional). The orchestrator validates access to each context before dispatch.                                                                                                                                                                                                                                                                                                                                         |
-| `registries`           | Private npm registry declarations the agent authenticates against before install (optional): `url`, `scope`, `tokenSecret` reference, `alwaysAuth`. Resolved token bytes never appear in the lock file. See [private registries](https://docs.kici.dev/user/private-registries/).                                                                                                                                                                                                        |
-| `installEnv`           | Extra qualified secret refs (`<context>:<secret-name>`) projected as env vars on the install subprocess for use with a committed `.kici/.npmrc` (optional). See [private registries](https://docs.kici.dev/user/private-registries/).                                                                                                                                                                                                                                                    |
-| `concurrency`          | Workflow-level concurrency config: `hasGroup`, `cancelInProgress`, `max` (optional). See [concurrency groups](https://docs.kici.dev/user/concurrency/).                                                                                                                                                                                                                                                                                                                                  |
-| `timeout`              | Whole-run wall-clock timeout in milliseconds (optional). The orchestrator reads this at run creation to set the run deadline.                                                                                                                                                                                                                                                                                                                                   |
-| `approval`             | Normalized approval gate (optional): `clauses`, `reason`, `timeoutSeconds`, `when`. When present the whole run is held before any job is dispatched. Job and step entries carry the same normalized block for job- and step-level gates. See [approval gates](https://docs.kici.dev/user/approvals/).                                                                                                                                                                                    |
-| `hasFilter`            | `true` when the workflow declares a workflow-level `filter` predicate (optional; omitted rather than `false`). The predicate itself is never serialized — the flag tells the orchestrator an agent must evaluate the workflow before any of its jobs is dispatched. See [global workflows](https://docs.kici.dev/user/global-workflows/#narrowing-with-a-filter).                                                                                                                        |
-| Hook flags             | Boolean flags (`hasOnCancel`, `hasCleanup`, `hasOnSuccess`, `hasOnFailure`) indicating which lifecycle hooks are defined. Job entries additionally have `hasBeforeStep` and `hasAfterStep`.                                                                                                                                                                                                                                                                     |
+| Field                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`                 | Workflow name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `source`               | Per-workflow source file and export reference.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `contentHash`          | SHA-256 of a digest over the whole `.kici/` directory mixed with `compileSchemaVersion` (and an `assetDigest` of declared `hashFiles` when present): `SHA-256(compileSchemaVersion + ":" + treeDigest [+ "\0" + assetDigest])`. The tree digest covers every file under `.kici/` except the paths declared in `.kici/.kiciignore` — see [files the content hash skips](https://docs.kici.dev/user/lock-file-and-drift/#files-the-content-hash-skips-kicikiciignore). Paths are sorted and line endings normalized. The orchestrator uses this as the source-tarball cache key and the agent re-computes it against the extracted tree to detect drift. |
+| `compileSchemaVersion` | Compiler schema version used when computing `contentHash` (currently `7`). The hash input is line-ending-normalized (CRLF → LF) so a lock file produced on Linux matches the agent's hash on Windows where Git's `core.autocrlf=true` rewrites checked-out text to CRLF. Bumping the schema version invalidates every existing source cache entry even if source is unchanged, which is the correct behavior when the compile-time or runtime contract changes.                                                                                                                                         |
+| `triggers`             | Trigger definitions extracted from the workflow (used by the orchestrator for event matching).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `jobs`                 | Job definitions with scheduling metadata (runsOn, needs, matrix, contexts, concurrency, container, checkout, gracePeriod, label routing, dynamic fields, etc.).                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `rules`                | Workflow-level conditional rules (optional). Stored as dynamic references since rule functions cannot be serialized.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `description`          | Optional workflow description.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `hashFiles`            | Declared glob patterns for extra files included in the content hash (optional). See [extra files in the content hash](https://docs.kici.dev/user/lock-file-and-drift/#extra-files-in-the-content-hash-hashfiles).                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `resolvedHashFiles`    | Resolved file paths from `hashFiles` at compile time (optional). Recorded so the agent can verify without re-discovering.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `contexts`             | Secret contexts declared by the workflow (optional). The orchestrator validates access to each context before dispatch.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `registries`           | Private npm registry declarations the agent authenticates against before install (optional): `url`, `scope`, `tokenSecret` reference, `alwaysAuth`. Resolved token bytes never appear in the lock file. See [private registries](https://docs.kici.dev/user/private-registries/).                                                                                                                                                                                                                                                                                                                                                |
+| `installEnv`           | Extra qualified secret refs (`<context>:<secret-name>`) projected as env vars on the install subprocess for use with a committed `.kici/.npmrc` (optional). See [private registries](https://docs.kici.dev/user/private-registries/).                                                                                                                                                                                                                                                                                                                                                                                            |
+| `concurrency`          | Workflow-level concurrency config: `hasGroup`, `cancelInProgress`, `max` (optional). See [concurrency groups](https://docs.kici.dev/user/concurrency/).                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `timeout`              | Whole-run wall-clock timeout in milliseconds (optional). The orchestrator reads this at run creation to set the run deadline.                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `approval`             | Normalized approval gate (optional): `clauses`, `reason`, `timeoutSeconds`, `when`. When present the whole run is held before any job is dispatched. Job and step entries carry the same normalized block for job- and step-level gates. See [approval gates](https://docs.kici.dev/user/approvals/).                                                                                                                                                                                                                                                                                                                            |
+| `hasFilter`            | `true` when the workflow declares a workflow-level `filter` predicate (optional; omitted rather than `false`). The predicate itself is never serialized — the flag tells the orchestrator an agent must evaluate the workflow before any of its jobs is dispatched. See [global workflows](https://docs.kici.dev/user/global-workflows/#narrowing-with-a-filter).                                                                                                                                                                                                                                                                |
+| Hook flags             | Boolean flags (`hasOnCancel`, `hasCleanup`, `hasOnSuccess`, `hasOnFailure`) indicating which lifecycle hooks are defined. Job entries additionally have `hasBeforeStep` and `hasAfterStep`.                                                                                                                                                                                                                                                                                                                                                                                                             |
 
 Step entries carry their own capability flags, so the orchestrator can reason about a step without loading your TypeScript:
 
@@ -7758,9 +7890,40 @@ kici compile --check
 
 This validates all workflows and generates the lock file in memory without writing it. If any workflow has syntax errors or invalid configuration, the command exits non-zero. Pair this with the agent-side hash verification (below) for full drift detection -- `--check` catches broken source, while the agent catches source-lock-file mismatches at run time.
 
+## Files the content hash skips (`.kici/.kiciignore`)
+
+The per-workflow content hash covers everything under `.kici/` except the paths declared in `.kici/.kiciignore`. `kici init` writes that file for you with this default set:
+
+```
+node_modules/
+types/
+.npmrc
+package-lock.json
+pnpm-lock.yaml
+kici.lock.json
+```
+
+Every entry except `kici.lock.json` names something KiCI itself regenerates. The agent installs your workflow's dependencies before it re-checks the hash, and that install rewrites `package-lock.json`, `pnpm-lock.yaml`, `.npmrc` and `node_modules/`; `kici compile` refreshes `types/` after it has already hashed the tree. Hashing any of them would make the hash change on every run, and the drift gate would reject work that never changed.
+
+`kici.lock.json` is different: the hash is written **into** that file, so hashing it would make it an input to itself. It stays excluded whatever your `.kiciignore` says.
+
+Patterns are gitignore-style and are matched relative to `.kici/`. A trailing `/` matches a directory and everything beneath it, a bare name matches at any depth, and a pattern containing a slash is anchored at `.kici/`.
+
+One rule differs from `git`: **a symlink to a directory counts as a directory**. So `node_modules/` covers a `.kici/node_modules` that is a symlink into a shared dependency tree, where `git` would treat that link as a file. The exclusion means "skip the dependency tree, whatever shape it takes on disk". Hashing the link instead produced a hash your build agent could not reproduce, because its own dependency install always writes a real directory there.
+
+A symlink the exclusions do **not** cover is still hashed — as its link target, not as the bytes behind it. The source tarball has to carry that link unchanged for the agent to agree. So `kici compile` warns about a link it cannot carry: one whose target is absolute (extraction strips the leading `/`), or whose target points outside `.kici/`'s parent (extraction drops the link). Point the link inside `.kici/`, replace it with the files it names, or list it in `.kiciignore`.
+
+:::caution[The file replaces the defaults — it does not add to them]
+When `.kici/.kiciignore` exists, it **is** the exclusion list. A one-line file excludes one path and re-includes everything else, `package-lock.json` included. `kici compile` warns when your file omits a path a run rewrites, and names both the path and the instability it causes. Delete the file to fall back to the defaults.
+:::
+
+`.kiciignore` is itself covered by the hash. Which files define a workflow's identity is part of that identity, so editing the file forces a recompile — and nobody can change what a lock file attests to without changing the lock file.
+
+> **Not the repo-root `.kiciignore`.** A `.kiciignore` at the root of your repository is a separate, unrelated file: it selects which working-tree files `kici run remote` uploads. Only the one inside `.kici/` affects the content hash.
+
 ## Extra files in the content hash (`hashFiles`)
 
-By default, the per-workflow content hash is `SHA-256(compileSchemaVersion + ":" + rawSource)` where `rawSource` is the TypeScript text of the workflow entry file. If your workflow depends on files outside `.kici/workflows/` -- configuration files, scripts, Dockerfiles, etc. -- changes to those files will **not** invalidate the cache unless you declare them.
+A helper the workflow imports from `.kici/lib/` is already covered, so editing it invalidates the cache on its own. If your workflow depends on files **outside** `.kici/` -- configuration files, scripts, Dockerfiles, etc. -- changes to those files will **not** invalidate the cache unless you declare them.
 
 Use the `hashFiles` option on a workflow to include additional paths or glob patterns (relative to the repo root) in the content hash:
 
@@ -7771,14 +7934,14 @@ export default workflow('deploy', {
 });
 ```
 
-When any of the matched files change, the content hash formula becomes `SHA-256(compileSchemaVersion + ":" + rawSource + "\0" + assetDigest)` where `assetDigest` is a deterministic encoding of the resolved file paths and their contents. This busts the source-tarball cache and forces the build agent to pack and upload a fresh `source/{contentHash}.tar.gz`. The resolved file paths are recorded in the lock file under `resolvedHashFiles` so the agent can verify without re-discovering the workflow.
+When any of the matched files change, the content hash formula becomes `SHA-256(compileSchemaVersion + ":" + treeDigest + "\0" + assetDigest)` where `assetDigest` is a deterministic encoding of the resolved file paths and their contents. This busts the source-tarball cache and forces the build agent to pack and upload a fresh tarball. The resolved file paths are recorded in the lock file under `resolvedHashFiles` so the agent can verify without re-discovering the workflow.
 
 ## Agent-side safety net
 
 If drift still occurs (e.g. someone committed only the `.ts` change), the agent detects it at run time before any step runs:
 
-- After extracting the `.kici/` source tarball (or loading source from a `git clone` on the build path), the agent reads the workflow entry file and re-computes `contentHash = SHA-256(compileSchemaVersion + ":" + rawSource [+ "\0" + assetDigest])` using the same formula as the compiler.
-- If the orchestrator sent a `contentHash` (from the lock file) and the computed hash does **not** match, the agent fails the run with an error like: **lock file is out of date** (workflow source changed without regenerating the lock file). The error includes the baked agent `@kici-dev/sdk` version + bundle hash so operators can debug cross-host compile mismatches.
+- After extracting the `.kici/` source tarball (or loading source from a `git clone` on the build path), the agent walks the whole extracted `.kici/` tree and re-computes `contentHash = SHA-256(compileSchemaVersion + ":" + treeDigest [+ "\0" + assetDigest])` using the same implementation as the compiler. Because it covers the tree, an edit to any file the workflow imports is caught, not just an edit to the entry file.
+- If the orchestrator sent a `contentHash` (from the lock file) and the computed hash does **not** match, the agent fails the run with an error like: **lock file is out of date** (workflow source changed without regenerating the lock file). The error includes the baked agent `@kici-dev/sdk` version + bundle hash so operators can debug cross-host compile mismatches. When the hashed tree carries symlinks, the error names them too — recompiling cannot reconcile a link the tarball omits or extraction rewrites, so the usual remedy would loop.
 
 So even without a pre-commit or CI check, a stale lock file will cause the run to fail with a clear message instead of running with the wrong workflow.
 
@@ -7790,6 +7953,7 @@ So even without a pre-commit or CI check, a stale lock file will cause the run t
 | Catch drift before commit    | Install a pre-commit hook with `kici hook install`.                                        |
 | Catch broken source in CI    | Run `kici compile --check` in CI.                                                          |
 | Bust cache on external files | Add `hashFiles: ['config.json']` to include non-workflow files in the content hash.        |
+| Skip a path inside `.kici/`  | List it in `.kici/.kiciignore` — remember the file replaces the defaults.                  |
 | Fail fast when drift remains | Rely on the agent’s hash verification when it compiles from source.                        |
 
 ## See also
@@ -8420,7 +8584,7 @@ Manage the **local dev plane** — the warm, per-user orchestrator (plus its own
 kici local up [--offline | --connected]   # Start, or reuse an already-running plane
 kici local status [--json]                 # Port, pid, PostgreSQL backend, attachment mode, readiness
 kici local down                            # Stop the orchestrator and its PostgreSQL, verifying the port is freed
-kici local logs                            # Print the orchestrator log file path
+kici local logs                            # Print the plane log paths and rotation policy
 kici local attach                          # Attach to the Platform (hybrid mode)
 kici local detach                          # Return the plane to offline (independent) mode
 kici local trust-root <file>               # Export the dev-signed trust root for offline verification
@@ -8437,6 +8601,8 @@ The plane runs in one of two modes:
 
 `kici local status` reports a plane whose process is alive but whose readiness probe fails — for example when its PostgreSQL has stopped — as running but not ready, together with its readiness checks, rather than as not running. When the holder is a KiCI plane orchestrator that this config directory did not start — a plane belonging to another `KICI_CONFIG_DIR`, or one whose record here was lost — status names it as such rather than as not ready, since its readiness is never probed, and points at `kici local down`, which does reclaim it. When the port is held by a process that is not a KiCI plane orchestrator, `kici local status` names that holder instead and points at `KICI_LOCAL_ORCH_PORT`, because `kici local down` will not stop it.
 
+The plane writes its orchestrator log to `orchestrator.log` in its state directory and, when it runs embedded PostgreSQL, the PostgreSQL log to `orchestrator.log.pg` beside it. `kici local logs` prints their location. Each is rotated to a `.1` sibling when it reaches 50 MB, at the next plane start — the plane keeps the current log and one previous generation, so neither can grow without bound.
+
 Pass `--json` for machine-readable output. It prints one object and exits 0 for
 every state, including when the plane is stopped — the state is in the payload,
 not the exit code:
@@ -8729,7 +8895,7 @@ Synopsis: `kici local down`
 
 ### `kici local logs`
 
-Print the local dev plane orchestrator log path
+Print the local dev plane log paths and rotation policy
 
 Synopsis: `kici local logs`
 
@@ -8959,6 +9125,12 @@ If you belong to a single organization, the org is resolved automatically. If
 you belong to several, pass an `orgId` argument to any tool (use `list_orgs` to
 find it).
 
+Only an **active** membership counts: an organization you have been suspended
+in, one that has been disabled, and one that has been deleted are all skipped.
+So a single active membership alongside a disabled one still resolves
+automatically, and a tool call against an organization you are suspended in is
+refused with the same message the dashboard gives.
+
 ### Limits and pagination
 
 The MCP server applies a few bounds so an agent loop can't overwhelm the shared
@@ -9048,7 +9220,7 @@ you hold, so an agent cannot escalate beyond its creator.
 
 **Repository scope comes along too.** If your role is restricted to a set of
 repositories, an agent token you mint is restricted to the same set. Runs
-outside it are simply not there: they are filtered out of `list_runs`,
+outside it are not there: they are filtered out of `list_runs`,
 `cancel_runs_by_branch` skips them, and naming one directly answers "not found"
 — the same answer a run id that does not exist gets, so an agent cannot use the
 tools to discover which repositories it is missing. Your organization's audit
@@ -9291,14 +9463,18 @@ Tokens authenticate; RBAC authorizes. Every org-scoped route runs `orgContextMid
 
 ### Configurable surfaces
 
-The dashboard is a browser SPA on top of the same `/api/v1/*` surface, so anything you can configure in the dashboard you can configure over HTTP. The mounted route groups include:
+The dashboard is a browser SPA on top of the same `/api/v1/*` surface, so nearly everything you can configure in the dashboard you can configure over HTTP. The exception is a short list of routes that only a **browser session** may call, marked † below. The mounted route groups include:
 
-- **Auth & identity:** `/cli/exchange-token`, `/pats`, `/user`, `/identity-links`, `/github-oauth`, `/invites`, `/invites/pending`, `/invites/:inviteId/{accept,decline}`
-- **Org & membership:** `/orgs`, `/orgs/:customerId`, `/orgs/:customerId/{members,roles,api-keys,orchestrator-keys,service-accounts,billing,trust-policies}`
+- **Auth & identity:** `/cli/exchange-token`†, `/pats`, `/user`, `/identity-links`, `/identity-links/:id` (DELETE)†, `/github-oauth`, `/auth/github/link`†, `/invites`, `/invites/pending`, `/invites/:inviteId/{accept,decline}`†
+- **Org & membership:** `/orgs` (POST)†, `/orgs/:customerId`, `/orgs/:customerId/{members,roles,api-keys,orchestrator-keys,service-accounts,billing,trust-policies}`
 - **Workflows & runs:** `/orgs/:customerId/{runs,registrations,workflows,held-runs,contexts,secrets,global-workflows}`
 - **Webhooks & event log:** `/orgs/:customerId/{sources,webhook-endpoints,event-log}`
 - **Diagnostics & activity:** `/orgs/:customerId/{diagnostics,activity,access-log}`
 
+**† Browser session only.** These routes answer **403** with `This endpoint requires an interactive login` to a `kici_pat_`, `kici_sk_` or `kici_sa_` token. They are the routes that create an organization, join or decline one, unlink a provider identity, start a GitHub account link, and exchange your session for a personal access token. Each mints a credential wider than the credential presenting it, or changes which organizations and provider identities your account reaches. A `kici_sk_` or `kici_sa_` token is bound to one organization and one permission set, so letting it take those actions would hand it access it was never granted. Do them in the dashboard, or with `kici login`, which runs the browser flow for you.
+
+`POST /pats` is the one route in between: it accepts a browser session **or** an existing `kici_pat_` (so `kici pat create` keeps working), and refuses `kici_sk_` and `kici_sa_`. A token minted from another token can never be wider than that token. The new token is capped by your own permissions **and** by the scopes of the token you called with, whether or not you pass `permissions` explicitly. Mint from an unscoped session when you need a broader token.
+
 The full route tree is the source of truth — every method, request schema, and response schema is enumerated server-side. There is currently no auto-generated OpenAPI spec; the typed `DashboardApiType` export is the canonical contract for TypeScript clients.
 
 ### Calling the API
@@ -9317,11 +9493,16 @@ curl -sS \
 
 **Browser console (after dashboard login):**
 
+Mint a personal access token and pass it explicitly. Do not script against the
+dashboard's own session token. That token is short-lived and tied to your
+identity-provider session, so anything built on it stops working at the next
+renewal or sign-out.
+
 ```js
-const ns = Object.keys(localStorage).find((k) => k.startsWith('oidc.user:'));
-const { access_token } = JSON.parse(localStorage.getItem(ns));
+// kici pat create --name console --expires-in-days 1   → prints the token
+const token = 'kici_pat_...';
 const res = await fetch('/<deployment-slug>/api/v1/orgs/<your-org-id>/runs?limit=5', {
-  headers: { Authorization: `Bearer ${access_token}` },
+  headers: { Authorization: `Bearer ${token}` },
 });
 console.log(await res.json());
 ```
@@ -9346,6 +9527,12 @@ The CLI stores authentication data in `~/.kici/config` with `0600` permissions (
 - Routing key for webhook source identification
 - API key, when you logged in with `--token`
 
+The web dashboard holds none of these. It keeps only the tokens of your current
+sign-in, in browser storage for the tab's origin. It does not request offline
+access, so those tokens die with your identity-provider session instead of
+staying valid for weeks. Its origin also serves a Content-Security-Policy that
+restricts which scripts run and which hosts the page may contact.
+
 ## Troubleshooting
 
 ### Browser doesn't open
@@ -9550,10 +9737,14 @@ kici init --private-registry https://npm.pkg.github.com/ \
   types/              # Directory for generated type declarations (kici types)
   package.json        # Dependencies (@kici-dev/sdk)
   tsconfig.json       # TypeScript configuration (includes types/**/*.d.ts)
+  .gitignore          # Keeps the generated types/ declarations untracked
+  .kiciignore         # Paths the workflow content hash does not cover
   AGENTS.md           # LLM authoring context (skip with --no-agents-md)
 .kiciignore           # Default exclusion patterns for test uploads
 ```
 
+The two `.kiciignore` files are unrelated. The one inside `.kici/` declares which paths the per-workflow content hash skips — see [Lock file and workflow drift](https://docs.kici.dev/user/lock-file-and-drift/#files-the-content-hash-skips-kicikiciignore). The one at the repo root selects which working-tree files a remote run uploads. Neither is overwritten when it already exists.
+
 `AGENTS.md` is written by default (the interactive prompt defaults to yes, and CI / non-interactive runs write it). An existing `.kici/AGENTS.md` is never overwritten, so hand edits survive a re-run.
 
 In interactive mode (TTY), `kici init` prompts you to:
@@ -9569,7 +9760,7 @@ In interactive mode (TTY), `kici init` prompts you to:
 
 **Standalone vs workspace integration:** by default `kici init` scaffolds a self-contained `.kici/` with its own `package.json`. When run inside a pnpm, npm, or yarn workspace, it offers an **integrate** option (or pass `--workspace`): `.kici/` joins the workspace, `@kici-dev/sdk` is added to your workspace-root `package.json`, and your workflows can `import` your other workspace packages (e.g. shared build or deploy utilities). In this mode there is no `.kici/package.json` — the workspace root manages dependencies, and the root install resolves the SDK. Your workflows resolve sibling packages through the workspace-root `node_modules`: under npm and yarn every workspace member is hoisted there automatically, while pnpm links only your root's declared dependencies, so under pnpm add the package you want to import to your workspace-root `dependencies` (this is how KiCI's own repository imports its packages from workflows). Pass `--standalone` to force the self-contained layout even inside a workspace. In CI / non-interactive runs the default is standalone; use `--workspace` to opt in explicitly. `--workspace` and `--standalone` are mutually exclusive, and `--workspace` errors if no workspace is found at or above the current directory.
 
-**Development mode:** When `KICI_DEV=true` or `package.json` has `"kici": { "development": true }`, the generated `package.json` uses prerelease-compatible version ranges (`>=0.0.1-0`) so npm resolves Verdaccio's prerelease builds.
+**Development mode:** When `KICI_DEV=true` or `package.json` has `"kici": { "development": true }`, the generated `package.json` pins `@kici-dev/sdk` to the `latest` dist-tag so npm resolves Verdaccio's newest prerelease build.
 
 ### kici org
 
@@ -10094,6 +10285,14 @@ to see it. The bundle holds your CLI, Node and orchestrator versions, your
 redacted configuration, and your project's workflow and lock-file state. With
 `--run` it also holds the failing run's detail and logs.
 
+For every orchestrator the probe returned the bundle also records where that
+orchestrator's own config files live — the paths only, never the contents. An
+orchestrator that is offline is still listed, with no paths: the CLI reads them
+from the live connection, so a disconnected one has none to report.
+Each path is a host path as that orchestrator sees it. A container deployment
+names a file on the container host, which is not a file you can open from the
+machine that read the bundle.
+
 ```bash
 kici report [options]
 ```
@@ -10507,6 +10706,18 @@ Secrets are always sourced from your real `.kici/` directory, not from the isola
 
 Pass `--in-place` to run against the real working directory instead — useful when you explicitly want in-tree execution. `--in-place` requires no git repository; the default isolated mode does, and fails with an actionable error pointing at `--in-place` when the directory is not a git repository.
 
+**If the trigger times out:**
+
+The command waits up to 60 seconds for the local dev plane to create the run. If nothing appears in that window it stops and names the cause it read back from the plane:
+
+| Message                                                                   | What it means                                                                                                                                                     |
+| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `plane is not leader yet (election grace period)`                         | The plane had not finished electing itself. A single-machine plane elects within seconds; if it does not, read the plane log (`kici local logs`).                 |
+| `no kici.lock.json at <commit> in <path>`                                 | The plane resolved no lock file for the commit the run packed, so nothing matched. Commit `.kici/kici.lock.json`, or make sure it is present in the working tree. |
+| `the plane recorded delivery <id> as "<status>"`                          | The plane processed the trigger and wrote down a terminal status for it without creating a run. The status names the stage that stopped.                          |
+| `no run appeared for delivery <id> — see <log>`                           | Neither the plane's cluster state nor its delivery record explained the timeout. The named log is the next place to look.                                         |
+| `no run appeared for this trigger — the plane never accepted the webhook` | Every webhook POST came back without a delivery id, so the plane never queued the trigger. Check the plane is up (`kici local status`), then read the named log.  |
+
 **Examples:**
 
 ```bash
@@ -11245,7 +11456,7 @@ You declare a gate in your workflow with `approval`. It is available at three le
 - **Job** — hold the job before any of its steps run.
 - **Workflow** — hold the whole run before any job is dispatched.
 
-A step-level gate can also fire **only when a check/apply step finds drift** — Terraform's plan→apply, per step. See [Drift gates](https://docs.kici.dev/user/approvals/#drift-gates-whendrift) below.
+A step-level gate can also fire **only when a check/apply step finds drift** — Terraform's plan→apply, per step. See [Drift gates](https://docs.kici.dev/user/approvals/#drift-gates-when-drift) below.
 
 Approvers are named as **teams** and **users**. A team is an operator-defined group of org members; your workflow code may name a team but can never change its membership, which is what makes a team clause a real gate rather than a suggestion. See [Approval gates (operator guide)](https://docs.kici.dev/operator/approvals/) for how operators define teams, the approval queue, and expiry; see [the architecture overview](https://docs.kici.dev/architecture/approvals/) for how a hold is evaluated and resumed.
 
@@ -11316,7 +11527,7 @@ approval: {
 
 | Field       | Type                  | Description                                                                                                                                                                                                      |
 | ----------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `when`      | `'always' \| 'drift'` | When the gate fires. `'always'` (default) gates before the element; `'drift'` gates a check/apply step only when it finds drift. See [Drift gates](https://docs.kici.dev/user/approvals/#drift-gates-whendrift).                                      |
+| `when`      | `'always' \| 'drift'` | When the gate fires. `'always'` (default) gates before the element; `'drift'` gates a check/apply step only when it finds drift. See [Drift gates](https://docs.kici.dev/user/approvals/#drift-gates-when-drift).                                     |
 | `approvers` | `ApproverClause[]`    | The AND list of `{ team }` / `{ user }` clauses. An empty list means "any approval-capable member".                                                                                                              |
 | `reason`    | `string`              | A human-readable label shown in the dashboard queue and the held-for-approval status check.                                                                                                                      |
 | `timeout`   | `number`              | Per-gate expiry in **seconds**, overriding the org default. Must be a **positive integer** number of seconds; a non-positive or non-finite value is rejected at compile time. On expiry the element is rejected. |
@@ -11495,7 +11706,7 @@ Available rules:
 - **Branch restrictions** — only allow specific branches to deploy.
 - **Required reviewer approvals** — gate the run on human sign-off.
 - **Wait timers** — delay execution for a fixed period.
-- **Concurrency limits** — prevent collisions between parallel deployments.
+- **Concurrency limits** — cap how many jobs run against the context at once.
 
 <!-- /help:contexts-protection -->
 
@@ -11584,7 +11795,7 @@ job('deploy', {
 
 **Skip-on-test (allow-and-warn).** On a test or local run (`kici run remote`, `kici run <event> --local`), a bound context never rejects the run. Any bound context that disallows local execution (`allowLocalExecution: false`) — or that is not configured — is **skipped**: its variables and secrets are omitted from the merge and its gates are not evaluated. The run proceeds, and a user-visible warning naming the skipped context(s) is shown both on the `kici run remote` CLI output and on the dashboard run view. This makes the test-only-variables pattern work: with `contexts: ['staging', 'my-testing']` where only `my-testing` allows local execution, a test run resolves just `my-testing`'s variables and warns that `staging` was skipped. If every bound context is skipped, the job runs with no environment variables. This is intentionally different from a fixture `secrets:` mapping, which is fail-closed — see the [testing guide](https://docs.kici.dev/user/testing-guide/).
 
-**Unconfigured contexts contribute nothing at dispatch.** At dispatch time a bound context name with no matching configured context (and no matching glob context) simply adds no variables, secrets, or protection rules — the job still runs, exactly as a single dynamic context resolving to an as-yet-unconfigured name does today.
+**Unconfigured contexts contribute nothing at dispatch.** At dispatch time a bound context name with no matching configured context (and no matching glob context) adds no variables, secrets, or protection rules — the job still runs, exactly as a single dynamic context resolving to an as-yet-unconfigured name does today.
 
 **Registration rejects a provably-unsatisfiable binding.** When a workflow is registered, KiCI statically checks every multi-context binding: a bound context that does not exist, a disabled one, or two contexts with mutually-exclusive fixed branch / trigger-type / repository restrictions (no value can satisfy both) makes the binding provably unsatisfiable, and the registration is rejected with a precise message naming the job, the contexts, and the rule — for example `unsatisfiable context binding: job 'deploy' binds contexts [staging, my-testing] with mutually exclusive branch restrictions (no value satisfies all bound contexts)`. Bindings whose restrictions use globs are undecidable at registration and fall through to the dispatch-time gate check instead.
 
@@ -11787,6 +11998,36 @@ The children of a matrix job count individually against the limit. A three-child
 matrix bound to a context with a limit of two dispatches two children and applies
 the strategy above to the third.
 
+A job counts against the limit from the moment it is dispatched until it
+finishes. It does not have to reach an agent first.
+
+#### What the limit does and does not guarantee
+
+A context concurrency limit is a **throughput control**. Treat it as a cap on
+how much work runs at once, not as a lock.
+
+Two events that arrive in the same instant read the limit before either job is
+recorded, so each can be admitted. The window is short — the time between one
+read and one write — but it is real, and it grows with the number of
+orchestrator processes serving the context.
+
+When a job must never run beside another copy of itself — a production deploy,
+a database migration — declare a workflow-level
+[concurrency group](https://docs.kici.dev/user/concurrency/) as well:
+
+```typescript
+export default workflow('deploy', {
+  on: push({ branches: ['main'] }),
+  concurrency: { group: () => 'deploy-prod', max: 1 },
+  jobs: [/* ... */],
+});
+```
+
+That mechanism claims its slot inside a single database transaction, so two
+runs arriving together cannot both take it. The two are complementary: the
+context limit caps throughput across every workflow bound to the context, and
+the concurrency group serializes one workflow against itself.
+
 ## Dashboard management
 
 ### Creating contexts
@@ -12093,7 +12334,7 @@ registries: [
 ## Security model
 
 - **Per-context scoping.** Every `tokenSecret` and `installEnv` entry is qualified with a context name. The orchestrator runs the same protection-rule pipeline (branch / trust / concurrency / reviewer / wait-timer) against each named context **before** resolving any secret, so a workflow that wants a `production` token from a feature branch is rejected exactly like a job that tries to deploy to `production` from a feature branch. A reviewer-gated install context **pauses** the whole workflow dispatch as a workflow-scoped held run instead of resolving the token — see [Reviewer-gated installs](https://docs.kici.dev/user/private-registries/#reviewer-gated-installs) below.
-- **Untrusted refs get no tokens.** When the trust resolution returns anything other than `trusted` — every fork pull request does — the orchestrator strips both `npmRegistries` and `installEnvSecrets` out of the dispatch. The install runs without auth and fails naturally on the first private dep. A fork pull request cannot observe a registry token, even if a context lacks an explicit [minimum trust](https://docs.kici.dev/user/contexts/#minimum-trust) rule.
+- **Untrusted refs get no tokens.** When the trust resolution returns anything other than `trusted` — every fork pull request does — the orchestrator strips `npmRegistries`, `installEnvSecrets`, and a container job's [registry credentials](https://docs.kici.dev/user/container-jobs/#private-images) out of the dispatch. The install runs without auth and fails naturally on the first private dep, and a private base image fails to pull. A fork pull request cannot observe a registry token, even if a context lacks an explicit [minimum trust](https://docs.kici.dev/user/contexts/#minimum-trust) rule.
 - **Lifecycle scripts disabled.** Whenever a private registry is in scope, the agent runs the install with `--ignore-scripts` (npm, pnpm, and yarn classic alike; yarn berry gets the equivalent `enableScripts: false`). A malicious `preinstall` / `postinstall` hook in committed `package.json` cannot read the synthesized token env vars, even though they exist in the install subprocess. For a pnpm or yarn workspace, the agent builds your in-repo dependency closure as a separate step **after** the install's auth is torn down, so build scripts never see the tokens either.
 - **Stderr is redacted.** If the install fails, the agent masks every token literal out of the surfaced stderr / stdout chunks before logging.
 - **Job-scoped env-var names.** The synthesized auth env var is `KICI_NPM_TOKEN_<jobIdShort>_<i>` where `jobIdShort` is the first 8 chars of the dispatched job id. The name is unguessable from outside the install subprocess and not reused across jobs.
@@ -12129,7 +12370,7 @@ The dashboard JSON lives at `infra/terraform/modules/grafana/dashboards/install-
 ## See also
 
 - [Secrets](https://docs.kici.dev/user/secrets/) — how to seed the `<context>:<secret-name>` values referenced by `tokenSecret` / `installEnv`.
-- [Contexts](https://docs.kici.dev/user/contexts/) — protection rules (`branch_restrictions`, `requires_review`, `minimum_trust`) that the install gate inherits.
+- [Contexts](https://docs.kici.dev/user/contexts/) — protection rules (branch restrictions, required reviewers, minimum trust) that the install gate inherits.
 - [Operator: `kici-admin org-settings`](https://docs.kici.dev/operator/orchestrator/kici-admin/org-settings/#org-settings----org-level-security-policy) — the `allow_http_npm_registries` toggle and other org-scoped knobs.
 
 ---
@@ -12247,6 +12488,107 @@ and the step never holds signing credentials — the orchestrator mints and sign
 the token on the step's behalf from its own run records. Like `attestProvenance`,
 it is only available inside a running job step.
 
+## ID-token claims and cloud trust policies
+
+A cloud provider's OIDC trust policy decides which builds may assume a role. The
+token below is what your policy matches on, so read this section before you
+write one.
+
+### The claim set
+
+| Claim                         | Value                                                                                                            |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `iss`                         | Your orchestrator's provenance issuer                                                                            |
+| `aud`                         | The audience you asked for                                                                                       |
+| `sub`                         | The build identity — see the two shapes below                                                                    |
+| `repository`                  | `owner/repo` the run acted on                                                                                    |
+| `ref`                         | The branch or tag the run PRESENTS. For a pull request this is the **base** branch, not the contributor's branch |
+| `base_ref`                    | The same value as `ref`, named the way GitHub Actions names it                                                   |
+| `head_ref`                    | The pull request's HEAD branch; `''` for a non-PR run                                                            |
+| `head_repository`             | `owner/repo` of the pull-request HEAD — the contributor's fork for a fork PR; `''` for a non-PR run              |
+| `is_fork`                     | `'true'`, `'false'`, or `'unresolved'`                                                                           |
+| `event_name`                  | The event that started the run (`push`, `pull_request:opened`, `schedule`, …)                                    |
+| `trust_tier`                  | The resolved trust tier of the triggering actor, or `'unresolved'`                                               |
+| `actor`                       | Provider login of the triggering actor                                                                           |
+| `sha`                         | The run's commit                                                                                                 |
+| `workflow_ref`                | `<workflow name>@<sha>`                                                                                          |
+| `kici_run_id` / `kici_job_id` | The run and job this token was minted for                                                                        |
+| `org_id`                      | Your organization id                                                                                             |
+
+Every claim in the table is **always present**. A value the run did not resolve
+is `''` or `'unresolved'`, never omitted and never guessed. That matters: an
+absent claim makes a `StringEquals` condition pass, which would silently remove
+a constraint you wrote expecting it to be enforced.
+
+### The two `sub` shapes
+
+```
+push, tag, schedule, …     repo:<owner/repo>:ref:<ref>:workflow:<workflow name>
+pull request, review       repo:<owner/repo>:pull_request
+```
+
+The pull-request shape carries **no ref segment**, mirroring GitHub Actions. A
+pull request's `ref` is its base branch. So a ref-bearing subject would be
+identical for a fork pull request targeting `main` and a trusted push to `main`.
+A policy pinning that subject would hand your cloud role to any contributor who
+opened a pull request running the same workflow.
+
+**A re-run keeps the shape of the run it repeats.** Re-running a pull-request
+run presents `repo:<owner/repo>:pull_request`, because it rebuilds the same
+commit from the same source. Its `event_name` claim still reads `rerun` — that
+claim says what started the run, while `sub` says which identity the run
+presents. A policy that pins the branch-shaped subject therefore does not match
+a re-run of a pull request, which is the same protection the first run gets.
+
+### A worked AWS trust policy
+
+Pin `sub`, and pin the fork context too. `sub` alone tells you a pull request
+ran; it does not tell you whose code ran.
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Principal": { "Federated": "arn:aws:iam::123456789012:oidc-provider/orch.example.com" },
+      "Action": "sts:AssumeRoleWithWebIdentity",
+      "Condition": {
+        "StringEquals": {
+          "orch.example.com:aud": "sts.amazonaws.com",
+          "orch.example.com:sub": "repo:acme/app:ref:main:workflow:deploy",
+          "orch.example.com:is_fork": "false",
+          "orch.example.com:head_repository": "acme/app",
+          "orch.example.com:trust_tier": "trusted"
+        }
+      }
+    }
+  ]
+}
+```
+
+This grants the role only to a run on `main` in `acme/app`, from code in that
+same repository, triggered by an actor your orchestrator resolved as trusted.
+A fork pull request fails on all three of the extra conditions, and a run whose
+context did not resolve fails too — `'unresolved'` matches none of them, so the
+policy fails closed.
+
+To let a same-repo pull request assume the role, add a second statement pinning
+`"sub": "repo:acme/app:pull_request"` alongside `"is_fork": "false"` and
+`"head_repository": "acme/app"`.
+
+### Migrating an existing policy
+
+If you already pin a ref-bearing `sub` for pull-request runs, that policy stops
+matching once you upgrade — which is the fix, because it was matching runs it
+should not have. Move it to `repo:<owner/repo>:pull_request` plus the fork
+conditions above. The same move covers a re-run of a pull request, which
+presents the pull-request subject too.
+
+While you migrate, `KICI_OIDC_LEGACY_PR_SUB=1` on the orchestrator restores the
+old subject. It restores the collision with it, so treat it as a short bridge,
+not a setting. See [deprecations](https://docs.kici.dev/user/deprecations/).
+
 ## Verifying an attestation
 
 Verify a bundle with the `kici verify-attestation` command. It establishes the
@@ -12872,6 +13214,8 @@ workflow('test', {
 
 When `max: 1` (default), runs are fully serialized within the group.
 
+`max` is enforced by the orchestrator's database, so the limit is cluster-wide and survives a restart. A run holding a slot keeps it across an orchestrator restart. Every orchestrator in a cluster counts against the same limit, so a group with `max: 1` runs one job at a time no matter which orchestrator dispatched it.
+
 ## Group key examples
 
 ### Deploy per environment
@@ -12931,6 +13275,14 @@ When a workflow has both `concurrency` and `context` protection rules:
 
 This means a run that passed approval won't need re-approval if it gets queued by concurrency.
 
+The two caps also differ in strength. A workflow-level concurrency group claims
+its slot inside a single database transaction, so two runs that arrive together
+cannot both take it. A context
+[concurrency limit](https://docs.kici.dev/user/contexts/#concurrency-limits) is a throughput control:
+simultaneous arrivals can each be admitted before either is recorded. Declare a
+concurrency group for anything that must never run beside itself, whatever the
+context limit says.
+
 ## Cancelling queued runs
 
 Queued runs can be cancelled before they start executing. The cancel request removes them from the queue immediately -- they don't go through the grace period since no step is running.
@@ -13141,6 +13493,17 @@ Store the secrets first with `kici-admin secret set`. Pasting a token straight
 into the workflow is rejected when the workflow is defined, because a token
 written into `.kici/` would be committed to your repository.
 
+The named context's protection rules run before the secret is read, exactly as
+they do for [git credentials](https://docs.kici.dev/user/patterns/git-credentials/#what-a-job-may-ask-for).
+A `prod:` reference from a branch the `prod` context restricts is refused, and
+the job is dispatched with no registry credentials — so a private image fails to
+pull rather than being pulled from a branch the context does not allow. The rule
+that refused it is named in your orchestrator's log, not in the run.
+
+**An untrusted ref receives no registry credentials.** A fork pull request is
+dispatched without them, so a private base image fails to pull and a public one
+is unaffected. The run's reduced-privilege note says so.
+
 The username is not a secret, so you may write it directly:
 
 ```typescript
@@ -13150,6 +13513,30 @@ auth: { username: 'ci-bot', tokenSecret: 'prod:REGISTRY_TOKEN' }
 Your orchestrator resolves these names at dispatch and sends only the resolved
 credentials to the agent. The agent never reads your secret store.
 
+### Naming the registry
+
+`auth` also takes a `registry` — the registry host the credentials belong to,
+such as `reg.internal:5000`.
+
+With `image` it is optional, because KiCI reads the host off the image
+reference. With `dockerfile` it is **required**: the base image is named inside
+your Dockerfile, so there is nothing to read it from. A `dockerfile` job whose
+`auth` omits `registry` is refused when you define the workflow.
+
+```typescript
+container: {
+  dockerfile: '.kici/ci.Dockerfile',
+  auth: {
+    registry: 'reg.internal:5000',
+    usernameSecret: 'prod:REGISTRY_USER',
+    tokenSecret: 'prod:REGISTRY_TOKEN',
+  },
+},
+```
+
+With `dockerfile`, these credentials pull the Dockerfile's own `FROM` base — not
+a job image, since the job image is the one KiCI builds.
+
 ### Credentials that only exist at run time
 
 A token fetched during the run — from a cloud registry's login command, for
@@ -13300,10 +13687,11 @@ The KiCI CLI reads the following environment variables to customize its behavior
 
 ## Development
 
-| Variable     | Description                                                                                                                                                                | Default |
-| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| `KICI_DEV`   | Enable development mode. When `true`, uses prerelease-compatible version ranges (`>=0.0.1-0`) for dev dependencies and skips npm version resolution.                       | unset   |
-| `KICI_DEBUG` | Enable debug logging. When `true`, prints verbose diagnostics (SDK alias resolution, step-level debug logs, stack traces on errors). Equivalent to the `--debug` CLI flag. | unset   |
+| Variable            | Description                                                                                                                                                                | Default |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| `KICI_DEV`          | Enable development mode. When `true`, pins `@kici-dev/sdk` to the `latest` dist-tag (so a dev registry's prerelease build resolves) and skips npm version resolution.      | unset   |
+| `KICI_DEV_REGISTRY` | npm registry the `@kici-dev` scope points at when `KICI_DEV` is set. `kici init` writes it into `.npmrc`; with no value it writes no `.npmrc`.                             | unset   |
+| `KICI_DEBUG`        | Enable debug logging. When `true`, prints verbose diagnostics (SDK alias resolution, step-level debug logs, stack traces on errors). Equivalent to the `--debug` CLI flag. | unset   |
 
 ## Local dev plane
 
@@ -13637,7 +14025,7 @@ job('provision', {
 
 ### Trust tiers on internal triggers
 
-An internally-triggered run resolves its [trust tier](https://docs.kici.dev/user/contexts/#minimum-trust) from the trigger. The tier decides the run's cache scope, whether it may run a [Dockerfile build](https://docs.kici.dev/user/container-jobs/#who-may-build), whether it receives [install secrets](https://docs.kici.dev/user/private-registries/), and whether a `minimumTrust` context holds it.
+An internally-triggered run resolves its [trust tier](https://docs.kici.dev/user/contexts/#minimum-trust) from the trigger. The tier decides the run's cache scope, whether it may run a [Dockerfile build](https://docs.kici.dev/user/container-jobs/#who-may-build), whether it receives [install secrets](https://docs.kici.dev/user/private-registries/), and whether a `minimumTrust` context holds it. It also decides whether the run's jobs receive [container-registry credentials](https://docs.kici.dev/user/container-jobs/#private-images) and their declared [git credentials](https://docs.kici.dev/user/patterns/git-credentials/#what-a-job-may-ask-for).
 
 Four rules resolve the tier, and KiCI applies them in this order:
 
@@ -14164,7 +14552,7 @@ The registration log line names the organization it decided against, so a refusa
 
 ### Secrets are not available
 
-A global workflow's job is dispatched with **no secret material** — not the source repo's, and not the workflow repo's own. The organization-wide dispatch path binds no secret contexts, so a `contexts:` declaration on a global workflow resolves to nothing and any secret the steps expect is simply absent. Plan for it: a global workflow is for checks, policy and reporting that need only the two checkouts, not for deploys that need credentials.
+A global workflow's job is dispatched with **no secret material** — not the source repo's, and not the workflow repo's own. The organization-wide dispatch path binds no secret contexts, so a `contexts:` declaration on a global workflow resolves to nothing and any secret the steps expect is absent. Plan for it: a global workflow is for checks, policy and reporting that need only the two checkouts, not for deploys that need credentials.
 
 This is about your **stored secrets**, not about repository access: the job is still handed a short-lived clone token for each repo it checks out, which is how the dual checkout works at all. What it does not get is anything from a secret context.
 
@@ -15394,10 +15782,14 @@ kici-admin secret set <orgId> "__source__/<sourceId>" pat --value "<your-forgejo
 Finally, configure the forge to deliver webhooks to:
 
 ```
-https://<platform-host>/webhook/<orgId>/generic/<source-name>
+https://<platform-host>/webhook/<orgId>/generic/<sourceId>
 ```
 
-with the same secret you passed to `--secret`.
+with the same secret you passed to `--secret`. `<orgId>` is your Platform
+organization id — the same value you passed to `--org`, which the source's
+routing key embeds — and `<sourceId>` is the id `source add` printed. The
+orchestrator's own ingest URL has the same shape but takes the source **name**
+in place of the id.
 
 ## SSH deploy key
 
@@ -15591,7 +15983,7 @@ interface LocalConfig {
 
 ### SharedConfig
 
-Shared settings stored in the PostgreSQL `config_versions` table. Defined once, shared across all instances:
+Settings stored in the PostgreSQL `config_versions` table, written and read by the `/admin/config` routes and their `kici-admin config` commands:
 
 ```typescript
 interface SharedConfig {
@@ -15635,11 +16027,13 @@ interface AppConfig {
 
 ### How they merge
 
+`resolveFullConfig()` takes a `LocalConfig` and an optional `SharedConfig` and merges them:
+
 ```
 defaults (getDefaults())
     |
     v
-SharedConfig (from DB)        ──deepMerge──>  merged layer 1+2
+SharedConfig (argument)        ──deepMerge──>  merged layer 1+2
     |
     v
 LocalConfig (from YAML)       ──deepMerge──>  merged layer 1+2+3
@@ -15656,29 +16050,48 @@ appConfigSchema.safeParse()    ──validate──>   typed AppConfig
 
 The `deepMerge` function merges objects recursively, replaces arrays (does not merge item-by-item), and skips `undefined`/`null` source values (they do not override existing values).
 
+**The `SharedConfig` argument is `null` in the shipped wiring.** `ConfigReloader` is the only non-test caller of `resolveFullConfig()`, and it is constructed with `sharedStore: null`. So the DB layer is skipped and the effective chain is defaults → YAML → env. The `config_versions` table is read by the `/admin/config` write and inspection routes, by `kici-admin rotate-key`, and by the cluster join flow — never by a running orchestrator's own config.
+
 ## Resolution chain
 
-### Two-phase design
+### Startup
+
+`server.ts` and `standalone.ts` both call `loadConfig()`, which parses `KICI_*` environment variables against the flat schema in `config.ts`. No YAML file and no database row participates:
 
 ```
-Phase 1 (local-only):
-  YAML file + KICI_ env vars
-      |
-      v
-  resolveLocalConfig() -> { databaseUrl, instanceId, port, mode }
-      |
-      v
-  Connect to PostgreSQL
-      |
-      v
-Phase 2 (full merge):
-  defaults -> DB -> YAML -> env
-      |
-      v
-  resolveFullConfig() -> AppConfig
+Process start
+    |
+    v
+loadConfig() -> envDef.parse(process.env) -> AppConfig
+    |
+    v
+Connect to PostgreSQL, run migrations
+    |
+    v
+Start server (HTTP, WS, scaler, cluster)
 ```
 
-**Why two phases?** The database URL must come from local config (YAML or env var) because we need it to connect to PostgreSQL. But the shared config is stored in PostgreSQL. This circular dependency is broken by resolving local config first (Phase 1), connecting to the DB, then doing the full merge (Phase 2).
+The database URL therefore has to be an environment variable: the orchestrator needs it to reach PostgreSQL, and the shared config lives in PostgreSQL.
+
+### Reload
+
+`resolveLocalConfig()` and `resolveFullConfig()` run on the reload path, not at startup:
+
+```
+SIGHUP / POST /admin/config/reload / kici-admin config reload
+    |
+    v
+resolveLocalConfig()  -> YAML file + KICI_ env overlay
+    |
+    v
+resolveFullConfig(local, null)  -> defaults -> YAML -> env -> AppConfig
+    |
+    v
+Hold databaseUrl, port, instanceId and storage at their startup values
+    |
+    v
+Atomic swap into ConfigReloader.currentConfig
+```
 
 ### Env var processing
 
@@ -15690,43 +16103,6 @@ Environment variables are processed in two stages:
 
 Type coercion is applied based on known field types: numeric fields are parsed as numbers, boolean fields are compared against `"true"`, all others remain strings.
 
-## Two-phase bootstrap
-
-```
-┌─────────────────┐
-│  Process Start   │
-└────────┬────────┘
-         │
-         ▼
-┌─────────────────┐
-│  Load YAML +    │  resolveLocalConfig()
-│  Env Overrides  │  -> databaseUrl, instanceId, port, mode
-└────────┬────────┘
-         │
-         ▼
-┌─────────────────┐
-│  Connect to     │  PostgreSQL
-│  Database       │  Run migrations
-└────────┬────────┘
-         │
-         ▼
-┌─────────────────┐
-│  Load Shared    │  SharedConfigStore.getLatest()
-│  Config from DB │  -> decrypt -> SharedConfig
-└────────┬────────┘
-         │
-         ▼
-┌─────────────────┐
-│  Full Merge     │  resolveFullConfig(local, db, env)
-│  + Validate     │  -> AppConfig
-└────────┬────────┘
-         │
-         ▼
-┌─────────────────┐
-│  Start Server   │  HTTP, WS, scaler, cluster
-└─────────────────┘
-```
-
 ## DB schema
 
 ### config_versions table
@@ -15826,7 +16202,7 @@ flowchart TD
     trigger --> execute["executeReload()<br/>boolean mutex"]
 
     execute --> resolveLocal["resolveLocalConfig()"]
-    execute --> getLatest["getLatest (DB)"]
+    execute --> getLatest["getLatest (DB)<br/>skipped: sharedStore is null"]
     execute --> resolveFull["resolveFullConfig()<br/>(merge + validate)"]
 
     resolveLocal --> check["Check restart-required fields"]
@@ -15845,26 +16221,26 @@ flowchart TD
 - **Mutex:** Boolean flag prevents concurrent reloads. Second reload returns `{ success: false, errors: ["Reload already in progress"] }`.
 - **Debounce:** Rapid triggers (e.g., multiple SIGHUP signals) are collapsed into a single reload with a 500ms window.
 - **Validation before swap:** The new config must pass full schema validation. On failure, the old config is preserved and an error is logged.
-- **Restart-required detection:** Fields like `databaseUrl`, `port`, `instanceId` are compared. If changed, the old values are preserved in the applied config and a warning is logged.
+- **Restart-required detection:** `databaseUrl`, `port`, `instanceId` and `storage` are compared. If changed, the old values are preserved in the applied config and a warning is logged.
 - **No crash on failure:** The orchestrator always keeps running with the old config if anything goes wrong during reload.
 
 ### Subsystem callbacks
 
 The `ConfigReloader` uses a dependency injection pattern with callbacks for subsystem re-initialization:
 
-| Callback              | When Called                   | Purpose                                                                                      |
-| --------------------- | ----------------------------- | -------------------------------------------------------------------------------------------- |
-| `onProviderChange`    | Provider config changed       | Reserved callback (providers are now DB-managed via sources table; currently always a no-op) |
-| `onScalerReload`      | Always on successful reload   | Reload scaler YAML config                                                                    |
-| `onPlatformReconnect` | Platform URL or token changed | Reconnect WS to Platform relay                                                               |
-| `onConfigApplied`     | Always on successful reload   | Atomic config reference swap, increment local config version                                 |
+| Callback              | When Called                   | Purpose                                                                                                                        |
+| --------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `onProviderChange`    | Provider config changed       | Reserved callback. Providers are DB-managed via the sources table, so the change detector always reports no change             |
+| `onScalerReload`      | Always on successful reload   | Reload scaler YAML config, from the path the process started with                                                              |
+| `onPlatformReconnect` | Platform URL or token changed | Logs that the Platform connection settings changed. The connection is not re-established; `standalone.ts` registers no handler |
+| `onConfigApplied`     | Always on successful reload   | Atomic config reference swap, increment local config version                                                                   |
 
 ### Prometheus metrics
 
-| Metric                          | Type    | Labels                                                                  | Description                           |
-| ------------------------------- | ------- | ----------------------------------------------------------------------- | ------------------------------------- |
-| `kici_orch_config_reload_total` | Counter | `result` (attempted/success/failed), `source` (sighup/http/cluster/cli) | Config reload attempts and outcomes   |
-| `kici_orch_config_version`      | Gauge   | --                                                                      | Current shared config version from DB |
+| Metric                          | Type    | Labels                                                                  | Description                                                                                                    |
+| ------------------------------- | ------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `kici_orch_config_reload_total` | Counter | `result` (attempted/success/failed), `source` (sighup/http/cluster/cli) | Config reload attempts and outcomes                                                                            |
+| `kici_orch_config_version`      | Gauge   | --                                                                      | Shared config version from the DB. Set only when the reload path reads a version, so it carries no value today |
 
 ## Multi-Provider
 
@@ -15896,40 +16272,42 @@ Each source record contains its own `appId` and `privateKey` (stored as scoped s
 
 ### Heartbeat config version
 
-In clustered deployments, each orchestrator includes its current config version in Raft heartbeat metadata via the `configVersion` optional field on the `peerHeartbeatSchema`.
+In clustered deployments, each orchestrator includes its config version in Raft heartbeat metadata via the `configVersion` optional field on the `peerHeartbeatSchema`.
+
+**That number is a local reload counter, not a shared config version.** `onConfigApplied` increments it on every successful reload and publishes the new value to the peer registry. It counts how many times this instance has reloaded.
 
 When the `PeerRegistry` processes a heartbeat:
 
 1. Compare `localConfigVersion` with `peer.configVersion`
 2. If `peer.configVersion > localConfigVersion` AND both are > 0:
    - Invoke the `onConfigVersionBehind` callback
-   - This triggers a config reload from the database
+   - This triggers a config reload, which re-reads the environment and the local YAML file
 
 ### Auto-remediation flow
 
 ```
-Orchestrator A (version 5)          Orchestrator B (version 3)
+Orchestrator A (reloaded 5x)        Orchestrator B (reloaded 3x)
          │                                     │
          │──── heartbeat(configVersion=5) ────>│
          │                                     │
          │                           compare: 5 > 3
-         │                           trigger reload from DB
+         │                           trigger reload
          │                                     │
-         │                           resolveFullConfig()
-         │                           -> version 5
+         │                           resolveFullConfig(local, null)
+         │                           -> counter becomes 4
          │                                     │
-         │<── heartbeat(configVersion=5) ──────│
+         │<── heartbeat(configVersion=4) ──────│
          │                                     │
-         │   both at version 5 ✓               │
 ```
 
+B converges on A's count only after it has reloaded as many times as A has. Each instance reads its own environment and its own YAML file, so the two agree on content only when those inputs agree.
+
 ### Guard conditions
 
 - Version comparison only triggers when **both** local and peer versions are > 0
 - This prevents false triggers from:
-  - Legacy orchestrators that do not report `configVersion` (field is optional, defaults to 0)
-  - Newly started orchestrators before their first config load
-- The `localConfigVersion` is a monotonically incrementing local counter (incremented on each successful reload)
+  - Orchestrators that do not report `configVersion` (field is optional, defaults to 0)
+  - Newly started orchestrators before their first reload
 
 ## See also
 
@@ -15960,7 +16338,7 @@ GitHub  -->  Platform Relay  -->  Orchestrator  -->  Agent
 
 1. **Provider sends webhook** to the Platform relay endpoint.
 2. **Platform routes the webhook** to the right orchestrator over WebSocket and forwards the body bytes verbatim. Platform never sees customer HMAC secrets — signature verification happens entirely on the orchestrator after reassembly.
-3. **Orchestrator verifies signature** (HMAC-SHA256 against per-source webhook secret, with dual-secret rotation support).
+3. **Orchestrator admits the delivery**, then **verifies the signature** (HMAC-SHA256 against per-source webhook secret, with dual-secret rotation support). Admission runs first, on the routing key alone: when the ingest admission controller sheds, the orchestrator records an `event_log` breadcrumb with status `shed` and ACKs `shed_retry_later`, which the Platform answers as **429** with `Retry-After`. See [ingest admission shed](https://docs.kici.dev/architecture/webhooks/webhook-delivery/#ingest-admission-shed-step-3).
 4. **Orchestrator dedup check** against dual-layer `DedupCache` (in-memory set + `dedup_cache` DB table).
 5. **Orchestrator resolves provider** by looking up the provider bundle from the `ProviderRegistry` using `getByRoutingKey()` (exact match first, falls back to provider type prefix for backward compatibility). Skips processing if the provider is unknown.
 6. **Orchestrator normalizes** the webhook via the provider's `WebhookNormalizer` (extracts branch, event type, action, sender).
@@ -16087,7 +16465,7 @@ Build Job Dispatch --> Build Agent (kici:role:builder + matching kici:os:/kici:a
   |                      |-- npm ci in .kici/
   |                      |-- Pack .kici/ source (portable tar.gz, excludes node_modules)
   |                      |-- Pack .kici/node_modules (portable tar.gz)
-  |                      |-- Upload source tarball to cache (source/{contentHash}.tar.gz)
+  |                      |-- Upload source tarball to cache (source/v2/{orgId}/{sourceTarDigest}.tar.gz)
   |                      |-- Upload deps tarball to cache (deps/{plat}-{arch}/{depsHash}.tar.gz)
   |                      |-- Upload deps companion .hash file
   |                      |-- Report success (cache.upload.complete × 2)
@@ -16162,7 +16540,7 @@ Dep cache misses alone do **not** trigger a build job. Deps are platform-specifi
 
 ### Cross-source / no-contentHash workflows
 
-- **Lock files without `contentHash`** (schema v1) skip the source cache entirely; agents compile from source. Regenerate lock files with `kici compile` to enable caching. The current lock file schema version is 39.
+- **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 41.
 - **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
@@ -16201,7 +16579,7 @@ Both source and dep caches use `S3CacheStorage` as the sole backend. The `CacheS
 
 Cache keys reflect that source tarballs and deps have different platform characteristics:
 
-- **Source:** `source/{contentHash}.tar.gz` — platform-agnostic. Raw TypeScript source is identical regardless of CPU architecture, so one entry is shared across all platforms. `contentHash` is the per-workflow hash from the lock file (`SHA-256(COMPILE_SCHEMA_VERSION + ":" + rawSource [+ "\0" + assetDigest])`, where `COMPILE_SCHEMA_VERSION = 5` and line endings are normalized to LF so the hash agrees across platforms).
+- **Source:** `source/v2/{orgId}/{sourceTarDigest}.tar.gz`, with a `source/v2/{orgId}/{contentHash}.hash` pointer — platform-agnostic, and scoped to the owning organization so two repositories with matching `.kici/` trees never share one object. Raw TypeScript source is identical regardless of CPU architecture, so one entry is shared across all platforms. `contentHash` is the per-workflow hash from the lock file (`SHA-256(COMPILE_SCHEMA_VERSION + ":" + rawSource [+ "\0" + assetDigest])`, where `COMPILE_SCHEMA_VERSION = 7` and line endings are normalized to LF so the hash agrees across platforms).
 - **Deps:** `deps/{platform}-{arch}/{depsHash}.tar.gz`, with a
   `deps/{platform}-{arch}/{lockfileHash}.hash` pointer holding that hash — the
   tarball is addressed by its own content, so two builds sharing a lock file
@@ -16932,14 +17310,14 @@ Shared business logic used by all three tiers. Single source of truth for cross-
 - Label utilities (platform label derivation, runsOn normalization, `kici:*` set-only reserved namespace, role labels)
 - Host inventory (the canonical queryable host-roster schema shared by the orchestrator's roster store, the agent-facing inventory API, and the SDK's `ctx.kici.inventory`)
 - Audit policy and retention (per-action access-log sampling, warm-retention windows for cold-store eligibility, federated activity row schema)
-- Scaler backend type enum (`container`, `bare-metal`, `firecracker`, `kubernetes`, `event`) and the reserved `kici.` event-name prefix that keeps a user step from forging a system event
+- Scaler backend type enum (`container`, `bare-metal`, `firecracker`, `kubernetes`, `event`; the orchestrator config rejects `kubernetes`) and the reserved `kici.` event-name prefix that keeps a user step from forging a system event
 - Job resource vocabulary (the requests/limits shape the SDK accepts, the compiler validates and emits, the orchestrator uses for capacity math and kernel-side enforcement, and the dashboard displays)
 - Registration trigger type enum (registerable trigger discriminator)
 - Sandbox capability set (the Linux capability names a container sandbox may add or drop, shared by the SDK validator, the compiler, and the dispatch resolver)
 - Plan tier vocabulary (the hosted plan tiers and the purchasable subset, shared by the Platform and the browser dashboard)
 - Infrastructure alert vocabulary (the diagnostics alert types and severities the Platform mints and the dashboard and `kici` CLI render)
 - Metric catalog (the generated Prometheus metric inventory, its naming policy, and metric-kind compatibility checks)
-- Bundler config (shared bundler configuration consumed by `e2e/helpers/service-deploy.ts`; the agent runtime uses the `@kici-dev/core/ts-loader-hook` to transform TypeScript on import, with no runtime bundler step)
+- Bundler config (the shared workflow-bundle configuration factory on the barrel; the agent runtime uses the `@kici-dev/core/ts-loader-hook` to transform TypeScript on import, so no runtime path bundles a workflow)
 
 > Source: `packages/engine/src/`
 
@@ -16959,7 +17337,7 @@ It also runs the **local dev plane** -- an on-demand, fully local execution stac
 
 ### `@kici-dev/core`
 
-Light shared utilities with no server-side dependencies. It provides JSON-structured logging, error helpers, async-local-storage request context, and human-readable formatting (`formatBytes`/`formatDuration`/`formatUptime`). It also provides cryptographic helpers (`sha256`/`sha256File`/`deriveSharedSecret` plus symmetric encrypt/decrypt), retry-backoff computation, and the shared diagnostics-result contract. The rest of its surface ships as subpath entry points: the temp-directory allocator and its garbage collector, package-manager detection, CI-environment detection, and the idempotent-step runner (the check / confirm / apply primitive behind idempotent steps). Finally it supplies zx initialization (`initZx()`) and the TypeScript loader hook that transforms TypeScript on import. It is the dependency-light core that the SDK, compiler, and `kici` CLI consume directly so they stay free of heavier server-only dependencies. `@kici-dev/shared` re-exports it, so existing `@kici-dev/shared` import paths keep working.
+Light shared utilities with no server-side dependencies. It provides JSON-structured logging, error helpers, async-local-storage request context, and human-readable formatting (`formatBytes`/`formatDuration`/`formatUptime`). It also provides cryptographic helpers (`sha256`/`sha256File`/`deriveSharedSecret` plus symmetric encrypt/decrypt), retry-backoff computation, and the shared diagnostics-result contract. The rest of its surface ships as subpath entry points: the temp-directory allocator and its garbage collector, package-manager detection, CI-environment detection, and the idempotent-step runner (the check / confirm / apply primitive behind idempotent steps). One further subpath holds the `.kici/` source digest: the single content-hash definition the compiler writes into the lock file and the agent recomputes as its drift gate. Finally it supplies zx initialization (`initZx()`) and the TypeScript loader hook that transforms TypeScript on import. It is the dependency-light core that the SDK, compiler, and `kici` CLI consume directly so they stay free of heavier server-only dependencies. `@kici-dev/shared` re-exports it, so existing `@kici-dev/shared` import paths keep working.
 
 > Source: `packages/core/src/`
 
@@ -17041,7 +17419,7 @@ KiCI uses three WebSocket layers for real-time communication.
 
 ### Platform ↔ Orchestrator
 
-The orchestrator connects outbound to the Platform WebSocket endpoint. After authentication (API key validated via SHA-256 hash lookup), the connection is used for webhook relay, execution telemetry (events, status, logs), source registration, and peer discovery. The Platform can also relay `job.reroute` messages between orchestrators that cannot reach each other directly.
+The orchestrator connects outbound to the Platform WebSocket endpoint. After authentication (API key validated via SHA-256 hash lookup), the connection is used for webhook relay, execution telemetry (events, status, logs), source registration, and peer discovery. Peer discovery is matchmaking only: the Platform pushes a `peer.update` membership list to every orchestrator sharing a routing key, and the orchestrators then connect to each other directly. Inter-orchestrator traffic such as `job.reroute` never transits the Platform.
 
 ### Orchestrator ↔ Orchestrator (P2P)