@kici-dev/compiler 0.6.0 → 0.7.0

package/dist/llm-context/llms-features-execution.txt

@@ -132,6 +132,8 @@ workflow('test', {
 
 When `max: 1` (default), runs are fully serialized within the group.
 
+`max` is enforced by the orchestrator's database, so the limit is cluster-wide and survives a restart. A run holding a slot keeps it across an orchestrator restart. Every orchestrator in a cluster counts against the same limit, so a group with `max: 1` runs one job at a time no matter which orchestrator dispatched it.
+
 ## Group key examples
 
 ### Deploy per environment
@@ -191,6 +193,14 @@ When a workflow has both `concurrency` and `context` protection rules:
 
 This means a run that passed approval won't need re-approval if it gets queued by concurrency.
 
+The two caps also differ in strength. A workflow-level concurrency group claims
+its slot inside a single database transaction, so two runs that arrive together
+cannot both take it. A context
+[concurrency limit](https://docs.kici.dev/user/contexts/#concurrency-limits) is a throughput control:
+simultaneous arrivals can each be admitted before either is recorded. Declare a
+concurrency group for anything that must never run beside itself, whatever the
+context limit says.
+
 ## Cancelling queued runs
 
 Queued runs can be cancelled before they start executing. The cancel request removes them from the queue immediately -- they don't go through the grace period since no step is running.
@@ -401,6 +411,17 @@ Store the secrets first with `kici-admin secret set`. Pasting a token straight
 into the workflow is rejected when the workflow is defined, because a token
 written into `.kici/` would be committed to your repository.
 
+The named context's protection rules run before the secret is read, exactly as
+they do for [git credentials](https://docs.kici.dev/user/patterns/git-credentials/#what-a-job-may-ask-for).
+A `prod:` reference from a branch the `prod` context restricts is refused, and
+the job is dispatched with no registry credentials — so a private image fails to
+pull rather than being pulled from a branch the context does not allow. The rule
+that refused it is named in your orchestrator's log, not in the run.
+
+**An untrusted ref receives no registry credentials.** A fork pull request is
+dispatched without them, so a private base image fails to pull and a public one
+is unaffected. The run's reduced-privilege note says so.
+
 The username is not a secret, so you may write it directly:
 
 ```typescript
@@ -410,6 +431,30 @@ auth: { username: 'ci-bot', tokenSecret: 'prod:REGISTRY_TOKEN' }
 Your orchestrator resolves these names at dispatch and sends only the resolved
 credentials to the agent. The agent never reads your secret store.
 
+### Naming the registry
+
+`auth` also takes a `registry` — the registry host the credentials belong to,
+such as `reg.internal:5000`.
+
+With `image` it is optional, because KiCI reads the host off the image
+reference. With `dockerfile` it is **required**: the base image is named inside
+your Dockerfile, so there is nothing to read it from. A `dockerfile` job whose
+`auth` omits `registry` is refused when you define the workflow.
+
+```typescript
+container: {
+  dockerfile: '.kici/ci.Dockerfile',
+  auth: {
+    registry: 'reg.internal:5000',
+    usernameSecret: 'prod:REGISTRY_USER',
+    tokenSecret: 'prod:REGISTRY_TOKEN',
+  },
+},
+```
+
+With `dockerfile`, these credentials pull the Dockerfile's own `FROM` base — not
+a job image, since the job image is the one KiCI builds.
+
 ### Credentials that only exist at run time
 
 A token fetched during the run — from a cloud registry's login command, for
@@ -560,10 +605,11 @@ The KiCI CLI reads the following environment variables to customize its behavior
 
 ## Development
 
-| Variable     | Description                                                                                                                                                                | Default |
-| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| `KICI_DEV`   | Enable development mode. When `true`, uses prerelease-compatible version ranges (`>=0.0.1-0`) for dev dependencies and skips npm version resolution.                       | unset   |
-| `KICI_DEBUG` | Enable debug logging. When `true`, prints verbose diagnostics (SDK alias resolution, step-level debug logs, stack traces on errors). Equivalent to the `--debug` CLI flag. | unset   |
+| Variable            | Description                                                                                                                                                                | Default |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| `KICI_DEV`          | Enable development mode. When `true`, uses prerelease-compatible version ranges (`>=0.0.1-0`) for dev dependencies and skips npm version resolution.                       | unset   |
+| `KICI_DEV_REGISTRY` | npm registry the `@kici-dev` scope points at when `KICI_DEV` is set. `kici init` writes it into `.npmrc`; with no value it writes no `.npmrc`.                             | unset   |
+| `KICI_DEBUG`        | Enable debug logging. When `true`, prints verbose diagnostics (SDK alias resolution, step-level debug logs, stack traces on errors). Equivalent to the `--debug` CLI flag. | unset   |
 
 ## Local dev plane
 
@@ -897,7 +943,7 @@ job('provision', {
 
 ### Trust tiers on internal triggers
 
-An internally-triggered run resolves its [trust tier](https://docs.kici.dev/user/contexts/#minimum-trust) from the trigger. The tier decides the run's cache scope, whether it may run a [Dockerfile build](https://docs.kici.dev/user/container-jobs/#who-may-build), whether it receives [install secrets](https://docs.kici.dev/user/private-registries/), and whether a `minimumTrust` context holds it.
+An internally-triggered run resolves its [trust tier](https://docs.kici.dev/user/contexts/#minimum-trust) from the trigger. The tier decides the run's cache scope, whether it may run a [Dockerfile build](https://docs.kici.dev/user/container-jobs/#who-may-build), whether it receives [install secrets](https://docs.kici.dev/user/private-registries/), and whether a `minimumTrust` context holds it. It also decides whether the run's jobs receive [container-registry credentials](https://docs.kici.dev/user/container-jobs/#private-images) and their declared [git credentials](https://docs.kici.dev/user/patterns/git-credentials/#what-a-job-may-ask-for).
 
 Four rules resolve the tier, and KiCI applies them in this order:
 
@@ -1153,14 +1199,21 @@ Patterns in `repos:` use the same globbing as `branches:` / `paths:` — plain g
 
 The agent checks out both repos. **Inside a step body**, `env` carries a pointer to each working tree:
 
-| `env` var                 | Points to                                                                                                                                    |
+| `env` var                 | Carries                                                                                                                                      |
 | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
 | `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.   |
+| `KICI_SOURCE_REPO`        | The source repo's `owner/repo` identifier — the same value as `ctx.event.sourceRepo`.                                                        |
+| `KICI_WORKFLOW_REPO`      | The workflow repo's `owner/repo` identifier.                                                                                                 |
+| `KICI_SOURCE_BRANCH`      | The source repo's checked-out ref. **Empty string** when the event carries no single ref.                                                    |
+| `KICI_SOURCE_SHA`         | The source repo's checked-out commit. **Empty string** when the event carries no single sha.                                                 |
+| `KICI_IS_GLOBAL_WORKFLOW` | `"true"`. Never set on the same-repo path, so it is the cheapest test for which path you are on.                                             |
+
+All seven are 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, not as a global candidate. The workflow then runs as an ordinary single-repo workflow: one checkout, and none of the seven set. Read them with a fallback, as the example above does.
 
-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.
+Guard those two on emptiness rather than absence: `??` does not catch `""`, but `||` does.
 
-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.
+These are real process environment variables for the whole job, so a subprocess a step spawns inherits them: `` await $`echo $KICI_SOURCE_REPO` `` works. What does **not** see them is anything resolved outside that process — a job-level `env:` block or a container image's entrypoint, both of which are settled before the job starts. Outside a step body, use the `sourceRepo` / `workflowRepo` pair on the filter, generator, and rule contexts described below.
 
 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.
 
@@ -1409,11 +1462,15 @@ A global workflow fires only if:
 
 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.
+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. That anchor is an ordinary organization for policy purposes: it carries no per-org lists, so by the empty-list rule above it restricts nothing, and the fleet-wide master switch alone governs it. A deployment whose sources are unmapped — the state a fresh install starts in, since the quickstart configures no sources — runs global workflows normally once that switch is on.
+
+Map a source to a real organization when you want per-org policy to be **expressible**: `kici-admin source update <routingKey> --customer-id <org>`. Allow- and deny-lists are stored per organization, so every unmapped source shares the one policy surface on the `__default__` anchor. That is a reason to map, not a precondition for dispatch.
+
+The registration log line names the organization it decided against, so a refusal is always attributable to a specific policy rather than to the anchor itself. See the troubleshooting table below.
 
 ### Secrets are not available
 
-A global workflow's job is dispatched with **no secret material** — not the source repo's, and not the workflow repo's own. The organization-wide dispatch path binds no secret contexts, so a `contexts:` declaration on a global workflow resolves to nothing and any secret the steps expect is simply absent. Plan for it: a global workflow is for checks, policy and reporting that need only the two checkouts, not for deploys that need credentials.
+A global workflow's job is dispatched with **no secret material** — not the source repo's, and not the workflow repo's own. The organization-wide dispatch path binds no secret contexts, so a `contexts:` declaration on a global workflow resolves to nothing and any secret the steps expect is absent. Plan for it: a global workflow is for checks, policy and reporting that need only the two checkouts, not for deploys that need credentials.
 
 This is about your **stored secrets**, not about repository access: the job is still handed a short-lived clone token for each repo it checks out, which is how the dual checkout works at all. What it does not get is anything from a secret context.
 
@@ -1468,19 +1525,19 @@ A `filter` reads the source tree, so the evaluation must be able to obtain one.
 
 ## 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` (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. Fix the cause, then re-run the errored `__globaleval__…` run (`kici runs rerun <run-id>`) to re-evaluate and clear the check; 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 an organization-wide run](https://docs.kici.dev/user/global-workflows/#re-running-an-organization-wide-run) — trigger it from the repo that defines the workflow 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.                                                                                                                                                                                                |
+| 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 fleet-wide master switch is off, or the authoring repo does not match a populated _Allowed author repos_ list.                                                                                                     | Orchestrator log: `Global workflows excluded from registration`, naming the organization it decided against. Check the switch first (`kici-admin cluster-settings show`), then that org's allow-list in the dashboard. An `"orgId": "__default__"` in the line is not itself the fault — that anchor carries no lists and restricts nothing. |
+| `repos:` has no effect — workflow only fires on its own repo                                    | The fleet-wide master switch is off. Without it, the orchestrator treats the workflow as per-repo-only.                                                                                                                | Check the fleet-wide switch with `kici-admin cluster-settings show`. The dashboard → Settings → Global workflows tab shows it as a read-only badge.                                                                                                                                                                                          |
+| Secrets unavailable in a global job                                                             | Expected — a global workflow's job receives no secrets at all, and the _Elevated access_ list is not enforced.                                                                                                         | Move the jobs that need credentials into a per-repository workflow in the repo that owns the secrets                                                                                                                                                                                                                                         |
+| 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. Fix the cause, then re-run the errored `__globaleval__…` run (`kici runs rerun <run-id>`) to re-evaluate and clear the check; 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 an organization-wide run](https://docs.kici.dev/user/global-workflows/#re-running-an-organization-wide-run) — trigger it from the repo that defines the workflow 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 the decision trace for a delivery
 

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

@@ -66,7 +66,7 @@ You declare a gate in your workflow with `approval`. It is available at three le
 - **Job** — hold the job before any of its steps run.
 - **Workflow** — hold the whole run before any job is dispatched.
 
-A step-level gate can also fire **only when a check/apply step finds drift** — Terraform's plan→apply, per step. See [Drift gates](https://docs.kici.dev/user/approvals/#drift-gates-whendrift) below.
+A step-level gate can also fire **only when a check/apply step finds drift** — Terraform's plan→apply, per step. See [Drift gates](https://docs.kici.dev/user/approvals/#drift-gates-when-drift) below.
 
 Approvers are named as **teams** and **users**. A team is an operator-defined group of org members; your workflow code may name a team but can never change its membership, which is what makes a team clause a real gate rather than a suggestion. See [Approval gates (operator guide)](https://docs.kici.dev/operator/approvals/) for how operators define teams, the approval queue, and expiry; see [the architecture overview](https://docs.kici.dev/architecture/approvals/) for how a hold is evaluated and resumed.
 
@@ -137,7 +137,7 @@ approval: {
 
 | Field       | Type                  | Description                                                                                                                                                                                                      |
 | ----------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `when`      | `'always' \| 'drift'` | When the gate fires. `'always'` (default) gates before the element; `'drift'` gates a check/apply step only when it finds drift. See [Drift gates](https://docs.kici.dev/user/approvals/#drift-gates-whendrift).                                      |
+| `when`      | `'always' \| 'drift'` | When the gate fires. `'always'` (default) gates before the element; `'drift'` gates a check/apply step only when it finds drift. See [Drift gates](https://docs.kici.dev/user/approvals/#drift-gates-when-drift).                                     |
 | `approvers` | `ApproverClause[]`    | The AND list of `{ team }` / `{ user }` clauses. An empty list means "any approval-capable member".                                                                                                              |
 | `reason`    | `string`              | A human-readable label shown in the dashboard queue and the held-for-approval status check.                                                                                                                      |
 | `timeout`   | `number`              | Per-gate expiry in **seconds**, overriding the org default. Must be a **positive integer** number of seconds; a non-positive or non-finite value is rejected at compile time. On expiry the element is rejected. |
@@ -316,7 +316,7 @@ Available rules:
 - **Branch restrictions** — only allow specific branches to deploy.
 - **Required reviewer approvals** — gate the run on human sign-off.
 - **Wait timers** — delay execution for a fixed period.
-- **Concurrency limits** — prevent collisions between parallel deployments.
+- **Concurrency limits** — cap how many jobs run against the context at once.
 
 <!-- /help:contexts-protection -->
 
@@ -405,7 +405,7 @@ job('deploy', {
 
 **Skip-on-test (allow-and-warn).** On a test or local run (`kici run remote`, `kici run <event> --local`), a bound context never rejects the run. Any bound context that disallows local execution (`allowLocalExecution: false`) — or that is not configured — is **skipped**: its variables and secrets are omitted from the merge and its gates are not evaluated. The run proceeds, and a user-visible warning naming the skipped context(s) is shown both on the `kici run remote` CLI output and on the dashboard run view. This makes the test-only-variables pattern work: with `contexts: ['staging', 'my-testing']` where only `my-testing` allows local execution, a test run resolves just `my-testing`'s variables and warns that `staging` was skipped. If every bound context is skipped, the job runs with no environment variables. This is intentionally different from a fixture `secrets:` mapping, which is fail-closed — see the [testing guide](https://docs.kici.dev/user/testing-guide/).
 
-**Unconfigured contexts contribute nothing at dispatch.** At dispatch time a bound context name with no matching configured context (and no matching glob context) simply adds no variables, secrets, or protection rules — the job still runs, exactly as a single dynamic context resolving to an as-yet-unconfigured name does today.
+**Unconfigured contexts contribute nothing at dispatch.** At dispatch time a bound context name with no matching configured context (and no matching glob context) adds no variables, secrets, or protection rules — the job still runs, exactly as a single dynamic context resolving to an as-yet-unconfigured name does today.
 
 **Registration rejects a provably-unsatisfiable binding.** When a workflow is registered, KiCI statically checks every multi-context binding: a bound context that does not exist, a disabled one, or two contexts with mutually-exclusive fixed branch / trigger-type / repository restrictions (no value can satisfy both) makes the binding provably unsatisfiable, and the registration is rejected with a precise message naming the job, the contexts, and the rule — for example `unsatisfiable context binding: job 'deploy' binds contexts [staging, my-testing] with mutually exclusive branch restrictions (no value satisfies all bound contexts)`. Bindings whose restrictions use globs are undecidable at registration and fall through to the dispatch-time gate check instead.
 
@@ -608,6 +608,36 @@ The children of a matrix job count individually against the limit. A three-child
 matrix bound to a context with a limit of two dispatches two children and applies
 the strategy above to the third.
 
+A job counts against the limit from the moment it is dispatched until it
+finishes. It does not have to reach an agent first.
+
+#### What the limit does and does not guarantee
+
+A context concurrency limit is a **throughput control**. Treat it as a cap on
+how much work runs at once, not as a lock.
+
+Two events that arrive in the same instant read the limit before either job is
+recorded, so each can be admitted. The window is short — the time between one
+read and one write — but it is real, and it grows with the number of
+orchestrator processes serving the context.
+
+When a job must never run beside another copy of itself — a production deploy,
+a database migration — declare a workflow-level
+[concurrency group](https://docs.kici.dev/user/concurrency/) as well:
+
+```typescript
+export default workflow('deploy', {
+  on: push({ branches: ['main'] }),
+  concurrency: { group: () => 'deploy-prod', max: 1 },
+  jobs: [/* ... */],
+});
+```
+
+That mechanism claims its slot inside a single database transaction, so two
+runs arriving together cannot both take it. The two are complementary: the
+context limit caps throughput across every workflow bound to the context, and
+the concurrency group serializes one workflow against itself.
+
 ## Dashboard management
 
 ### Creating contexts
@@ -914,7 +944,7 @@ registries: [
 ## Security model
 
 - **Per-context scoping.** Every `tokenSecret` and `installEnv` entry is qualified with a context name. The orchestrator runs the same protection-rule pipeline (branch / trust / concurrency / reviewer / wait-timer) against each named context **before** resolving any secret, so a workflow that wants a `production` token from a feature branch is rejected exactly like a job that tries to deploy to `production` from a feature branch. A reviewer-gated install context **pauses** the whole workflow dispatch as a workflow-scoped held run instead of resolving the token — see [Reviewer-gated installs](https://docs.kici.dev/user/private-registries/#reviewer-gated-installs) below.
-- **Untrusted refs get no tokens.** When the trust resolution returns anything other than `trusted` — every fork pull request does — the orchestrator strips both `npmRegistries` and `installEnvSecrets` out of the dispatch. The install runs without auth and fails naturally on the first private dep. A fork pull request cannot observe a registry token, even if a context lacks an explicit [minimum trust](https://docs.kici.dev/user/contexts/#minimum-trust) rule.
+- **Untrusted refs get no tokens.** When the trust resolution returns anything other than `trusted` — every fork pull request does — the orchestrator strips `npmRegistries`, `installEnvSecrets`, and a container job's [registry credentials](https://docs.kici.dev/user/container-jobs/#private-images) out of the dispatch. The install runs without auth and fails naturally on the first private dep, and a private base image fails to pull. A fork pull request cannot observe a registry token, even if a context lacks an explicit [minimum trust](https://docs.kici.dev/user/contexts/#minimum-trust) rule.
 - **Lifecycle scripts disabled.** Whenever a private registry is in scope, the agent runs the install with `--ignore-scripts` (npm, pnpm, and yarn classic alike; yarn berry gets the equivalent `enableScripts: false`). A malicious `preinstall` / `postinstall` hook in committed `package.json` cannot read the synthesized token env vars, even though they exist in the install subprocess. For a pnpm or yarn workspace, the agent builds your in-repo dependency closure as a separate step **after** the install's auth is torn down, so build scripts never see the tokens either.
 - **Stderr is redacted.** If the install fails, the agent masks every token literal out of the surfaced stderr / stdout chunks before logging.
 - **Job-scoped env-var names.** The synthesized auth env var is `KICI_NPM_TOKEN_<jobIdShort>_<i>` where `jobIdShort` is the first 8 chars of the dispatched job id. The name is unguessable from outside the install subprocess and not reused across jobs.
@@ -950,7 +980,7 @@ The dashboard JSON lives at `infra/terraform/modules/grafana/dashboards/install-
 ## See also
 
 - [Secrets](https://docs.kici.dev/user/secrets/) — how to seed the `<context>:<secret-name>` values referenced by `tokenSecret` / `installEnv`.
-- [Contexts](https://docs.kici.dev/user/contexts/) — protection rules (`branch_restrictions`, `requires_review`, `minimum_trust`) that the install gate inherits.
+- [Contexts](https://docs.kici.dev/user/contexts/) — protection rules (branch restrictions, required reviewers, minimum trust) that the install gate inherits.
 - [Operator: `kici-admin org-settings`](https://docs.kici.dev/operator/orchestrator/kici-admin/org-settings/#org-settings----org-level-security-policy) — the `allow_http_npm_registries` toggle and other org-scoped knobs.
 
 ---
@@ -1068,6 +1098,107 @@ and the step never holds signing credentials — the orchestrator mints and sign
 the token on the step's behalf from its own run records. Like `attestProvenance`,
 it is only available inside a running job step.
 
+## ID-token claims and cloud trust policies
+
+A cloud provider's OIDC trust policy decides which builds may assume a role. The
+token below is what your policy matches on, so read this section before you
+write one.
+
+### The claim set
+
+| Claim                         | Value                                                                                                            |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `iss`                         | Your orchestrator's provenance issuer                                                                            |
+| `aud`                         | The audience you asked for                                                                                       |
+| `sub`                         | The build identity — see the two shapes below                                                                    |
+| `repository`                  | `owner/repo` the run acted on                                                                                    |
+| `ref`                         | The branch or tag the run PRESENTS. For a pull request this is the **base** branch, not the contributor's branch |
+| `base_ref`                    | The same value as `ref`, named the way GitHub Actions names it                                                   |
+| `head_ref`                    | The pull request's HEAD branch; `''` for a non-PR run                                                            |
+| `head_repository`             | `owner/repo` of the pull-request HEAD — the contributor's fork for a fork PR; `''` for a non-PR run              |
+| `is_fork`                     | `'true'`, `'false'`, or `'unresolved'`                                                                           |
+| `event_name`                  | The event that started the run (`push`, `pull_request:opened`, `schedule`, …)                                    |
+| `trust_tier`                  | The resolved trust tier of the triggering actor, or `'unresolved'`                                               |
+| `actor`                       | Provider login of the triggering actor                                                                           |
+| `sha`                         | The run's commit                                                                                                 |
+| `workflow_ref`                | `<workflow name>@<sha>`                                                                                          |
+| `kici_run_id` / `kici_job_id` | The run and job this token was minted for                                                                        |
+| `org_id`                      | Your organization id                                                                                             |
+
+Every claim in the table is **always present**. A value the run did not resolve
+is `''` or `'unresolved'`, never omitted and never guessed. That matters: an
+absent claim makes a `StringEquals` condition pass, which would silently remove
+a constraint you wrote expecting it to be enforced.
+
+### The two `sub` shapes
+
+```
+push, tag, schedule, …     repo:<owner/repo>:ref:<ref>:workflow:<workflow name>
+pull request, review       repo:<owner/repo>:pull_request
+```
+
+The pull-request shape carries **no ref segment**, mirroring GitHub Actions. A
+pull request's `ref` is its base branch. So a ref-bearing subject would be
+identical for a fork pull request targeting `main` and a trusted push to `main`.
+A policy pinning that subject would hand your cloud role to any contributor who
+opened a pull request running the same workflow.
+
+**A re-run keeps the shape of the run it repeats.** Re-running a pull-request
+run presents `repo:<owner/repo>:pull_request`, because it rebuilds the same
+commit from the same source. Its `event_name` claim still reads `rerun` — that
+claim says what started the run, while `sub` says which identity the run
+presents. A policy that pins the branch-shaped subject therefore does not match
+a re-run of a pull request, which is the same protection the first run gets.
+
+### A worked AWS trust policy
+
+Pin `sub`, and pin the fork context too. `sub` alone tells you a pull request
+ran; it does not tell you whose code ran.
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Principal": { "Federated": "arn:aws:iam::123456789012:oidc-provider/orch.example.com" },
+      "Action": "sts:AssumeRoleWithWebIdentity",
+      "Condition": {
+        "StringEquals": {
+          "orch.example.com:aud": "sts.amazonaws.com",
+          "orch.example.com:sub": "repo:acme/app:ref:main:workflow:deploy",
+          "orch.example.com:is_fork": "false",
+          "orch.example.com:head_repository": "acme/app",
+          "orch.example.com:trust_tier": "trusted"
+        }
+      }
+    }
+  ]
+}
+```
+
+This grants the role only to a run on `main` in `acme/app`, from code in that
+same repository, triggered by an actor your orchestrator resolved as trusted.
+A fork pull request fails on all three of the extra conditions, and a run whose
+context did not resolve fails too — `'unresolved'` matches none of them, so the
+policy fails closed.
+
+To let a same-repo pull request assume the role, add a second statement pinning
+`"sub": "repo:acme/app:pull_request"` alongside `"is_fork": "false"` and
+`"head_repository": "acme/app"`.
+
+### Migrating an existing policy
+
+If you already pin a ref-bearing `sub` for pull-request runs, that policy stops
+matching once you upgrade — which is the fix, because it was matching runs it
+should not have. Move it to `repo:<owner/repo>:pull_request` plus the fork
+conditions above. The same move covers a re-run of a pull request, which
+presents the pull-request subject too.
+
+While you migrate, `KICI_OIDC_LEGACY_PR_SUB=1` on the orchestrator restores the
+old subject. It restores the collision with it, so treat it as a short bridge,
+not a setting. See [deprecations](https://docs.kici.dev/user/deprecations/).
+
 ## Verifying an attestation
 
 Verify a bundle with the `kici verify-attestation` command. It establishes the