@kici-dev/compiler 0.4.0 → 0.5.0

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

@@ -36,19 +36,19 @@ Your workflow is plain TypeScript, but different parts of it run at three distin
 
 ## The three phases
 
-| Phase            | Where it runs                            | What runs                                                                                                                                                     | When                      |
-| ---------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
-| **Compile**      | Your dev machine or CI (`kici compile`)  | Load your workflow modules, validate the DAG, assign step IDs, analyze dynamic-value purity, emit `kici.lock.json`                                            | Before anything is pushed |
-| **Orchestrator** | Your orchestrator (no repo clone)        | Match triggers against the lock, evaluate **pure** inline dynamic values in a sandboxed JavaScript VM, dispatch jobs                                          | On each incoming event    |
-| **Agent**        | An ephemeral agent (fresh clone per job) | Load the workflow module, evaluate job and step rules, run step bodies and hooks, run impure dynamic-value init jobs and `dynamicJob` generators (both forms) | After dispatch            |
+| Phase            | Where it runs                            | What runs                                                                                                                                               | When                      |
+| ---------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
+| **Compile**      | Your dev machine or CI (`kici compile`)  | Load your workflow modules, validate the DAG, assign step IDs, emit `kici.lock.json`                                                                    | Before anything is pushed |
+| **Orchestrator** | Your orchestrator (no repo clone)        | Match triggers against the lock and dispatch jobs; it never evaluates workflow code                                                                     | On each incoming event    |
+| **Agent**        | An ephemeral agent (fresh clone per job) | Load the workflow module, evaluate job and step rules, run step bodies and hooks, run dynamic-value init steps and `dynamicJob` generators (both forms) | After dispatch            |
 
 The lock file is the seam. Everything left of it is decided once at compile time and frozen into JSON; everything right of it reads that JSON. See [the lock file and workflow drift](https://docs.kici.dev/user/lock-file-and-drift/) and [the three-tier architecture](https://docs.kici.dev/architecture/overview/) for the wider picture.
 
 ## 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`, …), runs purity analysis over every dynamic-value function, and writes `kici.lock.json`.
+`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 (plus the serialized source of pure dynamic-value functions) 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 simply 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.
 
@@ -59,7 +59,7 @@ The lock is portable JSON. It carries:
 - Workflow and trigger metadata.
 - The job and step DAG, with compile-time step IDs.
 - Static values, verbatim.
-- The **source text** of pure dynamic-value functions, as inline expressions.
+- Markers noting which fields are dynamic, so the orchestrator knows to resolve them on the agent's init step.
 
 It does **not** carry:
 
@@ -72,11 +72,13 @@ The consequence is blunt: if a value isn't in the lock, the orchestrator can't s
 
 ## Orchestrator time
 
-On each event the orchestrator matches triggers using only the lock — it never clones your repository. Pure dynamic `context`, `env`, and `concurrencyGroup` functions are evaluated here, as inline expressions in a sandboxed JavaScript VM (~0ms overhead), instead of dispatching a separate job to resolve them.
+On each event the orchestrator matches triggers using only the lock — it never clones your repository and never evaluates workflow code. Dynamic `context`, `env`, and `concurrencyGroup` functions are not run here: the orchestrator dispatches a short init step to an agent to resolve them (see below).
 
-A runtime error in an inline expression fails the job immediately — there is no automatic fallback to the clone-and-evaluate path. The orchestrator does **not** run `dynamicJob` generator bodies itself: for the event-only (function) form it dispatches a dedicated dynamic-evaluation job to an agent at event time; the generator function then runs agent-side (see below).
+Trigger matching can query the **contents** of individual source files, not just their paths: a `pr()`, `push()`, or `tag()` trigger with a [`requires`](https://docs.kici.dev/user/sdk/triggers/#content-requirements-requires) filter is matched by reading the named files at the event's commit and evaluating the filter as declarative data — still with no repository clone and no workflow code executed. A `requires` regex is checked for catastrophic (ReDoS) shapes at `kici compile` time and rejected there, so only safe patterns reach the orchestrator.
 
-See [dynamic values](https://docs.kici.dev/user/dynamic-values/) for the exact rules that make a function pure or impure.
+The orchestrator also does **not** run `dynamicJob` generator bodies itself: for the event-only (function) form it dispatches a dedicated dynamic-evaluation job to an agent at event time; the generator function then runs agent-side (see below).
+
+See [dynamic values](https://docs.kici.dev/user/dynamic-values/) for how dynamic `context`, `env`, and `concurrencyGroup` functions resolve.
 
 ## Agent time
 
@@ -84,7 +86,7 @@ After dispatch, each job runs in its own ephemeral agent sandbox: a shallow clon
 
 1. **Job-level rules** are evaluated. By this point the agent has already spawned and the source has already been restored, so a job that its rules skip has **still** paid for that spawn and clone; only its steps are avoided.
 2. **Step-level rules**, then each step's `run()` body and its hooks.
-3. **Impure** dynamic values are resolved here too, via an init job that clones and evaluates the function (~5–10s) before the real job runs.
+3. **Dynamic values** (`context`, `env`, `concurrencyGroup` functions) are resolved here, via a short `__init__` job that runs the function before the real job runs; this shows in the run timeline as an `Init:` entry.
 4. **`dynamicJob` generators run here — both forms.** The event-only (function) form runs in a dedicated evaluation job dispatched at event time; the result-aware (options) form is deferred until its declared `needs` complete, then run with the upstream outputs frozen as `ctx.needs`.
 
 See [job execution](https://docs.kici.dev/architecture/execution/job-execution/) and [hooks and rules](https://docs.kici.dev/user/hooks/) for the details.
@@ -94,8 +96,7 @@ See [job execution](https://docs.kici.dev/architecture/execution/job-execution/)
 | Construct                    | Runs on          | When                            |
 | ---------------------------- | ---------------- | ------------------------------- |
 | Static value                 | Compile → lock   | Never re-evaluated              |
-| Pure dynamic value           | Orchestrator VM  | Per event                       |
-| Impure dynamic value         | Agent init job   | Per event                       |
+| Dynamic value                | Agent init step  | Per event                       |
 | Job-level rules              | Agent            | After clone                     |
 | Step-level rules             | Agent            | Per step                        |
 | `dynamicJob` (function form) | Agent (eval job) | Dispatched at event time        |
@@ -134,12 +135,11 @@ Outputs are typed across the job boundary too: reading `jobRef.result.…` or `c
 
 ## Common footguns
 
-| Symptom                                                                                                                        | Why                                                                                                                             | Fix                                                                                                                                      |
-| ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| A top-level `let seen = 0` (or a cache filled in job A) is empty in job B                                                      | Each job loads the workflow module fresh in its own agent process after its own clone — there is no shared memory between jobs  | Pass data through step/job **outputs** (`OutputProxy` / `needs`), not module variables                                                   |
-| `context: (event) => event.ref + SUFFIX`, where `SUFFIX` is a module constant, silently falls back to the slower init-job path | Purity analysis only allows the function's own params, locals, and a fixed safe-globals set — a free identifier makes it impure | Inline the constant, or accept the init-job path knowingly. See [pure functions](https://docs.kici.dev/user/dynamic-values/#pure-functions-inline-evaluation)   |
-| Fan-out job identities shift between re-evaluations                                                                            | `ctx.event` / `ctx.needs` are frozen and replayed, but `Date.now()` / `Math.random()` are not                                   | Derive job identity only from the frozen event/needs snapshot                                                                            |
-| A rule-skipped job still spawned an agent and cloned                                                                           | Job-level rules evaluate agent-side, after dispatch and clone — not on the orchestrator                                         | This is by design: rules can read true runtime context (`$`, `changedFiles`, `env`). See [step-level rules](https://docs.kici.dev/user/hooks/#step-level-rules) |
+| Symptom                                                                   | Why                                                                                                                            | Fix                                                                                                                                      |
+| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| A top-level `let seen = 0` (or a cache filled in job A) is empty in job B | Each job loads the workflow module fresh in its own agent process after its own clone — there is no shared memory between jobs | Pass data through step/job **outputs** (`OutputProxy` / `needs`), not module variables                                                   |
+| Fan-out job identities shift between re-evaluations                       | `ctx.event` / `ctx.needs` are frozen and replayed, but `Date.now()` / `Math.random()` are not                                  | Derive job identity only from the frozen event/needs snapshot                                                                            |
+| A rule-skipped job still spawned an agent and cloned                      | Job-level rules evaluate agent-side, after dispatch and clone — not on the orchestrator                                        | This is by design: rules can read true runtime context (`$`, `changedFiles`, `env`). See [step-level rules](https://docs.kici.dev/user/hooks/#step-level-rules) |
 
 ## See also
 
@@ -1080,12 +1080,16 @@ export default workflow('ci', {
 
 Rule check functions receive a `RuleContext` with:
 
-| Property       | Type                                | Description                         |
-| -------------- | ----------------------------------- | ----------------------------------- |
-| `event`        | `EventPayload`                      | The triggering event data           |
-| `changedFiles` | `string[]`                          | Files changed in this event         |
-| `env`          | `Record<string, string\|undefined>` | Environment variables               |
-| `$`            | zx shell                            | Shell executor for running commands |
+| Property       | Type                                | Description                                                                                    |
+| -------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `event`        | `EventPayload`                      | The triggering event data                                                                      |
+| `changedFiles` | `string[]`                          | Files changed in this event                                                                    |
+| `sourceRepo`   | `RepoInfo \| undefined`             | The repo whose event triggered the run, when the evaluation has a checkout                     |
+| `workflowRepo` | `RepoInfo \| undefined`             | The repo that registered the workflow. The same repo as `sourceRepo` outside a global workflow |
+| `env`          | `Record<string, string\|undefined>` | Environment variables                                                                          |
+| `$`            | zx shell                            | Shell executor for running commands                                                            |
+
+`RepoInfo` carries `path` — an absolute path to that repo's checkout — plus optional `ref` and `sha`. In a [global workflow](https://docs.kici.dev/user/global-workflows/) the two are different repos, which is what lets one rule read the source repo's tree while the workflow lives elsewhere. Read _through_ `path`: its contents are stable, but the path itself differs between the evaluation and the later run.
 
 ### Marker rules
 
@@ -2105,22 +2109,24 @@ function workflow(name: string, options: WorkflowOptions): Workflow;
 
 **Parameters:**
 
-| Parameter             | Type                                                                   | Required | Description                                                                                                                                                 |
-| --------------------- | ---------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `name`                | `string`                                                               | yes      | Unique workflow name                                                                                                                                        |
-| `options.jobs`        | `JobOrFactory[]`                                                       | yes      | Static jobs and/or dynamic job generators                                                                                                                   |
-| `options.on`          | `Trigger \| Trigger[]`                                                 | no       | When the workflow should trigger                                                                                                                            |
-| `options.rules`       | `Rule[]`                                                               | no       | Conditions that must pass for execution                                                                                                                     |
-| `options.description` | `string`                                                               | no       | Human-readable description                                                                                                                                  |
-| `options.hashFiles`   | `string[]`                                                             | no       | Extra repo-relative paths or globs mixed into the workflow content hash. Changes invalidate the source cache.                                               |
-| `options.registries`  | `Registry[]`                                                           | no       | Private npm registries the agent authenticates against before `npm install`. Each `tokenSecret` uses qualified `<context>:<secret>` syntax.                 |
-| `options.installEnv`  | `string[]`                                                             | no       | Qualified `<context>:<secret>` refs projected as env vars onto the install subprocess (used with a customer-committed `.kici/.npmrc`).                      |
-| `options.onCancel`    | `HookInput`                                                            | no       | Runs when the workflow is cancelled                                                                                                                         |
-| `options.cleanup`     | `HookInput`                                                            | no       | Always runs after the workflow (success, failure, or cancel)                                                                                                |
-| `options.onSuccess`   | `HookInput`                                                            | no       | Runs on workflow success                                                                                                                                    |
-| `options.onFailure`   | `HookInput`                                                            | no       | Runs on workflow failure                                                                                                                                    |
-| `options.concurrency` | `{ group: (ctx) => string; cancelInProgress?: boolean; max?: number }` | no       | Workflow-scoped concurrency. See [Concurrency](https://docs.kici.dev/user/concurrency/).                                                                                          |
-| `options.timeout`     | `number`                                                               | no       | Whole-run wall-clock timeout in milliseconds across all jobs. On breach the orchestrator cancels the run and marks it timed out. See [Timeouts](https://docs.kici.dev/user/sdk/core/#timeouts). |
+| Parameter             | Type                                                                   | Required | Description                                                                                                                                                                                                                                     |
+| --------------------- | ---------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`                | `string`                                                               | yes      | Unique workflow name                                                                                                                                                                                                                            |
+| `options.jobs`        | `JobOrFactory[]`                                                       | yes      | Static jobs and/or dynamic job generators                                                                                                                                                                                                       |
+| `options.on`          | `Trigger \| Trigger[]`                                                 | no       | When the workflow should trigger                                                                                                                                                                                                                |
+| `options.rules`       | `Rule[]`                                                               | no       | Conditions that must pass for execution                                                                                                                                                                                                         |
+| `options.filter`      | `FilterFn`                                                             | no       | Pre-dispatch predicate deciding whether the workflow applies to the event's source repo. A `false` result suppresses the workflow's jobs -- none is dispatched and none is reported as skipped. See [Global workflows](https://docs.kici.dev/user/global-workflows/). |
+| `options.description` | `string`                                                               | no       | Human-readable description                                                                                                                                                                                                                      |
+| `options.hashFiles`   | `string[]`                                                             | no       | Extra repo-relative paths or globs mixed into the workflow content hash. Changes invalidate the source cache.                                                                                                                                   |
+| `options.registries`  | `Registry[]`                                                           | no       | Private npm registries the agent authenticates against before `npm install`. Each `tokenSecret` uses qualified `<context>:<secret>` syntax.                                                                                                     |
+| `options.installEnv`  | `string[]`                                                             | no       | Qualified `<context>:<secret>` refs projected as env vars onto the install subprocess (used with a customer-committed `.kici/.npmrc`).                                                                                                          |
+| `options.onCancel`    | `HookInput`                                                            | no       | Runs when the workflow is cancelled                                                                                                                                                                                                             |
+| `options.cleanup`     | `HookInput`                                                            | no       | Always runs after the workflow (success, failure, or cancel)                                                                                                                                                                                    |
+| `options.onSuccess`   | `HookInput`                                                            | no       | Runs on workflow success                                                                                                                                                                                                                        |
+| `options.onFailure`   | `HookInput`                                                            | no       | Runs on workflow failure                                                                                                                                                                                                                        |
+| `options.concurrency` | `{ group: (ctx) => string; cancelInProgress?: boolean; max?: number }` | no       | Workflow-scoped concurrency. See [Concurrency](https://docs.kici.dev/user/concurrency/).                                                                                                                                                                              |
+| `options.timeout`     | `number`                                                               | no       | Whole-run wall-clock timeout in milliseconds across all jobs. On breach the orchestrator cancels the run and marks it timed out. See [Timeouts](https://docs.kici.dev/user/sdk/core/#timeouts).                                                                                     |
+| `options.approval`    | `ApprovalConfig`                                                       | no       | Pause for a manual human approval before the whole workflow dispatches. See [Approval gates](https://docs.kici.dev/user/approvals/).                                                                                                                                  |
 
 **Returns:** `Workflow` -- an immutable workflow definition.
 
@@ -2146,34 +2152,42 @@ function job(options: JobOptions): Job;
 
 **Parameters:**
 
-| Parameter                  | Type                                                                   | Required             | Description                                                                                                                                                                                                  |
-| -------------------------- | ---------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `name`                     | `string`                                                               | no                   | Job name (auto-generated UUID if omitted)                                                                                                                                                                    |
-| `options.runsOn`           | `RunsOn`                                                               | yes                  | Runner label(s) and optional exclusions (see below)                                                                                                                                                          |
-| `options.steps`            | `StepInput[]`                                                          | yes (or use `run`)   | Steps to execute in order. Mutually exclusive with `run`.                                                                                                                                                    |
-| `options.run`              | `(ctx) => Promise<unknown>`                                            | yes (or use `steps`) | Single-step shorthand -- see [Single-step job shorthand](https://docs.kici.dev/user/sdk/core/#single-step-job-shorthand). Mutually exclusive with `steps`.                                                                                       |
-| `options.needs`            | `NeedsEntry[]`                                                         | no                   | Job dependencies (must complete first) -- see [Job dependencies (`needs`)](https://docs.kici.dev/user/sdk/core/#job-dependencies-needs)                                                                                                          |
-| `options.rules`            | `Rule[]`                                                               | no                   | Conditions for conditional execution                                                                                                                                                                         |
-| `options.description`      | `string`                                                               | no                   | Human-readable description                                                                                                                                                                                   |
-| `options.matrix`           | `Matrix`                                                               | no                   | Matrix configuration for job expansion                                                                                                                                                                       |
-| `options.include`          | `MatrixInclude[]`                                                      | no                   | Additional matrix combinations                                                                                                                                                                               |
-| `options.exclude`          | `MatrixExclude[]`                                                      | no                   | Matrix combinations to remove                                                                                                                                                                                |
-| `options.checkout`         | `boolean`                                                              | no (default: `true`) | When `false`, agent skips git clone. Useful for deploy/notify jobs.                                                                                                                                          |
-| `options.container`        | `string \| ContainerConfig`                                            | no                   | Docker image for job execution. String form is the image name; object form adds `env`. All steps run inside the container.                                                                                   |
-| `options.sandbox`          | `{ capabilities?: string[]; network?: 'default' \| 'none' \| 'host' }` | no                   | Per-job container sandbox escape hatch (container jobs only). Request extra Linux capabilities / host networking; granted only within your operator's allow-list, else the run fails at dispatch. See below. |
-| `options.environment`      | `string \| ((event) => string \| Promise<string>)`                     | no                   | Deployment environment for this job. Static string or async/dynamic function -- see [Dynamic values](https://docs.kici.dev/user/dynamic-values/).                                                                                  |
-| `options.env`              | `Record<string, string> \| ((event) => Record<string, string>)`        | no                   | Environment variables. Static object or async/dynamic function -- see [Dynamic values](https://docs.kici.dev/user/dynamic-values/).                                                                                                |
-| `options.concurrencyGroup` | `string \| ((event) => string \| Promise<string>)`                     | no                   | Concurrency group name (defaults to environment name) -- see [Concurrency](https://docs.kici.dev/user/concurrency/).                                                                                                               |
-| `options.onCancel`         | `HookInput`                                                            | no                   | Hook that runs when the job is cancelled                                                                                                                                                                     |
-| `options.cleanup`          | `HookInput`                                                            | no                   | Hook that always runs after completion                                                                                                                                                                       |
-| `options.onSuccess`        | `HookInput`                                                            | no                   | Hook that runs when the job succeeds                                                                                                                                                                         |
-| `options.onFailure`        | `HookInput`                                                            | no                   | Hook that runs when the job fails                                                                                                                                                                            |
-| `options.beforeStep`       | `HookInput`                                                            | no                   | Hook that runs before each step                                                                                                                                                                              |
-| `options.afterStep`        | `HookInput`                                                            | no                   | Hook that runs after each step                                                                                                                                                                               |
-| `options.gracePeriod`      | `number`                                                               | no                   | Seconds before SIGKILL after SIGTERM during cancellation -- see [Hooks](https://docs.kici.dev/user/hooks/#hook-timeout).                                                                                                           |
-| `options.timeout`          | `number`                                                               | no                   | Total job wall-clock timeout in milliseconds (init + all steps + hooks). On breach the job is aborted and reported timed out. See [Timeouts](https://docs.kici.dev/user/sdk/core/#timeouts).                                                     |
-| `options.resources`        | `ResourceRequest`                                                      | no                   | Per-job CPU / memory request and limit. See [Per-job resources](https://docs.kici.dev/user/sdk/core/#per-job-resources) below.                                                                                                                   |
-| `options.init`             | `InitConfig`                                                           | no                   | Per-job initialization run after clone, before steps -- provisions a toolchain. A generic config, a typed preset (`'mise'` / `{ mise }`), `'auto'`, or `false`. See [Per-job init](https://docs.kici.dev/user/sdk/core/#per-job-init) below.     |
+| Parameter                      | Type                                                                             | Required              | Description                                                                                                                                                                                                  |
+| ------------------------------ | -------------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `name`                         | `string`                                                                         | no                    | Job name (auto-generated UUID if omitted)                                                                                                                                                                    |
+| `options.runsOn`               | `RunsOn`                                                                         | yes (or `runsOnAll`)  | Single-agent targeting -- runner label(s) and optional exclusions (see below). Mutually exclusive with `runsOnAll`.                                                                                          |
+| `options.runsOnAll`            | `RunsOnAllInput`                                                                 | yes (or `runsOn`)     | Host fan-out -- one pinned execution per roster host matching the predicate. Mutually exclusive with `runsOn`. See [runsOnAll host fan-out](https://docs.kici.dev/user/sdk/runs-on-all/).                                               |
+| `options.onUnreachable`        | `'skip' \| 'fail' \| 'hold'`                                                     | no (default: `hold`)  | Failure policy for unreachable durable hosts. `skip` omits them, `fail` fails the run, `hold` queues a pinned child and waits. Only meaningful alongside `runsOnAll`.                                        |
+| `options.includeUninitialized` | `boolean`                                                                        | no (default: `false`) | Widen a `runsOnAll` fan-out to declared-but-un-agented hosts -- a matching host with no live agent gets a temporary init-runner brought up over SSH. Only meaningful alongside `runsOnAll`.                  |
+| `options.steps`                | `StepInput[]`                                                                    | yes (or use `run`)    | Steps to execute in order. Mutually exclusive with `run`.                                                                                                                                                    |
+| `options.run`                  | `(ctx) => Promise<unknown>`                                                      | yes (or use `steps`)  | Single-step shorthand -- see [Single-step job shorthand](https://docs.kici.dev/user/sdk/core/#single-step-job-shorthand). Mutually exclusive with `steps`.                                                                                       |
+| `options.needs`                | `Array<Job \| string \| DynamicGroupRef \| { name; when? } \| { group; when? }>` | no                    | Job dependencies (must complete first) -- see [Job dependencies (`needs`)](https://docs.kici.dev/user/sdk/core/#job-dependencies-needs)                                                                                                          |
+| `options.rules`                | `Rule[]`                                                                         | no                    | Conditions for conditional execution                                                                                                                                                                         |
+| `options.description`          | `string`                                                                         | no                    | Human-readable description                                                                                                                                                                                   |
+| `options.matrix`               | `Matrix`                                                                         | no                    | Matrix configuration for job expansion                                                                                                                                                                       |
+| `options.include`              | `MatrixInclude[]`                                                                | no                    | Additional matrix combinations                                                                                                                                                                               |
+| `options.exclude`              | `MatrixExclude[]`                                                                | no                    | Matrix combinations to remove                                                                                                                                                                                |
+| `options.maxParallel`          | `number`                                                                         | no                    | Fan-out concurrency width -- the maximum number of fan-out children (matrix combinations or `runsOnAll` hosts) running at once. A sliding window; `1` is strictly serial. Must be `>= 1`.                    |
+| `options.failFast`             | `boolean`                                                                        | no (default: `false`) | Halt the fan-out on the first child failure: stop releasing new children and skip the ones still held. Applies to both matrix and `runsOnAll` fan-out.                                                       |
+| `options.checkout`             | `boolean`                                                                        | no (default: `true`)  | When `false`, agent skips git clone. Useful for deploy/notify jobs.                                                                                                                                          |
+| `options.container`            | `string \| ContainerConfig`                                                      | no                    | Docker image for job execution. String form is the image name; object form adds `env`. All steps run inside the container.                                                                                   |
+| `options.sandbox`              | `{ capabilities?: string[]; network?: 'default' \| 'none' \| 'host' }`           | no                    | Per-job container sandbox escape hatch (container jobs only). Request extra Linux capabilities / host networking; granted only within your operator's allow-list, else the run fails at dispatch. See below. |
+| `options.context`              | `string \| ((event) => string \| Promise<string>)`                               | no                    | Bound context for this job -- the secret / variable scope it resolves against. Static string or async/dynamic function -- see [Contexts](https://docs.kici.dev/user/contexts/) and [Dynamic values](https://docs.kici.dev/user/dynamic-values/).         |
+| `options.contexts`             | `(string \| ((event) => string \| Promise<string>))[]`                           | no                    | Bound contexts in merge order (later entries override earlier on name collisions). Mutually exclusive with `context`.                                                                                        |
+| `options.env`                  | `Record<string, string> \| ((event) => Record<string, string>)`                  | no                    | Environment variables. Static object or async/dynamic function -- see [Dynamic values](https://docs.kici.dev/user/dynamic-values/).                                                                                                |
+| `options.concurrencyGroup`     | `string \| ((event) => string \| Promise<string>)`                               | no                    | Concurrency group name. Defaults to the first bound context's name -- see [Concurrency](https://docs.kici.dev/user/concurrency/).                                                                                                  |
+| `options.onCancel`             | `HookInput`                                                                      | no                    | Hook that runs when the job is cancelled                                                                                                                                                                     |
+| `options.cleanup`              | `HookInput`                                                                      | no                    | Hook that always runs after completion                                                                                                                                                                       |
+| `options.onSuccess`            | `HookInput`                                                                      | no                    | Hook that runs when the job succeeds                                                                                                                                                                         |
+| `options.onFailure`            | `HookInput`                                                                      | no                    | Hook that runs when the job fails                                                                                                                                                                            |
+| `options.beforeStep`           | `HookInput`                                                                      | no                    | Hook that runs before each step                                                                                                                                                                              |
+| `options.afterStep`            | `HookInput`                                                                      | no                    | Hook that runs after each step                                                                                                                                                                               |
+| `options.gracePeriod`          | `number`                                                                         | no                    | Seconds before SIGKILL after SIGTERM during cancellation -- see [Hooks](https://docs.kici.dev/user/hooks/#hook-timeout).                                                                                                           |
+| `options.timeout`              | `number`                                                                         | no                    | Total job wall-clock timeout in milliseconds (init + all steps + hooks). On breach the job is aborted and reported timed out. See [Timeouts](https://docs.kici.dev/user/sdk/core/#timeouts).                                                     |
+| `options.resources`            | `ResourceRequest`                                                                | no                    | Per-job CPU / memory request and limit. See [Per-job resources](https://docs.kici.dev/user/sdk/core/#per-job-resources) below.                                                                                                                   |
+| `options.init`                 | `InitConfig`                                                                     | no                    | Per-job initialization run after clone, before steps -- provisions a toolchain. A generic config, a typed preset (`'mise'` / `{ mise }`), `'auto'`, or `false`. See [Per-job init](https://docs.kici.dev/user/sdk/core/#per-job-init) below.     |
+| `options.cache`                | `CacheInput`                                                                     | no                    | Declarative cache: restored before steps, saved after the job on a key miss. See [Caching](https://docs.kici.dev/user/sdk/caching/).                                                                                                    |
+| `options.approval`             | `ApprovalConfig`                                                                 | no                    | Pause for a manual human approval before this job dispatches. See [Approval gates](https://docs.kici.dev/user/approvals/).                                                                                                         |
 
 **Returns:** `Job` -- an immutable job definition.
 
@@ -3089,13 +3103,15 @@ type RuleCheckFn = (ctx: RuleContext) => Promise<boolean> | boolean;
 
 Can be sync or async. Receives a `RuleContext`:
 
-| Property             | Type                                      | Description                                                           |
-| -------------------- | ----------------------------------------- | --------------------------------------------------------------------- |
-| `event`              | `EventPayload`                            | The triggering event payload (discriminated union — narrow on `type`) |
-| `changedFiles`       | `string[]`                                | Files changed in this event (see availability note below)             |
-| `changedFilesStatus` | `'fetched' \| 'unavailable' \| 'skipped'` | Whether `changedFiles` is available                                   |
-| `env`                | `Record<string, string\|undefined>`       | Environment variables                                                 |
-| `$`                  | zx shell                                  | Shell executor for running commands                                   |
+| Property             | Type                                      | Description                                                             |
+| -------------------- | ----------------------------------------- | ----------------------------------------------------------------------- |
+| `event`              | `EventPayload`                            | The triggering event payload (discriminated union — narrow on `type`)   |
+| `changedFiles`       | `string[]`                                | Files changed in this event (see availability note below)               |
+| `changedFilesStatus` | `'fetched' \| 'unavailable' \| 'skipped'` | Whether `changedFiles` is available                                     |
+| `sourceRepo`         | `RepoInfo \| undefined`                   | Repo whose event triggered the run, when the evaluation has a checkout  |
+| `workflowRepo`       | `RepoInfo \| undefined`                   | Repo that registered the workflow (same repo outside a global workflow) |
+| `env`                | `Record<string, string\|undefined>`       | Environment variables                                                   |
+| `$`                  | zx shell                                  | Shell executor for running commands                                     |
 
 `changedFiles` is available on `push` and `pull_request` events — the agent computes the diff from its checkout, so no `paths:` trigger is required. It is `unavailable` for events with no diff (`schedule`, `tag`, `manual_schedule`), and in the rare case where the diff cannot be computed (e.g. a history deeper than the agent's bounded fetch). Reading `changedFiles` when it is unavailable throws and fails the job, so guard with `changedFilesStatus` first when a rule can run on such events:
 
@@ -3106,6 +3122,8 @@ rule('has source changes', (ctx) => {
 });
 ```
 
+The throw is a `ChangedFilesUnavailableError` (exported from `@kici-dev/sdk`, carrying the `changedFilesStatus` and `eventType` that produced it). `evaluateRules()` deliberately re-throws it rather than folding it into a `passed=false` skip, so a path-based gate fails loudly instead of silently mis-evaluating.
+
 ### evaluateRules(rules, context, label, onRuleResult?)
 
 Evaluate an array of rules sequentially with fail-fast behavior. Stops on the first failure.
@@ -3378,12 +3396,18 @@ type DynamicJobFn = (context: DynamicJobContext) => Promise<Job[]>;
 
 Receives a `DynamicJobContext`:
 
-| Property | Type                                | Description                 |
-| -------- | ----------------------------------- | --------------------------- |
-| `$`      | zx shell                            | Shell executor              |
-| `ctx`    | `{ workflow, event? }`              | Workflow metadata and event |
-| `log`    | `Logger`                            | Structured logger           |
-| `env`    | `Record<string, string\|undefined>` | Environment variables       |
+| Property       | Type                                | Description                                                             |
+| -------------- | ----------------------------------- | ----------------------------------------------------------------------- |
+| `$`            | zx shell                            | Shell executor                                                          |
+| `ctx`          | `{ workflow, event? }`              | Workflow metadata and event                                             |
+| `log`          | `Logger`                            | Structured logger                                                       |
+| `env`          | `Record<string, string\|undefined>` | Environment variables                                                   |
+| `sourceRepo`   | `RepoInfo \| undefined`             | Repo whose event triggered the run, when the evaluation has a checkout  |
+| `workflowRepo` | `RepoInfo \| undefined`             | Repo that registered the workflow (same repo outside a global workflow) |
+
+`RepoInfo` carries `path` — an absolute path to that repo's checkout — plus optional `ref` and `sha`; guard before reading either, since an event that carries no single ref leaves them undefined. In a [global workflow](https://docs.kici.dev/user/global-workflows/) `sourceRepo` and `workflowRepo` are different repos, so one generator can produce a different job set per source repo.
+
+**`sourceRepo.path` is not stable across calls.** A generator is invoked once to discover the job set and again to extract the step closures of the job being run; both see the same tree at the same commit, but not necessarily the same path or even the same machine. Read _through_ it, and derive job names from what the tree contains — never from the path itself, or the second call produces different names and the run fails the determinism check.
 
 ```typescript
 const discoverJobs: DynamicJobFn = async ({ $ }) => {
@@ -3576,6 +3600,182 @@ workflow runs rather than being silently dropped, and the delivery is recorded
 as degraded. GitHub always provides an exact list; a transient API error fails
 loudly, not as empty.
 
+### Content requirements (`requires`)
+
+Where `paths` filters on **which files changed**, `requires` filters on **what
+those files contain**. It is a declarative filter on the `pr()`, `push()`, and
+`tag()` triggers: a list of queries over the bytes of named source files, read
+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.
+
+Each entry is a `ContentRequirement`:
+
+```typescript
+interface ContentRequirement {
+  file: string; // repo-relative path to query
+  format?: 'auto' | 'json' | 'yaml' | 'text'; // how to parse the file (default: 'auto')
+  exists?: string[]; // JSONPath expressions that must each resolve to ≥1 node (json/yaml)
+  match?: Record<string, unknown>; // JSONPath → expected value; every one must match (json/yaml)
+  not?: Record<string, unknown>; // JSONPath → value; passes only when NONE match (json/yaml)
+  contains?: string | string[]; // literal substrings, all of which must appear (text only)
+  notContains?: string | string[]; // literal substrings, none of which may appear (text only)
+  matches?: string | RegExp | (string | RegExp)[]; // regexes, all of which must match (text only)
+  notMatches?: string | RegExp | (string | RegExp)[]; // regexes, none of which may match (text only)
+  ignoreCase?: boolean; // applies to contains/notContains only (default: false)
+  absent?: boolean; // passes only when the file does NOT exist
+}
+```
+
+**Format.** `format: 'auto'` (the default) picks the parser by extension:
+`.json` → JSON, `.yaml` / `.yml` → YAML, everything else → text. Set `format`
+explicitly to override — e.g. treat an extensionless file as JSON, or read a
+`.json` file as raw text. JSON and YAML both parse to an object, so the JSONPath
+keys (`exists` / `match` / `not`) work identically over either; `text` files are
+queried by `contains`, `notContains`, `matches`, and `notMatches` over the raw
+bytes.
+
+**Query keys.**
+
+- **`exists`** — an array of JSONPath expressions; each must resolve to at least
+  one node in the parsed document.
+- **`match`** — a JSONPath → expected-value map; every expression must match. An
+  expected value is an exact value, a regex string in `/pattern/flags` form
+  (against a string node), or an array of acceptable values (any one matches).
+- **`not`** — the same map shape, inverted: the entry passes only when **none** of
+  the expressions match.
+- **`contains` / `notContains`** — literal substrings tested against the raw file
+  text. Every entry must be present (`contains`) or absent (`notContains`). No
+  escaping needed (text format only).
+- **`matches`** — one or several regexes (a `RegExp` or `/pattern/flags` string),
+  each of which must match the raw file text (text format only).
+- **`notMatches`** — the inverse of `matches`: the entry passes only when none of
+  the regexes match (text format only).
+- **`ignoreCase`** — case-insensitive `contains` / `notContains` only; a regex
+  carries its own flags. Default false.
+- **`absent: true`** — passes only when the file does **not** exist at the event's
+  commit. It is mutually exclusive with the query keys above.
+- A bare `{ file }` with no query key requires the file to **exist**.
+
+The keys inside one entry are AND-ed, and the entries in a `requires` list are
+AND-ed with each other. An empty or absent `requires` matches everything, exactly
+like `paths`.
+
+**Examples:**
+
+```typescript
+// Only run CI when package.json declares a `ci` script.
+push({ branches: 'main', requires: [{ file: 'package.json', exists: ['$.scripts.ci'] }] });
+
+// Deploy only when the service config enables it (YAML, matched by value).
+push({
+  branches: 'main',
+  requires: [{ file: 'service.yaml', match: { '$.deploy.enabled': true } }],
+});
+
+// Only run when the Dockerfile builds from a Node base image (raw-text regex).
+pr({ requires: [{ file: 'Dockerfile', format: 'text', matches: '/^FROM node:/m' }] });
+
+// Skip the workflow whenever a repo carries an opt-out marker file.
+push({ requires: [{ file: '.skip-ci', absent: true }] });
+
+// Combine filters: a tag build that requires a version file AND forbids a draft flag.
+tag({
+  patterns: ['v*'],
+  requires: [
+    { file: 'VERSION', matches: '/^\\d+\\.\\d+\\.\\d+$/' },
+    { file: 'release.json', not: { '$.draft': true } },
+  ],
+});
+```
+
+**Fail-visible evaluation.** Files are read at the event's commit. If a
+referenced file is larger than **1 MiB**, or fails to parse for its format, the
+requirement is **indeterminate** — the candidate workflow is dropped and does
+**not** run. A `requires` that cannot be evaluated never silently passes.
+
+**Compile-time validation.** `kici compile` rejects a malformed requirement before
+it ever reaches the orchestrator: a raw-text key that is invalid or catastrophic
+(ReDoS-prone) is rejected by a safe-regex check; a text file cannot carry a
+JSON/YAML query key (`exists` / `match` / `not`) and a JSON/YAML file cannot carry a
+raw-text key; `absent` cannot be combined with a query key; and an explicit
+`format` with no query key is rejected as having nothing to check.
+
+### Commit-message filters (`commitMessage`)
+
+Where `requires` filters on what the repository's **files** contain,
+`commitMessage` filters on what the **event** says. It is a declarative filter on
+the `pr()`, `push()`, and `tag()` triggers. The orchestrator evaluates it
+directly from the webhook payload: no file is fetched, and no repository is
+cloned. For an organization-wide workflow it dispatches no evaluation job. It is
+the cheapest gate available.
+
+The text it tests is the **full head-commit message** — subject and body — for
+`push` and `tag`, and the **title plus body** for pull-request events.
+
+```typescript
+interface TextMatch {
+  contains?: string | string[]; // every needle must be present
+  notContains?: string | string[]; // no needle may be present
+  matches?: string | RegExp | (string | RegExp)[]; // every regex must match
+  notMatches?: string | RegExp | (string | RegExp)[]; // no regex may match
+  ignoreCase?: boolean; // applies to contains/notContains only (default: false)
+}
+```
+
+**Every entry in a list is a conjunct.** `contains: ['a', 'b']` passes only when
+the text contains both, and the keys AND together. To express OR, declare two
+triggers — a workflow's trigger list already matches on the first one that fits:
+
+```typescript
+// AND — one trigger.
+push({ commitMessage: { contains: ['release:', 'approved'] } });
+
+// OR — two triggers.
+on: [
+  push({ branches: 'main', commitMessage: { contains: 'deploy:' } }),
+  push({ branches: 'main', commitMessage: { contains: 'release:' } }),
+];
+```
+
+Needles are **literal substrings** — no glob, no regex, no escaping, so a needle
+containing `.*` matches only the literal `.*`. Use `matches` / `notMatches` for a
+pattern; both accept a `RegExp` literal, and the `m` flag reaches the body:
+
+```typescript
+// The single most common use: skip marker commits.
+push({ branches: 'main', commitMessage: { notContains: ['[skip ci]', '[ci skip]'] } });
+
+// Ignore dependency-bump noise across an organization.
+push({ commitMessage: { notMatches: /^chore\(deps\):/ } });
+
+// Require a conventional-commit prefix and forbid a WIP marker.
+pr({ target: 'main', commitMessage: { matches: /^(feat|fix)\(/, notContains: 'WIP' } });
+
+// Match a trailer in the commit body.
+push({ commitMessage: { matches: /^Fixes: #\d+$/m } });
+```
+
+`ignoreCase` affects `contains` and `notContains` only — a regex already carries
+its own flags, so write `/^feat:/i` rather than expecting `ignoreCase` to reach
+it.
+
+**Fail-visible evaluation.** Some events carry no message at all. A
+branch-deletion push has no head commit, and a self-hosted forge may publish
+none. The trigger then does **not** match, and the decision trace records it as
+`indeterminate` rather than as an exclusion. A `commitMessage` filter that cannot
+be evaluated never silently passes.
+
+**Compile-time validation.** `kici compile` rejects a malformed matcher. It
+refuses:
+
+- a matcher with no query key;
+- an `ignoreCase` that would affect nothing;
+- an empty needle list;
+- an empty-string needle (it would match every text);
+- a regex that is invalid or catastrophic (ReDoS-prone).
+
 ### tag()
 
 Create a tag trigger. Returns a frozen `TagTriggerConfig`.
@@ -5499,7 +5699,7 @@ When `--target` narrows a `runsOnAll` job to zero hosts, the run **fails** by de
 (a mistyped selector should be loud, not silently no-op). Pass `--target-allow-empty`
 to **skip** the zeroed job instead — it records a `skipped` status, and downstream jobs
 gated with `when: 'on-skip'` (or `when: 'always'`) still run, exactly as for an
-`onUnreachable: 'skip'` zero-host fan-out. See the [CLI reference](https://docs.kici.dev/user/cli-reference/#host-narrowing-with---target)
+`onUnreachable: 'skip'` zero-host fan-out. See the [CLI reference](https://docs.kici.dev/user/cli/runs-and-approvals/#host-narrowing-with---target)
 for the full flag behavior and the [`needs` gating model](https://docs.kici.dev/user/sdk/core/#job-dependencies-needs)
 for how a skipped upstream propagates.
 
@@ -5543,41 +5743,42 @@ All types are exported from `@kici-dev/sdk` as type-only imports.
 
 ### Trigger types
 
-| Type                            | Description                                                           |
-| ------------------------------- | --------------------------------------------------------------------- |
-| `Trigger`                       | Trigger definition (trigger config + source location)                 |
-| `TriggerConfig`                 | Union of all 23 trigger config types                                  |
-| `PrTriggerConfig`               | PR trigger configuration (from `pr()`)                                |
-| `PushTriggerConfig`             | Push trigger configuration (from `push()`)                            |
-| `TagTriggerConfig`              | Tag trigger configuration (from `tag()`)                              |
-| `CommentTriggerConfig`          | Comment trigger configuration (from `comment()`)                      |
-| `ReviewTriggerConfig`           | Review trigger configuration (from `review()`)                        |
-| `ReviewCommentTriggerConfig`    | Review comment trigger configuration (from `reviewComment()`)         |
-| `ReleaseTriggerConfig`          | Release trigger configuration (from `release()`)                      |
-| `DispatchTriggerConfig`         | Repository dispatch trigger configuration (from `dispatch()`)         |
-| `CreateTriggerConfig`           | Ref creation trigger configuration (from `create()`)                  |
-| `DeleteTriggerConfig`           | Ref deletion trigger configuration (from `delete()`)                  |
-| `StatusTriggerConfig`           | Commit status trigger configuration (from `status()`)                 |
-| `WorkflowRunTriggerConfig`      | Workflow run trigger configuration (from `workflowRun()`)             |
-| `ForkTriggerConfig`             | Fork trigger configuration (from `fork()`)                            |
-| `StarTriggerConfig`             | Star trigger configuration (from `star()`)                            |
-| `WatchTriggerConfig`            | Watch trigger configuration (from `watch()`)                          |
-| `WebhookTriggerConfig`          | Catch-all webhook trigger configuration (from `webhook()`)            |
-| `KiciEventTriggerConfig`        | Custom event trigger configuration (from `kiciEvent()`)               |
-| `WorkflowCompleteTriggerConfig` | Workflow completion trigger configuration (from `workflowComplete()`) |
-| `JobCompleteTriggerConfig`      | Job completion trigger configuration (from `jobComplete()`)           |
-| `GenericWebhookTriggerConfig`   | Generic webhook trigger configuration (from `genericWebhook()`)       |
-| `ScheduleTriggerConfig`         | Schedule trigger configuration (from `schedule()`)                    |
-| `LifecycleTriggerConfig`        | Lifecycle trigger configuration (from `lifecycle()`)                  |
-| `PrConfigInput`                 | Config object for `pr()` factory                                      |
-| `PushConfigInput`               | Config object for `push()` factory                                    |
-| `BranchPattern`                 | `{ type: 'glob', pattern } \| { type: 'regex', pattern, flags? }`     |
-| `PrEvent`                       | PR event string literal union (17 event types)                        |
-| `GenericWebhookConfigInput`     | Config object for `genericWebhook()` factory                          |
-| `GenericWebhookAuth`            | Union of generic webhook auth types (HMAC or API key)                 |
-| `GenericWebhookHmacAuth`        | HMAC-SHA256 auth configuration for generic webhooks                   |
-| `GenericWebhookApiKeyAuth`      | API key auth configuration for generic webhooks                       |
-| `GenericWebhookAuthMethod`      | Auth method string literal (`'hmac-sha256' \| 'api-key'`)             |
+| Type                                | Description                                                                    |
+| ----------------------------------- | ------------------------------------------------------------------------------ |
+| `Trigger`                           | Trigger definition (trigger config + source location)                          |
+| `TriggerConfig`                     | Union of all 23 trigger config types                                           |
+| `PrTriggerConfig`                   | PR trigger configuration (from `pr()`)                                         |
+| `PushTriggerConfig`                 | Push trigger configuration (from `push()`)                                     |
+| `TagTriggerConfig`                  | Tag trigger configuration (from `tag()`)                                       |
+| `CommentTriggerConfig`              | Comment trigger configuration (from `comment()`)                               |
+| `ReviewTriggerConfig`               | Review trigger configuration (from `review()`)                                 |
+| `ReviewCommentTriggerConfig`        | Review comment trigger configuration (from `reviewComment()`)                  |
+| `ReleaseTriggerConfig`              | Release trigger configuration (from `release()`)                               |
+| `DispatchTriggerConfig`             | Repository dispatch trigger configuration (from `dispatch()`)                  |
+| `CreateTriggerConfig`               | Ref creation trigger configuration (from `create()`)                           |
+| `DeleteTriggerConfig`               | Ref deletion trigger configuration (from `delete()`)                           |
+| `StatusTriggerConfig`               | Commit status trigger configuration (from `status()`)                          |
+| `WorkflowRunTriggerConfig`          | Workflow run trigger configuration (from `workflowRun()`)                      |
+| `ForkTriggerConfig`                 | Fork trigger configuration (from `fork()`)                                     |
+| `StarTriggerConfig`                 | Star trigger configuration (from `star()`)                                     |
+| `WatchTriggerConfig`                | Watch trigger configuration (from `watch()`)                                   |
+| `WebhookTriggerConfig`              | Catch-all webhook trigger configuration (from `webhook()`)                     |
+| `KiciEventTriggerConfig`            | Custom event trigger configuration (from `kiciEvent()`)                        |
+| `WorkflowCompleteTriggerConfig`     | Workflow completion trigger configuration (from `workflowComplete()`)          |
+| `WorkflowsFailedBatchTriggerConfig` | Batched workflow-failure trigger configuration (from `workflowsFailedBatch()`) |
+| `JobCompleteTriggerConfig`          | Job completion trigger configuration (from `jobComplete()`)                    |
+| `GenericWebhookTriggerConfig`       | Generic webhook trigger configuration (from `genericWebhook()`)                |
+| `ScheduleTriggerConfig`             | Schedule trigger configuration (from `schedule()`)                             |
+| `LifecycleTriggerConfig`            | Lifecycle trigger configuration (from `lifecycle()`)                           |
+| `PrConfigInput`                     | Config object for `pr()` factory                                               |
+| `PushConfigInput`                   | Config object for `push()` factory                                             |
+| `BranchPattern`                     | `{ type: 'glob', pattern } \| { type: 'regex', pattern, flags? }`              |
+| `PrEvent`                           | PR event string literal union (17 event types)                                 |
+| `GenericWebhookConfigInput`         | Config object for `genericWebhook()` factory                                   |
+| `GenericWebhookAuth`                | Union of generic webhook auth types (HMAC or API key)                          |
+| `GenericWebhookHmacAuth`            | HMAC-SHA256 auth configuration for generic webhooks                            |
+| `GenericWebhookApiKeyAuth`          | API key auth configuration for generic webhooks                                |
+| `GenericWebhookAuthMethod`          | Auth method string literal (`'hmac-sha256' \| 'api-key'`)                      |
 
 ### Rule types
 
@@ -7083,12 +7284,13 @@ companion at [Operator troubleshooting](https://docs.kici.dev/operator/troublesh
 
 ## Fast triage
 
-| You see...                                                     | Jump to                                                 |
-| -------------------------------------------------------------- | ------------------------------------------------------- |
-| A run finishes with `No jobs dispatched`                       | [No jobs dispatched](https://docs.kici.dev/user/common-failures/#no-jobs-dispatched)               |
-| A run fails complaining the lock file is stale or incompatible | [Lock-file drift](https://docs.kici.dev/user/common-failures/#lock-file-drift)                     |
-| You pushed but no run ever appears                             | [The webhook never arrives](https://docs.kici.dev/user/common-failures/#the-webhook-never-arrives) |
-| A run is stuck "queued" and no agent ever picks it up          | [The agent won't connect](https://docs.kici.dev/user/common-failures/#the-agent-wont-connect)      |
+| You see...                                                     | Jump to                                                                             |
+| -------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| A run finishes with `No jobs dispatched`                       | [No jobs dispatched](https://docs.kici.dev/user/common-failures/#no-jobs-dispatched)                                           |
+| A run fails complaining the lock file is stale or incompatible | [Lock-file drift](https://docs.kici.dev/user/common-failures/#lock-file-drift)                                                 |
+| You pushed but no run ever appears                             | [The webhook never arrives](https://docs.kici.dev/user/common-failures/#the-webhook-never-arrives)                             |
+| A run is stuck "queued" and no agent ever picks it up          | [The agent won't connect](https://docs.kici.dev/user/common-failures/#the-agent-wont-connect)                                  |
+| A `commitMessage`-gated workflow stops running for some events | [A `commitMessage` filter never evaluates](https://docs.kici.dev/user/common-failures/#a-commitmessage-filter-never-evaluates) |
 
 ## No jobs dispatched
 
@@ -7228,6 +7430,24 @@ the unpullable image) — hand this to your operator with the run's failure reas
 The full provisioning-failure playbook is in
 [Operator troubleshooting](https://docs.kici.dev/operator/troubleshooting/).
 
+## A `commitMessage` filter never evaluates
+
+**Symptom.** A workflow gated on a `commitMessage` trigger filter stops running
+for some events, even though the message looks like it should match.
+
+**Cause.** The event carries no commit message. A branch-deletion push has no
+head commit, and a self-hosted forge (Gogs, or a GitLab source) may publish none
+at the configured path. The filter is **fail-visible**: when it cannot read a
+message, the workflow does not run rather than running ungated.
+
+**Diagnose.** The decision trace records the `commitMessage` check with the
+verdict `indeterminate` and the reason `no commit message in payload`. That is
+distinct from an `excluded` verdict, which the message itself caused.
+
+**Fix.** For a self-hosted forge, set the source's `commitMessage` payload path so
+the orchestrator can read the head commit's message. A branch-deletion push
+genuinely carries no message and is expected not to match.
+
 ## When to escalate to your operator
 
 The failures above are ones you can resolve from your workflow repo and the
@@ -7521,6 +7741,7 @@ Each workflow entry includes:
 | `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:
@@ -10623,7 +10844,7 @@ group: () => 'deploy';
 group: (ctx) => `deploy-${ctx.event.targetBranch ?? 'default'}`;
 ```
 
-The workflow-level group function is always evaluated **agent-side** at runtime -- the lock file records only that a group function exists (`hasGroup: true`), not the function itself. The agent loads the workflow source, calls the group function with `{ branch, event }`, and reports the evaluated key back to the orchestrator before step execution begins. This differs from job-level `concurrencyGroup` (see [Contexts](https://docs.kici.dev/user/contexts/#concurrency-groups)), where the compiler performs purity analysis and can inline pure functions for orchestrator-side evaluation.
+The workflow-level group function is always evaluated **agent-side** at runtime -- the lock file records only that a group function exists (`hasGroup: true`), not the function itself. The agent loads the workflow source, calls the group function with `{ branch, event }`, and reports the evaluated key back to the orchestrator before step execution begins. Job-level `concurrencyGroup` functions (see [Contexts](https://docs.kici.dev/user/contexts/#concurrency-groups)) resolve the same way — on the agent's init step, never in the orchestrator.
 
 ## cancelInProgress mode
 
@@ -10860,7 +11081,7 @@ job('deploy-review', {
 });
 ```
 
-A pure function like the one above (see [Dynamic values](https://docs.kici.dev/user/dynamic-values/)) is evaluated inline at dispatch with no init-job overhead. Dynamic contexts that match a glob pattern (e.g., `review/*`) inherit the pattern's configuration, variables, and protection rules.
+A dynamic context function like the one above (see [Dynamic values](https://docs.kici.dev/user/dynamic-values/)) is resolved on the eval agent's init step before the job runs. Dynamic contexts that match a glob pattern (e.g., `review/*`) inherit the pattern's configuration, variables, and protection rules.
 
 ### Multiple contexts per job
 
@@ -11163,22 +11384,17 @@ job('deploy', {
 
 ## How it works
 
-When you define a dynamic value as a function, the compiler analyzes it at compile time to determine whether it is **pure** (can be evaluated without cloning the repo or running an init job).
+When you define a dynamic value as a function, it is resolved on the eval agent as a short **init** step that runs before the job:
 
-### Pure functions (inline evaluation)
+1. The orchestrator dispatches a lightweight `__init__` job to an agent.
+2. The agent loads the compiled workflow bundle and calls your function with the normalized event.
+3. The agent reports the resolved values back to the orchestrator, which dispatches the real execution job with them applied.
 
-A pure function is one that:
+This resolution appears in the run timeline as an `Init:` entry. The orchestrator never evaluates workflow code — every dynamic `context`, `env`, and `concurrencyGroup` function runs agent-side, whatever it references.
 
-- Is synchronous (no `async`/`await`)
-- Only references its parameters and local variables
-- Does not import or require external modules
-- Does not access globals like `process`, `fetch`, `console`, `setTimeout`, etc.
-- Uses only safe built-in constructors: `String`, `Number`, `Boolean`, `Array`, `Object`, `JSON`, `Math`, `parseInt`, `parseFloat`, `isNaN`, `isFinite`, `encodeURIComponent`, `decodeURIComponent`, `encodeURI`, `decodeURI`
-- Does not use `this`, `new`, `class`, `throw`, `try`/`catch`, `delete`, `var`, `yield`, or mutation operators (`++`, `--`, `+=`, etc.)
+`kici preview` lists the injected `__init__` job under each affected job, so you can spot it before the first run.
 
-When the compiler detects a pure function, it serializes the function source directly into the lock file as an inline expression. At dispatch time, the orchestrator evaluates the expression in a sandboxed VM context (~0ms overhead) instead of dispatching an init job.
-
-**Examples of pure functions:**
+**Examples:**
 
 ```typescript
 // Simple branch extraction
@@ -11190,65 +11406,32 @@ env: (event) => ({ BRANCH: event.targetBranch });
 // Concatenation with event data
 concurrencyGroup: (event) => `deploy-${event.targetBranch}`;
 
-// Using safe globals
-env: (event) => ({ UPPER: String(event.targetBranch).toUpperCase() });
-
-// Local variables are fine
+// Local variables and safe globals
 context: (event) => {
   const parts = event.targetBranch.split('/');
   return parts[parts.length - 1];
 };
-```
-
-### Impure functions (init-job evaluation)
-
-If the compiler determines a function is impure, it prints a `warning [W101]` naming the affected field (`context`, `env`, or `concurrencyGroup`), the reason the function was judged impure, and the ~5-10 second init-job cost — and compilation still succeeds. The function falls back to the two-phase init model. This means:
 
-1. The orchestrator dispatches a special `__init__` job to a builder agent
-2. The builder agent clones the repository and evaluates the function
-3. The resolved values are sent back to the orchestrator
-4. The orchestrator dispatches the real execution job with the resolved values
-
-This adds approximately 5-10 seconds of overhead for cloning and evaluation.
-
-`kici preview` lists the injected `__init__` job under each affected job, so you can spot the init-job cost before the first run.
-
-**Examples of impure functions (will use init job):**
-
-```typescript
-// Async functions cannot be inlined
+// Async lookups, module access, and process/global reads all work
 context: async (event) => await lookupEnv(event.targetBranch);
-
-// External module references
-env: (event) => {
-  const config = require('./config');
-  return config.env;
-};
-
-// Process/global access
-context: (event) => process.env.DEFAULT_ENV || 'staging';
-
-// Dynamic imports
-env: async (event) => {
-  const m = await import('./config.js');
-  return m.default;
-};
+env: (event) => ({ DEFAULT_ENV: process.env.DEFAULT_ENV ?? 'staging' });
 ```
 
-## Performance comparison
+## Performance
 
-| Evaluation path                      | Overhead | When used                                                       |
-| ------------------------------------ | -------- | --------------------------------------------------------------- |
-| Static value (string/object literal) | ~0ms     | `context: 'staging'`                                            |
-| Inline expression (pure function)    | ~0ms     | `context: (event) => event.targetBranch`                        |
-| Init job (impure function)           | ~5-10s   | `context: async (event) => await lookupEnv(event.targetBranch)` |
+| Value                    | Overhead  | Example                                  |
+| ------------------------ | --------- | ---------------------------------------- |
+| Static value             | None      | `context: 'staging'`                     |
+| Dynamic value (function) | Init step | `context: (event) => event.targetBranch` |
+
+A static value is baked into the lock file and needs no init step. A dynamic value always resolves through the agent's init step, so reach for a function only when the value genuinely depends on the event.
 
 ## Tips
 
-- **Write pure functions whenever possible** to avoid the init-job delay. Most context and env computations only need the event payload data.
-- **Check compiler warnings** -- the compiler prints a `warning [W101]` when a function is classified as impure, naming the reason and the ~5-10s init-job cost. Run `kici preview` to see the injected `__init__` job listed under each affected job before your first run.
-- **Runtime errors in inline expressions cause immediate job failure.** There is no fallback to the init-job path. If your pure function throws at runtime (e.g., accessing a property on `undefined`), the job fails immediately.
-- **See [how your workflow code executes](https://docs.kici.dev/user/execution-model/)** for the full picture of where pure vs. impure functions run relative to rules, hooks, and step bodies.
+- **Prefer static values when you can.** Most context and env values are the same on every event; only make them dynamic when they truly depend on the event payload.
+- **Run `kici preview`** to see the injected `__init__` job listed under each affected job before your first run.
+- **A runtime error in a dynamic function fails the job.** If your function throws when the init step runs it (e.g., accessing a property on `undefined`), the job fails immediately.
+- **See [how your workflow code executes](https://docs.kici.dev/user/execution-model/)** for the full picture of where dynamic values run relative to rules, hooks, and step bodies.
 - **The event parameter is the normalized event envelope** — the same shape rules receive as `ctx.event`: `{ type, action, targetBranch, sourceBranch, changedFiles, payload, … }` (see the [event payload reference](https://docs.kici.dev/user/sdk/event-payloads/) for the complete schema). Narrow on `event.type` (`'push'`, `'pull_request'`, `'tag'`, …) to branch per trigger kind. The raw provider webhook body is nested at `event.payload` (for GitHub pushes: `payload.ref`, `payload.after`, `payload.repository`, …).
 
 ---
@@ -11785,35 +11968,151 @@ export default workflow('org-lint', {
 });
 ```
 
-Patterns in `repos:` use the same globbing as `branches:` / `paths:` — plain globs (`myorg/*`), a leading `!` for exclusions (`!myorg/fork-*`), and a fully-qualified `owner/repo` identity for exact matches (`myorg/platform`). A bare `**` matches every repo in the org.
+Patterns in `repos:` use the same globbing as `branches:` / `paths:` — plain globs (`myorg/*`), a leading `!` for exclusions (`!myorg/fork-*`), and a fully-qualified `owner/repo` identity for exact matches (`myorg/platform`). A bare `**` matches every repo in the org, including one whose identifier starts with a dot (`.github/workflows-config`) — a repo identifier is an owner/name pair, not a file path, so a leading dot carries no meaning of its own. Path globs in `paths:` keep the usual convention and do not match dot-prefixed files unless the pattern spells the dot out.
 
 ### At a dual-repo checkout
 
-The agent receives two sets of context during a global workflow execution:
+The agent checks out both repos. **Inside a step body**, `env` carries a pointer to each working tree:
 
 | `env` var                 | Points to                                                                                                                                    |
 | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
 | `KICI_SOURCE_REPO_PATH`   | The **source** repo's working tree (the repo that emitted the event). This is the repo the job's `$` / `git` commands operate on by default. |
 | `KICI_WORKFLOW_REPO_PATH` | The **workflow** repo's working tree (the repo that authored the workflow). Useful for reading shared scripts or config from your CI repo.   |
 
-Source repo secrets are **not** available to a global workflow's job by default — see _Elevated access_ below.
+Both variables are step-body context. They are **not** projected into the job's process environment, so a job-level `env:` block, a container image's entrypoint, or a shell command outside a step body will not see them. Outside a step body, use the `sourceRepo` / `workflowRepo` pair on the filter, generator, and rule contexts described below.
+
+They are also set **only when there are two repos to point at**. An event from the workflow's own repo is matched from that repo's lock file rather than as a global candidate, so the workflow runs as an ordinary single-repo workflow: one checkout, and neither variable set. Read them with a fallback, as the example above does.
+
+A global workflow's job runs with **no secrets at all** — neither the source repo's nor its own. See _Secrets are not available_ below.
+
+### The triggering event
+
+`ctx.event` inside a global workflow's job is the **source** repo's normalized event — the push or PR that fired the workflow, from a repo the workflow's own author may not own. `ctx.event.sourceRepo` names that repo.
+
+That field is what makes a per-source-repo concurrency group expressible — and you have to write it. A global workflow runs on events from many repos, and their default branches share a name, so a group keyed on the branch alone puts every repo in one group, and with `cancelInProgress` (the default) one repo's push cancels another repo's in-flight run. That is still the behaviour of a branch-only group; naming the source repo in the key is what separates them:
+
+```ts
+concurrency: {
+  group: ({ branch, event }) => `${event.sourceRepo}:${branch}`,
+  cancelInProgress: true,
+},
+```
+
+### Narrowing to the repos that need it
+
+A global workflow that matches `myorg/*` will, by default, run on every repo in the org. Three mechanisms narrow it to the repos it actually applies to, in increasing order of power:
+
+1. **A `requires` content filter on the trigger** — the cheapest gate. The orchestrator checks a file's contents (a JSON-path probe over `package.json`, for example) and drops the workflow **before any agent is dispatched** when the condition is not met. See [`requires` on triggers](https://docs.kici.dev/user/sdk/triggers/#content-requirements-requires). This is provider-dependent — it needs a file-contents fetcher, which the GitHub provider supplies.
+2. **A workflow-level `filter` predicate** — arbitrary TypeScript over the checked-out source tree (below). Works with any provider that clones.
+3. **A `DynamicJobFn`** — generate the exact job set from the source repo's state ([Generating jobs per source repo](https://docs.kici.dev/user/global-workflows/#generating-jobs-per-source-repo) below).
+
+### Narrowing with a filter
+
+Before reaching for a `filter`, check whether a declarative filter answers the question. `commitMessage` (on the trigger) and `requires` (over source files) are evaluated by the orchestrator from data it already has, so they cost no evaluation job at all — while a `filter` predicate dispatches one per (event × workflow repo). Gating on a `[skip ci]` marker, a conventional-commit prefix, or the contents of a named config file needs no predicate.
+
+A workflow can declare a `filter`: a predicate that decides whether the workflow applies to this event at all.
+
+```ts
+import { workflow, job, step, push } from '@kici-dev/sdk';
+
+export default workflow('org-container-lint', {
+  on: [push({ repos: ['myorg/*'] })],
+  filter: async ({ sourceRepo, changedFilesStatus, $ }) => {
+    // `changedFiles` throws when the diff is unavailable, so guard first.
+    if (changedFilesStatus !== 'fetched') return true;
+    const found = await $`ls ${sourceRepo.path}`;
+    return found.stdout.includes('Dockerfile');
+  },
+  jobs: [
+    job('lint-dockerfile', {
+      runsOn: ['kici:os:linux'],
+      steps: [
+        step('lint', async ({ $, env }) => $`hadolint ${env.KICI_SOURCE_REPO_PATH}/Dockerfile`),
+      ],
+    }),
+  ],
+});
+```
+
+The filter receives a `FilterContext`:
+
+| Property             | Type                                      | Description                                                                                |
+| -------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `sourceRepo`         | `RepoInfo`                                | The repo whose event triggered this evaluation, checked out on the evaluating agent.       |
+| `workflowRepo`       | `RepoInfo`                                | The repo that registered the workflow. Identical to `sourceRepo` for a same-repo workflow. |
+| `event`              | `EventPayload`                            | The normalized event envelope.                                                             |
+| `changedFiles`       | `string[]`                                | Files changed in this event. Throws when unavailable — guard with `changedFilesStatus`.    |
+| `changedFilesStatus` | `'fetched' \| 'unavailable' \| 'skipped'` | Whether `changedFiles` can be read.                                                        |
+| `env`                | `Record<string, string\|undefined>`       | Environment variables.                                                                     |
+| `$`                  | zx shell                                  | Shell executor.                                                                            |
+
+`RepoInfo` carries `path` (an absolute path to the checkout on the evaluating agent) plus optional `ref` and `sha`. **Both are optional** — an event that carries no single ref leaves them undefined, so guard before reading them.
+
+**`sourceRepo.path` is not stable across evaluations.** Its _contents_ are: the evaluating agent and the later run see the same tree at the same commit. The path itself is not — a different working directory, and possibly a different machine. Read _through_ it; never embed it in a job name, an output, or anything compared across calls.
+
+**A `filter` must be pure and deterministic.** Decide from the context alone — the event, the changed files, and the checked-out tree — so the same event always yields the same verdict.
+
+### Global and same-repo filters differ
+
+The same `filter` keyword means two different things depending on whether the workflow is global:
+
+|                                | Global workflow (`repos:` on a trigger)          | Same-repo workflow                                                        |
+| ------------------------------ | ------------------------------------------------ | ------------------------------------------------------------------------- |
+| Evaluated                      | once per (event × workflow repo)                 | once per job that reaches dispatch, and once per job generator            |
+| Evaluated relative to the run  | **before** any run row exists                    | **after** the run row exists                                              |
+| A `false` verdict leaves       | no run at all — nothing appears in the dashboard | a run whose only entries are the evaluation jobs, rolling up to `success` |
+| `sourceRepo` vs `workflowRepo` | two different repos                              | the same repo                                                             |
+
+Two consequences of the same-repo shape are worth designing for. A workflow with ten jobs calls its filter ten times for one event — each on its own agent with its own checkout and its own `$` — so anything the predicate does happens that many times: keep it cheap and side-effect free. And if the predicate can answer differently for the same event, the workflow will _partially_ dispatch, running some jobs and not others.
+
+**A held or rejected job is not filtered at all.** A job held for approval, or rejected by a context rule, already has a gate — the hold or the rule — so it never takes a filter verdict, and an approved job dispatches without one. Concretely: a path filter cannot stop an approval request for a job the change does not concern.
+
+### Generating jobs per source repo
+
+A global workflow's job generators run in the same pre-run evaluation as the filter, with both repos on disk. `sourceRepo` and `workflowRepo` are on the generator context, so one workflow repo can produce a different job set per source repo:
+
+```ts
+import { job, step, workflow, push, type DynamicJobFn } from '@kici-dev/sdk';
+import { readFile } from 'node:fs/promises';
+
+const perRepoJobs: DynamicJobFn = async ({ sourceRepo }) => {
+  if (!sourceRepo) return [];
+  const pkg = JSON.parse(await readFile(`${sourceRepo.path}/package.json`, 'utf8'));
+  return Object.keys(pkg.scripts ?? {})
+    .filter((s) => s.startsWith('ci:'))
+    .map((s) =>
+      job(s.replace(':', '-'), {
+        runsOn: ['kici:os:linux'],
+        steps: [step('run', async ({ $ }) => $`pnpm ${s}`)],
+      }),
+    );
+};
+
+export default workflow('org-ci', {
+  on: [push({ repos: ['myorg/*'] })],
+  jobs: [perRepoJobs],
+});
+```
+
+The same `sourceRepo.path` caution applies: read the tree through it, and derive job names from the repo's _contents_, never from the path.
 
 ## Enabling global workflows
 
-Global workflows are **opt-in per org**. In a fresh org, `repos:`-bearing workflows are registered but never dispatched.
+Global workflows are gated by a **fleet-wide master switch** held by the orchestrator operator, off by default. Until it is on, `repos:`-bearing workflows are registered but never dispatched.
 
-1. Open the dashboard → **Settings → Global workflows**.
-2. Turn on **Enable global workflows** (the master toggle). This is the kill-switch — every other toggle below is ignored while this is off.
-3. Decide which authoring/source controls you need:
+1. **The operator enables it cluster-wide** with `kici-admin cluster-settings set --global-workflows-enabled true`. This is the kill-switch — every per-org control below is ignored while it is off, and it cannot be flipped from the dashboard. The dashboard's **Settings → Global workflows** tab shows its current state as a read-only badge.
+2. In the dashboard → **Settings → Global workflows**, decide which authoring/source controls you need. These per-org lists stay dashboard-editable; an org that has set none means "no per-org restrictions", not a denial.
 
-| Setting              | What it controls                                                                                                                                                                                     | Typical use                                                                                  |
-| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| 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      | Authoring repos listed here get **read access to source-repo secrets** during execution. Globs matched against the authoring repo identifier.                                                        | A `myorg/ci-deploy` repo that needs to read a source repo's `NPM_TOKEN` to publish releases. |
+| Setting              | What it controls                                                                                                                                                                                     | Typical use                                                                            |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| 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-*`).
 
+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.
+
 ### Saving and reverting
 
 The page is a two-state editor — changes are local until you click **Save changes**, and you can abandon them with **Discard changes**. There is no partial save; the PATCH is all-or-nothing per save click.
@@ -11825,17 +12124,23 @@ The page is a two-state editor — changes are local until you click **Save chan
 A global workflow fires only if:
 
 1. **The authoring repo is allowed.** If _Allowed author repos_ is ON, the workflow's authoring repo must match at least one allow-list glob. If OFF, any repo may author. Enforced at two points:
-   - At registration time (extraction from the lock file — non-matching globals are dropped with a warning).
+   - At registration time (extraction from the lock file — non-matching globals are dropped, and the orchestrator logs `Global workflows excluded from registration` naming each one).
    - At dispatch time (defense-in-depth — policy changes after registration still take effect).
 2. **The source repo is not denied.** If the event's source repo matches any glob in _Blocked source repos_, the global workflow is skipped. Enforced at dispatch time.
 
-Both checks are logged to the orchestrator. Grep the logs for `Skipping global workflow` to see enforcement in action.
+Both checks are logged to the orchestrator. Grep for `Global workflows excluded from registration` (registration time) and `Skipping global workflow dispatch` (dispatch time) to see enforcement in action.
+
+Both checks read the settings of the organization the **event's source** resolves to. If no webhook source maps the event's routing key to an organization, the orchestrator resolves the built-in `__default__` organization anchor instead — and since nobody has enabled global workflows for that anchor, every global workflow is refused. The registration log line carries the organization it decided against plus the remedy, so this case is distinguishable from a real opt-in that is simply switched off. See the troubleshooting table below.
+
+### Secrets are not available
 
-### Elevated access (source-repo secrets)
+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.
 
-By default a global workflow's job runs with credentials scoped to the **workflow** repo — it can clone both repos but cannot read the source repo's scoped secrets. That's the safe default: a random workflow in `myorg/ci-pipelines` does not get read access to secrets in `myorg/backend` just because it runs on a push there.
+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.
 
-Adding the authoring repo to the _Elevated access_ list flips that: the job receives the source repo's secret context, so deploy and release flows that need `NPM_TOKEN` / `AWS_ROLE_ARN` / etc. from the source repo can read them. Treat elevated repos as effective owners of every source repo's CI secrets — only add repos you fully trust.
+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?
 
@@ -11843,14 +12148,111 @@ Same-repo globals (a workflow in `myorg/app` with `repos: ['myorg/app']`) fire o
 
 Non-push triggers work too — `pr()`, `tag()`, `comment()`, `release()`, `workflowRun()`, etc. all accept `repos:`. `kiciEvent()` / `schedule()` / cron-like triggers have no source repo, so they're always per-org-registered regardless of `repos:`.
 
+A global workflow that declares a `filter` or a job generator is decided by one **evaluation job per (event × workflow repo)**, dispatched before any run exists. That job checks out both repos once and evaluates every candidate workflow from that repo, so ten global workflows in one CI repo cost one evaluation, not ten.
+
+When that evaluation cannot reach a verdict — it fails, breaches its budget, or never reports — the workflows it was deciding on **do not run**. On a provider that supports commit checks, that posts a `failure` check named **`KiCI: Organization workflow evaluation`** on the source commit, so the outcome is visible instead of silent. Three things to know about it:
+
+- The check is posted whether the evaluation failed **outright** or only **partly**. A per-workflow budget breach, or a `filter` that throws, leaves that one workflow undecided while its neighbours from the same repo are decided and run normally; the check then names only the undecided ones. So a broken `filter` is reported the same way whether or not other global workflows happen to share its repo.
+- Branch protection that lists required checks by name is unaffected, because the check is not on that list. Merge automation that requires _every_ check to be green will block on it.
+- **The check clears only on a new commit.** A provider redelivery of the same event is dropped as a duplicate, so re-delivering the webhook will not re-run the evaluation.
+
+## Approval gates are not supported
+
+A global workflow cannot carry an `approval` gate, at the workflow level or on a job. Approval holds are applied by the per-repository dispatch path; the global path dispatches its jobs without consulting one, so a gate declared here would never be enforced. `kici compile` refuses it with `error [E124]` rather than accepting a security control the workflow does not actually have. A job produced by a `dynamicJob` generator never passes through the compiler, so that case is caught at dispatch instead — the orchestrator logs an error naming the workflow and job, and runs it ungated.
+
+To gate a deployment behind a human, put the gated jobs in a workflow whose triggers carry no `repos:`.
+
+## Re-running is not supported
+
+A global workflow's run cannot be re-run. The rerun path resolves a workflow out of the repo the run acted on, and for a global workflow that is the **source** repo — not the workflow repo that declares it. Re-running is refused with an error naming both repos rather than resolving the wrong one, which for a source repo carrying a same-named workflow would silently run that workflow instead, with the source repo's credentials and none of the global job configuration.
+
+To run it again, push a new commit to the source repo (a provider redelivery of the same event is dropped as a duplicate), or trigger it from the workflow repo.
+
+## Requirements a filter places on the run
+
+A `filter` reads the source tree, so the evaluation must be able to obtain one. A job that restores its workflow source from the cache and has no source repository to clone from fails with an explicit error rather than evaluating the filter against an empty tree. This applies to dispatch paths that run without a source repository configured — a filter and such a path are mutually exclusive; drop one or the other.
+
 ## Troubleshooting
 
-| Symptom                                                      | Likely cause                                                                                       | Where to look                                                                                                      |
-| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| 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` / `Skipping global workflow registration: not permitted`     |
-| `repos:` has no effect — workflow only fires on its own repo | Master toggle OFF. Without opt-in, the orchestrator treats the workflow as per-repo-only.          | Dashboard → Settings → Global workflows (top toggle)                                                               |
-| Source repo secrets unavailable in a global job              | Expected default — elevate the authoring repo to grant access.                                     | Dashboard → Settings → Global workflows → _Elevated access_                                                        |
-| 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. |
+| Symptom                                                                                         | Likely cause                                                                                                                                                                                                           | Where to look                                                                                                                                                                                                                                                                                                                                        |
+| ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 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 push that should have registered it resolved to the `__default__` organization anchor, because no webhook source maps its routing key to an organization, or the fleet-wide master switch is off.                  | Orchestrator log: `Global workflows excluded from registration` with `"orgId": "__default__"`. Its `remedy` field names both fixes — map the source (`kici-admin source update <routingKey> --customer-id <org>`) and enable global workflows cluster-wide if it is not already (`kici-admin cluster-settings set --global-workflows-enabled true`). |
+| `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                                                                                                                                                                                                                                                 |
+| 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.                                                                                                                                                                                                 |
+| A `failure` check named `KiCI: Organization workflow evaluation` on a commit                    | The pre-run evaluation failed or timed out, so the global workflows from that repo were not run.                                                                                                                       | Orchestrator log for the evaluation job; push a new commit to re-evaluate (a redelivery is dropped as a duplicate).                                                                                                                                                                                                                                  |
+| Same-repo workflow shows a `success` run with no jobs in it                                     | Its `filter` returned `false`. A same-repo filter runs after the run exists, so the run remains, carrying only the evaluation jobs.                                                                                    | The run detail page — the evaluation job's log records the filter verdict.                                                                                                                                                                                                                                                                           |
+| Re-run is refused with "Cannot re-run an organization-wide workflow"                            | Expected — the run executed against a source repo that does not declare the workflow.                                                                                                                                  | [Re-running is not supported](https://docs.kici.dev/user/global-workflows/#re-running-is-not-supported) — push a new commit to the source repo instead.                                                                                                                                                                                                                                          |
+| Every global workflow stopped running right after an orchestrator upgrade                       | The agents were not upgraded first. An agent older than v0.5.0 cannot evaluate a global workflow, and one containing a `dynamicJob` now needs an evaluation even without a `filter` — so its **static** jobs stop too. | The `KiCI: Organization workflow evaluation` check names the agent versions it found. Upgrade every `kici:role:init-runner` agent to v0.5.0 or newer.                                                                                                                                                                                                |
+
+### Reading a global run in the dashboard
+
+A global run is attributed to the **source** repo — the repo whose event
+triggered it, and whose code the jobs check out. Its run detail page names both
+repos, so you can tell it apart from an ordinary per-repo run:
+
+| Row          | Shows                                                                    |
+| ------------ | ------------------------------------------------------------------------ |
+| `Repository` | the source repo — the one the run acted on                               |
+| `Defined in` | the workflow repo, tagged `Organization-wide`. Absent on an ordinary run |
+| `Workflow`   | links into the **workflow** repo, on its default branch                  |
+
+The `Workflow` link points at the workflow repo's default branch rather than at
+a commit: the run's own commit belongs to the source repo, and nothing records
+which commit of the workflow repo a given run used. So the link always shows the
+file as it stands now, which may have changed since the run.
+
+The `Payload` tab shows the source repo's event — the webhook delivery the
+workflow reacted to, which for a global workflow comes from a repo you may not
+own. A global run dispatched before your orchestrator stored payloads for this
+path has none, and its tab reports that it could not load one.
+
+#### Who can see it
+
+A global run belongs to **both** repos, so a member whose role is scoped to
+either one reaches it — the team whose push triggered it, and the team that
+authored the workflow. Both see it in the run list, in the repository filter
+(which offers both names), and on the run detail page. Cancelling follows the
+same rule, so the team whose workflow is running can always stop it.
+
+Releasing a **held** run is the one exception: approving a hold permits code to
+run against the source repo, so it stays with a member scoped to that repo. A
+member scoped only to the workflow repo sees the run but not its hold.
+
+This applies only where the two repos genuinely differ. An ordinary per-repo run
+records no separate workflow repo and is scoped to its own repo exactly as
+before, and a member scoped to neither repo sees nothing in either case.
+
+### Reading a global workflow's filter output
+
+A global workflow's `filter` runs in a pre-run evaluation round, and that round
+decides whether a run exists at all — so on the path where it suppresses a
+workflow there is no run, and nothing appears in the dashboard. The round's own
+log is still recorded. Read it with the orchestrator admin CLI, in two steps:
+
+```bash
+# 1. Find the round. Its workflow name is __globaleval__<owner>/<repo> of the
+#    WORKFLOW repo. In the JSON rows, `id` is the job id and `run_id` is the
+#    run id.
+kici-admin queue list --workflow-name '__globaleval__myorg/ci-pipelines' --limit 5 --json
+
+# 2. Print the round's log (step 0 is the evaluation itself).
+kici-admin runs logs <run_id> --job <id>
+```
+
+Use `--json` on the first command: the plain table abbreviates both ids to their
+first eight characters, and the second command needs them in full.
+
+The two steps need different permissions, so run both with an **owner or admin**
+token. Step 1 reads the dispatch queue, which requires `secret.read` — an auditor
+token is refused with a 403 and never reaches step 2. Step 2 requires only
+`run.read`, which every role carries.
+
+Anything your `filter` writes with `console.log` appears there, alongside the
+per-candidate verdicts the round recorded.
 
 ## See also
 
@@ -12036,7 +12438,7 @@ export default workflow('build', {
 
 Per-field rules:
 
-- **`url`** — Must be HTTPS. HTTP is permitted only for `localhost` / `127.0.0.0/8` / `::1` / `*.local` hosts, or when an operator has flipped the org-level `allow_http_npm_registries` toggle (see [`kici-admin org-settings allow-http-npm`](https://docs.kici.dev/operator/kici-admin-cli#allow-http-npm--permit-non-https-private-npm-registries)).
+- **`url`** — Must be HTTPS. HTTP is permitted only for `localhost` / `127.0.0.0/8` / `::1` / `*.local` hosts, or when an operator has flipped the org-level `allow_http_npm_registries` toggle (see [`kici-admin org-settings allow-http-npm`](https://docs.kici.dev/operator/orchestrator/kici-admin/org-settings/#allow-http-npm--permit-non-https-private-npm-registries)).
 - **`scope`** — Optional. When present, the registry serves only that scope (`@my-org`). When absent, this entry becomes the **default** registry — at most one entry may omit `scope`.
 - **`tokenSecret`** — Mandatory `<context>:<secret-name>`. The orchestrator looks up the secret in the named context via the per-context secret resolver. The bare name **must not** contain a colon.
 - **`alwaysAuth`** — Defaults to `true`. Forces npm to send the token on every request (even GETs), which is what most managed-registry providers require.
@@ -12250,7 +12652,7 @@ The dashboard JSON lives at `infra/terraform/modules/grafana/dashboards/install-
 
 - [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.
-- [Operator: `kici-admin org-settings`](https://docs.kici.dev/operator/kici-admin-cli#org-settings----org-level-security-policy) — the `allow_http_npm_registries` toggle and other org-scoped knobs.
+- [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.
 
 ---
 
@@ -12556,7 +12958,7 @@ KiCI provides an explicit secrets API that gives workflow steps controlled acces
 
 ## Overview
 
-Secrets are managed per-context in the orchestrator (see [operator docs](https://docs.kici.dev/operator/orchestrator/configuration) for setup). When a job runs with a `context` binding, the agent receives the secret keys available for that context but does **not** inject their values into the step's process environment. Instead, steps access secrets through the `ctx.secrets` API.
+Secrets are managed per-context in the orchestrator (see [operator docs](https://docs.kici.dev/operator/orchestrator/configuration/) for setup). When a job runs with a `context` binding, the agent receives the secret keys available for that context but does **not** inject their values into the step's process environment. Instead, steps access secrets through the `ctx.secrets` API.
 
 This design prevents accidental secret leakage through child processes, log output, or error messages. Only secrets you explicitly request are loaded into memory.
 
@@ -12577,13 +12979,13 @@ Use whichever fits the workflow — most small teams stay on the dashboard; ops
 
 ### When the operator has disabled dashboard writes
 
-The orchestrator operator can flip `secrets.set` (and `variables.set`) to **CLI-only** as part of the [dashboard-write policy](https://docs.kici.dev/operator/security/dashboard-write-policy). When that flip is on:
+The orchestrator operator can flip `secrets.set` (and `variables.set`) to **CLI-only** as part of the [dashboard-write policy](https://docs.kici.dev/operator/security/dashboard-write-policy/). When that flip is on:
 
 - The dashboard's "Add secret" / "Edit value" controls render with a lock icon. Hovering or keyboard-focusing the lock shows a tooltip with the exact `kici-admin secret set` invocation needed. The control itself is inert, so there is nothing to click.
 - The dashboard's secrets page still lists secret **names**, scopes, and bindings — only the value-entry path moves to the CLI.
 - `kici-admin secret set` becomes the single entry point for new and updated secret values.
 
-This configuration is common for SOC2-prep and regulated workloads, where the customer requirement is "the SaaS control plane process never receives plaintext customer secret values." The dashboard remains usable for everything else (read paths, name CRUD, environment bindings).
+This configuration is common for SOC2-prep and regulated workloads, where the customer requirement is "the SaaS control plane process never receives plaintext customer secret values." The dashboard remains usable for everything else (read paths, name CRUD, context bindings).
 
 ### CLI input modes
 
@@ -12618,7 +13020,7 @@ Two cross-cutting flags help every mode:
 
 `kici-admin variable set` uses the same flags for non-encrypted variables, plus `--locked` to mark a variable as immutable from subsequent dashboard writes.
 
-A full reference of input modes — including the default-mode resolution rules and the security trade-offs of each — lives in [Dashboard-write policy → CLI input modes](https://docs.kici.dev/operator/security/dashboard-write-policy#cli-input-modes-for-the-plaintext-path).
+A full reference of input modes — including the default-mode resolution rules and the security trade-offs of each — lives in [Dashboard-write policy → CLI input modes](https://docs.kici.dev/operator/security/dashboard-write-policy/#cli-input-modes-for-the-plaintext-path).
 
 ## Accessing secrets
 
@@ -12853,7 +13255,7 @@ Note that `get()` is async -- you must `await` the result.
 
 When you run `kici types`, the compiler generates a `.kici/secrets.d.ts` file that provides type-safe autocompletion for your secret keys. The generated types augment the `StepSecrets` interface so that `ctx.secrets.get('...')` and `ctx.secrets.has('...')` offer suggestions for known keys.
 
-See [CLI reference](https://docs.kici.dev/user/cli) for the `kici types` command.
+See [CLI reference](https://docs.kici.dev/user/cli/authoring-and-local/#kici-types) for the `kici types` command.
 
 ---
 
@@ -13169,9 +13571,8 @@ when you want a list entry pinned to this specific App rather than
 applying to any source in the org:
 
 ```bash
-# Enable global workflows for the org
-kici-admin org-settings global-workflows set-enabled true \
-  --customer-id <orgId>
+# Enable global workflows cluster-wide (the master switch is fleet-wide, held by the operator)
+kici-admin cluster-settings set --global-workflows-enabled true
 
 # Allow the listed repo as an author for any source in the org
 kici-admin org-settings global-workflows allow-add 'my-org/ci-workflows/*' \
@@ -13606,9 +14007,8 @@ org-scoped (one row per `customer_id`); each list entry can optionally
 pin to a specific source via `--source <routingKey>`:
 
 ```bash
-# Enable global workflows for the org
-kici-admin org-settings global-workflows set-enabled true \
-  --customer-id <orgId>
+# Enable global workflows cluster-wide (the master switch is fleet-wide, held by the operator)
+kici-admin cluster-settings set --global-workflows-enabled true
 
 # Allow authors from any source in the org
 kici-admin org-settings global-workflows allow-add \
@@ -13983,12 +14383,13 @@ The `ProviderRegistry` maps routing keys to provider bundles. Each routing key (
 - `WebhookNormalizer` (required) -- normalizes incoming webhooks to a standard format
 - `LockFileFetcher` -- fetches lock files from the repository
 - `ChangedFilesFetcher` -- determines which files changed
+- `FileContentsFetcher` -- reads arbitrary repository files at a ref, for the declarative content-requirements (`requires`) filter
 - `CloneTokenProvider` -- generates clone tokens for agents
 - `RepoUrlBuilder` -- builds clone URLs and raw file URLs
 - `ContributorResolver` -- resolves contributor permissions for trust-tier gating
 - `CheckStatusPoster` -- posts check statuses (approval/hold) to the git provider
 
-A GitHub App source populates all seven. A plain generic webhook source carries only the normalizer -- it has no repository API to fetch a lock file, resolve a contributor, or post a check against -- so the pipeline skips the stages whose interface is absent rather than failing the delivery.
+A GitHub App source populates all eight -- though the file-contents capability arrives as a per-delivery factory rather than a prebuilt instance, because a GitHub client is scoped to one installation and the installation id is only known once the delivery's credentials are resolved. A plain generic webhook source carries only the normalizer -- it has no repository API to fetch a lock file, resolve a contributor, or post a check against -- so the pipeline skips the stages whose interface is absent rather than failing the delivery.
 
 Provider registrations are managed via the `sources` database table, not via `SharedConfig`. When the orchestrator connects to the Platform relay, it reads source records from the DB and sends `source.register` messages. Changes to sources (add/remove) are detected via PostgreSQL LISTEN/NOTIFY on the `sources_change` channel and pushed to the Platform via `source.secrets` and `source.register`/`source.deregister`.
 
@@ -14076,10 +14477,11 @@ GitHub  -->  Platform Relay  -->  Orchestrator  -->  Agent
 12. **Orchestrator extracts registrations** on default-branch pushes: persists registerable workflows (event, schedule, lifecycle triggers) for cluster-wide event matching.
 13. **Orchestrator notifies the event router** on default-branch pushes: after the registrations are persisted, emits a `registration.updated` event via `eventRouter.emit()` (if event routing is active). Workflow event subscriptions are the persisted registrations themselves, matched at emit time through the registration index.
 14. **Orchestrator fetches changed files** via the provider's `ChangedFilesFetcher` for path-based trigger filtering (skipped when no workflow uses path filters).
-15. **Orchestrator matches triggers** against lock file using `matchAllWorkflows()` from `@kici-dev/engine`.
-16. **Orchestrator checks caches** for source tarballs and dependency tarballs.
-17. **Orchestrator dispatches jobs** to agents via the job queue and WebSocket.
-18. **Orchestrator persists a delivery row** keyed by `(org_id, delivery_id)` to its own `event_log`, including a pointer to the gzipped payload in object storage. The orchestrator's delivery log is surfaced in the dashboard's Settings → Event log tab. See [`webhook-delivery.md`](https://docs.kici.dev/architecture/webhooks/webhook-delivery/#delivery-log).
+15. **Orchestrator matches triggers** against the lock file using `matchWorkflowsForEvent()` from `@kici-dev/engine` -- an event-type-bucketed candidate scan that evaluates only the workflows subscribed to this event type. (The single-registration global / cross-source paths evaluate one lock entry at a time via `matchAllWorkflows()`.)
+16. **Orchestrator applies the content-requirements filter** to the matched candidates: for each trigger that declares `requires`, it reads the named source files at the event's ref through the provider's `FileContentsFetcher` (once per distinct `(repo, sha, path)` via an LRU cache) and evaluates the declarative requirement. Candidates that fail -- or that cannot be evaluated at all (unreadable or oversize content, a fetch error, no fetcher wired) -- are dropped before dispatch with the concrete reason logged. No workflow code runs at this stage. Skipped entirely when no matched trigger declares `requires`.
+17. **Orchestrator checks caches** for source tarballs and dependency tarballs.
+18. **Orchestrator dispatches jobs** to agents via the job queue and WebSocket.
+19. **Orchestrator persists a delivery row** keyed by `(org_id, delivery_id)` to its own `event_log`, including a pointer to the gzipped payload in object storage. The orchestrator's delivery log is surfaced in the dashboard's Settings → Event log tab. See [`webhook-delivery.md`](https://docs.kici.dev/architecture/webhooks/webhook-delivery/#delivery-log).
 
 ## Job execution flow
 
@@ -14195,7 +14597,7 @@ Execution Job Dispatch --> Execution Agent
   |                          |
   |                          |-- Download source tarball (sourceTarUrl) -> extract to workDir/.kici/
   |                          |-- Download deps tarball (depsUrl) -> verify SHA-256 -> extract to .kici/node_modules/
-  |                          |-- Register @kici-dev/shared/ts-loader-hook
+  |                          |-- Register @kici-dev/core/ts-loader-hook
   |                          |-- Verify workflow contentHash against lock file (drift guard)
   |                          |-- Dynamic-import workflow .ts
   |                          |-- Execute steps
@@ -14254,7 +14656,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 32.
+- **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 34.
 - **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
@@ -14499,7 +14901,7 @@ Agent                          Orchestrator
 
 ### Registration extraction flow
 
-When code is pushed to the default branch, the orchestrator extracts event-triggered workflows from the lock file and stores them as registrations for cluster-wide event matching.
+When code is pushed to the default branch, the orchestrator extracts registerable workflows from the lock file and stores them as registrations for cluster-wide event matching. Non-Git triggers (`kici_event`, `schedule`, `generic_webhook`, …) live there because they have no per-repo lock-file pipeline to fall back on; Git-provider triggers (`push`, `pr`, `tag`, …) are indexed too, so the cross-source dispatch path can resolve them by `(customer_id, repo_identifier)` when a generic webhook targets an externally-hosted repo. For same-source Git events the per-event lock-file pipeline remains the primary matcher — registration is an additive index.
 
 ```
 Git Push to Default Branch
@@ -14512,8 +14914,15 @@ GitHub Webhook -> Platform Relay -> Orchestrator Processor
     |-- extractRegisterableWorkflows(fullLockFile)
     |       |-- For each workflow entry in lock file:
     |       |     Check if any trigger type is registerable
-    |       |     (kici_event, workflow_complete, job_complete,
-    |       |      generic_webhook, schedule, lifecycle)
+    |       |     (the RegisterableTriggerType enum — the non-Git
+    |       |      set kici_event, workflow_complete,
+    |       |      workflows_failed_batch, job_complete,
+    |       |      generic_webhook, schedule, lifecycle, webhook,
+    |       |      plus every Git-provider trigger: push, pr, tag,
+    |       |      comment, review, review_comment, release,
+    |       |      dispatch, create, delete, status, workflow_run,
+    |       |      fork, star, watch)
+    |       |     ... or the workflow has repo patterns (global workflow)
     |       |-- Return array of registerable workflows
     |
     |-- globalWorkflowPolicy.isWorkflowRepoAllowed() (if policy configured)
@@ -14891,7 +15300,7 @@ The Platform tier exposes a `/ws/browser` WebSocket endpoint for dashboard clien
 - [Architecture overview](https://docs.kici.dev/architecture/overview/) -- three-tier model and component responsibilities
 - [Protocol messages](https://docs.kici.dev/architecture/protocol-messages/) -- WebSocket message schemas
 - [Event system internals](https://docs.kici.dev/architecture/webhooks/event-system/) -- event router, registration model, cron scheduler
-- [Execution lifecycle](https://docs.kici.dev/architecture/execution/state-machine/) -- run, job, and step status vocabularies and terminal states
+- [Execution status vocabulary](https://docs.kici.dev/architecture/execution/state-machine/) -- run, job, and step status vocabularies and terminal states
 - [Webhook delivery](https://docs.kici.dev/architecture/webhooks/webhook-delivery/) -- detailed webhook processing pipeline
 - [Operator: dependency caching](https://docs.kici.dev/operator/dependency-caching/) -- configuration guide
 - [Operator: monitoring & tracing](https://docs.kici.dev/operator/observability/monitoring/) -- trace fields and Loki queries
@@ -14990,7 +15399,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, CloneTokenProvider, RepoUrlBuilder, ContributorResolver, CheckStatusPoster)
+- Provider interfaces (WebhookNormalizer, LockFileFetcher, ChangedFilesFetcher, FileContentsFetcher, CloneTokenProvider, RepoUrlBuilder, ContributorResolver, CheckStatusPoster)
 - Trigger matching engine (branch, path, event evaluation)
 - Dispatch inputs (input descriptors, extraction from the trigger event, and coercion to typed values)
 - Matrix expansion and fanout (combination expansion with include/exclude, job-name suffix formatting, and materialization of one matrix or multi-host job into N dispatchable children)
@@ -15006,11 +15415,16 @@ Shared business logic used by all three tiers. Single source of truth for cross-
 - Build provenance (in-toto statement schema, DSSE envelope, attestation bundle, verification)
 - Artifact name contract (the shared filesystem/URL-safe name schema the orchestrator, agent, and SDK all validate against)
 - Developer MCP tool schemas (argument schemas for the AI-agent tool surface)
+- Developer-operations contract (one row per workflow-developer operation declaring which entrypoints expose it -- the shared REST API behind the web UI and the `kici` CLI, the AI-agent tool surface, and a curated UI flag -- asserted against each real surface by congruence tests)
 - 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`)
 - 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)
 
 > Source: `packages/engine/src/`
@@ -15134,7 +15548,7 @@ KiCI uses application-level tenant isolation. The Platform dashboard API accepts
 ## See also
 
 - [Multi-Orchestrator Architecture](https://docs.kici.dev/architecture/clustering/multi-orchestrator/) -- P2P clustering, Raft consensus, job rerouting
-- [Execution lifecycle](https://docs.kici.dev/architecture/execution/state-machine/) -- run, job, and step status vocabularies and the tracker that owns lifecycle state
+- [Execution status vocabulary](https://docs.kici.dev/architecture/execution/state-machine/) -- run, job, and step status vocabularies and the tracker that owns lifecycle state
 - [Protocol Messages](https://docs.kici.dev/architecture/protocol-messages/) -- WebSocket message schemas for all three layers
 - [Webhook Delivery](https://docs.kici.dev/architecture/webhooks/webhook-delivery/) -- end-to-end trace of a webhook through all three tiers