@kici-dev/compiler 0.5.0 → 0.6.1

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

@@ -1,6 +1,6 @@
-# KiCI Workflow features
+# KiCI Workflow features: access and approval
 
-This bundle covers: Workflow features: concurrency, contexts, secrets, approvals, provenance, events.
+This bundle covers: Deployment contexts, scoped secrets, private registries, approvals, provenance, dashboard and account access.
 
 ## Account and sign-in
 
@@ -196,6 +196,10 @@ Here `build-plan` runs, then the job pauses for a `dba` approval. On approval, `
 
 Because a step-level hold keeps an agent and its workspace occupied for the whole human wait, prefer job- or workflow-level gates when you do not need prior-step state, and keep step-level timeouts short. See the [operator note on agent occupancy](https://docs.kici.dev/operator/approvals/#agent-occupancy-during-step-level-holds).
 
+### Not available on organization-wide workflows
+
+An `approval` gate applies to per-repository workflows only. A workflow whose trigger carries `repos:` — an [organization-wide workflow](https://docs.kici.dev/user/global-workflows/) — is dispatched by a path that never consults the gate, so the gate would not hold anything. `kici compile` refuses it with `error [E124]` at the workflow level and on any static job, rather than accepting a security control the workflow does not have. Drop the `approval`, or move the gated jobs into a workflow whose triggers carry no `repos:`. A job produced by a `dynamicJob` generator never passes through the compiler, so that one is caught at dispatch instead: the orchestrator logs an error naming the workflow and job, and runs it ungated.
+
 ## Drift gates (`when: 'drift'`)
 
 A `when: 'drift'` gate is **step-scope only** and requires a [check/apply step](https://docs.kici.dev/user/idempotent-steps/). Instead of pausing unconditionally, it fires **between the step's `check` and `run`, only when `check` finds drift in apply mode** — exactly Terraform's plan→apply, scoped to one step. When the step is already in sync (no drift), nothing pauses and the step skips.
@@ -228,7 +232,7 @@ A `when: 'drift'` gate on a step without a `check` facet, or at job/workflow sco
 
 ## Mandatory vs. explicit gates
 
-`approval` is the **explicit** gate — a deliberate "pause for a human here" written by the workflow author. It composes with the **mandatory** gate an operator can attach to a protected context via required reviewers (see [Contexts](https://docs.kici.dev/user/contexts/#required-reviewers)). When both apply to the same job, all clauses from both sources must be satisfied before the job is released. The two funnel into one held-element mechanism, so the dashboard queue and `kici approve` work the same way regardless of which source held the element.
+`approval` is the **explicit** gate — a deliberate "pause for a human here" written by the workflow author. It composes with the **mandatory** gate an operator can attach to a protected context via required reviewers (see [Contexts](https://docs.kici.dev/user/contexts/#required-reviewers)). When both apply to the same job, all clauses from both sources must be satisfied before the job is released. A workflow-level `approval` is one of those sources. It gates every root job, so a root job that also binds a context with required reviewers must satisfy the workflow clauses, its own job clauses, and the context's reviewers. The sources funnel into one held-element mechanism, so the dashboard queue and `kici approve` work the same way regardless of which source held the element.
 
 ## Approving from the CLI
 
@@ -250,1629 +254,437 @@ kici reject <run-id> --job deploy-production --reason "Wrong release branch"
 
 You must be eligible for at least one unsatisfied clause — being a member of a named team or being a named user. The orchestrator verifies eligibility against the operator-defined teams, so naming a team in your workflow can never let an ineligible person release the gate. The command reports whether the element was released, how many clauses remain, or that it was rejected. See [`kici approve`](https://docs.kici.dev/user/cli/runs-and-approvals/#kici-approve) for the full command reference.
 
-### Inline approval and `--approve-all` in `kici run remote`
-
-When you trigger a run with `kici run remote` and it pauses on a gate, the CLI prints the gate (and, for a drift gate, the computed drift) and — in an interactive terminal — prompts you to approve or reject right there, without leaving the watch. In a non-interactive shell it prints how to approve out of band and keeps watching.
-
-To auto-approve **every gate of the run you just dispatched**, pass `--approve-all` (alias `--yes`):
-
-```bash
-kici run remote deploy-prod --approve-all
-```
-
-`--approve-all` is **run-scoped** — it only auto-approves holds belonging to the run this invocation dispatched; there is no fleet-wide or account-wide auto-approve. Eligibility is still enforced per hold: if you are not eligible for a gate, that gate still blocks. Each auto-approved gate prints its payload before resolving and is recorded distinctly in the audit trail (`held_run.auto_approve`).
-
-`--approve-all` is honored in non-interactive runs too: with `--json` or `--quiet` (no TTY), the flag still auto-approves each eligible gate as it appears instead of hanging or printing out-of-band instructions. Hold notices are routed to stderr so `--json` stdout stays pure machine-readable output.
-
-You can also approve from the dashboard approval queue. See [Dashboard](https://docs.kici.dev/user/dashboard/contexts-and-secrets/#approval-queue).
-
-## See also
-
-- [Idempotent steps](https://docs.kici.dev/user/idempotent-steps/) — the check/apply step facet that drift gates build on.
-- [Contexts](https://docs.kici.dev/user/contexts/) — operator-required reviewers on protected contexts.
-- [Approval gates (operator guide)](https://docs.kici.dev/operator/approvals/) — teams, the approval queue, expiry, and self-approval.
-- [Approval gates (architecture)](https://docs.kici.dev/architecture/approvals/) — the unified hold model and the step-level round-trip.
-
----
-
-## Concurrency groups
-
-Source: https://docs.kici.dev/user/concurrency/
-
-Concurrency groups prevent multiple workflow runs from executing in parallel when they target the same resource. Common use cases include preventing parallel deploys to the same environment or serializing database migrations.
-
-## Basic usage
-
-```typescript
-import { workflow, job, step, push } from '@kici-dev/sdk';
-
-export default workflow('deploy', {
-  on: push({ branches: ['main', 'staging'] }),
-  concurrency: {
-    group: (ctx) => `deploy-${ctx.branch}`,
-    cancelInProgress: true,
-    max: 1,
-  },
-  jobs: [
-    job('deploy', {
-      runsOn: 'linux',
-      steps: [
-        step('deploy', async ({ $ }) => {
-          await $`./deploy.sh`;
-        }),
-      ],
-    }),
-  ],
-});
-```
-
-## Configuration
-
-The `concurrency` option on a workflow accepts:
-
-| Field              | Type     | Default  | Description                                |
-| ------------------ | -------- | -------- | ------------------------------------------ |
-| `group`            | Function | Required | Returns the concurrency group key string   |
-| `cancelInProgress` | boolean  | `true`   | Cancel older runs when a newer run arrives |
-| `max`              | number   | `1`      | Maximum concurrent runs in the same group  |
-
-### Group key function
-
-The group key function receives a context with the branch name and event payload. Runs with the same group key are subject to concurrency limits.
-
-```typescript
-// Per-branch concurrency (most common)
-group: (ctx) => `deploy-${ctx.branch}`;
-
-// Global concurrency (across all branches)
-group: () => 'deploy';
-
-// Per-target-branch concurrency
-group: (ctx) => `deploy-${ctx.event.targetBranch ?? 'default'}`;
-```
-
-The workflow-level group function is always evaluated **agent-side** at runtime -- the lock file records only that a group function exists (`hasGroup: true`), not the function itself. The agent loads the workflow source, calls the group function with `{ branch, event }`, and reports the evaluated key back to the orchestrator before step execution begins. 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
-
-When `cancelInProgress: true`, a newer run supersedes older runs in the same group:
-
-```
-Run #1 starts deploying to main        -> running
-Run #2 arrives for deploy-main group   -> Run #1 cancelled ("Superseded by run in concurrency group 'deploy-main'")
-Run #2 continues                       -> running
-```
-
-This is the most common mode for deploy workflows -- you want the latest code deployed, not an outdated version.
-
-The cancelled run:
-
-- Receives a cancellation with reason "Superseded by run in concurrency group 'deploy-main'"
-- Goes through the normal cancel flow (grace period, hooks if graceful)
-- GitHub Check status updated to `cancelled` with the superseded reason
-
-```typescript
-workflow('deploy', {
-  concurrency: {
-    group: (ctx) => `deploy-${ctx.branch}`,
-    cancelInProgress: true,
-  },
-  jobs: [/* ... */],
-});
-```
-
-## Queue mode
-
-When `cancelInProgress: false`, newer runs will wait until older runs complete:
-
-```
-Run #1 starts deploying                -> running
-Run #2 arrives for same group          -> queued ("Waiting for deploy-main (1 ahead)")
-Run #1 completes                       -> success
-Run #2 starts                          -> running
-```
-
-In queue mode, the agent that picked up the queued run **stays connected** to the orchestrator and parks on a long-poll wait. When the holder finishes (success, failure, or cancel), the orchestrator dequeues the FIFO-next entry and pushes a `proceed` notification over the same WebSocket; the queued agent then continues with normal step execution against the workspace it already has. The agent's slot is therefore held for the duration of the queue wait — bound by `KICI_CONCURRENCY_WAIT_TIMEOUT_MS` (default 1 hour).
-
-```typescript
-workflow('migrate-db', {
-  concurrency: {
-    group: () => 'migrations',
-    cancelInProgress: false,
-    max: 1,
-  },
-  jobs: [/* ... */],
-});
-```
-
-The dashboard will show a "Queued" badge with the reason: "Waiting for deploy-main (1 ahead)".
-
-## Max concurrent runs
-
-The `max` field controls how many runs can execute simultaneously in the same group:
-
-```typescript
-// Allow up to 3 parallel test runs per branch
-workflow('test', {
-  concurrency: {
-    group: (ctx) => `test-${ctx.branch}`,
-    cancelInProgress: false,
-    max: 3,
-  },
-  jobs: [/* ... */],
-});
-```
-
-When `max: 1` (default), runs are fully serialized within the group.
-
-## Group key examples
-
-### Deploy per environment
-
-```typescript
-workflow('deploy', {
-  concurrency: {
-    group: (ctx) => `deploy-${ctx.branch}`,
-    cancelInProgress: true,
-  },
-  jobs: [
-    job('deploy-staging', {
-      runsOn: 'linux',
-      context: 'staging',
-      steps: [/* ... */],
-    }),
-  ],
-});
-```
-
-### Global singleton
-
-```typescript
-// Only one migration can run at a time, regardless of branch
-workflow('migrate', {
-  concurrency: {
-    group: () => 'db-migration',
-    cancelInProgress: false,
-  },
-  jobs: [/* ... */],
-});
-```
-
-### Environment-aware groups
-
-```typescript
-// Serialize deploys per environment
-workflow('deploy', {
-  concurrency: {
-    group: (ctx) => {
-      const env = ctx.branch === 'main' ? 'production' : 'staging';
-      return `deploy-${env}`;
-    },
-    cancelInProgress: true,
-  },
-  jobs: [/* ... */],
-});
-```
-
-## Interaction with context protection
-
-When a workflow has both `concurrency` and `context` protection rules:
-
-1. Context protection gates (required reviewers, wait timer) apply first
-2. Concurrency group check happens after protection gates pass
-3. If the run is queued by concurrency, it keeps its protection approval
-
-This means a run that passed approval won't need re-approval if it gets queued by concurrency.
-
-## 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.
-
-## Job-level concurrency groups
-
-In addition to workflow-level concurrency, individual jobs can define their own concurrency group via the `concurrencyGroup` property. This controls concurrent execution at the job level rather than the workflow level. See [Contexts — concurrency groups](https://docs.kici.dev/user/contexts/#concurrency-groups) for details.
-
-## Local execution
-
-`kici run <event> --local` is a real routed dispatch: your machine becomes an ephemeral agent behind the local dev plane, whose own orchestrator applies the same concurrency machinery described above. The `group` callback is evaluated agent-side against the simulated event, and `cancelInProgress` carries its usual semantics — `true` supersedes the older run in the group, `false` queues the newer one behind it.
-
-Coordination is scoped to that plane. The plane's state (including its database) lives under `~/.kici/local/`, so enforcement is per-machine and per-user: running the same workflow on two different machines does not serialize across them. For cross-host enforcement (queueing across agents, dashboard visibility), use `kici run remote` against a deployed orchestrator.
-
-See [`kici run <event> --local`](https://docs.kici.dev/user/cli/runs-and-approvals/#kici-run-event---local) for the rest of the local-run behavior, and [the local dev plane](https://docs.kici.dev/operator/orchestrator/local-dev-plane/) for the plane's state directory and lifecycle.
-
----
-
-_Source: `packages/sdk/src/types.ts` (WorkflowOptions.concurrency, JobOptions.concurrencyGroup)_
-
----
-
-## Contexts
-
-Source: https://docs.kici.dev/user/contexts/
-
-<!-- help:contexts-list#overview -->
-
-Contexts are named deployment targets (like staging or production) that control where your workflow jobs run. Each context can have its own variables, secrets, and protection rules to gate deployments.
-
-<!-- /help:contexts-list -->
-
-<!-- help:contexts-protection#protection-rules -->
-
-Protection rules control when jobs targeting a context can execute.
-
-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.
-
-<!-- /help:contexts-protection -->
-
-Contexts represent deployment targets like `staging`, `production`, or `review/PR-*`. Each context can have its own variables, bound secrets, and protection rules that control when and how jobs targeting that context can execute.
-
-## Overview
-
-A context in KiCI provides:
-
-- **Variables** -- non-secret key-value configuration (e.g., `API_URL`, `CLUSTER_NAME`)
-- **Scoped secrets** -- encrypted values bound to the context via scope bindings
-- **Protection rules** -- branch restrictions, required reviewers, wait timers, and concurrency limits
-- **Per-source overrides** -- repositories can override unlocked variables for their own deployments
-
-## SDK API
-
-### Job-level context property
-
-The `context` property is set on a job, not a workflow or step:
-
-```typescript
-import { workflow, job, step, push } from '@kici-dev/sdk';
-
-export default workflow('deploy', {
-  on: [push({ branches: ['main'] })],
-  jobs: [
-    job('deploy-staging', {
-      runsOn: 'default',
-      context: 'staging',
-      steps: [
-        step('deploy', async (ctx) => {
-          // ctx.context is the resolved context name
-          console.log(`Deploying to ${ctx.context}`);
-          // ctx.secrets provides async get/expose/has methods for context-bound secrets
-          const dbPassword = await ctx.secrets.get('DB_PASSWORD');
-          // Environment variables are in ctx.env
-          const apiUrl = ctx.env.API_URL;
-          await ctx.$`deploy --target ${ctx.context}`;
-        }),
-      ],
-    }),
-  ],
-});
-```
-
-### Dynamic contexts
-
-The context name can be a string or a function (sync or async) for dynamic contexts (e.g., per-PR review contexts). The function receives the normalized event envelope, with the raw provider body nested at `event.payload`:
-
-```typescript
-job('deploy-review', {
-  runsOn: 'default',
-  context: (event) => `review/PR-${event.payload.pull_request.number}`,
-  steps: [
-    step('deploy', async (ctx) => {
-      // ctx.context is 'review/PR-123' (resolved at runtime)
-      await ctx.$`deploy-preview --env ${ctx.context}`;
-    }),
-  ],
-});
-```
+### When a job is held twice
 
-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.
+A job can carry an `approval` gate **and** a [security hold](https://docs.kici.dev/user/contexts/#security-approval-queue) at the same time. Two setups reach it: a fork pull request on an organization whose fork policy is `hold`, and a context that sets both required reviewers and `minimumTrust`.
 
-### Multiple contexts per job
+The two are separate holds and **both** must be released before the job runs. They take different permissions: the approval hold needs `contexts:write` plus clause eligibility, the security hold needs `ci_trust:write`.
 
-A job can bind more than one context with `contexts`, an ordered array. This lets a single job draw secrets and variables from several contexts at once — for example a shared `staging` context plus a `my-testing` context that carries test-only variables:
+`--job` names both at once, so pick one with `--hold-type`:
 
-```typescript
-job('deploy', {
-  runsOn: 'default',
-  contexts: ['staging', 'my-testing'],
-  steps: [
-    step('deploy', async (ctx) => {
-      // ctx.secrets and ctx.env carry the merged set from both contexts
-      const dbUrl = await ctx.secrets.get('DB_URL');
-    }),
-  ],
-});
+```bash
+kici approve <run-id> --job deploy --hold-type reviewer
+kici approve <run-id> --job deploy --hold-type security
 ```
 
