@kici-dev/compiler 0.1.26 → 0.2.0

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

@@ -1,6 +1,6 @@
 # KiCI Workflow features
 
-This bundle covers: Workflow features: concurrency, environments, secrets, approvals, provenance, events.
+This bundle covers: Workflow features: concurrency, contexts, secrets, approvals, provenance, events.
 
 ## Account and sign-in
 
@@ -101,13 +101,13 @@ When the run reaches this job, it is held instead of dispatched. The held run ap
 job('deploy', {
   runsOn: 'default',
   approval: true,
-  steps: [
-    /* ... */
-  ],
+  steps: [/* ... */],
 });
 ```
 
-`approval: true` holds the element until **any** org member who can act on approvals signs off — anyone with the `environments:write` or `ci_trust:write` permission. Use it when you want a manual gate without restricting who may release it.
+`approval: true` holds the element until **any** org member who can act on approvals signs off — anyone with `contexts:write`, since an `approval` gate always raises a reviewer hold. Use it when you want a manual gate without restricting who may release it.
+
+A **security** hold is different: it is raised by the CI trust pipeline (an unknown contributor, a fork PR, a workflow-modifying PR), never by `approval`, and releasing one requires `ci_trust:write`. See [Approval gates (operator guide)](https://docs.kici.dev/operator/approvals/#who-may-approve).
 
 ### Approver list (AND)
 
@@ -135,15 +135,17 @@ approval: {
 },
 ```
 
