@kici-dev/compiler 0.7.0 → 0.9.0

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

@@ -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
@@ -847,7 +847,7 @@ Each guide is split into two parts. **Part 1** gets you a green run against your
 
 ## Bring a coding agent
 
-Workflows are TypeScript, so a coding agent can write them. KiCI ships its docs in a form an agent reads directly: point yours at [llms.txt](https://kici.dev/docs/llms.txt), or pipe a task bundle straight into its context with `kici docs llm` (`kici docs llm sdk` for the authoring API, `kici docs llm patterns` for recipes). An agent briefed that way can scaffold your first workflow, compile it, and read the failure when it breaks.
+Workflows are TypeScript, so a coding agent can write them. KiCI ships its docs in a form an agent reads directly: point yours at [llms.txt](https://kici.dev/llms.txt), or pipe a task bundle straight into its context with `kici docs llm` (`kici docs llm sdk` for the authoring API, `kici docs llm patterns` for recipes). An agent briefed that way can scaffold your first workflow, compile it, and read the failure when it breaks.
 
 If your agent finds that these docs promise something KiCI does not do, that is worth telling us — `kici feedback` prints how to report it, and [Reporting a discrepancy](https://docs.kici.dev/user/reporting-discrepancies/) is the full guide.
 
@@ -893,8 +893,10 @@ promised. You can report that.
 A human reader can use this page too. The rules below exist because the tracker
 is public and you are filing under someone else's GitHub identity.
 
-Run `kici feedback` to print this contract in your terminal, or
-`kici feedback --json` to read it as structured data.
+Run `kici feedback` to print this contract in your terminal,
+`kici feedback --json` to read it as structured data, or
+`kici feedback --draft <file.json> --open` to turn a draft into the prefilled form
+and open it.
 
 ## The rule, in one sentence
 
@@ -969,19 +971,20 @@ approval rule.
 
 ## What the report must carry
 
-Five things. A report missing any of them cannot be acted on:
+A report missing any of these fields cannot be acted on:
 
 | Field                                 | What it holds                                                                                                        |
 | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
 | What the docs or CLI advertise        | The exact claim, quoted, plus its source: a docs URL or the command whose `--help` says it.                          |
 | What actually happened                | The real output or behaviour, quoted, with any error text.                                                           |
 | Minimal reproduction, including setup | Every step from an empty directory: the setup commands, a minimal synthetic workflow, and the exact command you ran. |
-| Version and environment               | Output of `kici --version`, plus Node version and OS.                                                                |
+| KiCI version                          | Output of `kici --version`.                                                                                          |
+| Environment                           | Node version and OS.                                                                                                 |
 | Why this is a discrepancy             | One or two sentences ruling out the likely misreads — why the docs cannot be read to match what you observed.        |
 
 The last field is the one agents skip, and it is the one that makes a report
 usable. "The docs say `--foo` exists and it does not" is a claim. "`--foo` is
-documented at <url>, and `kici bar --help` on 0.1.16 lists no such flag" is a
+documented at <url>, and `kici bar --help` on the version I ran lists no such flag" is a
 finding someone can act on in one pass.
 
 Include setup steps whenever your reproduction needed any. A reproduction that
@@ -990,22 +993,36 @@ starts from state a maintainer cannot recreate is not a reproduction.
 ## Filing it
 
 The tracker is [kici-dev/kici-public](https://github.com/kici-dev/kici-public),
-and the form is **Agent report**:
+and the form is **Agent report** (`agent_report.yml`). It is a GitHub issue
+form, which only the browser can submit — `gh issue create` cannot fill it.
+So you draft, and the person files.
 
-```bash
-kici feedback --open
+Write the draft as JSON, one key per field of the form (`kici feedback --json`
+lists them under `draftFields`):
+
+```json
+{
+  "title": "kici compile --check writes a lock file",
+  "advertised": "https://docs.kici.dev/user/cli-reference/ says: `kici compile --check` type-checks without writing a lock file.",
+  "observed": ".kici/kici.lock.json was written; mtime changed.",
+  "reproduction": "$ mkdir /tmp/repro && cd /tmp/repro\n$ kici init\n$ kici compile --check",
+  "version": "0.8.0",
+  "environment": "Node 24.13.0, Ubuntu 24.04",
+  "justification": "The sentence names --check as the no-write mode; no reading of it allows a write."
+}
 ```
 
-Draft the complete body first. Show it to the person you are working with —
-the whole body, not a summary of it. File only after they say yes:
+Then build the prefilled form:
 
 ```bash
-gh issue create --repo kici-dev/kici-public --template agent_report.yml
+kici feedback --draft draft.json --open
 ```
 
-The form asks you to confirm the report was drafted by an agent and reviewed by
-a person before filing. Answer honestly; it is what lets maintainers triage
-agent-filed reports as a group.
+The command prints the form URL with every field filled in and, with
+`--open`, opens it. It reaches no network and files nothing. Show the person
+you are working with the whole draft — not a summary of it. They open the
+URL, read the prefilled form, tick the review boxes, and submit. File only
+after they say yes.
 
 If they say no, that is the end of it. Do not re-file the same finding in
 another form, and do not open it as a question instead.
@@ -3673,9 +3690,8 @@ 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.
+`@kici-dev/sdk/internal`, outside semver, and is not exported from the root barrel. 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.
 
@@ -3928,9 +3944,8 @@ 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.
+`@kici-dev/sdk/internal`, outside semver, and are not exported from the root barrel. They are
+described here because they define the combinations a matrix job actually produces.
 
 ```typescript
 import { expandMatrix, applyIncludeExclude } from '@kici-dev/sdk/internal';
@@ -4527,7 +4542,7 @@ Create a commit status trigger. Returns a frozen `StatusTriggerConfig`.
 function status(config?: StatusConfigInput): StatusTriggerConfig;
 ```
 
-**Config options:** `contexts` (picomatch strings like 'ci/\*'), `states` (error/failure/pending/success), `description`
+**Config options:** `contexts` (glob patterns like 'ci/\*'), `states` (error/failure/pending/success), `description`
 
 ```typescript
 status(); // Any status
@@ -5153,11 +5168,8 @@ a `.result` proxy reads, build the step context your workflow body receives, eva
 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/).
+a workflow. Everything a workflow author needs is on the root entry point above, and none
+of the runtime contract is exported there.
 
 ## See also
 
@@ -6502,6 +6514,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) */
@@ -6702,13 +6725,15 @@ 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.
+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/oidc/#id-token-claims-and-cloud-trust-policies) for the full claim table and a worked AWS policy.
 
 ```typescript
 const publish = job('publish', {
   steps: [
     step('mint', async (ctx) => {
-      const { token, expiresIn } = await ctx.kici.oidc.token({ audience: 'sigstore' });
+      const minted = await ctx.kici.oidc.token({ audience: 'sigstore' });
+      if ('deferred' in minted) throw new Error(`ID token deferred: ${minted.code}`);
+      const { token, expiresIn } = minted;
       ctx.log.info(`Got an ID token valid for ${expiresIn}s`);
       // Hand `token` to a tool that exchanges it with the trusting service.
     }),
@@ -6718,6 +6743,7 @@ const publish = job('publish', {
 
 **Behavior:**
 
+- The result is the minted token, or `{ deferred: true, code }` (`unavailable` | `failed`) when the orchestrator could not mint one right now. A step that exchanges the token fails on `deferred`; `ctx.attestProvenance` handles it by freezing the statement for later fulfilment.
 - The token is short-lived (about 10 minutes) and scoped to the current run and job.
 - The returned token value is automatically masked in step logs.
 - The step never holds signing credentials — the orchestrator mints and signs the token on the step's behalf from its own run records.
@@ -8573,7 +8599,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
@@ -8582,7 +8608,7 @@ kici local trust-root <file>               # Export the dev-signed trust root fo
 The plane runs in one of two modes:
 
 - **Independent (offline)** — the default for a plane that has never been attached. Identity tokens and attestations are signed by a local dev key under the clearly non-production issuer `kici-local`.
-- **Hybrid (attached)** — `kici local attach` mints an org-scoped key with your logged-in credentials and reboots the plane connected to the Platform, so local runs get real Platform-minted identity and attestation. `kici local up` honors a durable attachment record: an attached plane comes back up hybrid, and falls back to offline with a warning when the Platform is unreachable.
+- **Hybrid (attached)** — `kici local attach` mints an org-scoped key with your logged-in credentials and reboots the plane connected to the Platform, so local runs get identity and attestation signed by the plane's own key under its own issuer, as a deployed orchestrator would. `kici local up` honors a durable attachment record: an attached plane comes back up hybrid, and falls back to offline with a warning when the Platform is unreachable.
 
 `--offline` forces an independent boot without clearing the attachment record (only `detach` clears it); `--connected` requires an attached, reachable Platform and fails otherwise.
 
@@ -8590,6 +8616,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:
@@ -8748,7 +8776,7 @@ If multiple tools are detected, you are prompted to choose.
 Open the KiCI documentation site in the default browser. With the `llm` subcommand, print the LLM-friendly documentation bundle that ships with `@kici-dev/compiler` — pipe it into a coding agent's context buffer to brief the agent on authoring conventions without an internet round-trip.
 
 ```bash
-kici docs               # open https://kici.dev/docs/
+kici docs               # open https://docs.kici.dev/
 kici docs --no-open     # print the URL instead of opening a browser
 kici docs llm           # print the llms.txt index (a router over the task bundles)
 kici docs llm sdk       # print the SDK task bundle
@@ -8882,7 +8910,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`
 
@@ -9030,9 +9058,7 @@ behalf). The token is printed once — save it now; it cannot be retrieved later
 
 **Option B — an agent org API key.** Create one from the dashboard's
 **Settings → API keys** tab: set the key's kind to **Agent** and give it an
-agent name (the agent label). The same key can also be minted with
-`kici-platform-admin user api-key create --org <id> --agent --agent-label <label>`.
-Reach for an org agent key when the agent should act as a shared service account
+agent name (the agent label). Reach for an org agent key when the agent should act as a shared service account
 rather than as a single user — for example, a long-lived CI bot that outlives any
 individual's membership.
 
@@ -9747,7 +9773,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
 
@@ -10184,10 +10210,11 @@ kici verify-attestation --bundle ./app.tgz.kici.json \
 token was minted relative to the build. A normal attestation prints no marker
 (the token was minted live). A **deferred** attestation prints an `ATTESTATION:
 deferred` line — the build facts were sealed at build time and the token was
-minted later, after a transient platform outage, bound to the frozen statement
-by its hash. An **offline-backfill** attestation prints an `ATTESTATION:
-offline-backfill` line — the run was ingested while the platform was down, so its
-run/job rows were backfilled before the token was minted. Both still verify
+minted later, once the orchestrator's signing key was available again, bound to
+the frozen statement by its hash. An **offline-backfill** attestation prints an
+`ATTESTATION: offline-backfill` line — the run was ingested while the platform
+was down, so its run/job records were replayed to the platform before the token
+was minted. Both still verify
 (PASS); the marker discloses the temporal gap, and the organization id remains
 the authoritative anchor.
 
@@ -10346,6 +10373,9 @@ kici feedback --open
 
 # Read the same contract as structured data
 kici feedback --json
+
+# Turn a JSON draft (keys: draftFields from --json) into the prefilled form URL
+kici feedback --draft draft.json --open
 ```
 
 `--json` exists for coding agents: KiCI is built to be driven by an LLM, and
@@ -10396,10 +10426,11 @@ Synopsis: `kici feedback [options]`
 
 **Options**
 
-| Option   | Default | Description                                          |
-| -------- | ------- | ---------------------------------------------------- |
-| `--open` |         | Open the prefilled issue form in the default browser |
-| `--json` |         | Emit the reporting contract as JSON                  |
+| Option           | Default | Description                                                                                   |
+| ---------------- | ------- | --------------------------------------------------------------------------------------------- |
+| `--open`         |         | Open the prefilled issue form in the default browser                                          |
+| `--json`         |         | Emit the reporting contract as JSON                                                           |
+| `--draft <file>` |         | Build the prefilled issue-form URL from a JSON draft keyed by field id (with --open, open it) |
 
 ### `kici notifications`
 
@@ -10693,6 +10724,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
@@ -11922,13 +11965,12 @@ Hold a job whose run came from a fork:
 Minimum trust: trusted
 ```
 
-| Value     | Effect                                                     |
-| --------- | ---------------------------------------------------------- |
-| `trusted` | Holds a run whose ref came from a fork                     |
-| `known`   | Same effect; the value is deprecated and removed at v1.0.0 |
-| (unset)   | No trust-based gating                                      |
+| Value     | Effect                                 |
+| --------- | -------------------------------------- |
+| `trusted` | Holds a run whose ref came from a fork |
+| (unset)   | No trust-based gating                  |
 
-Both values block the same thing. Trust comes from the git ref, and that judgement has two answers: a ref in your repository is `trusted`, a ref from a fork is `unknown`. The value you declare still decides the wording of the hold reason.
+Trust comes from the git ref, and that judgement has two answers: a ref in your repository is `trusted`, a ref from a fork is `unknown`.
 
 When the gate holds a job, it enters the security approval queue. Someone with `ci_trust:write` or higher must approve it before execution proceeds.
 
@@ -12083,6 +12125,439 @@ This guide is split across the following pages:
 
 ---
 
+## Workload identity with OIDC
+
+Source: https://docs.kici.dev/user/oidc/
+
+A job step can prove **which run it is** to an outside service without a stored
+secret. The orchestrator mints a short-lived OIDC identity token for the step,
+signs it with its own key, and the service verifies it against the
+orchestrator's public keys. Your repository holds no long-lived credential for
+that service; the exchanged credential exists only inside the step.
+
+The orchestrator is the OIDC issuer. It publishes the discovery document and
+the key set under `KICI_ORCHESTRATOR_PROVENANCE_ISSUER`, and the service you
+exchange with must be able to reach that base URL — see
+[network requirements](https://docs.kici.dev/operator/network-requirements/) and
+[signing keys](https://docs.kici.dev/operator/orchestrator/signing-keys/) for the operator side.
+
+## Requesting an identity token
+
+Call `ctx.kici.oidc.token({ audience })` from a step when you need the identity
+token for a tool that trusts your orchestrator:
+
+```typescript
+step('mint', async (ctx) => {
+  const minted = await ctx.kici.oidc.token({ audience: 'sigstore' });
+  if ('deferred' in minted) throw new Error(`ID token deferred: ${minted.code}`);
+  const { token, expiresIn } = minted;
+  ctx.log.info(`Got an ID token valid for ${expiresIn}s`);
+  // Hand `token` to a tool that exchanges it with a service trusting the issuer.
+});
+```
+
+The result is either the minted token or `{ deferred: true, code }` when the
+orchestrator could not mint one right now (`unavailable` or `failed`). An
+exchange needs a live token, so a step that exchanges it fails on `deferred`;
+[`ctx.attestProvenance`](https://docs.kici.dev/user/provenance/) handles that case for you by freezing
+the statement and fulfilling it later. The token is a short-lived (about 10
+minutes) signed JWT scoped to the current run and job. Its identity claims
+(`repository`, `ref`, `sha`, `kici_run_id`, `kici_job_id`) are derived by the
+orchestrator from the run context, so a step cannot spoof them. The returned
+token value is automatically masked in step logs, and the step never holds
+signing credentials — the orchestrator mints and signs the token on the step's
+behalf from its own run records. It is only available inside a running job step.
+
+## Exchanging the token with an external service
+
+Any service that federates with a generic OIDC issuer can trust your
+orchestrator directly. The service fetches your issuer's discovery document
+(`<issuer>/.well-known/openid-configuration`) and public keys, so the issuer
+base URL must be reachable from that service.
+
+The pattern is the same everywhere: request a token with the audience the
+service expects, exchange it for the service's own short-lived credential, and
+use that credential inside the step. The workflows below are the ones KiCI's
+own test suite runs against a real Cloudsmith organization and a real AWS
+account. Each publishes a probe, reads it back, and deletes it. Replace the
+probe with your real publish or upload.
+
+Only the ID token is masked in step logs automatically. A credential you
+exchange it for is an ordinary string, so do not log it. Hand it to child
+processes through a scratch file or the environment, never on a command line.
+
+### Cloudsmith
+
+Cloudsmith exchanges any trusted issuer's token for a Cloudsmith API token
+through `POST https://api.cloudsmith.io/openid/<org>/`. The exchanged
+credential works as the Cloudsmith API key and as an npm auth token:
+
+<!-- BEGIN GENERATED: oidc-cloudsmith-workflow (do not edit; run the doc generator) -->
+
+```typescript
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { workflow, job, step, push } from '@kici-dev/sdk';
+
+// Exchanges the job's OIDC ID token with Cloudsmith, publishes a probe npm
+// package, reads it back through the Cloudsmith API and deletes it. Every
+// Cloudsmith call is made with the exchanged token; nothing here is a secret
+// the repo stores.
+const ORG = 'my-org';
+const REPO = 'my-repo';
+const REGISTRY = `https://npm.cloudsmith.io/${ORG}/${REPO}/`;
+const PACKAGES_API = `https://api.cloudsmith.io/v1/packages/${ORG}/${REPO}/`;
+const PREFIX = '[cloudsmith-oidc]';
+
+function decodeJwtPart(token: string, index: number): Record<string, unknown> {
+  return JSON.parse(Buffer.from(token.split('.')[index], 'base64url').toString('utf8'));
+}
+
+export default workflow('publish', {
+  on: push({ branches: ['main'] }),
+  jobs: [
+    job('publish', {
+      runsOn: 'container',
+      steps: [
+        step('exchange-and-publish', async (ctx) => {
+          // 1. Mint. Log the signing algorithm, key id and subject: when the
+          //    provider rejects the token, this line says which claim to compare
+          //    against the provider's required claims.
+          const minted = await ctx.kici.oidc.token({ audience: 'cloudsmith' });
+          // A deferred mint is a transient orchestrator-side failure; an exchange
+          // needs a live token, so the step fails rather than freezing a statement.
+          if ('deferred' in minted) throw new Error(`ID token mint deferred: ${minted.code}`);
+          const { token } = minted;
+          const header = decodeJwtPart(token, 0);
+          const payload = decodeJwtPart(token, 1);
+          ctx.log.info(`${PREFIX} alg=${header.alg} kid=${header.kid} sub=${payload.sub}`);
+
+          // 2. Exchange.
+          const exchange = await fetch(`https://api.cloudsmith.io/openid/${ORG}/`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ oidc_token: token, service_slug: 'ci-publisher' }),
+          });
+          if (!exchange.ok) {
+            const body = (await exchange.text()).split(token).join('<id-token>');
+            ctx.log.error(`${PREFIX} exchange=failed status=${exchange.status} body=${body}`);
+            throw new Error(`Cloudsmith token exchange failed: ${exchange.status}`);
+          }
+          const { token: csToken } = (await exchange.json()) as { token: string };
+          ctx.log.info(`${PREFIX} exchange=ok`);
+
+          // 3. Publish a unique probe version. The npmrc carrying the exchanged
+          //    token is a scratch file the job removes; it never reaches argv.
+          //    The run-id segment is prefixed with a letter: a prerelease identifier
+          //    made only of digits is numeric under semver and may not start with
+          //    0, so a run id such as 01234567 would make npm refuse the version.
+          const runIdShort = String(payload.kici_run_id).slice(0, 8);
+          const version = `0.0.0-e2e.r${runIdShort}.${Math.floor(Date.now() / 1000)}`;
+          const name = '@kici-e2e/oidc-probe';
+          const pkgDir = await ctx.mktemp('oidc-probe');
+          await writeFile(
+            join(pkgDir.path, 'package.json'),
+            JSON.stringify({ name, version, license: 'MIT', main: 'index.js' }, null, 2),
+          );
+          await writeFile(join(pkgDir.path, 'index.js'), 'module.exports = "kici oidc probe";\n');
+          const npmrc = await ctx.mktempFile('cloudsmith-npmrc');
+          await writeFile(
+            npmrc.path,
+            `//npm.cloudsmith.io/${ORG}/${REPO}/:_authToken=${csToken}\n`,
+          );
+          await ctx.$({
+            cwd: pkgDir.path,
+            env: { ...process.env, NPM_CONFIG_USERCONFIG: npmrc.path },
+          })`npm publish --registry ${REGISTRY} --tag e2e`;
+
+          // 4. Read it back through the API with the same token, then delete.
+          //    The version is unique per run, so it is the whole query.
+          const authHeaders = { 'X-Api-Key': `Bearer ${csToken}` };
+          const query = encodeURIComponent(`version:${version}`);
+          let slug: string | undefined;
+          const deadline = Date.now() + 120_000;
+          while (Date.now() < deadline && !slug) {
+            const list = await fetch(`${PACKAGES_API}?query=${query}`, { headers: authHeaders });
+            if (list.ok) {
+              const rows = (await list.json()) as Array<{
+                slug: string;
+                is_sync_completed: boolean;
+              }>;
+              const done = rows.find((r) => r.is_sync_completed);
+              if (done) slug = done.slug;
+            }
+            if (!slug) await new Promise((r) => setTimeout(r, 5_000));
+          }
+          if (!slug) throw new Error(`${name}@${version} never finished syncing in Cloudsmith`);
+          const del = await fetch(`${PACKAGES_API}${slug}/`, {
+            method: 'DELETE',
+            headers: authHeaders,
+          });
+          if (!del.ok) throw new Error(`Cloudsmith delete failed: ${del.status}`);
+          ctx.log.info(`${PREFIX} verdict=ok package=${name}@${version} deleted=true`);
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+<!-- END GENERATED: oidc-cloudsmith-workflow -->
+
+On the Cloudsmith side, add an OpenID Connect provider under your organization's
+authentication settings. The **provider URL** is your orchestrator's issuer
+(`KICI_ORCHESTRATOR_PROVENANCE_ISSUER`), and the **service account** is the one
+named by `service_slug`. The **required claims** pin which runs may
+authenticate. Pin `sub` to the build identity; for production add the fork
+conditions from the [claim table](https://docs.kici.dev/user/oidc/#the-claim-set) below so a fork pull request
+cannot exchange a token:
+
+```
+sub: repo:acme/app:ref:main:workflow:publish
+is_fork: false
+head_repository: acme/app
+```
+
+### AWS
+
+AWS exchanges the token through `AssumeRoleWithWebIdentity`, which needs no AWS
+credential of its own. The step imports `@aws-sdk/client-sts` and
+`@aws-sdk/client-s3`; declare both under `dependencies` in `.kici/package.json`
+so the compiled workflow can load them.
+
+<!-- BEGIN GENERATED: oidc-aws-workflow (do not edit; run the doc generator) -->
+
+```typescript
+import { workflow, job, step, push } from '@kici-dev/sdk';
+import { STSClient, AssumeRoleWithWebIdentityCommand } from '@aws-sdk/client-sts';
+import {
+  S3Client,
+  PutObjectCommand,
+  GetObjectCommand,
+  DeleteObjectCommand,
+  ListObjectsV2Command,
+} from '@aws-sdk/client-s3';
+
+// Exchanges the job's OIDC ID token with AWS STS for role credentials, writes
+// one probe object to S3, reads it back and deletes it. Nothing here is a
+// secret the repo stores; the credentials exist only inside this step.
+const REGION = 'eu-central-1';
+const ROLE_ARN = 'arn:aws:iam::123456789012:role/ci-uploader';
+const BUCKET = 'my-artifacts';
+const PREFIX = '[aws-oidc]';
+
+function decodeJwtPart(token: string, index: number): Record<string, unknown> {
+  return JSON.parse(Buffer.from(token.split('.')[index], 'base64url').toString('utf8'));
+}
+
+export default workflow('upload', {
+  on: push({ branches: ['main'] }),
+  jobs: [
+    job('upload', {
+      runsOn: 'container',
+      steps: [
+        step('assume-and-put', async (ctx) => {
+          // 1. Mint. Log the signing algorithm, key id, subject and audience:
+          //    when STS rejects the token, this line says which claim to compare
+          //    against the role's trust policy.
+          const minted = await ctx.kici.oidc.token({ audience: 'sts.amazonaws.com' });
+          // A deferred mint is a transient orchestrator-side failure; an exchange
+          // needs a live token, so the step fails rather than freezing a statement.
+          if ('deferred' in minted) throw new Error(`ID token mint deferred: ${minted.code}`);
+          const { token } = minted;
+          const header = decodeJwtPart(token, 0);
+          const payload = decodeJwtPart(token, 1);
+          ctx.log.info(
+            `${PREFIX} alg=${header.alg} kid=${header.kid} sub=${payload.sub} aud=${payload.aud}`,
+          );
+
+          // 2. Exchange. AssumeRoleWithWebIdentity is an unsigned operation, so
+          //    the client needs no credentials of its own.
+          const runId = String(payload.kici_run_id);
+          const sts = new STSClient({ region: REGION });
+          let creds;
+          try {
+            const out = await sts.send(
+              new AssumeRoleWithWebIdentityCommand({
+                RoleArn: ROLE_ARN,
+                RoleSessionName: `kici-e2e-${runId.slice(0, 8)}`,
+                WebIdentityToken: token,
+                DurationSeconds: 900,
+              }),
+            );
+            creds = out.Credentials;
+          } catch (err) {
+            const e = err as { name?: string; message?: string };
+            const message = String(e.message ?? err)
+              .split(token)
+              .join('<id-token>');
+            ctx.log.error(`${PREFIX} assume=failed code=${e.name ?? 'unknown'} message=${message}`);
+            throw err;
+          }
+          if (!creds?.AccessKeyId || !creds.SecretAccessKey || !creds.SessionToken) {
+            throw new Error('AssumeRoleWithWebIdentity returned no credentials');
+          }
+          ctx.log.info(`${PREFIX} assume=ok`);
+
+          // 3. Put + get with the role credentials.
+          const s3 = new S3Client({
+            region: REGION,
+            credentials: {
+              accessKeyId: creds.AccessKeyId,
+              secretAccessKey: creds.SecretAccessKey,
+              sessionToken: creds.SessionToken,
+            },
+          });
+          const key = `e2e/${runId}/probe.txt`;
+          const body = `kici aws-oidc probe run=${runId} ts=${new Date().toISOString()}\n`;
+          await s3.send(new PutObjectCommand({ Bucket: BUCKET, Key: key, Body: body }));
+          const got = await s3.send(new GetObjectCommand({ Bucket: BUCKET, Key: key }));
+          const readBack = await got.Body?.transformToString();
+          if (readBack !== body) {
+            throw new Error(`probe object did not round-trip: got ${JSON.stringify(readBack)}`);
+          }
+
+          // 4. Delete, then prove the prefix is empty.
+          await s3.send(new DeleteObjectCommand({ Bucket: BUCKET, Key: key }));
+          const left = await s3.send(
+            new ListObjectsV2Command({ Bucket: BUCKET, Prefix: `e2e/${runId}/` }),
+          );
+          if ((left.KeyCount ?? 0) !== 0) {
+            throw new Error(`${left.KeyCount} object(s) left under e2e/${runId}/`);
+          }
+          ctx.log.info(`${PREFIX} verdict=ok bucket=${BUCKET} key=${key} deleted=true`);
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+<!-- END GENERATED: oidc-aws-workflow -->
+
+On the AWS side, create an IAM OpenID Connect identity provider whose URL is
+your orchestrator's issuer and whose audience is `sts.amazonaws.com`, then
+attach the [worked trust policy](https://docs.kici.dev/user/oidc/#a-worked-aws-trust-policy) to the role. When
+the issuer URL carries a path, the condition keys carry it too:
+`orch.example.com/kici:sub`, not `orch.example.com:sub`.
+
+## 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                                                                                                              |
+| `orchestrator_id`             | The orchestrator that ran the job                                                                                                 |
+| `provider`                    | The source provider the run came from (`github`, `gitlab`, …)                                                                     |
+| `source_origin`               | `triggered` for a webhook-driven run; `run-remote` when the run executed an uploaded working tree (`kici run remote`)             |
+| `attestation_origin`          | `live` when the token was minted during the job; `deferred` or `offline-backfill` when it was minted later for a frozen statement |
+| `statement_hash`              | The hash of the frozen statement a deferred token is bound to; `null` for a live token                                            |
+
+Every claim in the table is **always present**. A value the run did not resolve
+is `''`, `'unresolved'` or `null`, 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:upload",
+          "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 every one 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.
+
+## See also
+
+- [Build provenance and attestations](https://docs.kici.dev/user/provenance/) — `ctx.attestProvenance`
+  builds on the identity token this page mints.
+- [Private registries](https://docs.kici.dev/user/private-registries/) — registry auth for installs,
+  and where an exchanged Cloudsmith token fits.
+- [SDK runtime reference](https://docs.kici.dev/user/sdk/runtime/) — the `ctx.kici.oidc.token` step
+  API in full.
+- [Signing keys](https://docs.kici.dev/operator/orchestrator/signing-keys/) — provisioning and
+  rotating the key that signs these tokens.
+- [Network requirements](https://docs.kici.dev/operator/network-requirements/) — what the
+  exchanging service must reach.
+
+---
+
 ## Private npm registries
 
 Source: https://docs.kici.dev/user/private-registries/
@@ -12306,6 +12781,10 @@ registries: [
 ],
 ```
 
+To publish to Cloudsmith from a step without a stored token, exchange the job's
+OIDC identity token for a Cloudsmith credential — see
+[exchanging the token with an external service](https://docs.kici.dev/user/oidc/#exchanging-the-token-with-an-external-service).
+
 ## 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.
@@ -12337,7 +12816,7 @@ The orchestrator exposes Prometheus counters and a histogram under the `kici_orc
 | ------------------------------------------------------------- | --------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `kici_orch_install_secrets_decisions_total`                   | Counter   | `decision`, `reason`           | Pass / reject / hold volume. `decision=hold` (reason `held`) counts dispatches paused at a reviewer-gated install context. Reject reasons enumerate the failure mode: `malformed_ref`, `invalid_url_scheme`, `env_not_found`, `protection_rule_block`, `missing_token`, `missing_install_env`, etc. |
 | `kici_orch_install_secrets_npm_registry_used_total`           | Counter   | `channel`, `provider`, `scope` | Per-channel + per-scope usage. `channel=registries` is Option A, `channel=install_env` is Option C. `scope=default` marks a no-scope default registry; `scope=-` marks Option C entries.                                                                                                            |
-| `kici_orch_install_secrets_contributor_stripped_total`        | Counter   | `trust_tier`                   | Number of dispatches where registry tokens were stripped because the contributor tier wasn't `trusted` (fork PRs from unknown / known contributors). Expected to be 0 in single-tenant orgs.                                                                                                        |
+| `kici_orch_install_secrets_contributor_stripped_total`        | Counter   | `trust_tier`                   | Number of dispatches where registry tokens were stripped because the contributor tier wasn't `trusted` (fork PRs). Expected to be 0 in single-tenant orgs.                                                                                                                                          |
 | `kici_orch_install_secrets_token_resolution_duration_seconds` | Histogram | `environment`                  | Latency of per-environment secret resolution. Pathological tails (>500ms) usually mean a Vault timeout or a slow Postgres replica.                                                                                                                                                                  |
 
 The dashboard JSON lives at `infra/terraform/modules/grafana/dashboards/install-secrets.json`; if you maintain your own monitoring stack, you can import it directly.
@@ -12434,7 +12913,10 @@ path or a precomputed digest:
 
 The identity token is fetched and masked in logs automatically — you never
 handle it. The call returns `{ storageKey, subjectDigest, bundleMediaType }`
-identifying the stored bundle.
+identifying the stored bundle. `ctx.attestProvenance` builds on the run's OIDC
+identity token; to mint that token yourself and exchange it with Cloudsmith,
+AWS, or any OIDC-federated service, see
+[Workload identity with OIDC](https://docs.kici.dev/user/oidc/).
 
 `ctx.attestProvenance` is only available inside a running job step; calling it
 outside one rejects with a clear error. `kici run --local` runs are supported:
@@ -12442,128 +12924,6 @@ the offline local dev plane signs with a dev identity under the
 clearly-non-production issuer `kici-local`, and those bundles verify against a
 trust root exported with `kici local trust-root`.
 
-### Requesting a raw identity token
-
-`ctx.attestProvenance` builds on a lower-level primitive you can call directly
-when you need the identity token for a different tool:
-
-```typescript
-step('mint', async (ctx) => {
-  const { token, expiresIn } = await ctx.kici.oidc.token({ audience: 'sigstore' });
-  ctx.log.info(`Got an ID token valid for ${expiresIn}s`);
-  // Hand `token` to a tool that exchanges it with a service trusting the issuer.
-});
-```
-
-The token is a short-lived (about 10 minutes) signed JWT scoped to the current
-run and job. Its identity claims (`repository`, `ref`, `sha`, `kici_run_id`,
-`kici_job_id`) are derived by the orchestrator from the run context, so a step
-cannot spoof them. The returned token value is automatically masked in step logs,
-and the step never holds signing credentials — the orchestrator mints and signs
-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
@@ -12739,8 +13099,10 @@ This page shows the parsed provenance for one attestation.
 
 ## See also
 
-- [SDK runtime reference](https://docs.kici.dev/user/sdk/runtime/) — the `ctx.attestProvenance` and
-  `ctx.kici.oidc.token` step APIs in full.
+- [Workload identity with OIDC](https://docs.kici.dev/user/oidc/) — minting the identity token
+  yourself and exchanging it with an external service.
+- [SDK runtime reference](https://docs.kici.dev/user/sdk/runtime/) — the `ctx.attestProvenance` step
+  API in full.
 - [CLI reference](https://docs.kici.dev/user/cli/notifications-and-diagnostics/#kici-verify-attestation) — every
   `kici verify-attestation` flag and exit code.
 
@@ -13664,7 +14026,7 @@ The KiCI CLI reads the following environment variables to customize its behavior
 
 | 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_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   |
 
@@ -14034,7 +14396,7 @@ The first two treat "no tier" as untrusted. The last two treat it as "no opinion
 
 A subscriber that inherits a tier below `trusted` loses its install secrets. A job that installs from a private registry then fails at install time.
 
-A `minimumTrust` context holds an `unknown` subscriber for security review, whatever value the context declares. Trust is a ref-based judgement with two answers, so `minimumTrust: 'trusted'` and the deprecated `minimumTrust: 'known'` block the same thing. The declared value still decides the wording of the hold reason. A subscriber that inherited the legacy `known` tier from a run row written by an earlier build passes both.
+A `minimumTrust: 'trusted'` context holds an `unknown` subscriber for security review. Trust is a ref-based judgement with two answers, so that is the only floor a context can declare.
 
 Both symptoms appear far from their cause. The tier belongs to the **emitting** run, so read that run's tier first.
 
@@ -14496,9 +14858,8 @@ Global workflows are gated by a **fleet-wide master switch** held by the orchest
 | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
 | Allowed author repos | Restricts which repos can **author** (register) global workflows. Globs matched against the authoring repo identifier. When OFF, any repo in the org may author globals.                             | Lock authoring to `myorg/ci-*` so random product repos can't ship org-wide automation. |
 | Blocked source repos | Blocks dispatch for events emitted from these **source** repos, regardless of authoring. Globs matched against the event source repo identifier. When OFF, events from any repo may trigger globals. | Protect against fork spam — e.g. `!myorg/*` via `myorg/fork-*`.                        |
-| Elevated access      | **Deprecated and not enforced.** Stored and echoed back, but nothing reads it — a global workflow's job receives no secrets, so there is no access for it to grant. See _Secrets are not available_. | None. Clear the list so it does not imply a grant that is not in force.                |
 
-All three lists accept globs. Leading `!` inside a single pattern is not supported here; negation is via the list-is-implicit-deny semantics, so keep it simple (`myorg/ci-*`, `myorg/platform-*`).
+Both lists accept globs. Leading `!` inside a single pattern is not supported here; negation is via the list-is-implicit-deny semantics, so keep it simple (`myorg/ci-*`, `myorg/platform-*`).
 
 Patterns match repo identifiers by the same rule as `repos:` on a trigger: an identifier is an owner/name pair, not a file path, so a leading dot carries no meaning of its own and a wildcard segment matches one. `myorg/*` covers `myorg/.github`, and `**` covers every repo in the org. Review any existing entry that relies on a wildcard to reach — or to spare — a dot-prefixed repo name.
 
@@ -14533,8 +14894,6 @@ This is about your **stored secrets**, not about repository access: the job is s
 
 To run something that needs secrets on a source repo's event, put those jobs in a per-repository workflow in that repo, where the workflow's `contexts:` resolve normally.
 
-The **Elevated access** setting reads as the way to lift this, and it is not: it is **deprecated and never consulted**. Nothing in the dispatch path reads the list, and adding a repo to it does not make any secret readable. It is kept only so an existing value stays visible and clearable, and is removed at the next major version — see [Deprecations](https://docs.kici.dev/user/deprecations/).
-
 ## When does it fire?
 
 Same-repo globals (a workflow in `myorg/app` with `repos: ['myorg/app']`) fire on pushes to `myorg/app`. Cross-repo globals fire on pushes to any source repo whose identifier matches a glob on the authoring workflow's trigger. The orchestrator de-duplicates between the per-repo and cross-repo matching passes, so a single event produces at most one run per (workflow, source-repo, trigger) triple.
@@ -14587,7 +14946,7 @@ A `filter` reads the source tree, so the evaluation must be able to obtain one.
 | Global workflow registered but never runs                                                       | Master toggle OFF, or allow-list blocks the authoring repo, or deny-list blocks the source repo                                                                                                                        | Orchestrator log: `Skipping global workflow dispatch` (dispatch time) / `Global workflows excluded from registration` (registration time)                                                                                                                                                                                                    |
 | A global workflow is never registered at all — it is absent from `kici-admin registration list` | The fleet-wide master switch is off, or the authoring repo does not match a populated _Allowed author repos_ list.                                                                                                     | Orchestrator log: `Global workflows excluded from registration`, naming the organization it decided against. Check the switch first (`kici-admin cluster-settings show`), then that org's allow-list in the dashboard. An `"orgId": "__default__"` in the line is not itself the fault — that anchor carries no lists and restricts nothing. |
 | `repos:` has no effect — workflow only fires on its own repo                                    | The fleet-wide master switch is off. Without it, the orchestrator treats the workflow as per-repo-only.                                                                                                                | Check the fleet-wide switch with `kici-admin cluster-settings show`. The dashboard → Settings → Global workflows tab shows it as a read-only badge.                                                                                                                                                                                          |
-| Secrets unavailable in a global job                                                             | Expected — a global workflow's job receives no secrets at all, and the _Elevated access_ list is not enforced.                                                                                                         | Move the jobs that need credentials into a per-repository workflow in the repo that owns the secrets                                                                                                                                                                                                                                         |
+| Secrets unavailable in a global job                                                             | Expected — a global workflow's job receives no secrets at all.                                                                                                                                                         | Move the jobs that need credentials into a per-repository workflow in the repo that owns the secrets                                                                                                                                                                                                                                         |
 | Dashboard shows workflow twice after registering                                                | Both a generic webhook source and a provider source (github, generic) re-registered the same repo.                                                                                                                     | Check `workflow_registrations` via `kici-admin workflow list` and confirm the right routing key owns the workflow.                                                                                                                                                                                                                           |
 | Global workflow registered, enabled, allowed — and still no run appears                         | Its `filter` returned `false`. A global filter runs before the run is created, so a suppressed workflow leaves nothing behind at all.                                                                                  | [Reading a global workflow's filter output](https://docs.kici.dev/user/global-workflows/#reading-a-global-workflows-filter-output) — the evaluation round's own log. The orchestrator also logs `Global workflow skipped by eval round`, naming the workflow and the reason.                                                                                                             |
 | Global workflow never fires for one particular source repo                                      | Its `repos:` patterns do not match that repo's identifier.                                                                                                                                                             | Orchestrator log: `Global workflows dropped by their repos filter` — one line per delivery, naming each dropped workflow, its repo and its patterns.                                                                                                                                                                                         |
@@ -14927,7 +15286,7 @@ Bind provisioning and teardown workflows to a context that carries the cloud cre
 
 ## The cloud-init that starts the agent
 
-`buildAgentCloudInit(creds, options)` renders the `#cloud-config` that boots the KiCI agent. In the claim-code form it writes the single-use claim code — never a token — into a root-only env file (`0600`, owned by root). The agent exchanges that code for its own token inside the instance, so the token never transits cloud-init, the instance metadata, or any other provisioning channel. The env file holds:
+`buildAgentCloudInit(creds, options)` renders the `#cloud-config` that boots the KiCI agent. It writes the single-use claim code — never a token — into a root-only env file (`0600`, owned by root). The agent exchanges that code for its own token inside the instance, so the token never transits cloud-init, the instance metadata, or any other provisioning channel. The env file holds:
 
 - `KICI_ORCHESTRATOR_URL` — from `creds.orchestratorUrl`.
 - `KICI_SCALER_CLAIM_CODE` — from `creds.claimCode`. The agent exchanges it for its own token in-instance.
@@ -14943,11 +15302,14 @@ The `0600` env file still protects the non-secret env from other users on the in
 
 Pass any of these options to shape the boot:
 
+- `agentImage` — the agent image `deliveryMode: 'container'` runs. Defaults to `quay.io/kici-dev/kici-agent:latest`.
+- `startCommand` — an escape hatch that replaces the whole agent-start command. It ignores `deliveryMode` and `agentImage`.
 - `packages` — extra apt/yum packages, merged into the cloud-init `packages:` list.
 - `writeFiles` — extra `write_files` entries (path, content, permissions, owner). The reserved env-file path is rejected, so a custom file cannot overwrite the credentials.
 - `runcmdBefore` / `runcmdAfter` — shell lines that run before or after the agent starts.
 - `agentEnv` — extra variables appended to the agent env file. Keys must be valid env names, and a value with a newline is rejected.
 - `baseCloudConfig` — a raw cloud-config document to merge everything into (users, ssh keys, apt mirrors, mounts, bootcmd). The builder unions its `packages`, `runcmd`, and `write_files` with yours.
+- `userDataEncoding` — `'raw'` (the default) returns the plain `#cloud-config` text that Hetzner `user_data` expects; `'base64'` returns it base64-encoded, the form AWS EC2 `UserData` and Azure `customData` expect.
 
 ## The teardown workflow
 
@@ -15118,7 +15480,7 @@ scalers:
 
 On `kici.scaler.scale-up`, the provisioning workflow dispatches a `kici-agent.yml` workflow run in a GitHub repo. It passes the claim code, orchestrator URL, agent id, and labels as dispatch inputs. The token never appears in those inputs — only the single-use claim code, which the agent exchanges for its own token in-instance.
 
-The `kici-agent.yml` run starts the agent on the runner itself with `KICI_SCALER_CLAIM_CODE` set. `KICI_SCALER_MANAGED=1` and a zero idle timeout make the agent register, run one job, and exit. The GitHub Actions run then completes on its own. By default the run installs the published agent from npm; set `agent_bundle_release` to a release tag holding a `kici-admin agent package` tarball to pin an exact build or to serve runners that cannot reach npm.
+The `kici-agent.yml` run starts the agent on the runner itself with `KICI_SCALER_CLAIM_CODE` set. `KICI_SCALER_MANAGED=1` and a zero idle timeout make the agent register, run one job, and exit. The GitHub Actions run then completes on its own. The job carries `timeout-minutes: 15`. A wedged run (an agent the orchestrator refused, a job that never dispatched) then releases the runner instead of holding it for the six-hour default. Raise the limit if your jobs run longer. By default the run installs the published agent from npm; set `agent_bundle_release` to a release tag holding a `kici-admin agent package` tarball to pin an exact build or to serve runners that cannot reach npm.
 
 Teardown is largely automatic. A GitHub Actions run self-completes when its agent exits. So the `kici.scaler.scale-down` workflow only cancels a run GitHub has not yet marked finished, and only for reasons where the agent will never do useful work (`spawn-timeout`, `heartbeat-timeout`).
 
@@ -15888,8 +16250,8 @@ kici-admin org-settings global-workflows deny-add \
 ```
 
 See [Global workflows](https://docs.kici.dev/architecture/global-workflows/) for the
-policy model (`isWorkflowRepoAllowed` + `isSourceRepoAllowed` +
-`isElevatedAccessAllowed`) and the cross-provider dispatch contract.
+policy model (`isWorkflowRepoAllowed` + `isSourceRepoAllowed`) and the
+cross-provider dispatch contract.
 
 ## Routing-key collisions
 
@@ -16340,7 +16702,7 @@ Orchestrator                         Agent                    Sandbox (child pro
     |                                  |                          |
     |-- job.dispatch (WS) ------------>|                          |
     |   (jobConfig, sourceTarUrl,      |                          |
-    |    sourceTarHash, depsUrl,       |-- Create sandbox ------->|
+    |    sourceTarDigest, depsUrl,     |-- Create sandbox ------->|
     |    depsHash)                     |   (container/bare-metal/ |
     |                                  |    firecracker)          |
     |                                  |                          |-- Restore .kici/ source (tarball)
@@ -16522,6 +16884,8 @@ Dep cache misses alone do **not** trigger a build job. Deps are platform-specifi
 
 When multiple webhooks trigger simultaneously for the same repository state, the `BuildCoordinator` coalesces concurrent build requests using a combined key (`contentHash:lockfileHash`). Only one build job runs; all waiting dispatches share the result.
 
+The coalescing map is per coordinator. The build job itself sits on the cluster-wide dispatch queue, so an agent connected to a sibling coordinator can claim it. That sibling persists the terminal `job.status` to the shared `execution_jobs` row (`precursor_result`), and the dispatching coordinator's `PendingPrecursorDbWatcher` reads the row back and settles the pending build through `settlePendingPrecursor()`. The local agent socket goes through the same function. See [runs that span coordinators](https://docs.kici.dev/operator/orchestrator/clustering/#runs-that-span-coordinators).
+
 ### Graceful degradation
 
 If cache storage is unavailable or a download fails:
@@ -16596,7 +16960,7 @@ Agent                         Orchestrator                    S3
   |                                |    for deps integrity)    |
 ```
 
-The two-phase metadata approach (`upload via PUT` then `initMeta via CopyObject`) works around the limitation that S3 pre-signed URLs cannot include custom metadata headers. For dependency tarballs, the agent also reports the SHA-256 content hash in `cache.upload.complete`; the orchestrator stores it as a companion `.hash` file alongside the tarball. When dispatching execution jobs, the orchestrator reads this hash and includes it as `depsHash` in `job.dispatch`, enabling agent-side integrity verification on download. Source tarballs do not use a companion `.hash` file — the workflow `contentHash` carried in `sourceTarHash` is used to verify the extracted source against the lock file after extraction, which covers drift end-to-end.
+The two-phase metadata approach (`upload via PUT` then `initMeta via CopyObject`) works around the limitation that S3 pre-signed URLs cannot include custom metadata headers. For dependency tarballs, the agent also reports the SHA-256 content hash in `cache.upload.complete`; the orchestrator stores it as a companion `.hash` file alongside the tarball. When dispatching execution jobs, the orchestrator reads this hash and includes it as `depsHash` in `job.dispatch`, enabling agent-side integrity verification on download. Source tarballs carry their own SHA-256 as `sourceTarDigest` in `job.dispatch`, verified before extraction; the workflow `contentHash` is then re-computed against the extracted source to verify it against the lock file, which covers drift end-to-end.
 
 ### URL delivery (downloads)
 
@@ -17095,7 +17459,7 @@ The compiler processes the workflow definition:
 
 When `kici run <event> --local` runs a workflow:
 
-1. **SDK module resolution:** The runner resolves `setStepOutputsMap` / `setJobOutputsMap` from the same `@kici-dev/sdk` module instance that the workflow uses (ensures the proxy reads from the same map)
+1. **SDK module resolution:** The runner resolves `setStepOutputsMap` / `setJobOutputsMap` from the `@kici-dev/sdk/internal` subpath of the same SDK copy that the workflow uses (ensures the proxy reads from the same map)
 2. **Map injection:** Fresh `OutputsMap` and `StepRefMap` are created and injected via `setStepOutputsMap()` / `setStepRefMap()` before each job
 3. **Step execution:** Each step runs sequentially. If the step returns a value, it is stored in the `OutputsMap` keyed by step name
 4. **Bare function normalization:** Bare functions in the steps array are assigned counter names and registered in the `StepRefMap` (maps function reference to step name)
@@ -17230,7 +17594,7 @@ The Platform never processes, stores, or executes customer code, and never sees
 
 The orchestrator is the execution brain. It decides what to run and dispatches work to agents.
 
-- **Trigger matching** -- Evaluates lock file triggers against webhook payloads to determine which jobs to run. Uses branch, path, and event matching via picomatch.
+- **Trigger matching** -- Evaluates lock file triggers against webhook payloads to determine which jobs to run. Uses glob-based branch, path, and event matching.
 - **Lock file caching** -- Fetches `kici.lock.json` via the configured source's fetcher (GitHub API, universal-git clone for generic webhook sources backed by a git URL, or the local filesystem for `file://` sources). An LRU cache wraps the per-provider fetcher, keyed by `{provider}:{repo}:{ref}` so cross-provider fallback resolutions stay isolated.
 - **Agent registry** -- Tracks connected agents with label-based routing for job dispatch.
 - **Job queue** -- PostgreSQL-backed FIFO queue for reliable dispatch.
@@ -17262,7 +17626,7 @@ The agent is the execution worker. It runs on customer infrastructure and has fu
 Shared business logic used by all three tiers. Single source of truth for cross-tier concerns. Has no internal `@kici-dev/*` dependencies -- only a handful of third-party libraries.
 
 - Protocol message schemas (Zod-based, direction-specific unions including dashboard REST-over-WS, browser live streaming, the test-relay control plane, log pull, run events, peer-to-peer, cluster join, and source registration)
-- Provider interfaces (WebhookNormalizer, LockFileFetcher, ChangedFilesFetcher, FileContentsFetcher, CloneTokenProvider, RepoUrlBuilder, CheckStatusPoster), plus the deprecated `ContributorResolver` the pipeline no longer calls
+- Provider interfaces (WebhookNormalizer, LockFileFetcher, ChangedFilesFetcher, FileContentsFetcher, CloneTokenProvider, RepoUrlBuilder, CheckStatusPoster)
 - Git credential vocabulary (forge names plus the credential reference, grant, request, and result shapes the SDK declares and the orchestrator's broker resolves) and the agent→orchestrator relay protocol its credential helper calls. See [Git credentials](https://docs.kici.dev/user/patterns/git-credentials/)
 - Trigger matching engine (branch, path, event evaluation)
 - Content-requirement matcher (the declarative `requires` filter -- pure data describing a query over the bytes of one source file at the event's ref, interpreted by the orchestrator via the `FileContentsFetcher` so no author code runs there) and the shared text-match vocabulary (`contains` / `notContains` / `matches` / `notMatches`) it shares with the commit-message trigger filter
@@ -17312,7 +17676,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). 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.
+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. It also owns the published docs host: `docsUrl()` builds every docs link a CLI prints or a template scaffolds from one `DOCS_SITE_URL` constant, so no other package spells the host. 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/`
 
@@ -17394,7 +17758,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)