-- `context` (singular) and `contexts` (array) are mutually exclusive — setting both is a compile error. `context: 'staging'` is exactly equivalent to `contexts: ['staging']`.
-- Each array entry is a static name or a function of the event, resolved per element exactly like a single dynamic context.
-
-**Merge order — last wins.** All bound contexts are resolved on every dispatch (webhook, scheduled, and test runs alike) and merged in array order. When the same secret or variable key is defined in more than one context, the later entry in the array wins. With `contexts: ['staging', 'my-testing']`, a key defined in both resolves to `my-testing`'s value; keys defined in only one are preserved. The longest-scope-path-wins rule still applies _within_ each context.
-
-**Protection rules combine all-must-pass.** A job must satisfy **every** bound context's gates — adding a context can never loosen access. Branch restrictions, trigger-type filters, and repo patterns must pass for all contexts; the minimum trust tier is the most restrictive across them; required reviewers are the union of all contexts' reviewers; the wait timer is the longest; and the hold expiry is the shortest. If a run is gated out, the rejection names which context and which rule rejected it (visible via `kici runs show <run-id>` and the run's rejection reason), so a mutually-exclusive set of rules surfaces as a clear failure rather than a silent perpetual rejection.
+Pass `--hold <id>` when the command's error lists two holds that `--hold-type` still cannot separate. The pull request's `KiCI Security` check stays pending until both holds have ended, and its description names the second gate and the permission that clears it.
 
-**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.
+Each hold carries its own expiry, so the job is cancelled when the **first** one runs out.
 
-**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.
+### Inline approval and `--approve-all` in `kici run remote`
 
-### Job-level environment variables
+When you trigger a run with `kici run remote` and it pauses on a gate, the CLI prints the gate (and, for a drift gate, the computed drift) and — in an interactive terminal — prompts you to approve or reject right there, without leaving the watch. In a non-interactive shell it prints how to approve out of band and keeps watching.
 
-The `env` property on a job provides static or dynamic environment variables:
-
-```typescript
-job('deploy', {
-  runsOn: 'default',
-  context: 'production',
-  env: { DEPLOY_TARGET: 'us-east-1' },
-  // Or dynamic:
-  // env: (event) => ({ DEPLOY_SHA: event.payload.after?.slice(0, 7) }),
-  steps: [
-    step('deploy', async (ctx) => {
-      // DEPLOY_TARGET is available in ctx.env
-      await ctx.$`deploy --region ${ctx.env.DEPLOY_TARGET}`;
-    }),
-  ],
-});
-```
-
-### Concurrency groups
-
-Jobs can define their own concurrency groups to control concurrent execution within a context. For workflow-level concurrency (which applies to all jobs in a workflow), see [Concurrency groups](https://docs.kici.dev/user/concurrency/).
-
-Control concurrent deployments to the same context:
-
-```typescript
-job('deploy', {
-  runsOn: 'default',
-  context: 'production',
-  concurrencyGroup: 'production-api',
-  // Or dynamic:
-  // concurrencyGroup: (event) => `review-${event.payload.pull_request.number}`,
-  steps: [/* ... */],
-});
-```
-
-If no `concurrencyGroup` is specified, the context name is used as the default concurrency group. For a job bound to multiple contexts, the default is the **first** bound context's name.
-
-### Step context
-
-Inside a step, the `ctx` object provides:
-
-| Property      | Type                                  | Description                                                                               |
-| ------------- | ------------------------------------- | ----------------------------------------------------------------------------------------- |
-| `ctx.context` | `string \| undefined`                 | Resolved context name (undefined for jobs without context)                                |
-| `ctx.env`     | `Record<string, string \| undefined>` | Environment variables (merged from system, org, source, and job-level `env`)              |
-| `ctx.secrets` | `StepSecretsTyped`                    | Async accessor for bound secrets (get, expose, has, getMeta, list, mountFile, exposeFile) |
-
-| Method                                       | Returns                   | Description                                                                                                                                                        |
-| -------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `await ctx.secrets.get(key)`                 | `string`                  | Retrieve a secret value. Throws `SecretNotFoundError` if not found.                                                                                                |
-| `await ctx.secrets.expose(key)`              | `void`                    | Set the secret as an environment variable for this step — visible via `ctx.env` and to child processes (`process.env`). Throws `SecretNotFoundError` if not found. |
-| `ctx.secrets.has(key)`                       | `boolean`                 | Check if a secret key exists. Synchronous, never throws.                                                                                                           |
-| `ctx.secrets.getMeta(key)`                   | `SecretMeta \| undefined` | Retrieve metadata (value, backend name, scope path) for a resolved secret. Returns `undefined` if not found.                                                       |
-| `ctx.secrets.list()`                         | `string[]`                | Every secret key available to the step, sorted alphabetically. Synchronous, never throws.                                                                          |
-| `await ctx.secrets.mountFile(opts)`          | `{ path }`                | Materialise one or more secrets to a per-step tmpfile (auto-removed at step end). See [Secrets → Mounting secrets as files](https://docs.kici.dev/user/secrets/#mounting-secrets-as-files). |
-| `await ctx.secrets.exposeFile(envVar, opts)` | `{ path }`                | `mountFile` plus `process.env[envVar] = path`; the env var is unset at step end.                                                                                   |
-| `ctx.setSecretOutput(key, val)`              | `void`                    | Publish an encrypted secret output from this job, consumable by downstream jobs via `needs`. Never logged or stored in plaintext.                                  |
-
-The full secrets API — including `SecretFileOptions`, log masking, and the canonical `sops` example — is documented in [Secrets](https://docs.kici.dev/user/secrets/).
-
-## Environment variable merge precedence
-
-When a job targets a context, variables are merged in this order (last wins):
-
-1. **Allowed system vars** -- `PATH`, `HOME`, etc. from the agent process
-2. **Sandbox defaults** -- `FORCE_COLOR=1`
-3. **KICI\_\* system vars** -- orchestrator-generated metadata
-4. **Org-level context vars** -- from the dashboard, managed per-context
-5. **Source-level overrides** -- per-repository overrides (skips locked vars)
-6. **Job env** -- from the `env` property in the SDK
-7. **`setEnv()` calls** -- runtime modifications within steps
-
-> **Note:** Secrets are NOT part of the environment variable merge. They are delivered to the step context via IPC and accessed through `ctx.secrets`, not through `process.env`. See the [step context](https://docs.kici.dev/user/contexts/#step-context) section above.
-
-## Protection rules
-
-Contexts can have protection rules that gate job execution:
-
-### Branch restrictions
-
-Limit which branches can deploy to a context:
-
-```
-Allowed branches: main, release/*
-```
-
-Jobs from other branches are rejected immediately with an error message.
-
-### Required reviewers
-
-Require manual approval before a job can proceed:
-
-```
-Required reviewers: alice, bob
-```
-
-When reviewers are required, the job enters a "held" state. Reviewers can approve or reject via the dashboard, the [`kici approve`](https://docs.kici.dev/user/cli/runs-and-approvals/#kici-approve) command, or the API. Held runs expire after a configurable timeout.
-
-This operator-set rule is the **mandatory** form of an approval gate. Workflow authors can also declare gates in code with `approval` at step, job, or workflow level — see [Approval gates](https://docs.kici.dev/user/approvals/). Both forms use the same held-element mechanism and the same queue.
-
-### Wait timer
-
-Add a mandatory delay before deployment starts:
-
-```
-Wait timer: 300 seconds
-```
-
-The job waits for the specified duration before proceeding. Useful for staged rollouts.
-
-### Minimum trust
-
-Gate job execution based on the contributor's trust tier for PR-triggered runs:
-
-```
-Minimum trust: known
-```
-
-| Value     | Effect                                              |
-| --------- | --------------------------------------------------- |
-| `known`   | Blocks unknown contributors; allows known + trusted |
-| `trusted` | Blocks unknown + known; allows only trusted         |
-
-When a contributor does not meet the minimum trust level, the job is held in the security approval queue. Someone with `ci_trust:write` or higher must approve it before execution proceeds.
-
-Trust tier is determined by the contributor's identity link and CI trust RBAC level:
-
-- **Trusted** -- identity-linked org member with `ci_trust:write+` AND provider write access
-- **Known** -- identity-linked member or verified collaborator via provider API
-- **Unknown** -- no identity link and no provider access, fork PRs
-
-The trust tier also affects which lock file is used for PR-triggered runs: trusted contributors use the PR head lock file, while known and unknown contributors use the base branch lock file. This prevents untrusted workflow modifications from affecting execution.
-
-See the [CI security architecture docs](https://docs.kici.dev/architecture/security/ci-security/) for the full trust resolution flow.
-
-### Security approval queue
-
-When a PR is held for security review — the org trust policy held it (a non-trusted contributor modified `.kici/` files, the PR came from a fork, or the contributor could not be resolved to a known identity), or a `minimumTrust` gate blocked the contributor — it enters the security approval queue. This is separate from the context approval queue: a security hold asks "is it safe to run this contributor's code at all?", while a context approval hold asks "should this job be promoted?". The two never cross — releasing a security hold needs `ci_trust:write` or higher, releasing a context approval hold needs `contexts:write` plus eligibility for one of the gate's clauses. See [Approval holds vs security holds](https://docs.kici.dev/architecture/approvals/#approval-holds-vs-security-holds) for the full comparison.
-
-Held runs can be approved:
-
-- Via the **dashboard** in Settings > CI trust > Approval queue
-- Via a PR comment: `/kici approve` (commenter must have `ci_trust:write+`)
-
-A hold raised by the org trust policy covers the whole PR and uses the org's approval expiry (default 72 hours). A `minimumTrust` hold is raised by a context rather than by the org policy, so it uses that context's own hold expiry (default one hour).
-
-While the org trust policy is holding a pull request, your organization's global workflows do not run for it. Approving the hold releases that pull request's own workflows; it does not retroactively run the organization's global workflows for the event.
-
-### Concurrency limits
-
-Control how many jobs can run simultaneously in a context:
-
-```
-Concurrency limit: 1
-Strategy: queue (or cancel-pending)
-```
-
-The concurrency limit is a positive integer; leave it unset for unlimited concurrency.
-
-- **queue** -- new jobs wait in a FIFO queue (with configurable timeout, default 1 hour)
-- **cancel-pending** -- pending (queued) jobs are cancelled when the limit is reached
-
-## Dashboard management
-
-### Creating contexts
-
-Navigate to **Settings > Contexts** in the dashboard. Click **New context** to choose the context name and type (Fixed or Glob).
-
-- **Fixed** -- applies to jobs that declare exactly this context name, like `staging` or `production`
-- **Glob** -- applies to any context name a job declares that matches the pattern, e.g. `review/*` matches a job with `context: 'review/PR-123'`
-
-The contexts list shows each context's type, whether test runs may use it (the `allowLocalExecution` flag -- see the [testing guide](https://docs.kici.dev/user/testing-guide/)), and whether it is enabled.
-
-### Context detail page
-
-Each context has four tabs:
-
-1. **Variables** -- manage key-value pairs with lock toggles. Locked variables cannot be overridden by source-level overrides. Source overrides are managed in a sub-tab.
-
-2. **Secrets** -- view bound secret scopes and their resolved secret count. Add bindings by specifying scope glob patterns (e.g., `aws/prod/**`).
-
-3. **Protection** -- configure branch restrictions, required reviewers, wait timers, and concurrency limits with enable toggles for each section. Turning a section's toggle off and saving clears that rule on the context, so the gate stops applying to new runs. Emptying the hold expiry field clears it too, and held runs fall back to the default one-hour hold window.
-
-4. **History** -- view filtered runs targeting this context.
-
-### Bound contexts on runs
-
-A job's bound deployment contexts are shown as chips on the run detail page (in the job metadata panel) in the order the job declared them, and the distinct set across a run's jobs appears as compact chips on the run list. For a multi-context job the chips read left-to-right in merge order — later contexts override earlier ones on key collisions. A `(dynamic)` chip marks a context whose name is computed at runtime; it resolves to the real name once the run starts. A job that binds a single context shows one chip; a job that binds none shows no chip.
-
-If a multi-context binding is gated out, the run's failure banner names which context and which rule rejected it (the same all-must-pass detail surfaced by `kici runs show <run-id>`).
-
-### Secrets management
-
-Secrets are individual encrypted values organized by scope paths (e.g., `aws/prod`, `databases/postgres`). Scopes are bound to contexts via bindings:
-
-- **Scope-centric view** (Secrets page): tree view of scopes with per-scope context binding checkboxes
-- **Context-centric view** (inside context detail): bound scopes, resolved secrets, add binding
-
-When scope paths collide on the same key name, the longer (more specific) path wins.
-
-## Type generation
-
-Running `kici types` generates two augmented interfaces: `KnownSecretKeys` (union of all secret keys across all contexts) and `ContextSecrets` (per-context key unions):
-
-```typescript
-interface KnownSecretKeys {
-  DB_PASSWORD: string;
-  API_KEY: string;
-}
-
-interface ContextSecrets {
-  production: 'DB_PASSWORD' | 'API_KEY';
-  staging: 'DB_PASSWORD';
-}
-```
-
-`KnownSecretKeys` narrows `ctx.secrets.get()` and `ctx.secrets.expose()` key parameters to valid key names. `ContextSecrets` maps each context to its available secret key names as a string union. Dynamic contexts fall back to the full `KnownSecretKeys` union.
-
----
-
-## Dashboard
-
-Source: https://docs.kici.dev/user/dashboard/
-
-The KiCI dashboard is the browser interface for monitoring workflow runs, inspecting jobs and logs, and managing your organization. It signs in via OIDC and talks to KiCI over its API.
-
-This guide is split across the following pages:
-
-| Page                                                                                  | Covers                                                                        |
-| ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| [Getting started](https://docs.kici.dev/user/dashboard/getting-started/)                                     | Onboarding checklist and your organizations list                              |
-| [Navigation and layout](https://docs.kici.dev/user/dashboard/navigation/)                                    | Sidebar, mobile nav, theme, time display, shortcuts, error pages              |
-| [Runs and logs](https://docs.kici.dev/user/dashboard/runs/)                                                  | Run list, run detail, the log viewer                                          |
-| [Settings](https://docs.kici.dev/user/dashboard/settings/)                                                   | Members, roles, teams, keys, sources, billing, security, support access       |
-| [Workflows, diagnostics, and orchestrators](https://docs.kici.dev/user/dashboard/workflows-and-diagnostics/) | Registered workflows, infra health, per-cluster views                         |
-| [Contexts, secrets, and approvals](https://docs.kici.dev/user/dashboard/contexts-and-secrets/)               | Contexts, secret scopes, approval queue                                       |
-| [Activity and DLQ](https://docs.kici.dev/user/dashboard/activity-and-dlq/)                                   | Forensic activity log and dead-letter queue                                   |
-| [Notifications](https://docs.kici.dev/user/dashboard/notifications/)                                         | Personal run notifications and org-wide channels, subscriptions, delivery log |
-| [Account](https://docs.kici.dev/user/dashboard/account/)                                                     | Personal account settings                                                     |
-
----
-
-## Dynamic values
-
-Source: https://docs.kici.dev/user/dynamic-values/
-
-Dynamic values let you compute `context`, `env`, and `concurrencyGroup` at runtime based on the incoming event. Instead of hardcoding static strings, you pass a function that receives the normalized event envelope and returns the resolved value.
-
-```typescript
-job('deploy', {
-  runsOn: ['default'],
-  context: (event) => event.targetBranch,
-  env: (event) => ({ BRANCH: event.targetBranch }),
-  concurrencyGroup: (event) => `deploy-${event.targetBranch}`,
-  steps: [/* ... */],
-});
-```
-
-```typescript
-job('deploy', {
-  runsOn: 'default',
-  // One shape everywhere: branch on the normalized event type.
-  context: (event) => (event.type === 'pull_request' ? 'preview' : 'production'),
-  steps: [/* ... */],
-});
-```
-
-## How it works
-
-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:
-
-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.
-
-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.
-
-`kici preview` lists the injected `__init__` job under each affected job, so you can spot it before the first run.
-
-**Examples:**
-
-```typescript
-// Simple branch extraction
-context: (event) => event.targetBranch;
-
-// Object literal with string operations
-env: (event) => ({ BRANCH: event.targetBranch });
-
-// Concatenation with event data
-concurrencyGroup: (event) => `deploy-${event.targetBranch}`;
-
-// Local variables and safe globals
-context: (event) => {
-  const parts = event.targetBranch.split('/');
-  return parts[parts.length - 1];
-};
-
-// Async lookups, module access, and process/global reads all work
-context: async (event) => await lookupEnv(event.targetBranch);
-env: (event) => ({ DEFAULT_ENV: process.env.DEFAULT_ENV ?? 'staging' });
-```
-
-## Performance
-
-| 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
-
-- **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`, …).
-
----
-
-## Environment variables
-
-Source: https://docs.kici.dev/user/env-vars/
-
-The KiCI CLI reads the following environment variables to customize its behavior. OAuth login (`kici login` without `--token`) defaults `KICI_PLATFORM_URL`, `KICI_OIDC_ISSUER`, and `KICI_OIDC_CLIENT_ID` to the hosted KiCI Platform, so `kici login` works with no configuration. Set them only to target another KiCI environment (e.g. a testing instance) or a custom OIDC provider.
-
-## Authentication
-
-| Variable              | Description                            | Default                                      |
-| --------------------- | -------------------------------------- | -------------------------------------------- |
-| `KICI_OIDC_ISSUER`    | OIDC issuer URL for authentication     | `https://auth.kici.dev/realms/kici-internal` |
-| `KICI_OIDC_CLIENT_ID` | OIDC client ID for the CLI application | `kici-cli`                                   |
-| `KICI_PLATFORM_URL`   | Platform API base URL                  | `https://api.kici.dev`                       |
-| `KICI_CONFIG_DIR`     | Override the KiCI config directory     | `~/.kici`                                    |
-
-## Browser behavior
-
-| Variable             | Description                                                                                                                                          | Default                         |
-| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
-| `KICI_BROWSER_CMD`   | Custom browser command for OAuth login. Supports `{url}` placeholder. Set to `none` to suppress browser opening and print the URL to stdout instead. | Uses the system default browser |
-| `KICI_CALLBACK_PORT` | Fixed port for the OAuth PKCE callback server. Useful when firewall rules require a known port.                                                      | Random available port           |
-
-## 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   |
-
-## Local dev plane
-
-Read by the [local dev plane](https://docs.kici.dev/user/cli/authoring-and-local/#kici-local) that `kici run <event> --local` dispatches through.
-
-| Variable                           | Description                                                                                                                                                                         | Default              |
-| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
-| `KICI_LOCAL_ORCH_PORT`             | Port the plane orchestrator listens on (HTTP + WebSocket). Change it when another process already holds the default.                                                                | `4319`               |
-| `KICI_LOCAL_PG_PORT`               | Port the plane's PostgreSQL listens on.                                                                                                                                             | `45432`              |
-| `KICI_LOCAL_PG_MODE`               | Set to `podman` to force the container PostgreSQL fallback instead of the embedded binary.                                                                                          | Embedded PostgreSQL  |
-| `KICI_LOCAL_ACCEPTANCE_TIMEOUT_MS` | How long a local run waits for an agent to claim its first job before failing fast. Raise it on a slow host; the run still fails quickly when no scaler label set matches `runsOn`. | `120000` (2 minutes) |
-
-## CI detection
-
-The CLI also reads the conventional CI markers your CI provider sets. They are not KiCI variables — KiCI only consumes them.
-
-| Variable         | Description                                  | Default |
-| ---------------- | -------------------------------------------- | ------- |
-| `CI`             | Generic CI marker. Set by most CI providers. | unset   |
-| `GITHUB_ACTIONS` | Set to `true` by GitHub Actions.             | unset   |
-| `GITLAB_CI`      | Set to `true` by GitLab CI/CD.               | unset   |
-
-### How `CI` is interpreted
-
-`kici` treats the environment as CI when `CI`, `GITHUB_ACTIONS`, or `GITLAB_CI` is set to any value other than an explicit opt-out. `0` and `false` are the opt-outs, compared case-insensitively, so `CI=0`, `CI=false`, and `CI=False` all mean "not CI". Surrounding whitespace is ignored, and a value that is empty or only whitespace (`CI=`) is treated as unset.
-
-A vendor marker outranks the generic opt-out: `CI=false GITHUB_ACTIONS=true` is still CI, because an explicit vendor marker names a real runner rather than a preference.
-
-This affects which login flow `kici login` chooses (browser vs device) and whether interactive commands such as `kici init` prompt.
-
-## Usage examples
-
-### CI/CD environment
-
-Authenticate with a pre-existing API key (no browser needed):
+To auto-approve **every gate of the run you just dispatched**, pass `--approve-all` (alias `--yes`):
 
 ```bash
-kici login --token "$KICI_API_KEY"
-```
-
-### Targeting another environment or custom OIDC provider
-
-`kici login` targets the hosted KiCI Platform by default. To point the CLI at another KiCI environment (e.g. a testing instance) or a custom OIDC provider, override the defaults:
-
-```bash
-export KICI_OIDC_ISSUER=https://your-idp.example.com
-export KICI_OIDC_CLIENT_ID=your-client-id
-export KICI_PLATFORM_URL=https://your-platform.example.com
-kici login
-```
-
-### Headless SSH session
-
-The CLI auto-detects headless environments and uses the device flow. To force PKCE with URL output instead:
-
-```bash
-export KICI_BROWSER_CMD=none
-kici login
-```
-
-This prints the authorization URL to stdout as `KICI_AUTH_URL=<url>`. Open the URL in any browser to complete authentication.
-
-### Fixed callback port
-
-When behind a firewall or using port forwarding:
-
-```bash
-export KICI_CALLBACK_PORT=19876
-kici login
-```
-
-### Custom config location
-
-Store the KiCI config in a non-default location:
-
-```bash
-export KICI_CONFIG_DIR=/tmp/kici-test
-kici login
-```
-
----
-
-## Event system
-
-Source: https://docs.kici.dev/user/events/
-
-KiCI supports two broad categories of workflow triggers: **git-based triggers** that work immediately, and **event-based triggers** that use a registration model. Understanding this distinction is key to working effectively with non-git triggers like schedules, custom events, and generic webhooks.
-
-## Overview
-
-Git-based triggers (`push()`, `pr()`, `tag()`, `comment()`, `review()`, `release()`, etc.) work immediately after you commit your lock file. When a GitHub webhook arrives, the orchestrator fetches your lock file and evaluates triggers on the spot -- no advance setup needed.
-
-Event-based triggers work differently. The orchestrator needs to know about them _before_ the event arrives. This is because event-based triggers are matched against a pre-built registration index rather than being evaluated per-event from a lock file fetch. The six event-based trigger types are:
-
-- `kiciEvent()` -- custom events emitted from workflow steps
-- `workflowComplete()` -- fires when a workflow finishes
-- `jobComplete()` -- fires when a specific job finishes
-- `genericWebhook()` -- HTTP webhooks from external services
-- `schedule()` -- cron-based time triggers
-- `lifecycle()` -- orchestrator lifecycle events (workflow completion, job failure, registration updates)
-
-All six require the **registration model** to function -- covered in detail below.
-
-## Event types
-
-### Custom events
-
-Custom events are user-defined events emitted from workflow steps using `ctx.emit()`. Use `kiciEvent()` to listen for them.
-
-```typescript
-import { kiciEvent } from '@kici-dev/sdk';
-
-// Listen for a custom event by name
-kiciEvent({ name: 'deploy-complete' });
-
-// With payload matching (JSONPath)
-kiciEvent({ name: 'deploy-complete', match: { '$.env': 'prod' } });
-
-// With negative filter
-kiciEvent({ name: 'deploy-complete', not: { '$.env': 'staging' } });
-
-// From a specific repository
-kiciEvent({ name: 'deploy-complete', source: 'org/infra-repo' });
-```
-
-**Config options:** `name` (required), `match`, `not`, `source`, `description`.
-
-### System events
-
-The orchestrator automatically emits completion events when workflows and jobs finish. No manual emission needed -- these fire automatically.
-
-**Workflow completion:**
-
-```typescript
-import { workflowComplete } from '@kici-dev/sdk';
-
-// Any workflow completion
-workflowComplete();
-
-// Specific workflow by name
-workflowComplete({ name: 'build' });
-
-// Only successful completions
-workflowComplete({ name: 'build', status: ['success'] });
-```
-
-**Config options:** `name`, `status` (`'success'`, `'failed'`, `'cancelled'`), `source`, `description`.
-
-**Job completion:**
-
-```typescript
-import { jobComplete } from '@kici-dev/sdk';
-
-// Any job completion
-jobComplete();
-
-// Specific workflow + job
-jobComplete({ workflow: 'build', job: 'test' });
-
-// Only failures
-jobComplete({ workflow: 'build', job: 'test', status: ['failed'] });
-```
-
-**Config options:** `workflow`, `job`, `status` (`'success'`, `'failed'`, `'cancelled'`, `'skipped'`), `source`, `description`.
-
-### External events
-
-Generic webhooks let you trigger workflows from any HTTP service -- Stripe, ArgoCD, Slack, Grafana, or your own internal services.
-
-```typescript
-import { genericWebhook } from '@kici-dev/sdk';
-
-// Match any event from a source
-genericWebhook({ source: 'stripe' });
-
-// Match specific event types
-genericWebhook({ source: 'stripe', events: ['invoice.paid'] });
-
-// With HMAC-SHA256 signature verification
-genericWebhook({
-  source: 'stripe',
-  events: ['invoice.paid'],
-  auth: {
-    method: 'hmac-sha256',
-    secret: 'stripe-signing-key',
-    signatureHeader: 'stripe-signature',
-  },
-});
-
-// With API key auth
-genericWebhook({
-  source: 'slack',
-  auth: { method: 'api-key', secret: 'slack-token' },
-});
-```
-
-**Config options:** `source` (required), `events`, `match`, `not`, `auth`, `path`, `description`.
-
-The `source` field MUST match the `--name` that an operator passed to `kici-admin source add generic --name <name>` when the source was created — that string is the source's identifier in the orchestrator. Generic webhook sources must be created by an operator before events can be received; see [Operator guide: event routing](https://docs.kici.dev/operator/event-routing/) for setup instructions.
-
-### Schedule events
-
-Cron-based triggers evaluated by the orchestrator on a periodic interval. Only the Raft leader evaluates schedules in a clustered deployment.
-
-```typescript
-import { schedule } from '@kici-dev/sdk';
-
-// Run every hour
-schedule({ cron: '0 * * * *' });
-
-// Run daily at 2 AM UTC
-schedule({ cron: '0 2 * * *' });
-
-// Run weekly on Mondays at 9 AM Eastern
-schedule({ cron: '0 9 * * 1', timezone: 'America/New_York' });
-```
-
-**Config options:** `cron` (required), `timezone` (defaults to `'UTC'`), `description`.
-
-### Lifecycle events
-
-Lifecycle triggers listen for orchestrator-level events related to workflow execution and system state changes.
-
-```typescript
-import { lifecycle } from '@kici-dev/sdk';
-
-// Trigger when any workflow completes
-lifecycle({ events: ['workflow_complete'] });
-
-// Trigger on job failures from a specific repo
-lifecycle({ events: ['job_failed'], sources: ['org/deploy-repo'] });
-
-// Trigger when registrations are updated
-lifecycle({ events: ['registration_updated'] });
-```
-
-**Available events:** `'workflow_complete'`, `'job_complete'`, `'job_failed'`, `'registration_updated'`.
-
-**Config options:** `events` (required), `sources`, `description`.
-
-## The registration model
-
-This is the most important concept for understanding event-based triggers.
-
-### Why registrations exist
-
-When a GitHub webhook arrives (push, PR, etc.), the orchestrator fetches your lock file from the repository and evaluates triggers on the spot. This works because the event itself tells the orchestrator _which repository_ to look at.
-
-Event-based triggers are different. When a cron timer fires or a custom event is emitted, there is no incoming webhook pointing to a specific repository. The orchestrator needs to know _in advance_ which workflows care about which events. That is what the registration model provides: a pre-built index of event-based workflows.
-
-### How registration works
-
-1. You define a workflow with an event-based trigger (e.g., `schedule()`, `kiciEvent()`, `genericWebhook()`)
-2. You compile the workflow (`kici compile`), which produces a lock file
-3. You push the lock file to your repository's **default branch** (e.g., `main` or `master`)
-4. The orchestrator receives the push webhook, detects it targets the default branch, and extracts all workflows with event-based triggers from the lock file
-5. Those workflows are stored in the orchestrator's registration database
-6. From that point on, matching events will trigger those workflows
-
-### Key implications
-
-- **Event-based workflows do not trigger until you push to the default branch.** If you add a new `schedule()` workflow, it will not start running until you merge to your default branch. This is by design -- the orchestrator cannot match events to workflows it does not know about.
-
-- **Registration is automatic.** There is no manual setup. Push your code, and the orchestrator handles the rest.
-
-- **Registrations refresh on every default-branch push.** If you add, remove, or modify event-based workflows and push to the default branch, the orchestrator updates its registration index automatically. Removed workflows stop triggering. New workflows start triggering.
-
-- **Git-based triggers are unaffected.** Triggers like `push()`, `pr()`, and `tag()` do not use registrations. They work immediately from any branch because the orchestrator evaluates them per-event from the lock file.
-
-### Practical example
-
-You create a nightly build workflow:
-
-```typescript
-import { workflow, job, step, schedule } from '@kici-dev/sdk';
-
-export default workflow('nightly-build', {
-  on: schedule({ cron: '0 2 * * *' }),
-  jobs: [
-    job('build', {
-      runsOn: 'linux',
-      steps: [
-        step('build', async ({ $ }) => {
-          await $`pnpm build`;
-        }),
-      ],
-    }),
-  ],
-});
-```
-
-You compile it, commit the lock file, and push to a feature branch. **Nothing happens** -- the cron will not fire because the orchestrator has not registered this workflow yet.
-
-You merge the feature branch into `main`. On the merge push, the orchestrator extracts the `nightly-build` workflow (it has a `ScheduleTrigger`) and registers it. Starting at the next 2 AM UTC, the workflow will trigger.
-
-## How events are matched
-
-When an event arrives, the orchestrator follows this flow:
-
-1. **Event received** -- a custom event is emitted by a step, a cron timer fires, or a generic webhook arrives
-2. **Registration lookup** -- the orchestrator queries its registration index for workflows matching the event type (e.g., all workflows with `ScheduleTrigger` for a cron fire, or all workflows with `KiciEventTrigger` for a custom event)
-3. **Trigger evaluation** -- for each candidate workflow, the orchestrator evaluates the trigger conditions: event name patterns, payload matching, status filters, source filters
-4. **Dispatch** -- matched workflows are dispatched to agents for execution, following the same job queue and agent routing as git-triggered workflows
-
-This lookup is fast because the registration index is held in memory and refreshed only when the registry version changes (on default-branch pushes).
-
-### Cross-source webhook delivery
-
-The catch-all `webhook()` trigger (see [SDK reference: webhook()](https://docs.kici.dev/user/sdk/triggers/#webhook)) participates in this same registration lookup, but with one twist: it fires for matching events arriving via **any** inbound webhook source in the same org, not just the source the workflow's repo is bound to. The orchestrator maintains a `(customerId, eventName)` index over webhook trigger registrations and consults it on every inbound generic webhook.
-
-The lookup is structurally org-isolated — a generic webhook delivered to org A can never reach a workflow registered against org B, because foreign-org rows live in a different bucket of the index. When a webhook fires across sources, the runtime clone token, repo URL, and check-status posting all come from the **registration's** source bundle, not the inbound source. The inbound source contributes only the event payload.
-
-## Circuit breaker
-
-Events can trigger workflows that emit more events, creating chains. The circuit breaker prevents runaway event storms.
-
-### Chain depth limit
-
-Each event carries a `chainDepth` counter. When a workflow triggered by an event emits a new event, the new event's chain depth increments. The orchestrator rejects events that exceed the maximum chain depth.
-
-- **Default limit:** 10 levels deep
-- **What happens when hit:** the event is dropped and logged. It is not queued for later delivery.
-
-For example: Workflow A emits event X (depth 0) -> Workflow B triggers, emits event Y (depth 1) -> ... -> at depth 10, any further emitted events are dropped.
-
-### Rate limiting
-
-Each workflow is rate-limited on how many events it can process per minute, using a sliding window.
-
-- **Default limit:** 100 events per workflow per minute
-- **What happens when hit:** additional events for that workflow are dropped and logged until the window clears.
-
-These defaults are hardcoded in the orchestrator and are not currently configurable via environment variables.
-
-## Delivery guarantees
-
-KiCI's event router delivers every accepted event with **at-least-once** semantics:
-
-- An event that passes the circuit breaker (chain depth + rate limit) and commits
-  to the `kici_events` table is guaranteed to dispatch to all matching workflows
-  at least once.
-- Each dispatch attempt acquires a short-lived lease (default 60 s) on the row.
-  If the dispatching node crashes or the handler throws, the lease expires (or
-  is released on failure) and the event is automatically retried.
-- The retry policy is exponential backoff with full jitter: base 5 s, cap 5 min,
-  up to 5 attempts before the event lands in the **DLQ** (dead-letter queue).
-  Operators triage DLQ entries via `kici-admin event-dlq list / count / retry / discard`.
-
-**What this means for workflow authors:**
-
-- **Make event handlers idempotent.** A retried dispatch may run a handler more
-  than once (e.g. if the first attempt threw after a partial side-effect).
-  Workflows that mutate external state should use idempotency keys, conditional
-  writes, or other deduplication patterns — same advice as for any distributed
-  CI system.
-- **Schedule fires are at-least-once too.** A cron schedule that fires while a
-  leader is being killed will commit (atomically with `cron_last_fired`) or roll
-  back together — never half. Recovery on the new leader does not backfill
-  multiple missed instants; if your workflow needs at-least-N guarantees across
-  outages, drive it from a different mechanism (e.g. a workflow that runs more
-  frequently and emits its own custom event).
-- **Drops are still possible — and visible.** Events rejected by the circuit
-  breaker (chain depth or rate limit exceeded) are dropped and logged, not
-  retried. That's a deliberate safety mechanism; the metric to watch is
-  `kici_orch_events_dropped_total{reason}`.
-
-## Emitting custom events
-
-Custom events are emitted from workflow steps using `ctx.emit()`. You can optionally define typed event schemas using `defineEvent()`.
-
-### Basic emission
-
-```typescript
-import { workflow, job, step, push } from '@kici-dev/sdk';
-
-export default workflow('build', {
-  on: push({ branches: 'main' }),
-  jobs: [
-    job('build', {
-      runsOn: 'linux',
-      steps: [
-        step('build', async ({ $ }) => {
-          await $`pnpm build`;
-        }),
-        step('notify', async (ctx) => {
-          await ctx.emit('build-complete', {
-            version: '1.0.0',
-            success: true,
-          });
-        }),
-      ],
-    }),
-  ],
-});
-```
-
-### Typed event definitions
-
-Use `defineEvent()` with Zod schemas to create a typed contract for event payloads:
-
-```typescript
-import { defineEvent, z } from '@kici-dev/sdk';
-
-export const deployComplete = defineEvent(
-  'deploy-complete',
-  z.object({
-    env: z.string(),
-    version: z.string(),
-    services: z.array(z.string()),
-  }),
-);
-```
-
-Then emit using the definition — the payload is checked against the schema:
-
-```typescript
-step('emit', async (ctx) => {
-  await ctx.emit(deployComplete, {
-    env: 'prod',
-    version: '1.2.3',
-    services: ['api', 'web'],
-  });
-});
-```
-
-And consume in another workflow:
-
-```typescript
-import { workflow, job, step, kiciEvent } from '@kici-dev/sdk';
-
-export default workflow('post-deploy', {
-  on: kiciEvent({ name: 'deploy-complete', match: { '$.env': 'prod' } }),
-  jobs: [
-    job('smoke-test', {
-      runsOn: 'linux',
-      steps: [
-        step('test', async ({ $ }) => {
-          await $`./scripts/smoke-test.sh`;
-        }),
-      ],
-    }),
-  ],
-});
-```
-
-Custom events are delivered immediately when emitted (mid-workflow, not queued until workflow completion). See the [SDK reference: emitting events](https://docs.kici.dev/user/sdk/validation-events/#emitting-events) section for the full `ctx.emit()` API.
-
-## See also
-
-- [SDK reference: event triggers](https://docs.kici.dev/user/sdk/triggers/#event-triggers) -- complete API signatures for all trigger builders
-- [SDK reference: emitting events](https://docs.kici.dev/user/sdk/validation-events/#emitting-events) -- `ctx.emit()` and `defineEvent()` API
-- [Workflow patterns: workflow chaining](https://docs.kici.dev/user/patterns/integrations/#workflow-chaining) -- examples of event-driven workflow chains
-- [Operator guide: event routing](https://docs.kici.dev/operator/event-routing/) -- configuring generic webhook sources, trust relationships, and event routing
-- [Architecture: event system](https://docs.kici.dev/architecture/webhooks/event-system/) -- internal event routing design, registration model, cluster synchronization
-
----
-
-## Global workflows
-
-Source: https://docs.kici.dev/user/global-workflows/
-
-Global workflows let one **workflow repo** define jobs that run on events from many **source repos** in the same org. They're the answer to "I want one CI policy / release pipeline / security scan to fire on every repo without copy-pasting `.kici/` folders everywhere."
-
-If you've only ever used per-repo workflows so far, start with the mental model section — global workflows add two new concepts (workflow repo vs. source repo, and authoring vs. source axes) that show up everywhere from SDK syntax to dashboard settings.
-
-## Mental model
-
-| Term           | Meaning                                                                                                                                                |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Workflow repo  | The repo whose `.kici/workflows/*.ts` file **declares** the global workflow. Holds the steps. Also known as the _authoring_ repo.                      |
-| Source repo    | The repo that **emits** the event (push / PR / tag / ...) that causes the global workflow to fire. The agent checks out this repo as the working copy. |
-| Global         | A workflow whose trigger carries one or more `repos:` glob patterns. The presence of `repos:` is what classifies a workflow as global.                 |
-| Authoring axis | Policy that answers "which repos may **author** global workflows?" Controlled by the allow-list in the dashboard's _Allowed author repos_ setting.     |
-| Source axis    | Policy that answers "which **source** repos' events are allowed to trigger global workflows?" Controlled by the deny-list in _Blocked source repos_.   |
+kici run remote deploy-prod --approve-all
+```
 
-The two axes are independent. A global workflow fires only if it passes **both** — its authoring repo is allowed AND the source repo is not denied.
+`--approve-all` is **run-scoped** — it only auto-approves holds belonging to the run this invocation dispatched; there is no fleet-wide or account-wide auto-approve. Eligibility is still enforced per hold: if you are not eligible for a gate, that gate still blocks. Each auto-approved gate prints its payload before resolving and is recorded distinctly in the audit trail (`held_run.auto_approve`).
 
-## Declaring a global workflow
+`--approve-all` is honored in non-interactive runs too: with `--json` or `--quiet` (no TTY), the flag still auto-approves each eligible gate as it appears instead of hanging or printing out-of-band instructions. Hold notices are routed to stderr so `--json` stdout stays pure machine-readable output.
 
-Add `repos:` to any trigger. Any workflow with at least one `repos:`-bearing trigger becomes global automatically; no separate flag is required.
+You can also approve from the dashboard approval queue. See [Dashboard](https://docs.kici.dev/user/dashboard/contexts-and-secrets/#approval-queue).
 
-```ts
-import { workflow, job, step, push } from '@kici-dev/sdk';
+## See also
 
-export default workflow('org-lint', {
-  on: [
-    push({
-      repos: ['myorg/*', '!myorg/archived-*'],
-      branches: ['main'],
-    }),
-  ],
-  jobs: [
-    job('lint', {
-      steps: [
-        step('lint-all', async ({ $, env }) => {
-          await $`echo source=${env.KICI_SOURCE_REPO_PATH ?? 'unknown'}`;
-          await $`npm run lint`;
-        }),
-      ],
-    }),
-  ],
-});
-```
+- [Idempotent steps](https://docs.kici.dev/user/idempotent-steps/) — the check/apply step facet that drift gates build on.
+- [Contexts](https://docs.kici.dev/user/contexts/) — operator-required reviewers on protected contexts.
+- [Approval gates (operator guide)](https://docs.kici.dev/operator/approvals/) — teams, the approval queue, expiry, and self-approval.
+- [Approval gates (architecture)](https://docs.kici.dev/architecture/approvals/) — the unified hold model and the step-level round-trip.
+- [Organization-wide workflows](https://docs.kici.dev/user/global-workflows/) — why an approval gate is refused there.
 
-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
+## Contexts
 
-The agent checks out both repos. **Inside a step body**, `env` carries a pointer to each working tree:
+Source: https://docs.kici.dev/user/contexts/
 
-| `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.   |
+<!-- help:contexts-list#overview -->
 
-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.
+Contexts are named deployment targets (like staging or production) that control where your workflow jobs run. Each context can have its own variables, secrets, and protection rules to gate deployments.
 
-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.
+<!-- /help:contexts-list -->
 
-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.
+<!-- help:contexts-protection#protection-rules -->
 
-### The triggering event
+Protection rules control when jobs targeting a context can execute.
 
-`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.
+Available rules:
 
-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:
+- **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.
 
-```ts
-concurrency: {
-  group: ({ branch, event }) => `${event.sourceRepo}:${branch}`,
-  cancelInProgress: true,
-},
-```
+<!-- /help:contexts-protection -->
 
-### Narrowing to the repos that need it
+## Overview
 
-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:
+A context in KiCI provides:
 
-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).
+- **Variables** -- non-secret key-value configuration (e.g., `API_URL`, `CLUSTER_NAME`)
+- **Scoped secrets** -- encrypted values bound to the context via scope bindings
+- **Protection rules** -- branch restrictions, required reviewers, wait timers, and concurrency limits
+- **Per-source overrides** -- repositories can override unlocked variables for their own deployments
 
-### Narrowing with a filter
+## SDK API
 
-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.
+### Job-level context property
 
-A workflow can declare a `filter`: a predicate that decides whether the workflow applies to this event at all.
+The `context` property is set on a job, not a workflow or step:
 
-```ts
+```typescript
 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');
-  },
+export default workflow('deploy', {
+  on: [push({ branches: ['main'] })],
   jobs: [
-    job('lint-dockerfile', {
-      runsOn: ['kici:os:linux'],
+    job('deploy-staging', {
+      runsOn: 'default',
+      context: 'staging',
       steps: [
-        step('lint', async ({ $, env }) => $`hadolint ${env.KICI_SOURCE_REPO_PATH}/Dockerfile`),
+        step('deploy', async (ctx) => {
+          // ctx.context is the resolved context name
+          console.log(`Deploying to ${ctx.context}`);
+          // ctx.secrets provides async get/expose/has methods for context-bound secrets
+          const dbPassword = await ctx.secrets.get('DB_PASSWORD');
+          // Environment variables are in ctx.env
+          const apiUrl = ctx.env.API_URL;
+          await ctx.$`deploy --target ${ctx.context}`;
+        }),
       ],
     }),
   ],
 });
 ```
 
-The filter receives a `FilterContext`:
+### Dynamic contexts
+
+The context name can be a string or a function (sync or async) for dynamic contexts (e.g., per-PR review contexts). The function receives the normalized event envelope, with the raw provider body nested at `event.payload`:
 
-| 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.                                                                            |
+```typescript
+job('deploy-review', {
+  runsOn: 'default',
+  context: (event) => `review/PR-${event.payload.pull_request.number}`,
+  steps: [
+    step('deploy', async (ctx) => {
+      // ctx.context is 'review/PR-123' (resolved at runtime)
+      await ctx.$`deploy-preview --env ${ctx.context}`;
+    }),
+  ],
+});
+```
 
-`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.
+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.
 
-**`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.
+### Multiple contexts per job
 
-**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.
+A job can bind more than one context with `contexts`, an ordered array. This lets a single job draw secrets and variables from several contexts at once — for example a shared `staging` context plus a `my-testing` context that carries test-only variables:
 
-### Global and same-repo filters differ
+```typescript
+job('deploy', {
+  runsOn: 'default',
+  contexts: ['staging', 'my-testing'],
+  steps: [
+    step('deploy', async (ctx) => {
+      // ctx.secrets and ctx.env carry the merged set from both contexts
+      const dbUrl = await ctx.secrets.get('DB_URL');
+    }),
+  ],
+});
+```
 
-The same `filter` keyword means two different things depending on whether the workflow is global:
+- `context` (singular) and `contexts` (array) are mutually exclusive — setting both is a compile error. `context: 'staging'` is exactly equivalent to `contexts: ['staging']`.
+- Each array entry is a static name or a function of the event, resolved per element exactly like a single dynamic context.
 
-|                                | 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                                                             |
+**Merge order — last wins.** All bound contexts are resolved on every dispatch (webhook, scheduled, and test runs alike) and merged in array order. When the same secret or variable key is defined in more than one context, the later entry in the array wins. With `contexts: ['staging', 'my-testing']`, a key defined in both resolves to `my-testing`'s value; keys defined in only one are preserved. The longest-scope-path-wins rule still applies _within_ each context.
 
-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.
+**Protection rules combine all-must-pass.** A job must satisfy **every** bound context's gates — adding a context can never loosen access. Branch restrictions, trigger-type filters, and repo patterns must pass for all contexts. The minimum trust tier is the most restrictive across them, and required reviewers are the union of all contexts' reviewers. The wait timer is the longest, and the hold expiry is the shortest. If a rule rejects a job, that job is not dispatched. It still appears on the run, as a failed job whose reason names the context and the rule that rejected it. Read the reason with `kici runs show <run-id>`, or on the run detail page.
 
-**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.
+**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/).
 
-### Generating jobs per source repo
+**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.
 
-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:
+**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.
 
-```ts
-import { job, step, workflow, push, type DynamicJobFn } from '@kici-dev/sdk';
-import { readFile } from 'node:fs/promises';
+### Job-level environment variables
 
-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}`)],
-      }),
-    );
-};
+The `env` property on a job provides static or dynamic environment variables:
 
-export default workflow('org-ci', {
-  on: [push({ repos: ['myorg/*'] })],
-  jobs: [perRepoJobs],
+```typescript
+job('deploy', {
+  runsOn: 'default',
+  context: 'production',
+  env: { DEPLOY_TARGET: 'us-east-1' },
+  // Or dynamic:
+  // env: (event) => ({ DEPLOY_SHA: event.payload.after?.slice(0, 7) }),
+  steps: [
+    step('deploy', async (ctx) => {
+      // DEPLOY_TARGET is available in ctx.env
+      await ctx.$`deploy --region ${ctx.env.DEPLOY_TARGET}`;
+    }),
+  ],
 });
 ```
 
-The same `sourceRepo.path` caution applies: read the tree through it, and derive job names from the repo's _contents_, never from the path.
+### Concurrency groups
 
-## Enabling global workflows
+Jobs can define their own concurrency groups to control concurrent execution within a context. For workflow-level concurrency (which applies to all jobs in a workflow), see [Concurrency groups](https://docs.kici.dev/user/concurrency/).
 
-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.
+Control concurrent deployments to the same context:
 
-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.
+```typescript
+job('deploy', {
+  runsOn: 'default',
+  context: 'production',
+  concurrencyGroup: 'production-api',
+  // Or dynamic:
+  // concurrencyGroup: (event) => `review-${event.payload.pull_request.number}`,
+  steps: [/* ... */],
+});
+```
 
-| 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.                |
+If no `concurrencyGroup` is specified, the context name is used as the default concurrency group. For a job bound to multiple contexts, the default is the **first** bound context's name.
 
-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-*`).
+### Step context
 
-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.
+Inside a step, the `ctx` object provides:
 
-### Saving and reverting
+| Property      | Type                                  | Description                                                                               |
+| ------------- | ------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `ctx.context` | `string \| undefined`                 | Resolved context name (undefined for jobs without context)                                |
+| `ctx.env`     | `Record<string, string \| undefined>` | Environment variables (merged from system, org, source, and job-level `env`)              |
+| `ctx.secrets` | `StepSecretsTyped`                    | Async accessor for bound secrets (get, expose, has, getMeta, list, mountFile, exposeFile) |
 
-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.
+| Method                                       | Returns                   | Description                                                                                                                                                        |
+| -------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `await ctx.secrets.get(key)`                 | `string`                  | Retrieve a secret value. Throws `SecretNotFoundError` if not found.                                                                                                |
+| `await ctx.secrets.expose(key)`              | `void`                    | Set the secret as an environment variable for this step — visible via `ctx.env` and to child processes (`process.env`). Throws `SecretNotFoundError` if not found. |
+| `ctx.secrets.has(key)`                       | `boolean`                 | Check if a secret key exists. Synchronous, never throws.                                                                                                           |
+| `ctx.secrets.getMeta(key)`                   | `SecretMeta \| undefined` | Retrieve metadata (value, backend name, scope path) for a resolved secret. Returns `undefined` if not found.                                                       |
+| `ctx.secrets.list()`                         | `string[]`                | Every secret key available to the step, sorted alphabetically. Synchronous, never throws.                                                                          |
+| `await ctx.secrets.mountFile(opts)`          | `{ path }`                | Materialise one or more secrets to a per-step tmpfile (auto-removed at step end). See [Secrets → Mounting secrets as files](https://docs.kici.dev/user/secrets/#mounting-secrets-as-files). |
+| `await ctx.secrets.exposeFile(envVar, opts)` | `{ path }`                | `mountFile` plus `process.env[envVar] = path`; the env var is unset at step end.                                                                                   |
+| `ctx.setSecretOutput(key, val)`              | `void`                    | Publish an encrypted secret output from this job, consumable by downstream jobs via `needs`. Never logged or stored in plaintext.                                  |
 
-## Security model
+The full secrets API — including `SecretFileOptions`, log masking, and the canonical `sops` example — is documented in [Secrets](https://docs.kici.dev/user/secrets/).
 
-### Two independent axes
+## Environment variable merge precedence
 
-A global workflow fires only if:
+When a job targets a context, variables are merged in this order (last wins):
 
-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, 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.
+1. **Allowed system vars** -- `PATH`, `HOME`, etc. from the agent process
+2. **Sandbox defaults** -- `FORCE_COLOR=1`
+3. **KICI\_\* system vars** -- orchestrator-generated metadata
+4. **Org-level context vars** -- from the dashboard, managed per-context
+5. **Source-level overrides** -- per-repository overrides (skips locked vars)
+6. **Job env** -- from the `env` property in the SDK
+7. **`setEnv()` calls** -- runtime modifications within steps
 
-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.
+> **Note:** Secrets are NOT part of the environment variable merge. They are delivered to the step context via IPC and accessed through `ctx.secrets`, not through `process.env`. See the [step context](https://docs.kici.dev/user/contexts/#step-context) section above.
 
-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.
+## Protection rules
 
-### Secrets are not available
+Contexts can have protection rules that gate job execution:
 
-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.
+### Branch restrictions
 
-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.
+Limit which branches can deploy to a context:
 
-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.
+```
+Allowed branches: main, release/*
+```
 
-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/).
+Jobs from other branches are rejected immediately with an error message.
 
-## When does it fire?
+**Most internally-triggered runs carry a branch.** KiCI starts these runs for itself: a [schedule](https://docs.kici.dev/user/sdk/triggers/) fire, a [custom event](https://docs.kici.dev/user/events/), a completion trigger, a failure batch, or an [invoke gate](https://docs.kici.dev/user/global-workflows/) summon. None comes from a branch push. A run with one source branch presents it:
 
-Same-repo globals (a workflow in `myorg/app` with `repos: ['myorg/app']`) fire on pushes to `myorg/app`. Cross-repo globals fire on pushes to any source repo whose identifier matches a glob on the authoring workflow's trigger. The orchestrator de-duplicates between the per-repo and cross-repo matching passes, so a single event produces at most one run per (workflow, source-repo, trigger) triple.
+- A **schedule** fire executes the default branch's workflow, so it presents the repository's default branch.
+- A **`kiciEvent()` subscriber**, a **completion trigger** (`workflowComplete`, `jobComplete`) and an **invoke-gate summon** present the branch of the run behind them. That is the same branch the run behind them presented. For a pull-request run it is the branch the PR targets, not the contributor's own branch — so a subscriber of an event emitted by a PR against `main` presents `main`.
 
-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 branch restriction compares that branch against your patterns like any other run. So a nightly deploy bound to a `production` context restricted to `main` runs.
 
-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.
+A branch restriction is not a trust control. It checks the branch a run presents, never where the code came from. A pull request against `main` presents `main`, whoever opened it. To gate on that, set a [minimum trust tier](https://docs.kici.dev/user/contexts/#minimum-trust) on the same context.
 
-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:
+A run with no single source branch presents no branch, and a branch restriction then rejects 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.
+- A **failure batch** (`workflowsFailedBatch`). One accumulation window of failed runs causes it, on as many branches, so no one branch is its own.
+- A **scaler event** (`kici.scaler.scale-up`, `kici.scaler.scale-down`). The orchestrator mints these itself, with no run behind them. See [autoscaling workflows](https://docs.kici.dev/user/workflows/autoscaling-workflows/).
+- A **schedule** fire in a repository that has not pushed to its default branch since you upgraded KiCI. The default branch is captured when a push re-registers the workflows, so the first such push after the upgrade fixes it.
+- Any event whose emitting run is no longer on record.
 
-## Approval gates are not supported
+The rejection reason says so:
 
-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.
+```
+Context 'production' restricts branches: this internally-triggered run carries no
+branch, so no branch restriction can be satisfied - a scheduled run gains its
+branch after the next push to the default branch re-registers the workflow;
+alternatively bind a context without a branch restriction, or restrict by trigger
+type instead
+```
 
-To gate a deployment behind a human, put the gated jobs in a workflow whose triggers carry no `repos:`.
+To limit a context by how the run started instead of by branch, use a **trigger-type filter**: the trigger type is a real name (`schedule`, `kici_event`, `workflow_complete`, `job_complete`), so a filter that allows it works on these runs.
 
-## Re-running is not supported
+### Required reviewers
 
-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.
+Require manual approval before a job can proceed:
 
-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.
+```
+Required reviewers: alice, bob
+```
 
-## Requirements a filter places on the run
+When reviewers are required, the job enters a "held" state. Reviewers can approve or reject via the dashboard, the [`kici approve`](https://docs.kici.dev/user/cli/runs-and-approvals/#kici-approve) command, or the API. Held runs expire after a configurable timeout.
 
-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.
+This operator-set rule is the **mandatory** form of an approval gate. Workflow authors can also declare gates in code with `approval` at step, job, or workflow level — see [Approval gates](https://docs.kici.dev/user/approvals/). Both forms use the same held-element mechanism and the same queue.
 
-## Troubleshooting
+### Wait timer
 
-| 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.                                                                                                                                                                                                |
+Add a mandatory delay before deployment starts:
 
-### Reading a global run in the dashboard
+```
+Wait timer: 300 seconds
+```
 
-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:
+The job waits for the specified duration before proceeding. Useful for staged rollouts.
 
-| 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                  |
+### Minimum trust
 
-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.
+Hold a job whose run came from a fork:
 
-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.
+```
+Minimum trust: trusted
+```
 
-#### Who can see it
+| Value     | Effect                                                     |
+| --------- | ---------------------------------------------------------- |
+| `trusted` | Holds a run whose ref came from a fork                     |
+| `known`   | Same effect; the value is deprecated and removed at v1.0.0 |
+| (unset)   | No trust-based gating                                      |
 
-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.
+Both values block the same thing. Trust comes from the git ref, and that judgement has two answers: a ref in your repository is `trusted`, a ref from a fork is `unknown`. The value you declare still decides the wording of the hold reason.
 
-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.
+When the gate holds a job, it enters the security approval queue. Someone with `ci_trust:write` or higher must approve it before execution proceeds.
 
-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.
+A run that resolved **no** tier passes the gate. A pull request from a source with no fork model resolves none, and so does an internal run whose inheritance lookup failed. See [trust tiers on internal triggers](https://docs.kici.dev/user/events/#trust-tiers-on-internal-triggers) for the full table.
 
-### Reading a global workflow's filter output
+The trust tier also affects which lock file a pull-request run uses: a trusted ref evaluates the head lock file, a fork ref evaluates the base branch's. A fork run additionally carries no install or registry secrets, and its build-cache writes are confined to that run. So a fork pull request cannot change what CI does, and cannot read a private-registry token, whether or not you set this gate.
 
-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:
+Set the gate on any context that carries a credential a fork run must not reach. See the [deployment checklist](https://docs.kici.dev/operator/security/security/#deployment-checklist-which-contexts-need-it).
 
-```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
+An internally-triggered run carries a tier too. A schedule fire and the orchestrator's own lifecycle events are trusted. A `kiciEvent()` subscriber inherits the tier of the run that emitted the event, so a `minimumTrust` gate on the subscriber's context reads the **emitting** run's tier. See [trust tiers on internal triggers](https://docs.kici.dev/user/events/#trust-tiers-on-internal-triggers).
 
-# 2. Print the round's log (step 0 is the evaluation itself).
-kici-admin runs logs <run_id> --job <id>
-```
+See the [CI security architecture docs](https://docs.kici.dev/architecture/security/ci-security/) for the full trust resolution flow.
 
-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.
+### Security approval queue
 
-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.
+A pull request held for security review enters the security approval queue. Two things put it there: the organization's fork switch set to `hold`, and a `minimumTrust` gate blocking a fork run. This is separate from the context approval queue: a security hold asks "is it safe to run this contributor's code at all?", while a context approval hold asks "should this job be promoted?". The two never cross — releasing a security hold needs `ci_trust:write` or higher, releasing a context approval hold needs `contexts:write` plus eligibility for one of the gate's clauses. See [Approval holds vs security holds](https://docs.kici.dev/architecture/approvals/#approval-holds-vs-security-holds) for the full comparison.
 
-Anything your `filter` writes with `console.log` appears there, alongside the
-per-candidate verdicts the round recorded.
+Held runs can be approved:
 
-## See also
+- Via the **dashboard** on the [Approval queue](https://docs.kici.dev/user/dashboard/contexts-and-secrets/#approval-queue) page, which lists security and context holds together
+- Via a PR comment: `/kici approve` (commenter must have `ci_trust:write+`)
 
-- [Architecture — global workflows](https://docs.kici.dev/architecture/global-workflows/) — dual-query dispatch flow, cross-provider auth, security model, lock-file schema.
-- [Universal-git provider](https://docs.kici.dev/user/providers/universal-git/#global-workflows) — how global workflows interact with `generic:<orgId>:<sourceId>` routing keys.
-- [SDK reference](https://docs.kici.dev/user/sdk-reference/) — the full set of triggers that accept `repos:`.
+A hold raised by the fork switch covers the whole pull request and uses the org's approval expiry (default 72 hours). A `minimumTrust` hold is raised by a context, so it uses that context's own hold expiry (default one hour). A job carrying both a reviewer approval hold and a security hold carries both expiries, and whichever comes first cancels the run.
 
----
+While the fork switch is holding a pull request, your organization's global workflows do not run for it. Approving the hold releases that pull request's own workflows; it does not retroactively run the organization's global workflows for the event.
 
-## Idempotent steps and check mode
+### Concurrency limits
 
-Source: https://docs.kici.dev/user/idempotent-steps/
+Control how many jobs can run simultaneously in a context:
 
-An **idempotent step** describes _desired state_ rather than a fixed sequence of
-commands. You give the step a `check` function that inspects the world and a
-`run` function that converges it. KiCI then executes the workflow in one of two
-modes:
+```
+Concurrency limit: 1
+Strategy: queue (or cancel-pending)
+```
 
-- **Apply mode** (the default): for each step, `check()` runs first; on drift the
-  step applies the change; when already in sync the step is skipped.
-- **Check mode** (`--check`): for each step, `check()` runs and KiCI reports what
-  _would_ change — **without changing anything**. This is the same model as a
-  dry-run plan: you see the drift before any side effect happens.
+The concurrency limit is a positive integer; leave it unset for unlimited concurrency.
 
-This turns a workflow into convergent configuration management: re-running an
-apply is safe (in-sync steps do nothing), and a check-mode run is a read-only
-preview you can gate a build on.
+- **queue** -- new jobs wait in a FIFO queue (with configurable timeout, default 1 hour)
+- **cancel-pending** -- pending (queued) jobs are cancelled when the limit is reached
 
-## Authoring a checked step
+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.
 
-Add a `check` facet to the existing `step()` factory. When `check` is present,
-`run` becomes the _apply_ function and receives the drift value `check`
-returned:
+## Dashboard management
 
-```typescript
-import { step, z } from '@kici-dev/sdk';
+### Creating contexts
 
-const configureNginx = step('configure-nginx', {
-  // optional schema for the drift value — gives the dashboard a typed shape
-  drift: z.object({ want: z.string() }),
+Navigate to **Settings > Contexts** in the dashboard. Click **New context** to choose the context name and type (Fixed or Glob).
 
-  // read-only inspection; return null when already in the desired state
-  check: async (ctx) => {
-    const current = await ctx.$`nginx -T`;
-    return current.stdout.includes(DESIRED) ? null : { want: DESIRED };
-  },
+- **Fixed** -- applies to jobs that declare exactly this context name, like `staging` or `production`
+- **Glob** -- applies to any context name a job declares that matches the pattern, e.g. `review/*` matches a job with `context: 'review/PR-123'`
 
-  // human-readable preview line — REQUIRED when check is set. It is the drift's
-  // serializable face: it streams to the logs and persists for the dashboard.
-  summarize: (drift) => `would rewrite nginx.conf (${drift.want.length} bytes)`,
+The contexts list shows each context's type, whether test runs may use it (the `allowLocalExecution` flag -- see the [testing guide](https://docs.kici.dev/user/testing-guide/)), and whether it is enabled.
 
-  // apply — runs only when check returned drift (apply mode); receives that drift
-  run: async (ctx, drift) => {
-    await writeConfig(drift.want);
-    return { reloaded: true };
-  },
+### Context detail page
 
-  // optional — runs when check returned null, to produce the step's outputs
-  whenInSync: async () => ({ reloaded: false }),
-});
-```
+Each context has four tabs:
 
-### The facet fields
+1. **Variables** -- manage key-value pairs with lock toggles. Locked variables cannot be overridden by source-level overrides. Source overrides are managed in a sub-tab.
 
-| Field        | Required         | Purpose                                                                |
-| ------------ | ---------------- | ---------------------------------------------------------------------- |
-| `check`      | to opt in        | Read-only inspection. Return a drift value, or `null` when in sync.    |
-| `summarize`  | when `check` set | Human-readable, serializable preview of the drift. Streams + persists. |
-| `run`        | always           | Apply function. With `check`, it receives the drift as its second arg. |
-| `whenInSync` | optional         | Produces the step's outputs when `check` returned `null`.              |
-| `drift`      | optional         | Schema that validates / shapes the drift value.                        |
+2. **Secrets** -- view bound secret scopes and their resolved secret count. Add bindings by specifying scope glob patterns (e.g., `aws/prod/**`).
 
-`summarize` is **required** whenever `check` is declared. `run` and `whenInSync`
-both produce the same output type — one output shape per step, whichever path
-runs. Every other step facet (`cache`, `rules`, `continueOnError`, `timeout`,
-`retry`, `approval`, `onCancel`, `cleanup`, `outputs`) composes unchanged.
+3. **Protection** -- configure branch restrictions, required reviewers, wait timers, and concurrency limits with enable toggles for each section. Turning a section's toggle off and saving clears that rule on the context, so the gate stops applying to new runs. Emptying the hold expiry field clears it too, and held runs fall back to the default one-hour hold window.
 
-A plain `step()` without `check` keeps its exact current behavior — the check
-facet is fully optional.
+4. **History** -- view filtered runs targeting this context.
 
-## Run modes
+### Bound contexts on runs
 
-A run carries one of three modes:
+A job's bound deployment contexts are shown as chips on the run detail page (in the job metadata panel) in the order the job declared them, and the distinct set across a run's jobs appears as compact chips on the run list. For a multi-context job the chips read left-to-right in merge order — later contexts override earlier ones on key collisions. A `(dynamic)` chip marks a context whose name is computed at runtime; it resolves to the real name once the run starts. A job that binds a single context shows one chip; a job that binds none shows no chip.
 
-| Mode                  | CLI flags                 | Behavior                                                                                   |
-| --------------------- | ------------------------- | ------------------------------------------------------------------------------------------ |
-| `apply`               | (default, no flags)       | Converge: drift ⇒ apply ⇒ **applied**; null ⇒ **in sync** (skipped).                       |
-| `check`               | `--check`                 | Preview only: drift ⇒ **would change**; null ⇒ **in sync**. Never applies. Always exits 0. |
-| `check-fail-on-drift` | `--check --fail-on-drift` | Same as check, but the run **fails** if any step reports drift.                            |
+A job a bound context rejects keeps its chips, and shows as failed because it never ran. Its failure reason names the context and the rule that rejected it. `kici runs show <run-id>` prints the same reason.
 
-Per-step outcomes:
+### Secrets management
 
-- **applied** — drift was found and the step applied the change (apply mode).
-- **in sync** — `check` returned `null`; nothing to do.
-- **would change** — drift was found in check mode; the change was previewed, not applied.
-- **no check** — a plain step (no `check`) reached under check mode. A
-  side-effecting step can't be safely previewed, so it is skipped.
+Secrets are individual encrypted values organized by scope paths (e.g., `aws/prod`, `databases/postgres`). Scopes are bound to contexts via bindings:
 
-In check mode KiCI never invokes a checked step's `run` (apply) — the preview is
-guaranteed side-effect-free.
+- **Scope-centric view** (Secrets page): tree view of scopes with per-scope context binding checkboxes
+- **Context-centric view** (inside context detail): bound scopes, resolved secrets, add binding
 
-## Running in check mode
+When scope paths collide on the same key name, the longer (more specific) path wins.
 
-`--check` and `--fail-on-drift` control drift reporting on `kici run remote`:
+## Type generation
 
-```bash
-# Apply (default): converge the workflow.
-kici run push --local
-kici run remote my-fixture
+Running `kici types` generates two augmented interfaces: `KnownSecretKeys` (union of all secret keys across all contexts) and `ContextSecrets` (per-context key unions):
 
-# Check: report drift, change nothing. Always exits 0.
-kici run remote my-fixture --check
+```typescript
+interface KnownSecretKeys {
+  DB_PASSWORD: string;
+  API_KEY: string;
+}
 
-# Check + fail on drift: fail the run when any step reports drift. Use this as a
-# CI gate ("fail the build if prod has drifted").
-kici run remote my-fixture --check --fail-on-drift
+interface ContextSecrets {
+  production: 'DB_PASSWORD' | 'API_KEY';
+  staging: 'DB_PASSWORD';
+}
 ```
 
-`--fail-on-drift` only modifies check mode — passing it without `--check` is an
-error.
+`KnownSecretKeys` narrows `ctx.secrets.get()` and `ctx.secrets.expose()` key parameters to valid key names. `ContextSecrets` maps each context to its available secret key names as a string union. Dynamic contexts fall back to the full `KnownSecretKeys` union.
 
-## Where outcomes show up
+---
 
-A check-mode run is labeled in the dashboard with a **CHECK MODE — preview**
-badge on the run header. Each step shows its outcome chip — applied / in sync /
-would change / no check — and, when drift was detected, the `summarize` line
-describing what would change. The rendering is read-only.
+## Dashboard
 
-## See also
+Source: https://docs.kici.dev/user/dashboard/
 
-- [Idempotent SDK helpers](https://docs.kici.dev/user/sdk/idempotent/) — the `idempotent()` / `idempotentStep()` convenience wrappers (always apply on drift), plus `checkStep()`, the clean-shape sibling that respects the run-level check mode.
-- [Core SDK reference](https://docs.kici.dev/user/sdk/core/) — the `step()`, `job()`, and `workflow()` factories the check facet extends.
-- [Lock file and drift](https://docs.kici.dev/user/lock-file-and-drift/) — how the lock file carries step capability flags.
+The KiCI dashboard is the browser interface for monitoring workflow runs, inspecting jobs and logs, and managing your organization. It signs in via OIDC and talks to KiCI over its API.
+
+This guide is split across the following pages:
+
+| Page                                                                                  | Covers                                                                        |
+| ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| [Getting started](https://docs.kici.dev/user/dashboard/getting-started/)                                     | Onboarding checklist and your organizations list                              |
+| [Navigation and layout](https://docs.kici.dev/user/dashboard/navigation/)                                    | Sidebar, mobile nav, theme, time display, shortcuts, error pages              |
+| [Runs and logs](https://docs.kici.dev/user/dashboard/runs/)                                                  | Run list, run detail, the log viewer                                          |
+| [Settings](https://docs.kici.dev/user/dashboard/settings/)                                                   | Members, roles, teams, keys, sources, billing, security, support access       |
+| [Workflows, diagnostics, and orchestrators](https://docs.kici.dev/user/dashboard/workflows-and-diagnostics/) | Registered workflows, infra health, per-cluster views                         |
+| [Contexts, secrets, and approvals](https://docs.kici.dev/user/dashboard/contexts-and-secrets/)               | Contexts, secret scopes, approval queue                                       |
+| [Activity and DLQ](https://docs.kici.dev/user/dashboard/activity-and-dlq/)                                   | Forensic activity log and dead-letter queue                                   |
+| [Notifications](https://docs.kici.dev/user/dashboard/notifications/)                                         | Personal run notifications and org-wide channels, subscriptions, delivery log |
+| [Account](https://docs.kici.dev/user/dashboard/account/)                                                     | Personal account settings                                                     |
 
 ---
 
@@ -2102,7 +914,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 contributors get no tokens.** When a fork PR is dispatched and the contributor-trust resolution returns anything other than `trusted`, the orchestrator strips both `npmRegistries` and `installEnvSecrets` out of the dispatch. The install runs without auth and fails naturally on the first private dep — fork PRs cannot ever observe a registry token, even if a misconfigured 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 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.
 - **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.
@@ -2294,11 +1106,12 @@ commonly, an offline `{ issuer, jwks }` file for air-gapped checks.
 
 ### Why you supply it out-of-band
 
-Given there's a single issuer, why pass it at all instead of letting the
-verifier read it from the token? Because the issuer named **inside** a token
-cannot be trusted: a forged bundle could carry a token that names
-`iss: https://attacker.example` _and_ bundle a key set that "verifies" it,
-making the whole signature chain circular and self-attesting. The verifier
+The verifier already resolves a sensible default, so why is naming the trust
+root a supported step at all -- why not let the verifier read the issuer from
+the token? Because the issuer named **inside** a token cannot be trusted. A
+forged bundle could carry a token that names `iss: https://attacker.example`
+_and_ bundle a key set that "verifies" it. That makes the whole signature chain
+circular and self-attesting. The verifier
 therefore pins to an issuer you supply out-of-band and checks the token against
 _that_ — the bundle is verified against a key set you trust, not one it shipped
 with. Naming the trust root is a security requirement, not a multiple-choice
@@ -2740,7 +1553,9 @@ Note that `get()` is async -- you must `await` the result.
 
 ## Typed secrets
 
-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.
+When you run `kici types`, the compiler generates a `.kici/types/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.
+
+This file is a local development aid, not source: `kici init` gitignores `.kici/types/`, so each team member generates their own copy with `kici types` rather than committing it. When the Platform is unreachable, `kici types` keeps any existing copy untouched, or writes an empty stub if none exists, so type checking degrades to "no known keys" instead of failing.
 
 See [CLI reference](https://docs.kici.dev/user/cli/authoring-and-local/#kici-types) for the `kici types` command.