-| Field       | Type                  | Description                                                                                                                                                                 |
-| ----------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `when`      | `'always' \| 'drift'` | When the gate fires. `'always'` (default) gates before the element; `'drift'` gates a check/apply step only when it finds drift. See [Drift gates](https://docs.kici.dev/user/approvals/#drift-gates-whendrift). |
-| `approvers` | `ApproverClause[]`    | The AND list of `{ team }` / `{ user }` clauses. An empty list means "any approval-capable member".                                                                         |
-| `reason`    | `string`              | A human-readable label shown in the dashboard queue and the held-for-approval status check.                                                                                 |
-| `timeout`   | `number`              | Per-gate expiry in **seconds**, overriding the org default. On expiry the element is rejected.                                                                              |
+| Field       | Type                  | Description                                                                                                                                                                                                      |
+| ----------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `when`      | `'always' \| 'drift'` | When the gate fires. `'always'` (default) gates before the element; `'drift'` gates a check/apply step only when it finds drift. See [Drift gates](https://docs.kici.dev/user/approvals/#drift-gates-whendrift).                                      |
+| `approvers` | `ApproverClause[]`    | The AND list of `{ team }` / `{ user }` clauses. An empty list means "any approval-capable member".                                                                                                              |
+| `reason`    | `string`              | A human-readable label shown in the dashboard queue and the held-for-approval status check.                                                                                                                      |
+| `timeout`   | `number`              | Per-gate expiry in **seconds**, overriding the org default. Must be a **positive integer** number of seconds; a non-positive or non-finite value is rejected at compile time. On expiry the element is rejected. |
 
 When `timeout` is omitted, the gate uses the org's default approval expiry (set by the operator). On expiry, the held element is rejected and the run fails — see [expiry](https://docs.kici.dev/operator/approvals/#expiry).
 
+A `timeout` that is zero, negative, or non-finite (for example a computed `minutes * 60` where `minutes` is `0`) fails `kici compile` with a clear author-facing error, so a misconfigured gate can never silently expire the moment it is created. If an orchestrator ever receives such a value from a hand-edited lock file, the run fails fast with an **Approval gate misconfigured** init-failure rather than dispatching ungated.
+
 ## Granularity
 
 The same `approval` field is accepted on a workflow, a job, and a step.
@@ -168,9 +170,7 @@ A job-level gate holds just that job; other jobs in the run proceed normally:
 job('publish', {
   runsOn: 'default',
   approval: [{ team: 'leads' }],
-  steps: [
-    /* ... */
-  ],
+  steps: [/* ... */],
 });
 ```
 
@@ -228,7 +228,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 environment via required reviewers (see [Environments](https://docs.kici.dev/user/environments/#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. 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.
 
 ## Approving from the CLI
 
@@ -241,14 +241,14 @@ kici approve <run-id>
 # Approve a held job
 kici approve <run-id> --job deploy-production
 
-# Approve a held step
-kici approve <run-id> --job migrate-and-deploy --step apply-migration
+# Approve a held step (--step takes the step's zero-based index within the job)
+kici approve <run-id> --job migrate-and-deploy --step 1
 
 # Reject (a reason is required)
 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-reference/#kici-approve) for the full command reference.
+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`
 
@@ -262,12 +262,14 @@ 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`).
 
-You can also approve from the dashboard approval queue. See [Dashboard](https://docs.kici.dev/user/dashboard/environments-and-secrets/#approval-queue).
+`--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.
-- [Environments](https://docs.kici.dev/user/environments/) — operator-required reviewers on protected environments.
+- [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.
 
@@ -329,7 +331,7 @@ group: () => 'deploy';
 group: (ctx) => `deploy-${ctx.event.targetBranch ?? 'default'}`;
 ```
 
-The workflow-level group function is always evaluated **agent-side** at runtime -- the lock file records only that a group function exists (`hasGroup: true`), not the function itself. The agent loads the workflow source, calls the group function with `{ branch, event }`, and reports the evaluated key back to the orchestrator before step execution begins. This differs from job-level `concurrencyGroup` (see [Environments](https://docs.kici.dev/user/environments/#concurrency-groups)), where the compiler performs purity analysis and can inline pure functions for orchestrator-side evaluation.
+The workflow-level group function is always evaluated **agent-side** at runtime -- the lock file records only that a group function exists (`hasGroup: true`), not the function itself. The agent loads the workflow source, calls the group function with `{ branch, event }`, and reports the evaluated key back to the orchestrator before step execution begins. This differs from job-level `concurrencyGroup` (see [Contexts](https://docs.kici.dev/user/contexts/#concurrency-groups)), where the compiler performs purity analysis and can inline pure functions for orchestrator-side evaluation.
 
 ## cancelInProgress mode
 
@@ -355,9 +357,7 @@ workflow('deploy', {
     group: (ctx) => `deploy-${ctx.branch}`,
     cancelInProgress: true,
   },
-  jobs: [
-    /* ... */
-  ],
+  jobs: [/* ... */],
 });
 ```
 
@@ -381,9 +381,7 @@ workflow('migrate-db', {
     cancelInProgress: false,
     max: 1,
   },
-  jobs: [
-    /* ... */
-  ],
+  jobs: [/* ... */],
 });
 ```
 
@@ -401,9 +399,7 @@ workflow('test', {
     cancelInProgress: false,
     max: 3,
   },
-  jobs: [
-    /* ... */
-  ],
+  jobs: [/* ... */],
 });
 ```
 
@@ -422,10 +418,8 @@ workflow('deploy', {
   jobs: [
     job('deploy-staging', {
       runsOn: 'linux',
-      environment: 'staging',
-      steps: [
-        /* ... */
-      ],
+      context: 'staging',
+      steps: [/* ... */],
     }),
   ],
 });
@@ -440,9 +434,7 @@ workflow('migrate', {
     group: () => 'db-migration',
     cancelInProgress: false,
   },
-  jobs: [
-    /* ... */
-  ],
+  jobs: [/* ... */],
 });
 ```
 
@@ -458,17 +450,15 @@ workflow('deploy', {
     },
     cancelInProgress: true,
   },
-  jobs: [
-    /* ... */
-  ],
+  jobs: [/* ... */],
 });
 ```
 
-## Interaction with environment protection
+## Interaction with context protection
 
-When a workflow has both `concurrency` and `environment` protection rules:
+When a workflow has both `concurrency` and `context` protection rules:
 
-1. Environment protection gates (required reviewers, wait timer) apply first
+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
 
@@ -480,17 +470,15 @@ Queued runs can be cancelled before they start executing. The cancel request rem
 
 ## 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 [Environments — concurrency groups](https://docs.kici.dev/user/environments/#concurrency-groups) for details.
+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 local` honors workflow-level `concurrency` per-machine, per-user. The `group` callback is evaluated against the simulated event identically to the remote orchestrator path; `cancelInProgress` carries the same semantics — `true` interrupts the holder via `SIGTERM` (escalating to `SIGKILL` after a grace window) and proceeds with the new run, while `false` queues the new invocation in FIFO order until the holder finishes.
-
-Coordination is local only. Running the same workflow on two different machines does not serialize across them — that requires the orchestrator. For full cross-host enforcement (queueing across agents, dashboard visibility, `max > 1`), use `kici run remote` against a deployed orchestrator.
+`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.
 
-Lock files live under `$XDG_RUNTIME_DIR/kici-local-locks/` on Linux, falling back to `os.tmpdir()/kici-local-locks-<uid>/`. A workflow whose `group` callback throws aborts the run with a clear error rather than running unprotected. See [`kici run local` — Concurrency enforcement](https://docs.kici.dev/user/cli-reference/#concurrency-enforcement) for the `KICI_LOCAL_LOCK_KILL_GRACE_MS` override and the diagnostic output emitted while contending on a busy lock.
+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.
 
-The `kici run local --concurrency <n>` flag is a separate concept — it caps **job-level** parallelism within a single run (how many jobs from one workflow run at once), not cross-run serialization.
+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.
 
 ---
 
@@ -498,239 +486,19 @@ _Source: `packages/sdk/src/types.ts` (WorkflowOptions.concurrency, JobOptions.co
 
 ---
 
-## 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                   |
-| [Environments, secrets, and approvals](https://docs.kici.dev/user/dashboard/environments-and-secrets/)       | Environments, secret scopes, approval queue                             |
-| [Activity and DLQ](https://docs.kici.dev/user/dashboard/activity-and-dlq/)                                   | Forensic activity log and dead-letter queue                             |
-| [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 `environment`, `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'],
-  environment: (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.
-  environment: (event) => (event.type === 'pull_request' ? 'preview' : 'production'),
-  steps: [
-    /* ... */
-  ],
-});
-```
-
-## How it works
-
-When you define a dynamic value as a function, the compiler analyzes it at compile time to determine whether it is **pure** (can be evaluated without cloning the repo or running an init job).
-
-### Pure functions (inline evaluation)
-
-A pure function is one that:
-
-- Is synchronous (no `async`/`await`)
-- Only references its parameters and local variables
-- Does not import or require external modules
-- Does not access globals like `process`, `fetch`, `console`, `setTimeout`, etc.
-- Uses only safe built-in constructors: `String`, `Number`, `Boolean`, `Array`, `Object`, `JSON`, `Math`, `parseInt`, `parseFloat`, `isNaN`, `isFinite`, `encodeURIComponent`, `decodeURIComponent`, `encodeURI`, `decodeURI`
-- Does not use `this`, `new`, `class`, `throw`, `try`/`catch`, `delete`, `var`, `yield`, or mutation operators (`++`, `--`, `+=`, etc.)
-
-When the compiler detects a pure function, it serializes the function source directly into the lock file as an inline expression. At dispatch time, the orchestrator evaluates the expression in a sandboxed VM context (~0ms overhead) instead of dispatching an init job.
-
-**Examples of pure functions:**
-
-```typescript
-// Simple branch extraction
-environment: (event) => event.targetBranch;
-
-// Object literal with string operations
-env: (event) => ({ BRANCH: event.targetBranch });
-
-// Concatenation with event data
-concurrencyGroup: (event) => `deploy-${event.targetBranch}`;
-
-// Using safe globals
-env: (event) => ({ UPPER: String(event.targetBranch).toUpperCase() });
-
-// Local variables are fine
-environment: (event) => {
-  const parts = event.targetBranch.split('/');
-  return parts[parts.length - 1];
-};
-```
-
-### Impure functions (init-job evaluation)
-
-If the compiler determines a function is impure, it emits a warning during compilation and falls back to the two-phase init model. This means:
-
-1. The orchestrator dispatches a special `__init__` job to a builder agent
-2. The builder agent clones the repository and evaluates the function
-3. The resolved values are sent back to the orchestrator
-4. The orchestrator dispatches the real execution job with the resolved values
-
-This adds approximately 5-10 seconds of overhead for cloning and evaluation.
-
-**Examples of impure functions (will use init job):**
-
-```typescript
-// Async functions cannot be inlined
-environment: async (event) => await lookupEnv(event.targetBranch);
-
-// External module references
-env: (event) => {
-  const config = require('./config');
-  return config.env;
-};
-
-// Process/global access
-environment: (event) => process.env.DEFAULT_ENV || 'staging';
-
-// Dynamic imports
-env: async (event) => {
-  const m = await import('./config.js');
-  return m.default;
-};
-```
-
-## Performance comparison
-
-| Evaluation path                      | Overhead | When used                                                           |
-| ------------------------------------ | -------- | ------------------------------------------------------------------- |
-| Static value (string/object literal) | ~0ms     | `environment: 'staging'`                                            |
-| Inline expression (pure function)    | ~0ms     | `environment: (event) => event.targetBranch`                        |
-| Init job (impure function)           | ~5-10s   | `environment: async (event) => await lookupEnv(event.targetBranch)` |
-
-## Tips
-
-- **Write pure functions whenever possible** to avoid the init-job delay. Most environment and env computations only need the event payload data.
-- **Check compiler warnings** -- the compiler tells you when a function is classified as impure and explains why.
-- **Runtime errors in inline expressions cause immediate job failure.** There is no fallback to the init-job path. If your pure function throws at runtime (e.g., accessing a property on `undefined`), the job fails immediately.
-- **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 via the `open` package |
-| `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   |
-
-## Usage examples
-
-### CI/CD environment
-
-Authenticate with a pre-existing API key (no browser needed):
-
-```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
-```
-
----
-
-## Environments
+## Contexts
 
-Source: https://docs.kici.dev/user/environments/
+Source: https://docs.kici.dev/user/contexts/
 
-<!-- help:environments-list#overview -->
+<!-- help:contexts-list#overview -->
 
-Environments are named deployment targets (like staging or production) that control where your workflow jobs run. Each environment can have its own variables, secrets, and protection rules to gate deployments.
+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:environments-list -->
+<!-- /help:contexts-list -->
 
-<!-- help:environments-protection#protection-rules -->
+<!-- help:contexts-protection#protection-rules -->
 
-Protection rules control when jobs targeting an environment can execute.
+Protection rules control when jobs targeting a context can execute.
 
 Available rules:
 
@@ -739,24 +507,24 @@ Available rules:
 - **Wait timers** — delay execution for a fixed period.
 - **Concurrency limits** — prevent collisions between parallel deployments.
 
-<!-- /help:environments-protection -->
+<!-- /help:contexts-protection -->
 
-Environments represent deployment targets like `staging`, `production`, or `review/PR-*`. Each environment can have its own variables, bound secrets, and protection rules that control when and how jobs targeting that environment can execute.
+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
 
-An environment in KiCI provides:
+A context in KiCI provides:
 
 - **Variables** -- non-secret key-value configuration (e.g., `API_URL`, `CLUSTER_NAME`)
-- **Scoped secrets** -- encrypted values bound to the environment via scope bindings
+- **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 environment property
+### Job-level context property
 
-The `environment` property is set on a job, not a workflow or step:
+The `context` property is set on a job, not a workflow or step:
 
 ```typescript
 import { workflow, job, step, push } from '@kici-dev/sdk';
@@ -766,16 +534,16 @@ export default workflow('deploy', {
   jobs: [
     job('deploy-staging', {
       runsOn: 'default',
-      environment: 'staging',
+      context: 'staging',
       steps: [
         step('deploy', async (ctx) => {
-          // ctx.environment is the resolved environment name
-          console.log(`Deploying to ${ctx.environment}`);
-          // ctx.secrets provides async get/expose/has methods for environment-bound secrets
+          // 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.environment}`;
+          await ctx.$`deploy --target ${ctx.context}`;
         }),
       ],
     }),
@@ -783,54 +551,54 @@ export default workflow('deploy', {
 });
 ```
 
-### Dynamic environments
+### Dynamic contexts
 
-The environment name can be a string or a function (sync or async) for dynamic environments (e.g., per-PR review environments). The function receives the normalized event envelope, with the raw provider body nested at `event.payload`:
+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',
-  environment: (event) => `review/PR-${event.payload.pull_request.number}`,
+  context: (event) => `review/PR-${event.payload.pull_request.number}`,
   steps: [
     step('deploy', async (ctx) => {
-      // ctx.environment is 'review/PR-123' (resolved at runtime)
-      await ctx.$`deploy-preview --env ${ctx.environment}`;
+      // ctx.context is 'review/PR-123' (resolved at runtime)
+      await ctx.$`deploy-preview --env ${ctx.context}`;
     }),
   ],
 });
 ```
 
-A pure function like the one above (see [Dynamic values](https://docs.kici.dev/user/dynamic-values/)) is evaluated inline at dispatch with no init-job overhead. Dynamic environments that match a glob pattern (e.g., `review/*`) inherit the pattern's configuration, variables, and protection rules.
+A pure function like the one above (see [Dynamic values](https://docs.kici.dev/user/dynamic-values/)) is evaluated inline at dispatch with no init-job overhead. Dynamic contexts that match a glob pattern (e.g., `review/*`) inherit the pattern's configuration, variables, and protection rules.
 
-### Multiple environments per job
+### Multiple contexts per job
 
-A job can bind more than one environment with `environments`, an ordered array. This lets a single job draw secrets and variables from several environments at once — for example a shared `staging` environment plus a `my-testing` environment that carries test-only variables:
+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:
 
 ```typescript
 job('deploy', {
   runsOn: 'default',
-  environments: ['staging', 'my-testing'],
+  contexts: ['staging', 'my-testing'],
   steps: [
     step('deploy', async (ctx) => {
-      // ctx.secrets and ctx.env carry the merged set from both environments
+      // ctx.secrets and ctx.env carry the merged set from both contexts
       const dbUrl = await ctx.secrets.get('DB_URL');
     }),
   ],
 });
 ```
 
-- `environment` (singular) and `environments` (array) are mutually exclusive — setting both is a compile error. `environment: 'staging'` is exactly equivalent to `environments: ['staging']`.
-- Each array entry is a static name or a function of the event, resolved per element exactly like a single dynamic environment.
+- `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 environments 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 environment, the later entry in the array wins. With `environments: ['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 environment.
+**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 environment's gates — adding an environment can never loosen access. Branch restrictions, trigger-type filters, and repo patterns must pass for all environments; the minimum trust tier is the most restrictive across them; required reviewers are the union of all environments' reviewers; the wait timer is the longest; and the hold expiry is the shortest. If a run is gated out, the rejection names which environment 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.
+**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.
 
-**Skip-on-test (allow-and-warn).** On a test or local run (`kici run remote`, `kici run local`), a bound environment never rejects the run. Any bound environment 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 environment(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 `environments: ['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 environment 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/).
+**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 environments contribute nothing at dispatch.** At dispatch time a bound environment name with no matching configured environment (and no matching glob environment) simply adds no variables, secrets, or protection rules — the job still runs, exactly as a single dynamic environment resolving to an as-yet-unconfigured name does today.
+**Unconfigured contexts contribute nothing at dispatch.** At dispatch time a bound context name with no matching configured context (and no matching glob context) 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.
 
-**Registration rejects a provably-unsatisfiable binding.** When a workflow is registered, KiCI statically checks every multi-environment binding: a bound environment that does not exist, a disabled one, or two environments 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 environments, and the rule — for example `unsatisfiable environment binding: job 'deploy' binds environments [staging, my-testing] with mutually exclusive branch restrictions (no value satisfies all bound environments)`. Bindings whose restrictions use globs are undecidable at registration and fall through to the dispatch-time gate check instead.
+**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.
 
 ### Job-level environment variables
 
@@ -839,7 +607,7 @@ The `env` property on a job provides static or dynamic environment variables:
 ```typescript
 job('deploy', {
   runsOn: 'default',
-  environment: 'production',
+  context: 'production',
   env: { DEPLOY_TARGET: 'us-east-1' },
   // Or dynamic:
   // env: (event) => ({ DEPLOY_SHA: event.payload.after?.slice(0, 7) }),
@@ -854,34 +622,32 @@ job('deploy', {
 
 ### Concurrency groups
 
-Jobs can define their own concurrency groups to control concurrent execution within an environment. For workflow-level concurrency (which applies to all jobs in a workflow), see [Concurrency groups](https://docs.kici.dev/user/concurrency/).
+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 environment:
+Control concurrent deployments to the same context:
 
 ```typescript
 job('deploy', {
   runsOn: 'default',
-  environment: 'production',
+  context: 'production',
   concurrencyGroup: 'production-api',
   // Or dynamic:
   // concurrencyGroup: (event) => `review-${event.payload.pull_request.number}`,
-  steps: [
-    /* ... */
-  ],
+  steps: [/* ... */],
 });
 ```
 
-If no `concurrencyGroup` is specified, the environment name is used as the default concurrency group. For a job bound to multiple environments, the default is the **first** bound environment's name.
+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.environment` | `string \| undefined`                 | Resolved environment name (undefined for jobs without environment)                        |
-| `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) |
+| 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                                                                                                                                                        |
 | -------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -898,25 +664,25 @@ The full secrets API — including `SecretFileOptions`, log masking, and the can
 
 ## Environment variable merge precedence
 
-When a job targets an environment, variables are merged in this order (last wins):
+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 environment vars** -- from the dashboard, managed per-environment
+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/environments/#step-context) section above.
+> **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
 
-Environments can have protection rules that gate job execution:
+Contexts can have protection rules that gate job execution:
 
 ### Branch restrictions
 
-Limit which branches can deploy to an environment:
+Limit which branches can deploy to a context:
 
 ```
 Allowed branches: main, release/*
@@ -932,7 +698,7 @@ 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-reference/#kici-approve) command, or the API. Held runs expire after a configurable timeout.
+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.
 
@@ -973,68 +739,72 @@ See the [CI security architecture docs](https://docs.kici.dev/architecture/secur
 
 ### Security approval queue
 
-When a PR is held for security review (unknown contributor, workflow modification, or trust policy violation), it enters the security approval queue. This is separate from environment-level approval queues.
+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+`)
 
-Security holds expire after a configurable timeout (default 1 hour).
+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 an environment:
+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 environments
+### Creating contexts
 
-Navigate to **Settings > Environments** in the dashboard. Click **New environment** to choose the environment name and type (Fixed or Glob).
+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 environment name, like `staging` or `production`
-- **Glob** -- applies to any environment name a job declares that matches the pattern, e.g. `review/*` matches a job with `environment: 'review/PR-123'`
+- **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 environments list shows each environment'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.
+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.
 
-### Environment detail page
+### Context detail page
 
-Each environment has four tabs:
+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.
+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 environment.
+4. **History** -- view filtered runs targeting this context.
 
-### Bound environments on runs
+### Bound contexts on runs
 
-A job's bound deployment environments 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-environment job the chips read left-to-right in merge order — later environments override earlier ones on key collisions. A `(dynamic)` chip marks an environment whose name is computed at runtime; it resolves to the real name once the run starts. A job that binds a single environment shows one chip; a job that binds none shows no chip.
+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-environment binding is gated out, the run's failure banner names which environment and which rule rejected it (the same all-must-pass detail surfaced by `kici runs show <run-id>`).
+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 environments via bindings:
+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 environment binding checkboxes
-- **Environment-centric view** (inside environment detail): bound scopes, resolved secrets, add binding
+- **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 environments) and `EnvironmentSecrets` (per-environment key unions):
+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 {
@@ -1042,13 +812,262 @@ interface KnownSecretKeys {
   API_KEY: string;
 }
 
-interface EnvironmentSecrets {
+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. `EnvironmentSecrets` maps each environment to its available secret key names as a string union. Dynamic environments fall back to the full `KnownSecretKeys` union.
+`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, the compiler analyzes it at compile time to determine whether it is **pure** (can be evaluated without cloning the repo or running an init job).
+
+### Pure functions (inline evaluation)
+
+A pure function is one that:
+
+- Is synchronous (no `async`/`await`)
+- Only references its parameters and local variables
+- Does not import or require external modules
+- Does not access globals like `process`, `fetch`, `console`, `setTimeout`, etc.
+- Uses only safe built-in constructors: `String`, `Number`, `Boolean`, `Array`, `Object`, `JSON`, `Math`, `parseInt`, `parseFloat`, `isNaN`, `isFinite`, `encodeURIComponent`, `decodeURIComponent`, `encodeURI`, `decodeURI`
+- Does not use `this`, `new`, `class`, `throw`, `try`/`catch`, `delete`, `var`, `yield`, or mutation operators (`++`, `--`, `+=`, etc.)
+
+When the compiler detects a pure function, it serializes the function source directly into the lock file as an inline expression. At dispatch time, the orchestrator evaluates the expression in a sandboxed VM context (~0ms overhead) instead of dispatching an init job.
+
+**Examples of pure functions:**
+
+```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}`;
+
+// Using safe globals
+env: (event) => ({ UPPER: String(event.targetBranch).toUpperCase() });
+
+// Local variables are fine
+context: (event) => {
+  const parts = event.targetBranch.split('/');
+  return parts[parts.length - 1];
+};
+```
+
+### Impure functions (init-job evaluation)
+
+If the compiler determines a function is impure, it prints a `warning [W101]` naming the affected field (`context`, `env`, or `concurrencyGroup`), the reason the function was judged impure, and the ~5-10 second init-job cost — and compilation still succeeds. The function falls back to the two-phase init model. This means:
+
+1. The orchestrator dispatches a special `__init__` job to a builder agent
+2. The builder agent clones the repository and evaluates the function
+3. The resolved values are sent back to the orchestrator
+4. The orchestrator dispatches the real execution job with the resolved values
+
+This adds approximately 5-10 seconds of overhead for cloning and evaluation.
+
+`kici preview` lists the injected `__init__` job under each affected job, so you can spot the init-job cost before the first run.
+
+**Examples of impure functions (will use init job):**
+
+```typescript
+// Async functions cannot be inlined
+context: async (event) => await lookupEnv(event.targetBranch);
+
+// External module references
+env: (event) => {
+  const config = require('./config');
+  return config.env;
+};
+
+// Process/global access
+context: (event) => process.env.DEFAULT_ENV || 'staging';
+
+// Dynamic imports
+env: async (event) => {
+  const m = await import('./config.js');
+  return m.default;
+};
+```
+
+## Performance comparison
+
+| Evaluation path                      | Overhead | When used                                                       |
+| ------------------------------------ | -------- | --------------------------------------------------------------- |
+| Static value (string/object literal) | ~0ms     | `context: 'staging'`                                            |
+| Inline expression (pure function)    | ~0ms     | `context: (event) => event.targetBranch`                        |
+| Init job (impure function)           | ~5-10s   | `context: async (event) => await lookupEnv(event.targetBranch)` |
+
+## Tips
+
+- **Write pure functions whenever possible** to avoid the init-job delay. Most context and env computations only need the event payload data.
+- **Check compiler warnings** -- the compiler prints a `warning [W101]` when a function is classified as impure, naming the reason and the ~5-10s init-job cost. Run `kici preview` to see the injected `__init__` job listed under each affected job before your first run.
+- **Runtime errors in inline expressions cause immediate job failure.** There is no fallback to the init-job path. If your pure function throws at runtime (e.g., accessing a property on `undefined`), the job fails immediately.
+- **See [how your workflow code executes](https://docs.kici.dev/user/execution-model/)** for the full picture of where pure vs. impure functions run relative to rules, hooks, and step bodies.
+- **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):
+
+```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
+```
 
 ---
 
@@ -1383,11 +1402,11 @@ export const deployComplete = defineEvent(
 );
 ```
 
-Then emit using the definition's name:
+Then emit using the definition — the payload is checked against the schema:
 
 ```typescript
 step('emit', async (ctx) => {
-  await ctx.emit(deployComplete.name, {
+  await ctx.emit(deployComplete, {
     env: 'prod',
     version: '1.2.3',
     services: ['api', 'web'],
@@ -1442,7 +1461,7 @@ If you've only ever used per-repo workflows so far, start with the mental model
 | 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 _Workflow authors_ setting.         |
+| 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_.   |
 
 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.
@@ -1497,7 +1516,7 @@ Global workflows are **opt-in per org**. In a fresh org, `repos:`-bearing workfl
 
 | Setting              | What it controls                                                                                                                                                                                     | Typical use                                                                                  |
 | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| Workflow authors     | 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.       |
+| Allowed author repos | Restricts which repos can **author** (register) global workflows. Globs matched against the authoring repo identifier. When OFF, any repo in the org may author globals.                             | Lock authoring to `myorg/ci-*` so random product repos can't ship org-wide automation.       |
 | Blocked source repos | Blocks dispatch for events emitted from these **source** repos, regardless of authoring. Globs matched against the event source repo identifier. When OFF, events from any repo may trigger globals. | Protect against fork spam — e.g. `!myorg/*` via `myorg/fork-*`.                              |
 | Elevated access      | Authoring repos listed here get **read access to source-repo secrets** during execution. Globs matched against the authoring repo identifier.                                                        | A `myorg/ci-deploy` repo that needs to read a source repo's `NPM_TOKEN` to publish releases. |
 
@@ -1513,7 +1532,7 @@ The page is a two-state editor — changes are local until you click **Save chan
 
 A global workflow fires only if:
 
-1. **The authoring repo is allowed.** If _Workflow authors_ 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:
+1. **The authoring repo is allowed.** If _Allowed author repos_ is ON, the workflow's authoring repo must match at least one allow-list glob. If OFF, any repo may author. Enforced at two points:
    - At registration time (extraction from the lock file — non-matching globals are dropped with a warning).
    - At 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.
@@ -1615,7 +1634,7 @@ const configureNginx = step('configure-nginx', {
 `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`,
-`approval`, `onCancel`, `cleanup`, `outputs`) composes unchanged.
+`retry`, `approval`, `onCancel`, `cleanup`, `outputs`) composes unchanged.
 
 A plain `step()` without `check` keeps its exact current behavior — the check
 facet is fully optional.
@@ -1643,21 +1662,19 @@ guaranteed side-effect-free.
 
 ## Running in check mode
 
-`--check` and `--fail-on-drift` work on both local and remote runs:
+`--check` and `--fail-on-drift` control drift reporting on `kici run remote`:
 
 ```bash
 # Apply (default): converge the workflow.
-kici run local push
+kici run push --local
 kici run remote my-fixture
 
 # Check: report drift, change nothing. Always exits 0.
-kici run local push --check
 kici run remote my-fixture --check
 
-# Check + fail on drift: exit non-zero (2) locally, or fail the run remotely,
-# when any step reports drift. Use this as a CI gate ("fail the build if prod
-# has drifted").
-kici run local push --check --fail-on-drift
+# 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
 ```
 
 `--fail-on-drift` only modifies check mode — passing it without `--check` is an
@@ -1696,7 +1713,7 @@ The two channels (Option A and Option C) compose. If you declare both, the agent
 
 ## Option A — `registries:` block
 
-Declare the registry in your workflow file and point its `tokenSecret` at a scoped secret using the qualified `<environment>:<secret-name>` syntax. The orchestrator resolves the token at dispatch time and the agent applies it for one `npm install` only.
+Declare the registry in your workflow file and point its `tokenSecret` at a scoped secret using the qualified `<context>:<secret-name>` syntax. The orchestrator resolves the token at dispatch time and the agent applies it for one `npm install` only.
 
 ```typescript
 import { workflow, job, step, push } from '@kici-dev/sdk';
@@ -1713,7 +1730,7 @@ export default workflow('build', {
   jobs: [
     job('build', {
       runsOn: 'default',
-      environment: 'production',
+      context: 'production',
       steps: [
         step('install-and-build', async (ctx) => {
           // .kici/package.json can now reference @my-org/* packages
@@ -1729,7 +1746,7 @@ Per-field rules:
 
 - **`url`** — Must be HTTPS. HTTP is permitted only for `localhost` / `127.0.0.0/8` / `::1` / `*.local` hosts, or when an operator has flipped the org-level `allow_http_npm_registries` toggle (see [`kici-admin org-settings allow-http-npm`](https://docs.kici.dev/operator/kici-admin-cli#allow-http-npm--permit-non-https-private-npm-registries)).
 - **`scope`** — Optional. When present, the registry serves only that scope (`@my-org`). When absent, this entry becomes the **default** registry — at most one entry may omit `scope`.
-- **`tokenSecret`** — Mandatory `<environment>:<secret-name>`. The orchestrator looks up the secret in the named environment via the per-environment secret resolver. The bare name **must not** contain a colon.
+- **`tokenSecret`** — Mandatory `<context>:<secret-name>`. The orchestrator looks up the secret in the named context via the per-context secret resolver. The bare name **must not** contain a colon.
 - **`alwaysAuth`** — Defaults to `true`. Forces npm to send the token on every request (even GETs), which is what most managed-registry providers require.
 
 ### How tokens reach `npm install`
@@ -1738,6 +1755,17 @@ The agent never writes the token bytes to your `.kici/.npmrc`. Each registry tok
 
 After the install completes (success or failure), the agent restores the original `.kici/.npmrc` — your committed file is never permanently modified.
 
+### Package managers
+
+The agent detects the package manager from the cloned repo — npm, pnpm, or yarn (classic and berry are both supported) — and applies the auth overlay the detected manager actually reads:
+
+| Detected manager        | Auth file the agent overlays | Notes                                                                                                                                       |
+| ----------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| npm, pnpm, yarn classic | `.kici/.npmrc`               | Auth lines carry `${VAR}` references to the job-scoped token env vars.                                                                      |
+| yarn berry (v2+)        | `.kici/.yarnrc.yml`          | Berry reads `.yarnrc.yml` instead of `.npmrc`, so the overlay uses berry's own registry/scope/auth keys with the same `${VAR}` indirection. |
+
+Either file is restored on cleanup, exactly as described above.
+
 ## Option C — committed `.kici/.npmrc` + `installEnv:`
 
 If you'd rather hand-craft the `.npmrc`, commit it under `.kici/.npmrc` with `${VAR}` placeholders, then list each variable in the workflow's `installEnv:` block using the same qualified syntax as `tokenSecret`.
@@ -1759,14 +1787,14 @@ export default workflow('build', {
   jobs: [
     job('build', {
       runsOn: 'default',
-      environment: 'production',
+      context: 'production',
       steps: [step('build', async (ctx) => ctx.$`npm run build`)],
     }),
   ],
 });
 ```
 
-The orchestrator resolves `MY_NPM_TOKEN` from the `production` environment's secret store and seeds it as `MY_NPM_TOKEN` (bare name) in the install subprocess. Your committed `.npmrc` reads it through `${MY_NPM_TOKEN}`.
+The orchestrator resolves `MY_NPM_TOKEN` from the `production` context's secret store and seeds it as `MY_NPM_TOKEN` (bare name) in the install subprocess. Your committed `.npmrc` reads it through `${MY_NPM_TOKEN}`.
 
 This path is the right answer when:
 
@@ -1788,7 +1816,7 @@ export default workflow('build', {
   jobs: [
     job('mint-codeartifact-token', {
       runsOn: 'default',
-      environment: 'production',
+      context: 'production',
       steps: [
         step('mint', async (ctx) => {
           const awsKey = await ctx.secrets.get('AWS_ACCESS_KEY_ID');
@@ -1813,7 +1841,7 @@ export default workflow('build', {
     }),
     job('build', {
       runsOn: 'default',
-      environment: 'production',
+      context: 'production',
       needs: ['mint-codeartifact-token'],
       steps: [step('build', async (ctx) => ctx.$`npm run build`)],
     }),
@@ -1837,7 +1865,7 @@ registries: [
 ],
 ```
 
-Mint the token from a fine-grained PAT with `read:packages` scope, store it as a scoped secret in the `production` environment.
+Mint the token from a fine-grained PAT with `read:packages` scope, store it as a scoped secret in the `production` context.
 
 ### GitLab Packages
 
@@ -1892,21 +1920,21 @@ registries: [
 
 ## Security model
 
-- **Per-environment scoping.** Every `tokenSecret` and `installEnv` entry is qualified with an environment name. The orchestrator runs the same protection-rule pipeline (branch / trust / concurrency / reviewer / wait-timer) against each named environment **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 environment **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 environment lacks an explicit `requiredTrustTier`.
-- **Lifecycle scripts disabled.** Whenever a private registry is in scope, the agent runs the install with `--ignore-scripts` (npm or pnpm alike). 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 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.
+- **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.
+- **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.
 - **`.npmrc` restored.** Whatever the agent appended for one install is stripped (or the file unlinked) on cleanup, so the workspace is never permanently modified.
 
 ## Reviewer-gated installs
 
-When the named install environment carries a protection rule that holds — a required reviewer (`hold`) or a wait timer (`wait`) — the install gate **pauses the whole workflow dispatch** instead of rejecting it. The run is created in the `held` state, no jobs are queued, and a workflow-scoped row appears on the held-runs page with a `Workflow` scope badge.
+When the named install context carries a protection rule that holds — a required reviewer (`hold`) or a wait timer (`wait`) — the install gate **pauses the whole workflow dispatch** instead of rejecting it. The run is created in the `held` state, no jobs are queued, and a workflow-scoped row appears on the held-runs page with a `Workflow` scope badge.
 
 - **Reviewer hold:** the run waits for an approver. On approval the dispatch resumes from the install gate, resolves the token, and dispatches its jobs as a normal run. On rejection the run transitions to `cancelled` — no jobs ever run.
 - **Wait timer:** the run waits out the timer and resumes automatically when it elapses.
 
-A `reject` protection outcome (for example a disabled environment or a branch the environment forbids) still fails the dispatch loudly with a clear reason, exactly as before — the orchestrator never dispatches a run with an unresolved install token.
+A `reject` protection outcome (for example a disabled context or a branch the context forbids) still fails the dispatch loudly with a clear reason, exactly as before — the orchestrator never dispatches a run with an unresolved install token.
 
 ## Limitations
 
@@ -1917,19 +1945,19 @@ A `reject` protection outcome (for example a disabled environment or a branch th
 
 The orchestrator exposes Prometheus counters and a histogram under the `kici_orch_install_secrets_*` prefix on its `/metrics` endpoint. They populate the **Install secrets resolution** Grafana dashboard and let operators graph install-secrets activity without digging through Loki.
 
-| Metric                                                        | Type      | Labels                         | What it tells you                                                                                                                                                                                                                                                                                       |
-| ------------------------------------------------------------- | --------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `kici_orch_install_secrets_decisions_total`                   | Counter   | `decision`, `reason`           | Pass / reject / hold volume. `decision=hold` (reason `held`) counts dispatches paused at a reviewer-gated install environment. Reject reasons enumerate the failure mode: `malformed_ref`, `invalid_url_scheme`, `env_not_found`, `protection_rule_block`, `missing_token`, `missing_install_env`, etc. |
-| `kici_orch_install_secrets_npm_registry_used_total`           | Counter   | `channel`, `provider`, `scope` | Per-channel + per-scope usage. `channel=registries` is Option A, `channel=install_env` is Option C. `scope=default` marks a no-scope default registry; `scope=-` marks Option C entries.                                                                                                                |
-| `kici_orch_install_secrets_contributor_stripped_total`        | Counter   | `trust_tier`                   | Number of dispatches where registry tokens were stripped because the contributor tier wasn't `trusted` (fork PRs from unknown / known contributors). Expected to be 0 in single-tenant orgs.                                                                                                            |
-| `kici_orch_install_secrets_token_resolution_duration_seconds` | Histogram | `environment`                  | Latency of per-environment secret resolution. Pathological tails (>500ms) usually mean a Vault timeout or a slow Postgres replica.                                                                                                                                                                      |
+| Metric                                                        | Type      | Labels                         | What it tells you                                                                                                                                                                                                                                                                                   |
+| ------------------------------------------------------------- | --------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `kici_orch_install_secrets_decisions_total`                   | Counter   | `decision`, `reason`           | Pass / reject / hold volume. `decision=hold` (reason `held`) counts dispatches paused at a reviewer-gated install context. Reject reasons enumerate the failure mode: `malformed_ref`, `invalid_url_scheme`, `env_not_found`, `protection_rule_block`, `missing_token`, `missing_install_env`, etc. |
+| `kici_orch_install_secrets_npm_registry_used_total`           | Counter   | `channel`, `provider`, `scope` | Per-channel + per-scope usage. `channel=registries` is Option A, `channel=install_env` is Option C. `scope=default` marks a no-scope default registry; `scope=-` marks Option C entries.                                                                                                            |
+| `kici_orch_install_secrets_contributor_stripped_total`        | Counter   | `trust_tier`                   | Number of dispatches where registry tokens were stripped because the contributor tier wasn't `trusted` (fork PRs from unknown / known contributors). Expected to be 0 in single-tenant orgs.                                                                                                        |
+| `kici_orch_install_secrets_token_resolution_duration_seconds` | Histogram | `environment`                  | Latency of per-environment secret resolution. Pathological tails (>500ms) usually mean a Vault timeout or a slow Postgres replica.                                                                                                                                                                  |
 
 The dashboard JSON lives at `infra/terraform/modules/grafana/dashboards/install-secrets.json`; if you maintain your own monitoring stack, you can import it directly.
 
 ## See also
 
-- [Secrets](https://docs.kici.dev/user/secrets/) — how to seed the `<environment>:<secret-name>` values referenced by `tokenSecret` / `installEnv`.
-- [Environments](https://docs.kici.dev/user/environments/) — protection rules (`branch_restrictions`, `requires_review`, `minimum_trust`) that the install gate inherits.
+- [Secrets](https://docs.kici.dev/user/secrets/) — how to seed the `<context>:<secret-name>` values referenced by `tokenSecret` / `installEnv`.
+- [Contexts](https://docs.kici.dev/user/contexts/) — protection rules (`branch_restrictions`, `requires_review`, `minimum_trust`) that the install gate inherits.
 - [Operator: `kici-admin org-settings`](https://docs.kici.dev/operator/kici-admin-cli#org-settings----org-level-security-policy) — the `allow_http_npm_registries` toggle and other org-scoped knobs.
 
 ---
@@ -1958,13 +1986,20 @@ An attestation is a self-contained bundle holding three things:
   commit, ref, workflow, run/job identifiers, timestamps).
 - A **[DSSE](https://github.com/secure-systems-lab/dsse) signature** over that
   statement, made with an ephemeral signing key generated for the run.
-- A short-lived **OIDC identity token** issued by the KiCI platform that binds
-  the signature to the build identity. The token's identity claims
-  (`repository`, `ref`, `sha`, run/job ids) are derived by the platform from the
-  run itself — a step cannot forge them.
+- A short-lived **OIDC identity token** issued by your **orchestrator** that
+  binds the signature to the build identity. The token's identity claims
+  (`repository`, `ref`, `sha`, run/job ids) are derived by the orchestrator from
+  the run itself — a step cannot forge them.
+
+The orchestrator owns the provenance root of trust: it holds its own long-lived
+ES256 signing key, mints and signs the identity token **locally** from its own
+run records, and publishes its own OIDC discovery + public key set (JWKS). Builds
+therefore produce verifiable provenance with **no dependency on the hosted KiCI
+platform** — the availability, sovereignty, and air-gap story all follow from
+this.
 
 Because the bundle carries the identity token and the public signing key, it is
-**offline-verifiable**: a verifier checks it against the platform's published
+**offline-verifiable**: a verifier checks it against the orchestrator's published
 signing keys with no per-attestation online lookup.
 
 ## Attesting an artifact in a workflow
@@ -2013,8 +2048,11 @@ The identity token is fetched and masked in logs automatically — you never
 handle it. The call returns `{ storageKey, subjectDigest, bundleMediaType }`
 identifying the stored bundle.
 
-`ctx.attestProvenance` is only available inside a running job step. Calling it
-during local execution rejects with a clear error.
+`ctx.attestProvenance` is only available inside a running job step; calling it
+outside one rejects with a clear error. `kici run --local` runs are supported:
+the offline local dev plane signs with a dev identity under the
+clearly-non-production issuer `kici-local`, and those bundles verify against a
+trust root exported with `kici local trust-root`.
 
 ### Requesting a raw identity token
 
@@ -2031,11 +2069,11 @@ step('mint', async (ctx) => {
 
 The token is a short-lived (about 10 minutes) signed JWT scoped to the current
 run and job. Its identity claims (`repository`, `ref`, `sha`, `kici_run_id`,
-`kici_job_id`) are derived by the platform from the run context, so a step cannot
-spoof them. The returned token value is automatically masked in step logs, and
-the step never holds platform credentials — the request is relayed through the
-orchestrator, which mints the token on the step's behalf. Like
-`attestProvenance`, it is only available inside a running job step.
+`kici_job_id`) are derived by the orchestrator from the run context, so a step
+cannot spoof them. The returned token value is automatically masked in step logs,
+and the step never holds signing credentials — the orchestrator mints and signs
+the token on the step's behalf from its own run records. Like `attestProvenance`,
+it is only available inside a running job step.
 
 ## Verifying an attestation
 
@@ -2051,14 +2089,27 @@ kici verify-attestation [artifact] --bundle <path-or-url> [--trust-root <url-or-
 
 ### Which trust root do I use?
 
-The trust root is the **KiCI platform's provenance issuer** — the same hosted
-KiCI platform you `kici login` against. KiCI attestations are issued by, and
-verified against, that one issuer; there are no competing "roots" to choose
-between. So the answer to "shouldn't I just use KiCI as the trust root?" is yes
-— and that's the **default**: omit `--trust-root` and the verifier checks the
-bundle against the hosted KiCI platform automatically. You only pass
-`--trust-root` to verify against a different environment or, more commonly, an
-offline `{ issuer, jwks }` file for air-gapped checks.
+The trust root is **your orchestrator's provenance issuer** — the orchestrator
+you `kici login` against, which owns the provenance signing key and publishes its
+own JWKS. That is the **default**: omit `--trust-root` and the verifier checks the
+bundle against your configured orchestrator automatically. There are three ways to
+verify, and offline is always the primary one:
+
+1. **Offline against a JWKS / trust-root file (air-gap)** — export the
+   `{ issuer, jwks }` file once with `kici-admin signing-key export --public` and
+   verify against it with `--trust-root <file>`. No network needed at verify time.
+2. **Directly online against your orchestrator** — the default: the verifier
+   resolves your orchestrator's discovery → JWKS. You can also POST a bundle to
+   the orchestrator's native `POST /v1/verify-attestation` endpoint for a verdict
+   against its live keys (fresh rotations / revocations included).
+3. **Against the hosted KiCI platform** — bundles produced before your
+   orchestrator owned signing were signed by the hosted platform; those keep
+   verifying forever. When no orchestrator is configured, the default falls back
+   to the hosted platform's issuer so those historical bundles still verify with
+   no flag.
+
+You pass `--trust-root` to verify against a different environment or, most
+commonly, an offline `{ issuer, jwks }` file for air-gapped checks.
 
 ### Why you supply it out-of-band
 
@@ -2101,7 +2152,7 @@ when it does not (or on an error such as a missing flag or unreachable trust
 root).
 
 ```bash
-# Default: verify against the hosted KiCI platform (no --trust-root needed):
+# Default: verify against your configured orchestrator (no --trust-root needed):
 kici verify-attestation ./dist/app.tgz --bundle ./app.tgz.kici.json
 
 # Override the trust root to verify against a specific issuer:
@@ -2115,7 +2166,7 @@ kici verify-attestation ./dist/app.tgz \
   --trust-root ./kici-trust-root.json
 ```
 
-The full flag reference is in the [CLI reference](https://docs.kici.dev/user/cli-reference/#kici-verify-attestation).
+The full flag reference is in the [CLI reference](https://docs.kici.dev/user/cli/notifications-and-diagnostics/#kici-verify-attestation).
 
 ## Viewing attestations in the dashboard
 
@@ -2157,6 +2208,7 @@ The **Attestations** page lists every build-provenance attestation your organiza
 - **Search** by artifact digest (exact `sha256:…`) or name to trace a specific artifact.
 - **Filter** by verification status, repository, workflow, job, or date.
 - Each row's **status badge** is the verdict KiCI recorded when the attestation was produced (`verified`, `failed`, `unverifiable`, or `pending`).
+- **Retry** on a `pending` row asks your orchestrator to mint that run's outstanding attestations now; **Retry pending** does the same for every pending run at once.
 
 Open a row for the parsed provenance statement and a live re-verification.
 
@@ -2170,6 +2222,19 @@ the bundle did not pass; `unverifiable` means no verdict could be computed (no
 provenance issuer configured, or its keys could not be read — not a forgery
 signal); `pending` means the verdict has not been computed yet.
 
+A `pending` row is one still waiting to be minted — the attestation was signed
+at build time, but attaching its identity token has not completed yet. Those
+rows carry a **Retry** button that asks your orchestrator to mint that run's
+outstanding attestations immediately, and the page header offers **Retry
+pending** to do the same across every pending run. Only one retry runs at a
+time — the other retry buttons are unavailable until it finishes.
+
+Retrying is safe to repeat while the mint is only temporarily unavailable: the
+row stays pending and the next retry tries again. A mint that is definitively
+rejected — for example the run's records are no longer there to bind the
+attestation to — is terminal: the row stops being retried, and re-arming it is
+an operator action (`kici-admin attestations retry --include-rejected`).
+
 Opening a row leads to the **attestation detail page**:
 
 <!-- help:attestation-detail#browsing-attestations-across-runs -->
@@ -2179,13 +2244,14 @@ This page shows the parsed provenance for one attestation.
 - **Builder identity, source, and build type** come from the signed SLSA statement.
 - The **stored badge** is the verdict recorded at build time; **Re-verify** runs the check live in your browser against the current signing keys.
 - **Download** exports the signed bundle for offline verification with `kici verify-attestation`.
+
 <!-- /help:attestation-detail -->
 
 ## See also
 
 - [SDK runtime reference](https://docs.kici.dev/user/sdk/runtime/) — the `ctx.attestProvenance` and
   `ctx.kici.oidc.token` step APIs in full.
-- [CLI reference](https://docs.kici.dev/user/cli-reference/#kici-verify-attestation) — every
+- [CLI reference](https://docs.kici.dev/user/cli/notifications-and-diagnostics/#kici-verify-attestation) — every
   `kici verify-attestation` flag and exit code.
 
 ---
@@ -2198,11 +2264,11 @@ KiCI provides an explicit secrets API that gives workflow steps controlled acces
 
 ## Overview
 
-Secrets are managed per-environment in the orchestrator (see [operator docs](https://docs.kici.dev/operator/orchestrator/configuration) for setup). When a job runs with an `environment` binding, the agent receives the secret keys available for that environment but does **not** inject their values into the step's process environment. Instead, steps access secrets through the `ctx.secrets` API.
+Secrets are managed per-context in the orchestrator (see [operator docs](https://docs.kici.dev/operator/orchestrator/configuration) for setup). When a job runs with a `context` binding, the agent receives the secret keys available for that context but does **not** inject their values into the step's process environment. Instead, steps access secrets through the `ctx.secrets` API.
 
 This design prevents accidental secret leakage through child processes, log output, or error messages. Only secrets you explicitly request are loaded into memory.
 
-A job can bind several environments with `environments: ['staging', 'my-testing']`; the secret keys from all bound environments are merged in array order, with a later environment's value winning on a key collision. See [Multiple environments per job](https://docs.kici.dev/user/environments/#multiple-environments-per-job).
+A job can bind several contexts with `contexts: ['staging', 'my-testing']`; the secret keys from all bound contexts are merged in array order, with a later context's value winning on a key collision. See [Multiple contexts per job](https://docs.kici.dev/user/contexts/#multiple-contexts-per-job).
 
 ## Where secret values come from
 
@@ -2213,7 +2279,7 @@ Secret values are written either through the dashboard or through `kici-admin` r
 A fresh orchestrator starts in **permissive** mode: both surfaces are available.
 
 - **Dashboard:** Settings → Secrets → pick a scope → enter the secret name and value.
-- **CLI:** `kici-admin secret set --scope <scope> <KEY>` against the orchestrator's HTTP admin API.
+- **CLI:** `kici-admin secret set <orgId> <scope> <KEY>` against the orchestrator's HTTP admin API.
 
 Use whichever fits the workflow — most small teams stay on the dashboard; ops engineers and CI scripts use the CLI.
 
@@ -2221,7 +2287,7 @@ Use whichever fits the workflow — most small teams stay on the dashboard; ops
 
 The orchestrator operator can flip `secrets.set` (and `variables.set`) to **CLI-only** as part of the [dashboard-write policy](https://docs.kici.dev/operator/security/dashboard-write-policy). When that flip is on:
 
-- The dashboard's "Add secret" / "Edit value" controls render with a lock icon. Clicking them shows a tooltip with the exact `kici-admin secret set` invocation needed.
+- The dashboard's "Add secret" / "Edit value" controls render with a lock icon. Hovering or keyboard-focusing the lock shows a tooltip with the exact `kici-admin secret set` invocation needed. The control itself is inert, so there is nothing to click.
 - The dashboard's secrets page still lists secret **names**, scopes, and bindings — only the value-entry path moves to the CLI.
 - `kici-admin secret set` becomes the single entry point for new and updated secret values.
 
@@ -2229,26 +2295,30 @@ This configuration is common for SOC2-prep and regulated workloads, where the cu
 
 ### CLI input modes
 
-`kici-admin secret set` accepts five input modes — pick the one that fits your workflow:
+`kici-admin secret set` takes the target as three positional arguments — `<orgId> <scope> <key>` — and accepts five input modes; pick the one that fits your workflow:
 
 ```bash
 # Interactive prompt (default when stdin is a TTY). No echo, no shell history.
-kici-admin secret set --scope production DB_PASSWORD --prompt
+kici-admin secret set my-org production DB_PASSWORD --prompt
 
 # Pipe from another tool (default when stdin is not a TTY).
-pass show prod/db | kici-admin secret set --scope production DB_PASSWORD --from-stdin
+pass show prod/db | kici-admin secret set my-org production DB_PASSWORD --from-stdin
 
 # Read from a file (handy after `sops -d` to a tmpfile).
-kici-admin secret set --scope production DB_PASSWORD --from-file ./db.pass
+kici-admin secret set my-org production DB_PASSWORD --from-file ./db.pass
 
 # Read from a named environment variable (CI-friendly).
 KICI_SECRET_VALUE=$(my-secrets-fetcher prod db) \
-  kici-admin secret set --scope production DB_PASSWORD --from-env KICI_SECRET_VALUE
+  kici-admin secret set my-org production DB_PASSWORD --from-env KICI_SECRET_VALUE
 
 # Direct argv — discouraged. Prints a stderr warning ("visible in shell history").
-kici-admin secret set --scope production DB_PASSWORD --value "<plaintext>"
+kici-admin secret set my-org production DB_PASSWORD --value "<plaintext>"
 ```
 
+When the scope is a deployment context, a flag-based sugar form is also accepted:
+`kici-admin secret set --org my-org --context production --key DB_PASSWORD --prompt`.
+The two forms are mutually exclusive — mixing them is refused.
+
 Two cross-cutting flags help every mode:
 
 - `--confirm-fingerprint <hex>` — pre-compute SHA-256 of the value and pass it. The CLI rejects the call if the value's fingerprint doesn't match. Catches paste corruption.
@@ -2270,7 +2340,7 @@ export default workflow('deploy', {
   jobs: [
     job('deploy', {
       runsOn: 'default',
-      environment: 'production',
+      context: 'production',
       steps: [
         step('deploy', async (ctx) => {
           const token = await ctx.secrets.get('DEPLOY_TOKEN');
@@ -2394,7 +2464,7 @@ export default workflow('deploy', {
   jobs: [
     job('decrypt-and-deploy', {
       runsOn: 'default',
-      environment: 'production',
+      context: 'production',
       steps: [
         step('decrypt', async (ctx) => {
           const ageKeys = ctx.secrets.list().filter((k) => k.startsWith('AGE_KEY_'));
@@ -2426,7 +2496,7 @@ export default workflow('deploy', {
   jobs: [
     job('decrypt-and-deploy', {
       runsOn: 'default',
-      environment: 'production',
+      context: 'production',
       steps: [
         step('decrypt-to-env', async (ctx) => {
           await ctx.secrets.exposeFile('SOPS_AGE_KEY_FILE', {