@kici-dev/compiler 0.1.22 → 0.1.23

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

@@ -0,0 +1,2389 @@
+# KiCI Workflow features
+
+This bundle covers: Workflow features: concurrency, environments, secrets, approvals, provenance, events.
+
+## Account and sign-in
+
+Source: https://docs.kici.dev/user/account-and-login/
+
+Your KiCI account is a single identity. It stays the same no matter how you
+sign in — whether you signed up with GitHub or with an email and password.
+Changing your sign-in method does not create a new account or move your data;
+your organizations, roles, and API keys stay attached to the same identity.
+
+## Where sign-in methods are managed
+
+Sign-in methods and passwords are managed in your **account console**, provided
+by the identity provider that handles single sign-on for KiCI. The dashboard's
+**Linked accounts** page does not control how you sign in — see
+[Linked accounts vs sign-in methods](https://docs.kici.dev/user/account-and-login/#linked-accounts-vs-sign-in-methods) below.
+
+You can open the account console from the dashboard: go to your personal
+settings, open **Linked accounts**, and use the **Account console** link.
+
+## Adding a password to a GitHub-created account
+
+If you registered by signing in with GitHub and now want to sign in with an
+email and password as well:
+
+1. Open your account console.
+2. Add a password (and, if prompted, confirm your email).
+
+After this, you can sign in either with GitHub or with your email and password —
+it is the same account.
+
+## Removing GitHub as a sign-in method
+
+To stop using GitHub to sign in:
+
+1. First add a password (see above). The identity provider will not let you
+   remove your only sign-in method, so you must have another one first.
+2. In your account console, remove the GitHub sign-in method.
+
+Your account, organizations, and data are unaffected — you simply sign in a
+different way afterward.
+
+## Linked accounts vs sign-in methods
+
+The dashboard's **Linked accounts** page controls **run-attribution metadata**
+only — for example, showing your GitHub username on the runs you trigger and
+determining your contributor trust level. Unlinking a provider there removes
+that display link; it does **not** remove the provider as a way to sign in.
+
+To actually change how you sign in, use your account console as described above.
+
+---
+
+## Approval gates
+
+Source: https://docs.kici.dev/user/approvals/
+
+An **approval gate** pauses execution until an authorized person approves it. Execution resumes from exactly where it paused; a rejection (or an expired hold) fails the run.
+
+You declare a gate in your workflow with `approval`. It is available at three levels of granularity:
+
+- **Step** — pause mid-job, before a specific step runs. The agent holds the live workspace (with all prior-step state intact) for the duration of the wait.
+- **Job** — hold the job before any of its steps run.
+- **Workflow** — hold the whole run before any job is dispatched.
+
+A step-level gate can also fire **only when a check/apply step finds drift** — Terraform's plan→apply, per step. See [Drift gates](https://docs.kici.dev/user/approvals/#drift-gates-whendrift) below.
+
+Approvers are named as **teams** and **users**. A team is an operator-defined group of org members; your workflow code may name a team but can never change its membership, which is what makes a team clause a real gate rather than a suggestion. See [Approval gates (operator guide)](https://docs.kici.dev/operator/approvals/) for how operators define teams, the approval queue, and expiry; see [the architecture overview](https://docs.kici.dev/architecture/approvals/) for how a hold is evaluated and resumed.
+
+## Quick start
+
+Hold a deploy job until a member of the `leads` team approves:
+
+```typescript
+import { workflow, job, step, push } from '@kici-dev/sdk';
+
+export default workflow('deploy', {
+  on: [push({ branches: ['main'] })],
+  jobs: [
+    job('deploy-production', {
+      runsOn: 'default',
+      approval: [{ team: 'leads' }],
+      steps: [step('deploy', async (ctx) => ctx.$`deploy --prod`)],
+    }),
+  ],
+});
+```
+
+When the run reaches this job, it is held instead of dispatched. The held run appears in the dashboard approval queue and can be released from there or with the [`kici approve`](https://docs.kici.dev/user/approvals/#approving-from-the-cli) command. Once a member of `leads` approves, the job dispatches normally.
+
+## The `approval` field
+
+`approval` accepts three forms.
+
+### Shorthand: `true`
+
+```typescript
+job('deploy', {
+  runsOn: 'default',
+  approval: true,
+  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.
+
+### Approver list (AND)
+
+```typescript
+approval: [{ team: 'leads' }, { user: 'cto' }],
+```
+
+A list of approver clauses is an **AND** list: every clause must be satisfied before the element is released.
+
+- `{ team: 'leads' }` is satisfied once **any** member of the `leads` team approves.
+- `{ user: 'cto' }` is satisfied once the user `cto` approves.
+
+A single approver may satisfy more than one clause. If `cto` is also a member of `leads`, one approval from `cto` satisfies both `{ team: 'leads' }` and `{ user: 'cto' }`, releasing the element. A user is named by their KiCI user identifier (their linked identity), and a team by its name as defined by your operator.
+
+There is no OR or nested logic — clauses are always a flat AND list.
+
+### Object form: when, reason, and timeout
+
+```typescript
+approval: {
+  when: 'always',
+  approvers: [{ team: 'security' }, { team: 'leads' }],
+  reason: 'Production deploy requires security + leads sign-off',
+  timeout: 7200, // seconds
+},
+```
+
+| 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.                                                                              |
+
+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).
+
+## Granularity
+
+The same `approval` field is accepted on a workflow, a job, and a step.
+
+### Workflow-level
+
+A workflow-level gate holds the entire run before any job is dispatched:
+
+```typescript
+export default workflow('release', {
+  on: [push({ branches: ['main'] })],
+  approval: [{ team: 'release-managers' }],
+  jobs: [buildJob, publishJob],
+});
+```
+
+### Job-level
+
+A job-level gate holds just that job; other jobs in the run proceed normally:
+
+```typescript
+job('publish', {
+  runsOn: 'default',
+  approval: [{ team: 'leads' }],
+  steps: [
+    /* ... */
+  ],
+});
+```
+
+### Step-level
+
+A step-level gate pauses mid-job, immediately before the named step. Earlier steps in the job have already run and their workspace state is preserved across the wait:
+
+```typescript
+job('migrate-and-deploy', {
+  runsOn: 'default',
+  steps: [
+    step('build-plan', async (ctx) => ctx.$`./gen-migration-plan.sh`),
+    step('apply-migration', {
+      approval: [{ team: 'dba' }],
+      run: async (ctx) => ctx.$`./apply-migration.sh`,
+    }),
+    step('deploy', async (ctx) => ctx.$`deploy --prod`),
+  ],
+});
+```
+
+Here `build-plan` runs, then the job pauses for a `dba` approval. On approval, `apply-migration` runs against the exact workspace `build-plan` produced, followed by `deploy`. A rejection or expiry fails the job.
+
+Because a step-level hold keeps an agent and its workspace occupied for the whole human wait, prefer job- or workflow-level gates when you do not need prior-step state, and keep step-level timeouts short. See the [operator note on agent occupancy](https://docs.kici.dev/operator/approvals/#agent-occupancy-during-step-level-holds).
+
+## Drift gates (`when: 'drift'`)
+
+A `when: 'drift'` gate is **step-scope only** and requires a [check/apply step](https://docs.kici.dev/user/idempotent-steps/). Instead of pausing unconditionally, it fires **between the step's `check` and `run`, only when `check` finds drift in apply mode** — exactly Terraform's plan→apply, scoped to one step. When the step is already in sync (no drift), nothing pauses and the step skips.
+
+When the gate fires, the held run carries the **computed drift** as a payload: the rendering your `summarize(drift)` produced (the per-file diff, the commands that would run), plus the structured drift. The dashboard approval queue and the [CLI](https://docs.kici.dev/user/approvals/#approving-from-the-cli) show the actual diff the operator is approving — not a static reason string.
+
+```typescript
+job('patch-prod', {
+  runsOn: 'default',
+  steps: [
+    step('apply-nginx-config', {
+      check: async (ctx) => ((await inSync(ctx)) ? null : { want: DESIRED_CONF }),
+      summarize: (drift) => `would rewrite nginx.conf (${drift.want.length} bytes)`,
+      run: async (ctx, drift) => {
+        await writeConfig(drift.want);
+      },
+      approval: { when: 'drift', approvers: [{ team: 'ops' }], reason: 'prod patch' },
+    }),
+  ],
+});
+```
+
+Behavior:
+
+- The gate fires **only in apply mode**. In `--check` mode nothing applies, so nothing gates — drift is just reported.
+- **Approve** → the step's `run(ctx, drift)` applies the change.
+- **Reject** → fail-stop: the step fails, the job fails, and the `needs:` skip-cascade aborts everything downstream.
+
+A `when: 'drift'` gate on a step without a `check` facet, or at job/workflow scope, is a compile error.
+
+## 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.
+
+## Approving from the CLI
+
+Approve or reject a held element with the `kici` CLI:
+
+```bash
+# Approve a workflow-level hold
+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
+
+# 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.
+
+### Inline approval and `--approve-all` in `kici run remote`
+
+When you trigger a run with `kici run remote` and it pauses on a gate, the CLI prints the gate (and, for a drift gate, the computed drift) and — in an interactive terminal — prompts you to approve or reject right there, without leaving the watch. In a non-interactive shell it prints how to approve out of band and keeps watching.
+
+To auto-approve **every gate of the run you just dispatched**, pass `--approve-all` (alias `--yes`):
+
+```bash
+kici run remote deploy-prod --approve-all
+```
+
+`--approve-all` is **run-scoped** — it only auto-approves holds belonging to the run this invocation dispatched; there is no fleet-wide or account-wide auto-approve. Eligibility is still enforced per hold: if you are not eligible for a gate, that gate still blocks. Each auto-approved gate prints its payload before resolving and is recorded distinctly in the audit trail (`held_run.auto_approve`).
+
+You can also approve from the dashboard approval queue. See [Dashboard](https://docs.kici.dev/user/dashboard/environments-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.
+- [Approval gates (operator guide)](https://docs.kici.dev/operator/approvals/) — teams, the approval queue, expiry, and self-approval.
+- [Approval gates (architecture)](https://docs.kici.dev/architecture/approvals/) — the unified hold model and the step-level round-trip.
+
+---
+
+## Concurrency groups
+
+Source: https://docs.kici.dev/user/concurrency/
+
+Concurrency groups prevent multiple workflow runs from executing in parallel when they target the same resource. Common use cases include preventing parallel deploys to the same environment or serializing database migrations.
+
+## Basic usage
+
+```typescript
+import { workflow, job, step, push } from '@kici-dev/sdk';
+
+export default workflow('deploy', {
+  on: push({ branches: ['main', 'staging'] }),
+  concurrency: {
+    group: (ctx) => `deploy-${ctx.branch}`,
+    cancelInProgress: true,
+    max: 1,
+  },
+  jobs: [
+    job('deploy', {
+      runsOn: 'linux',
+      steps: [
+        step('deploy', async ({ $ }) => {
+          await $`./deploy.sh`;
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+## Configuration
+
+The `concurrency` option on a workflow accepts:
+
+| Field              | Type     | Default  | Description                                |
+| ------------------ | -------- | -------- | ------------------------------------------ |
+| `group`            | Function | Required | Returns the concurrency group key string   |
+| `cancelInProgress` | boolean  | `true`   | Cancel older runs when a newer run arrives |
+| `max`              | number   | `1`      | Maximum concurrent runs in the same group  |
+
+### Group key function
+
+The group key function receives a context with the branch name and event payload. Runs with the same group key are subject to concurrency limits.
+
+```typescript
+// Per-branch concurrency (most common)
+group: (ctx) => `deploy-${ctx.branch}`;
+
+// Global concurrency (across all branches)
+group: () => 'deploy';
+
+// Per-target-branch concurrency
+group: (ctx) => `deploy-${ctx.event.targetBranch ?? 'default'}`;
+```
+
+The workflow-level group function is always evaluated **agent-side** at runtime -- the lock file records only that a group function exists (`hasGroup: true`), not the function itself. The agent loads the workflow source, calls the group function with `{ branch, event }`, and reports the evaluated key back to the orchestrator before step execution begins. 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.
+
+## cancelInProgress mode
+
+When `cancelInProgress: true`, a newer run supersedes older runs in the same group:
+
+```
+Run #1 starts deploying to main        -> running
+Run #2 arrives for deploy-main group   -> Run #1 cancelled ("Superseded by run in concurrency group 'deploy-main'")
+Run #2 continues                       -> running
+```
+
+This is the most common mode for deploy workflows -- you want the latest code deployed, not an outdated version.
+
+The cancelled run:
+
+- Receives a cancellation with reason "Superseded by run in concurrency group 'deploy-main'"
+- Goes through the normal cancel flow (grace period, hooks if graceful)
+- GitHub Check status updated to `cancelled` with the superseded reason
+
+```typescript
+workflow('deploy', {
+  concurrency: {
+    group: (ctx) => `deploy-${ctx.branch}`,
+    cancelInProgress: true,
+  },
+  jobs: [
+    /* ... */
+  ],
+});
+```
+
+## Queue mode
+
+When `cancelInProgress: false`, newer runs will wait until older runs complete:
+
+```
+Run #1 starts deploying                -> running
+Run #2 arrives for same group          -> queued ("Waiting for deploy-main (1 ahead)")
+Run #1 completes                       -> success
+Run #2 starts                          -> running
+```
+
+In queue mode, the agent that picked up the queued run **stays connected** to the orchestrator and parks on a long-poll wait. When the holder finishes (success, failure, or cancel), the orchestrator dequeues the FIFO-next entry and pushes a `proceed` notification over the same WebSocket; the queued agent then continues with normal step execution against the workspace it already has. The agent's slot is therefore held for the duration of the queue wait — bound by `KICI_CONCURRENCY_WAIT_TIMEOUT_MS` (default 1 hour).
+
+```typescript
+workflow('migrate-db', {
+  concurrency: {
+    group: () => 'migrations',
+    cancelInProgress: false,
+    max: 1,
+  },
+  jobs: [
+    /* ... */
+  ],
+});
+```
+
+The dashboard will show a "Queued" badge with the reason: "Waiting for deploy-main (1 ahead)".
+
+## Max concurrent runs
+
+The `max` field controls how many runs can execute simultaneously in the same group:
+
+```typescript
+// Allow up to 3 parallel test runs per branch
+workflow('test', {
+  concurrency: {
+    group: (ctx) => `test-${ctx.branch}`,
+    cancelInProgress: false,
+    max: 3,
+  },
+  jobs: [
+    /* ... */
+  ],
+});
+```
+
+When `max: 1` (default), runs are fully serialized within the group.
+
+## Group key examples
+
+### Deploy per environment
+
+```typescript
+workflow('deploy', {
+  concurrency: {
+    group: (ctx) => `deploy-${ctx.branch}`,
+    cancelInProgress: true,
+  },
+  jobs: [
+    job('deploy-staging', {
+      runsOn: 'linux',
+      environment: 'staging',
+      steps: [
+        /* ... */
+      ],
+    }),
+  ],
+});
+```
+
+### Global singleton
+
+```typescript
+// Only one migration can run at a time, regardless of branch
+workflow('migrate', {
+  concurrency: {
+    group: () => 'db-migration',
+    cancelInProgress: false,
+  },
+  jobs: [
+    /* ... */
+  ],
+});
+```
+
+### Environment-aware groups
+
+```typescript
+// Serialize deploys per environment
+workflow('deploy', {
+  concurrency: {
+    group: (ctx) => {
+      const env = ctx.branch === 'main' ? 'production' : 'staging';
+      return `deploy-${env}`;
+    },
+    cancelInProgress: true,
+  },
+  jobs: [
+    /* ... */
+  ],
+});
+```
+
+## Interaction with environment protection
+
+When a workflow has both `concurrency` and `environment` protection rules:
+
+1. Environment protection gates (required reviewers, wait timer) apply first
+2. Concurrency group check happens after protection gates pass
+3. If the run is queued by concurrency, it keeps its protection approval
+
+This means a run that passed approval won't need re-approval if it gets queued by concurrency.
+
+## Cancelling queued runs
+
+Queued runs can be cancelled before they start executing. The cancel request removes them from the queue immediately -- they don't go through the grace period since no step is running.
+
+## Job-level concurrency groups
+
+In addition to workflow-level concurrency, individual jobs can define their own concurrency group via the `concurrencyGroup` property. This controls concurrent execution at the job level rather than the workflow level. See [Environments — concurrency groups](https://docs.kici.dev/user/environments/#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.
+
+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.
+
+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.
+
+---
+
+_Source: `packages/sdk/src/types.ts` (WorkflowOptions.concurrency, JobOptions.concurrencyGroup)_
+
+---
+
+## 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 a self-hosted Platform or a testing environment.
+
+## 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"
+```
+
+### Self-hosted Platform or custom OIDC provider
+
+`kici login` targets the hosted KiCI Platform by default. To point the CLI at a self-hosted Platform or a testing 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
+
+Source: https://docs.kici.dev/user/environments/
+
+<!-- help:environments-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.
+
+<!-- /help:environments-list -->
+
+<!-- help:environments-protection#protection-rules -->
+
+Protection rules control when jobs targeting an environment can execute.
+
+Available rules:
+
+- **Branch restrictions** — only allow specific branches to deploy.
+- **Required reviewer approvals** — gate the run on human sign-off.
+- **Wait timers** — delay execution for a fixed period.
+- **Concurrency limits** — prevent collisions between parallel deployments.
+
+<!-- /help:environments-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.
+
+## Overview
+
+An environment 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
+- **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
+
+The `environment` property is set on a job, not a workflow or step:
+
+```typescript
+import { workflow, job, step, push } from '@kici-dev/sdk';
+
+export default workflow('deploy', {
+  on: [push({ branches: ['main'] })],
+  jobs: [
+    job('deploy-staging', {
+      runsOn: 'default',
+      environment: '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
+          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}`;
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+### Dynamic environments
+
+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`:
+
+```typescript
+job('deploy-review', {
+  runsOn: 'default',
+  environment: (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}`;
+    }),
+  ],
+});
+```
+
+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.
+
+### Job-level environment variables
+
+The `env` property on a job provides static or dynamic environment variables:
+
+```typescript
+job('deploy', {
+  runsOn: 'default',
+  environment: 'production',
+  env: { DEPLOY_TARGET: 'us-east-1' },
+  // Or dynamic:
+  // env: (event) => ({ DEPLOY_SHA: event.payload.after?.slice(0, 7) }),
+  steps: [
+    step('deploy', async (ctx) => {
+      // DEPLOY_TARGET is available in ctx.env
+      await ctx.$`deploy --region ${ctx.env.DEPLOY_TARGET}`;
+    }),
+  ],
+});
+```
+
+### Concurrency groups
+
+Jobs can define their own concurrency groups to control concurrent execution within an environment. 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:
+
+```typescript
+job('deploy', {
+  runsOn: 'default',
+  environment: 'production',
+  concurrencyGroup: 'production-api',
+  // Or dynamic:
+  // concurrencyGroup: (event) => `review-${event.payload.pull_request.number}`,
+  steps: [
+    /* ... */
+  ],
+});
+```
+
+If no `concurrencyGroup` is specified, the environment name is used as the default concurrency group.
+
+### 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)                 |
+
+| Method                          | Returns                   | Description                                                                                                                       |
+| ------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `await ctx.secrets.get(key)`    | `string`                  | Retrieve a secret value. Throws `SecretNotFoundError` if not found.                                                               |
+| `await ctx.secrets.expose(key)` | `void`                    | Inject a secret into the step's environment variables (`ctx.env`). Throws `SecretNotFoundError` if not found.                     |
+| `ctx.secrets.has(key)`          | `boolean`                 | Check if a secret key exists. Synchronous, never throws.                                                                          |
+| `ctx.secrets.getMeta(key)`      | `SecretMeta \| undefined` | Retrieve metadata (value, backend name, scope path) for a resolved secret. Returns `undefined` if not found.                      |
+| `ctx.setSecretOutput(key, val)` | `void`                    | Publish an encrypted secret output from this job, consumable by downstream jobs via `needs`. Never logged or stored in plaintext. |
+
+## Environment variable merge precedence
+
+When a job targets an environment, 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
+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.
+
+## Protection rules
+
+Environments can have protection rules that gate job execution:
+
+### Branch restrictions
+
+Limit which branches can deploy to an environment:
+
+```
+Allowed branches: main, release/*
+```
+
+Jobs from other branches are rejected immediately with an error message.
+
+### Required reviewers
+
+Require manual approval before a job can proceed:
+
+```
+Required reviewers: alice, bob
+```
+
+When reviewers are required, the job enters a "held" state. Reviewers can approve or reject via the dashboard, the [`kici approve`](https://docs.kici.dev/user/cli-reference/#kici-approve) command, or the API. Held runs expire after a configurable timeout.
+
+This operator-set rule is the **mandatory** form of an approval gate. Workflow authors can also declare gates in code with `approval` at step, job, or workflow level — see [Approval gates](https://docs.kici.dev/user/approvals/). Both forms use the same held-element mechanism and the same queue.
+
+### Wait timer
+
+Add a mandatory delay before deployment starts:
+
+```
+Wait timer: 300 seconds
+```
+
+The job waits for the specified duration before proceeding. Useful for staged rollouts.
+
+### Minimum trust
+
+Gate job execution based on the contributor's trust tier for PR-triggered runs:
+
+```
+Minimum trust: known
+```
+
+| Value     | Effect                                              |
+| --------- | --------------------------------------------------- |
+| `known`   | Blocks unknown contributors; allows known + trusted |
+| `trusted` | Blocks unknown + known; allows only trusted         |
+
+When a contributor does not meet the minimum trust level, the job is held in the security approval queue. Someone with `ci_trust:write` or higher must approve it before execution proceeds.
+
+Trust tier is determined by the contributor's identity link and CI trust RBAC level:
+
+- **Trusted** -- identity-linked org member with `ci_trust:write+` AND provider write access
+- **Known** -- identity-linked member or verified collaborator via provider API
+- **Unknown** -- no identity link and no provider access, fork PRs
+
+The trust tier also affects which lock file is used for PR-triggered runs: trusted contributors use the PR head lock file, while known and unknown contributors use the base branch lock file. This prevents untrusted workflow modifications from affecting execution.
+
+See the [CI security architecture docs](https://docs.kici.dev/architecture/security/ci-security/) for the full trust resolution flow.
+
+### Security approval queue
+
+When a PR is held for security review (unknown contributor, workflow modification, or trust policy violation), it enters the security approval queue. This is separate from environment-level approval queues.
+
+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).
+
+### Concurrency limits
+
+Control how many jobs can run simultaneously in an environment:
+
+```
+Concurrency limit: 1
+Strategy: queue (or cancel-pending)
+```
+
+- **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
+
+Navigate to **Settings > Environments** in the dashboard. Click **New environment** to choose the environment 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'`
+
+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.
+
+### Environment detail page
+
+Each environment 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.
+
+4. **History** -- view filtered runs targeting this environment.
+
+### Secrets management
+
+Secrets are individual encrypted values organized by scope paths (e.g., `aws/prod`, `databases/postgres`). Scopes are bound to environments 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
+
+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):
+
+```typescript
+interface KnownSecretKeys {
+  DB_PASSWORD: string;
+  API_KEY: string;
+}
+
+interface EnvironmentSecrets {
+  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.
+
+---
+
+## Event system
+
+Source: https://docs.kici.dev/user/events/
+
+KiCI supports two broad categories of workflow triggers: **git-based triggers** that work immediately, and **event-based triggers** that use a registration model. Understanding this distinction is key to working effectively with non-git triggers like schedules, custom events, and generic webhooks.
+
+## Overview
+
+Git-based triggers (`push()`, `pr()`, `tag()`, `comment()`, `review()`, `release()`, etc.) work immediately after you commit your lock file. When a GitHub webhook arrives, the orchestrator fetches your lock file and evaluates triggers on the spot -- no advance setup needed.
+
+Event-based triggers work differently. The orchestrator needs to know about them _before_ the event arrives. This is because event-based triggers are matched against a pre-built registration index rather than being evaluated per-event from a lock file fetch. The six event-based trigger types are:
+
+- `kiciEvent()` -- custom events emitted from workflow steps
+- `workflowComplete()` -- fires when a workflow finishes
+- `jobComplete()` -- fires when a specific job finishes
+- `genericWebhook()` -- HTTP webhooks from external services
+- `schedule()` -- cron-based time triggers
+- `lifecycle()` -- orchestrator lifecycle events (workflow completion, job failure, registration updates)
+
+All six require the **registration model** to function -- covered in detail below.
+
+## Event types
+
+### Custom events
+
+Custom events are user-defined events emitted from workflow steps using `ctx.emit()`. Use `kiciEvent()` to listen for them.
+
+```typescript
+import { kiciEvent } from '@kici-dev/sdk';
+
+// Listen for a custom event by name
+kiciEvent({ name: 'deploy-complete' });
+
+// With payload matching (JSONPath)
+kiciEvent({ name: 'deploy-complete', match: { '$.env': 'prod' } });
+
+// With negative filter
+kiciEvent({ name: 'deploy-complete', not: { '$.env': 'staging' } });
+
+// From a specific repository
+kiciEvent({ name: 'deploy-complete', source: 'org/infra-repo' });
+```
+
+**Config options:** `name` (required), `match`, `not`, `source`, `description`.
+
+### System events
+
+The orchestrator automatically emits completion events when workflows and jobs finish. No manual emission needed -- these fire automatically.
+
+**Workflow completion:**
+
+```typescript
+import { workflowComplete } from '@kici-dev/sdk';
+
+// Any workflow completion
+workflowComplete();
+
+// Specific workflow by name
+workflowComplete({ name: 'build' });
+
+// Only successful completions
+workflowComplete({ name: 'build', status: ['success'] });
+```
+
+**Config options:** `name`, `status` (`'success'`, `'failed'`, `'cancelled'`), `source`, `description`.
+
+**Job completion:**
+
+```typescript
+import { jobComplete } from '@kici-dev/sdk';
+
+// Any job completion
+jobComplete();
+
+// Specific workflow + job
+jobComplete({ workflow: 'build', job: 'test' });
+
+// Only failures
+jobComplete({ workflow: 'build', job: 'test', status: ['failed'] });
+```
+
+**Config options:** `workflow`, `job`, `status` (`'success'`, `'failed'`, `'cancelled'`, `'skipped'`), `source`, `description`.
+
+### External events
+
+Generic webhooks let you trigger workflows from any HTTP service -- Stripe, ArgoCD, Slack, Grafana, or your own internal services.
+
+```typescript
+import { genericWebhook } from '@kici-dev/sdk';
+
+// Match any event from a source
+genericWebhook({ source: 'stripe' });
+
+// Match specific event types
+genericWebhook({ source: 'stripe', events: ['invoice.paid'] });
+
+// With HMAC-SHA256 signature verification
+genericWebhook({
+  source: 'stripe',
+  events: ['invoice.paid'],
+  auth: {
+    method: 'hmac-sha256',
+    secret: 'stripe-signing-key',
+    signatureHeader: 'stripe-signature',
+  },
+});
+
+// With API key auth
+genericWebhook({
+  source: 'slack',
+  auth: { method: 'api-key', secret: 'slack-token' },
+});
+```
+
+**Config options:** `source` (required), `events`, `match`, `not`, `auth`, `path`, `description`.
+
+The `source` field MUST match the `--name` that an operator passed to `kici-admin source add generic --name <name>` when the source was created — that string is the source's identifier in the orchestrator. Generic webhook sources must be created by an operator before events can be received; see [Operator guide: event routing](https://docs.kici.dev/operator/event-routing/) for setup instructions.
+
+### Schedule events
+
+Cron-based triggers evaluated by the orchestrator on a periodic interval. Only the Raft leader evaluates schedules in a clustered deployment.
+
+```typescript
+import { schedule } from '@kici-dev/sdk';
+
+// Run every hour
+schedule({ cron: '0 * * * *' });
+
+// Run daily at 2 AM UTC
+schedule({ cron: '0 2 * * *' });
+
+// Run weekly on Mondays at 9 AM Eastern
+schedule({ cron: '0 9 * * 1', timezone: 'America/New_York' });
+```
+
+**Config options:** `cron` (required), `timezone` (defaults to `'UTC'`), `description`.
+
+### Lifecycle events
+
+Lifecycle triggers listen for orchestrator-level events related to workflow execution and system state changes.
+
+```typescript
+import { lifecycle } from '@kici-dev/sdk';
+
+// Trigger when any workflow completes
+lifecycle({ events: ['workflow_complete'] });
+
+// Trigger on job failures from a specific repo
+lifecycle({ events: ['job_failed'], sources: ['org/deploy-repo'] });
+
+// Trigger when registrations are updated
+lifecycle({ events: ['registration_updated'] });
+```
+
+**Available events:** `'workflow_complete'`, `'job_complete'`, `'job_failed'`, `'registration_updated'`.
+
+**Config options:** `events` (required), `sources`, `description`.
+
+## The registration model
+
+This is the most important concept for understanding event-based triggers.
+
+### Why registrations exist
+
+When a GitHub webhook arrives (push, PR, etc.), the orchestrator fetches your lock file from the repository and evaluates triggers on the spot. This works because the event itself tells the orchestrator _which repository_ to look at.
+
+Event-based triggers are different. When a cron timer fires or a custom event is emitted, there is no incoming webhook pointing to a specific repository. The orchestrator needs to know _in advance_ which workflows care about which events. That is what the registration model provides: a pre-built index of event-based workflows.
+
+### How registration works
+
+1. You define a workflow with an event-based trigger (e.g., `schedule()`, `kiciEvent()`, `genericWebhook()`)
+2. You compile the workflow (`kici compile`), which produces a lock file
+3. You push the lock file to your repository's **default branch** (e.g., `main` or `master`)
+4. The orchestrator receives the push webhook, detects it targets the default branch, and extracts all workflows with event-based triggers from the lock file
+5. Those workflows are stored in the orchestrator's registration database
+6. From that point on, matching events will trigger those workflows
+
+### Key implications
+
+- **Event-based workflows do not trigger until you push to the default branch.** If you add a new `schedule()` workflow, it will not start running until you merge to your default branch. This is by design -- the orchestrator cannot match events to workflows it does not know about.
+
+- **Registration is automatic.** There is no manual setup. Push your code, and the orchestrator handles the rest.
+
+- **Registrations refresh on every default-branch push.** If you add, remove, or modify event-based workflows and push to the default branch, the orchestrator updates its registration index automatically. Removed workflows stop triggering. New workflows start triggering.
+
+- **Git-based triggers are unaffected.** Triggers like `push()`, `pr()`, and `tag()` do not use registrations. They work immediately from any branch because the orchestrator evaluates them per-event from the lock file.
+
+### Practical example
+
+You create a nightly build workflow:
+
+```typescript
+import { workflow, job, step, schedule } from '@kici-dev/sdk';
+
+export default workflow('nightly-build', {
+  on: schedule({ cron: '0 2 * * *' }),
+  jobs: [
+    job('build', {
+      runsOn: 'linux',
+      steps: [
+        step('build', async ({ $ }) => {
+          await $`pnpm build`;
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+You compile it, commit the lock file, and push to a feature branch. **Nothing happens** -- the cron will not fire because the orchestrator has not registered this workflow yet.
+
+You merge the feature branch into `main`. On the merge push, the orchestrator extracts the `nightly-build` workflow (it has a `ScheduleTrigger`) and registers it. Starting at the next 2 AM UTC, the workflow will trigger.
+
+## How events are matched
+
+When an event arrives, the orchestrator follows this flow:
+
+1. **Event received** -- a custom event is emitted by a step, a cron timer fires, or a generic webhook arrives
+2. **Registration lookup** -- the orchestrator queries its registration index for workflows matching the event type (e.g., all workflows with `ScheduleTrigger` for a cron fire, or all workflows with `KiciEventTrigger` for a custom event)
+3. **Trigger evaluation** -- for each candidate workflow, the orchestrator evaluates the trigger conditions: event name patterns, payload matching, status filters, source filters
+4. **Dispatch** -- matched workflows are dispatched to agents for execution, following the same job queue and agent routing as git-triggered workflows
+
+This lookup is fast because the registration index is held in memory and refreshed only when the registry version changes (on default-branch pushes).
+
+### Cross-source webhook delivery
+
+The catch-all `webhook()` trigger (see [SDK reference: webhook()](https://docs.kici.dev/user/sdk/triggers/#webhook)) participates in this same registration lookup, but with one twist: it fires for matching events arriving via **any** inbound webhook source in the same org, not just the source the workflow's repo is bound to. The orchestrator maintains a `(customerId, eventName)` index over webhook trigger registrations and consults it on every inbound generic webhook.
+
+The lookup is structurally org-isolated — a generic webhook delivered to org A can never reach a workflow registered against org B, because foreign-org rows live in a different bucket of the index. When a webhook fires across sources, the runtime clone token, repo URL, and check-status posting all come from the **registration's** source bundle, not the inbound source. The inbound source contributes only the event payload.
+
+## Circuit breaker
+
+Events can trigger workflows that emit more events, creating chains. The circuit breaker prevents runaway event storms.
+
+### Chain depth limit
+
+Each event carries a `chainDepth` counter. When a workflow triggered by an event emits a new event, the new event's chain depth increments. The orchestrator rejects events that exceed the maximum chain depth.
+
+- **Default limit:** 10 levels deep
+- **What happens when hit:** the event is dropped and logged. It is not queued for later delivery.
+
+For example: Workflow A emits event X (depth 0) -> Workflow B triggers, emits event Y (depth 1) -> ... -> at depth 10, any further emitted events are dropped.
+
+### Rate limiting
+
+Each workflow is rate-limited on how many events it can process per minute, using a sliding window.
+
+- **Default limit:** 100 events per workflow per minute
+- **What happens when hit:** additional events for that workflow are dropped and logged until the window clears.
+
+These defaults are hardcoded in the orchestrator and are not currently configurable via environment variables.
+
+## Delivery guarantees
+
+KiCI's event router delivers every accepted event with **at-least-once** semantics:
+
+- An event that passes the circuit breaker (chain depth + rate limit) and commits
+  to the `kici_events` table is guaranteed to dispatch to all matching workflows
+  at least once.
+- Each dispatch attempt acquires a short-lived lease (default 60 s) on the row.
+  If the dispatching node crashes or the handler throws, the lease expires (or
+  is released on failure) and the event is automatically retried.
+- The retry policy is exponential backoff with full jitter: base 5 s, cap 5 min,
+  up to 5 attempts before the event lands in the **DLQ** (dead-letter queue).
+  Operators triage DLQ entries via `kici-admin event-dlq list / count / retry / discard`.
+
+**What this means for workflow authors:**
+
+- **Make event handlers idempotent.** A retried dispatch may run a handler more
+  than once (e.g. if the first attempt threw after a partial side-effect).
+  Workflows that mutate external state should use idempotency keys, conditional
+  writes, or other deduplication patterns — same advice as for any distributed
+  CI system.
+- **Schedule fires are at-least-once too.** A cron schedule that fires while a
+  leader is being killed will commit (atomically with `cron_last_fired`) or roll
+  back together — never half. Recovery on the new leader does not backfill
+  multiple missed instants; if your workflow needs at-least-N guarantees across
+  outages, drive it from a different mechanism (e.g. a workflow that runs more
+  frequently and emits its own custom event).
+- **Drops are still possible — and visible.** Events rejected by the circuit
+  breaker (chain depth or rate limit exceeded) are dropped and logged, not
+  retried. That's a deliberate safety mechanism; the metric to watch is
+  `kici_orch_events_dropped_total{reason}`.
+
+## Emitting custom events
+
+Custom events are emitted from workflow steps using `ctx.emit()`. You can optionally define typed event schemas using `defineEvent()`.
+
+### Basic emission
+
+```typescript
+import { workflow, job, step, push } from '@kici-dev/sdk';
+
+export default workflow('build', {
+  on: push({ branches: 'main' }),
+  jobs: [
+    job('build', {
+      runsOn: 'linux',
+      steps: [
+        step('build', async ({ $ }) => {
+          await $`pnpm build`;
+        }),
+        step('notify', async (ctx) => {
+          await ctx.emit('build-complete', {
+            version: '1.0.0',
+            success: true,
+          });
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+### Typed event definitions
+
+Use `defineEvent()` with Zod schemas to create a typed contract for event payloads:
+
+```typescript
+import { defineEvent, z } from '@kici-dev/sdk';
+
+export const deployComplete = defineEvent(
+  'deploy-complete',
+  z.object({
+    env: z.string(),
+    version: z.string(),
+    services: z.array(z.string()),
+  }),
+);
+```
+
+Then emit using the definition's name:
+
+```typescript
+step('emit', async (ctx) => {
+  await ctx.emit(deployComplete.name, {
+    env: 'prod',
+    version: '1.2.3',
+    services: ['api', 'web'],
+  });
+});
+```
+
+And consume in another workflow:
+
+```typescript
+import { workflow, job, step, kiciEvent } from '@kici-dev/sdk';
+
+export default workflow('post-deploy', {
+  on: kiciEvent({ name: 'deploy-complete', match: { '$.env': 'prod' } }),
+  jobs: [
+    job('smoke-test', {
+      runsOn: 'linux',
+      steps: [
+        step('test', async ({ $ }) => {
+          await $`./scripts/smoke-test.sh`;
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+Custom events are delivered immediately when emitted (mid-workflow, not queued until workflow completion). See the [SDK reference: emitting events](https://docs.kici.dev/user/sdk/validation-events/#emitting-events) section for the full `ctx.emit()` API.
+
+## See also
+
+- [SDK reference: event triggers](https://docs.kici.dev/user/sdk/triggers/#event-triggers) -- complete API signatures for all trigger builders
+- [SDK reference: emitting events](https://docs.kici.dev/user/sdk/validation-events/#emitting-events) -- `ctx.emit()` and `defineEvent()` API
+- [Workflow patterns: workflow chaining](https://docs.kici.dev/user/patterns/integrations/#workflow-chaining) -- examples of event-driven workflow chains
+- [Operator guide: event routing](https://docs.kici.dev/operator/event-routing/) -- configuring generic webhook sources, trust relationships, and event routing
+- [Architecture: event system](https://docs.kici.dev/architecture/webhooks/event-system/) -- internal event routing design, registration model, cluster synchronization
+
+---
+
+## Global workflows
+
+Source: https://docs.kici.dev/user/global-workflows/
+
+Global workflows let one **workflow repo** define jobs that run on events from many **source repos** in the same org. They're the answer to "I want one CI policy / release pipeline / security scan to fire on every repo without copy-pasting `.kici/` folders everywhere."
+
+If you've only ever used per-repo workflows so far, start with the mental model section — global workflows add two new concepts (workflow repo vs. source repo, and authoring vs. source axes) that show up everywhere from SDK syntax to dashboard settings.
+
+## Mental model
+
+| Term           | Meaning                                                                                                                                                |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Workflow repo  | The repo whose `.kici/workflows/*.ts` file **declares** the global workflow. Holds the steps. Also known as the _authoring_ repo.                      |
+| Source repo    | The repo that **emits** the event (push / PR / tag / ...) that causes the global workflow to fire. The agent checks out this repo as the working copy. |
+| Global         | A workflow whose trigger carries one or more `repos:` glob patterns. The presence of `repos:` is what classifies a workflow as global.                 |
+| Authoring axis | Policy that answers "which repos may **author** global workflows?" Controlled by the allow-list in the dashboard's _Workflow authors_ 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.
+
+## Declaring a global workflow
+
+Add `repos:` to any trigger. Any workflow with at least one `repos:`-bearing trigger becomes global automatically; no separate flag is required.
+
+```ts
+import { workflow, job, step, push } from '@kici-dev/sdk';
+
+export default workflow('org-lint', {
+  on: [
+    push({
+      repos: ['myorg/*', '!myorg/archived-*'],
+      branches: ['main'],
+    }),
+  ],
+  jobs: [
+    job('lint', {
+      steps: [
+        step('lint-all', async ({ $, env }) => {
+          await $`echo source=${env.KICI_SOURCE_REPO_PATH ?? 'unknown'}`;
+          await $`npm run lint`;
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+Patterns in `repos:` use the same globbing as `branches:` / `paths:` — plain globs (`myorg/*`), a leading `!` for exclusions (`!myorg/fork-*`), and a fully-qualified `owner/repo` identity for exact matches (`myorg/platform`). A bare `**` matches every repo in the org.
+
+### At a dual-repo checkout
+
+The agent receives two sets of context during a global workflow execution:
+
+| `env` var                 | Points to                                                                                                                                    |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `KICI_SOURCE_REPO_PATH`   | The **source** repo's working tree (the repo that emitted the event). This is the repo the job's `$` / `git` commands operate on by default. |
+| `KICI_WORKFLOW_REPO_PATH` | The **workflow** repo's working tree (the repo that authored the workflow). Useful for reading shared scripts or config from your CI repo.   |
+
+Source repo secrets are **not** available to a global workflow's job by default — see _Elevated access_ below.
+
+## Enabling global workflows
+
+Global workflows are **opt-in per org**. In a fresh org, `repos:`-bearing workflows are registered but never dispatched.
+
+1. Open the dashboard → **Settings → Global workflows**.
+2. Turn on **Enable global workflows** (the master toggle). This is the kill-switch — every other toggle below is ignored while this is off.
+3. Decide which authoring/source controls you need:
+
+| 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.       |
+| 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. |
+
+All three lists accept globs. Leading `!` inside a single pattern is not supported here; negation is via the list-is-implicit-deny semantics, so keep it simple (`myorg/ci-*`, `myorg/platform-*`).
+
+### Saving and reverting
+
+The page is a two-state editor — changes are local until you click **Save changes**, and you can abandon them with **Discard changes**. There is no partial save; the PATCH is all-or-nothing per save click.
+
+## Security model
+
+### Two independent axes
+
+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:
+   - 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.
+
+Both checks are logged to the orchestrator. Grep the logs for `Skipping global workflow` to see enforcement in action.
+
+### Elevated access (source-repo secrets)
+
+By default a global workflow's job runs with credentials scoped to the **workflow** repo — it can clone both repos but cannot read the source repo's scoped secrets. That's the safe default: a random workflow in `myorg/ci-pipelines` does not get read access to secrets in `myorg/backend` just because it runs on a push there.
+
+Adding the authoring repo to the _Elevated access_ list flips that: the job receives the source repo's secret context, so deploy and release flows that need `NPM_TOKEN` / `AWS_ROLE_ARN` / etc. from the source repo can read them. Treat elevated repos as effective owners of every source repo's CI secrets — only add repos you fully trust.
+
+## When does it fire?
+
+Same-repo globals (a workflow in `myorg/app` with `repos: ['myorg/app']`) fire on pushes to `myorg/app`. Cross-repo globals fire on pushes to any source repo whose identifier matches a glob on the authoring workflow's trigger. The orchestrator de-duplicates between the per-repo and cross-repo matching passes, so a single event produces at most one run per (workflow, source-repo, trigger) triple.
+
+Non-push triggers work too — `pr()`, `tag()`, `comment()`, `release()`, `workflowRun()`, etc. all accept `repos:`. `kiciEvent()` / `schedule()` / cron-like triggers have no source repo, so they're always per-org-registered regardless of `repos:`.
+
+## Troubleshooting
+
+| Symptom                                                      | Likely cause                                                                                       | Where to look                                                                                                      |
+| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| Global workflow registered but never runs                    | Master toggle OFF, or allow-list blocks the authoring repo, or deny-list blocks the source repo    | Orchestrator log: `Skipping global workflow dispatch` / `Skipping global workflow registration: not permitted`     |
+| `repos:` has no effect — workflow only fires on its own repo | Master toggle OFF. Without opt-in, the orchestrator treats the workflow as per-repo-only.          | Dashboard → Settings → Global workflows (top toggle)                                                               |
+| Source repo secrets unavailable in a global job              | Expected default — elevate the authoring repo to grant access.                                     | Dashboard → Settings → Global workflows → _Elevated access_                                                        |
+| Dashboard shows workflow twice after registering             | Both a generic webhook source and a provider source (github, generic) re-registered the same repo. | Check `workflow_registrations` via `kici-admin workflow list` and confirm the right routing key owns the workflow. |
+
+## See also
+
+- [Architecture — global workflows](https://docs.kici.dev/architecture/global-workflows/) — dual-query dispatch flow, cross-provider auth, security model, lock-file schema.
+- [Universal-git provider](https://docs.kici.dev/user/providers/universal-git/#global-workflows) — how global workflows interact with `generic:<orgId>:<sourceId>` routing keys.
+- [SDK reference](https://docs.kici.dev/user/sdk-reference/) — the full set of triggers that accept `repos:`.
+
+---
+
+## Idempotent steps and check mode
+
+Source: https://docs.kici.dev/user/idempotent-steps/
+
+An **idempotent step** describes _desired state_ rather than a fixed sequence of
+commands. You give the step a `check` function that inspects the world and a
+`run` function that converges it. KiCI then executes the workflow in one of two
+modes:
+
+- **Apply mode** (the default): for each step, `check()` runs first; on drift the
+  step applies the change; when already in sync the step is skipped.
+- **Check mode** (`--check`): for each step, `check()` runs and KiCI reports what
+  _would_ change — **without changing anything**. This is the same model as a
+  dry-run plan: you see the drift before any side effect happens.
+
+This turns a workflow into convergent configuration management: re-running an
+apply is safe (in-sync steps do nothing), and a check-mode run is a read-only
+preview you can gate a build on.
+
+## Authoring a checked step
+
+Add a `check` facet to the existing `step()` factory. When `check` is present,
+`run` becomes the _apply_ function and receives the drift value `check`
+returned:
+
+```typescript
+import { step, z } from '@kici-dev/sdk';
+
+const configureNginx = step('configure-nginx', {
+  // optional schema for the drift value — gives the dashboard a typed shape
+  drift: z.object({ want: z.string() }),
+
+  // read-only inspection; return null when already in the desired state
+  check: async (ctx) => {
+    const current = await ctx.$`nginx -T`;
+    return current.stdout.includes(DESIRED) ? null : { want: DESIRED };
+  },
+
+  // human-readable preview line — REQUIRED when check is set. It is the drift's
+  // serializable face: it streams to the logs and persists for the dashboard.
+  summarize: (drift) => `would rewrite nginx.conf (${drift.want.length} bytes)`,
+
+  // apply — runs only when check returned drift (apply mode); receives that drift
+  run: async (ctx, drift) => {
+    await writeConfig(drift.want);
+    return { reloaded: true };
+  },
+
+  // optional — runs when check returned null, to produce the step's outputs
+  whenInSync: async () => ({ reloaded: false }),
+});
+```
+
+### The facet fields
+
+| Field        | Required         | Purpose                                                                |
+| ------------ | ---------------- | ---------------------------------------------------------------------- |
+| `check`      | to opt in        | Read-only inspection. Return a drift value, or `null` when in sync.    |
+| `summarize`  | when `check` set | Human-readable, serializable preview of the drift. Streams + persists. |
+| `run`        | always           | Apply function. With `check`, it receives the drift as its second arg. |
+| `whenInSync` | optional         | Produces the step's outputs when `check` returned `null`.              |
+| `drift`      | optional         | Schema that validates / shapes the drift value.                        |
+
+`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.
+
+A plain `step()` without `check` keeps its exact current behavior — the check
+facet is fully optional.
+
+## Run modes
+
+A run carries one of three modes:
+
+| Mode                  | CLI flags                 | Behavior                                                                                   |
+| --------------------- | ------------------------- | ------------------------------------------------------------------------------------------ |
+| `apply`               | (default, no flags)       | Converge: drift ⇒ apply ⇒ **applied**; null ⇒ **in sync** (skipped).                       |
+| `check`               | `--check`                 | Preview only: drift ⇒ **would change**; null ⇒ **in sync**. Never applies. Always exits 0. |
+| `check-fail-on-drift` | `--check --fail-on-drift` | Same as check, but the run **fails** if any step reports drift.                            |
+
+Per-step outcomes:
+
+- **applied** — drift was found and the step applied the change (apply mode).
+- **in sync** — `check` returned `null`; nothing to do.
+- **would change** — drift was found in check mode; the change was previewed, not applied.
+- **no check** — a plain step (no `check`) reached under check mode. A
+  side-effecting step can't be safely previewed, so it is skipped.
+
+In check mode KiCI never invokes a checked step's `run` (apply) — the preview is
+guaranteed side-effect-free.
+
+## Running in check mode
+
+`--check` and `--fail-on-drift` work on both local and remote runs:
+
+```bash
+# Apply (default): converge the workflow.
+kici run local push
+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
+```
+
+`--fail-on-drift` only modifies check mode — passing it without `--check` is an
+error.
+
+## Where outcomes show up
+
+A check-mode run is labeled in the dashboard with a **CHECK MODE — preview**
+badge on the run header. Each step shows its outcome chip — applied / in sync /
+would change / no check — and, when drift was detected, the `summarize` line
+describing what would change. The rendering is read-only.
+
+## See also
+
+- [Idempotent SDK helpers](https://docs.kici.dev/user/sdk/idempotent/) — the `idempotent()` / `idempotentStep()` convenience wrappers (always apply on drift), plus `checkStep()`, the clean-shape sibling that respects the run-level check mode.
+- [Core SDK reference](https://docs.kici.dev/user/sdk/core/) — the `step()`, `job()`, and `workflow()` factories the check facet extends.
+- [Lock file and drift](https://docs.kici.dev/user/lock-file-and-drift/) — how the lock file carries step capability flags.
+
+---
+
+## Private npm registries
+
+Source: https://docs.kici.dev/user/private-registries/
+
+A workflow's `.kici/package.json` may depend on packages published to a private registry — your org's internal CodeArtifact, a GitHub Packages scope, a self-hosted Verdaccio, JFrog, Cloudsmith, GitLab, etc. KiCI ships two ways to authenticate `npm install` against those registries from inside a job, plus an escape hatch for short-lived tokens.
+
+## Choose a path
+
+| Path                                                    | When to pick it                                                                                                                                                                                               |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Option A — `registries:` block in the workflow**      | The token is a long-lived secret you rotate manually (GH Packages PAT, CodeArtifact IAM access key, Verdaccio service token). KiCI manages the `.npmrc` for you.                                              |
+| **Option C — Committed `.kici/.npmrc` + `installEnv:`** | You already have an `.npmrc` you want to keep verbatim (e.g. it carries an `audit=false` line, a custom CA, or a complex multi-scope mapping). KiCI just supplies the env vars your `${VAR}` references need. |
+| **Setup-step pattern (short-lived tokens)**             | The token is minted at workflow time (CodeArtifact authorization token, GCP Artifact Registry token). A `setup` job runs the cloud CLI, writes a fresh `.kici/.npmrc`, and the install jobs read it.          |
+
+The two channels (Option A and Option C) compose. If you declare both, the agent's auto-generated lines come **after** your committed `.npmrc`, so npm's last-wins semantics let agent-managed registries override committed ones — never the other way around.
+
+## 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.
+
+```typescript
+import { workflow, job, step, push } from '@kici-dev/sdk';
+
+export default workflow('build', {
+  on: [push({ branches: ['main'] })],
+  registries: [
+    {
+      url: 'https://npm.pkg.github.com/',
+      scope: '@my-org',
+      tokenSecret: 'production:GITHUB_PACKAGES_TOKEN',
+    },
+  ],
+  jobs: [
+    job('build', {
+      runsOn: 'default',
+      environment: 'production',
+      steps: [
+        step('install-and-build', async (ctx) => {
+          // .kici/package.json can now reference @my-org/* packages
+          await ctx.$`npm run build`;
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+Per-field rules:
+
+- **`url`** — Must be HTTPS. HTTP is permitted only for `localhost` / `127.0.0.0/8` / `::1` / `*.local` hosts, or when an operator has flipped the org-level `allow_http_npm_registries` toggle (see [`kici-admin org-settings allow-http-npm`](https://docs.kici.dev/operator/kici-admin-cli#allow-http-npm--permit-non-https-private-npm-registries)).
+- **`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.
+- **`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`
+
+The agent never writes the token bytes to your `.kici/.npmrc`. Each registry token is exposed to the install subprocess as a job-scoped env var (`KICI_NPM_TOKEN_<jobIdShort>_<i>`), and the on-disk auth line carries a `${VAR}` reference that npm substitutes at read time. The job-scoped nonce makes the env var name unguessable from outside the install subprocess.
+
+After the install completes (success or failure), the agent restores the original `.kici/.npmrc` — your committed file is never permanently modified.
+
+## 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`.
+
+```ini
+# .kici/.npmrc
+@my-org:registry=https://npm.example.com/
+//npm.example.com/:_authToken=${MY_NPM_TOKEN}
+//npm.example.com/:always-auth=true
+audit=false
+```
+
+```typescript
+import { workflow, job, step, push } from '@kici-dev/sdk';
+
+export default workflow('build', {
+  on: [push({ branches: ['main'] })],
+  installEnv: ['production:MY_NPM_TOKEN'],
+  jobs: [
+    job('build', {
+      runsOn: 'default',
+      environment: '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}`.
+
+This path is the right answer when:
+
+- The `.npmrc` carries non-auth knobs (`audit=false`, `legacy-peer-deps=true`, custom CA bundles).
+- You want a single source of truth for registry topology that `npm` tooling outside KiCI can consume too.
+- The auth lines reference the **same** env var across multiple registries.
+
+## Short-lived tokens (CodeArtifact, GCP Artifact Registry)
+
+AWS CodeArtifact authorization tokens expire after 12 hours; GCP Artifact Registry tokens after 60 minutes. Storing one as a long-lived `tokenSecret` does not work — by the time a build runs, the token may be expired.
+
+The supported pattern is a **setup job** that mints a fresh token, writes `.kici/.npmrc`, and downstream jobs install with it.
+
+```typescript
+import { workflow, job, step, push } from '@kici-dev/sdk';
+
+export default workflow('build', {
+  on: [push({ branches: ['main'] })],
+  jobs: [
+    job('mint-codeartifact-token', {
+      runsOn: 'default',
+      environment: 'production',
+      steps: [
+        step('mint', async (ctx) => {
+          const awsKey = await ctx.secrets.get('AWS_ACCESS_KEY_ID');
+          const awsSecret = await ctx.secrets.get('AWS_SECRET_ACCESS_KEY');
+          process.env.AWS_ACCESS_KEY_ID = awsKey;
+          process.env.AWS_SECRET_ACCESS_KEY = awsSecret;
+
+          const token = (
+            await ctx.$`aws codeartifact get-authorization-token --domain my-domain --query authorizationToken --output text`
+          ).stdout.trim();
+
+          // Write directly into the workspace's .kici/ — the next job reuses the same workspace.
+          const npmrc = [
+            '@my-org:registry=https://my-domain-1234567890.d.codeartifact.eu-central-1.amazonaws.com/npm/workflow-deps/',
+            `//my-domain-1234567890.d.codeartifact.eu-central-1.amazonaws.com/npm/workflow-deps/:_authToken=${token}`,
+            '//my-domain-1234567890.d.codeartifact.eu-central-1.amazonaws.com/npm/workflow-deps/:always-auth=true',
+            '',
+          ].join('\n');
+          await ctx.$`tee .kici/.npmrc`.stdin(npmrc);
+        }),
+      ],
+    }),
+    job('build', {
+      runsOn: 'default',
+      environment: 'production',
+      needs: ['mint-codeartifact-token'],
+      steps: [step('build', async (ctx) => ctx.$`npm run build`)],
+    }),
+  ],
+});
+```
+
+The same pattern works for GCP Artifact Registry — replace the `aws codeartifact` call with `gcloud auth print-access-token`. The manual setup-step shown here is the supported path for these short-lived flows.
+
+## Provider-specific examples
+
+### GitHub Packages
+
+```typescript
+registries: [
+  {
+    url: 'https://npm.pkg.github.com/',
+    scope: '@my-org',
+    tokenSecret: 'production:GITHUB_PACKAGES_TOKEN',
+  },
+],
+```
+
+Mint the token from a fine-grained PAT with `read:packages` scope, store it as a scoped secret in the `production` environment.
+
+### GitLab Packages
+
+```typescript
+registries: [
+  {
+    url: 'https://gitlab.example.com/api/v4/projects/123/packages/npm/',
+    scope: '@my-group',
+    tokenSecret: 'production:GITLAB_DEPLOY_TOKEN',
+  },
+],
+```
+
+Use a project- or group-level deploy token with `read_package_registry` scope.
+
+### Verdaccio (self-hosted)
+
+```typescript
+registries: [
+  {
+    url: 'https://npm.internal.example.com/',
+    tokenSecret: 'production:VERDACCIO_TOKEN',
+  },
+],
+```
+
+For local development against a Verdaccio container, point at `http://localhost:4873/` — the loopback exemption means the operator does NOT need to flip `allow_http_npm_registries`.
+
+### JFrog Artifactory
+
+```typescript
+registries: [
+  {
+    url: 'https://artifactory.example.com/artifactory/api/npm/npm-virtual/',
+    scope: '@my-org',
+    tokenSecret: 'production:JFROG_API_KEY',
+  },
+],
+```
+
+### Cloudsmith
+
+```typescript
+registries: [
+  {
+    url: 'https://npm.cloudsmith.io/my-org/my-repo/',
+    scope: '@my-org',
+    tokenSecret: 'production:CLOUDSMITH_TOKEN',
+  },
+],
+```
+
+## 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.
+- **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.
+
+- **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.
+
+## Limitations
+
+- **`registries:` is workflow-level only in v1.** Per-job overrides aren't supported — there is one shared `.kici/` per workspace, so a per-job `registries:` would be physically nonsensical.
+- **Container registries (Docker Hub, ECR, GHCR) are out of scope.** This feature covers **npm** registry auth only. Container image pulls travel through the executor backend's own credential paths.
+
+## Observability
+
+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.                                                                                                                                                                      |
+
+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.
+- [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.
+
+---
+
+## Build provenance and attestations
+
+Source: https://docs.kici.dev/user/provenance/
+
+Build provenance is a signed, verifiable statement of **what produced an
+artifact** — the source repository, commit, ref, workflow path, and builder that
+ran. When a workflow step attests an artifact, KiCI records that statement,
+signs it, and makes it retrievable so anyone can later prove the artifact came
+from a specific KiCI run and was not swapped along the way.
+
+This is the same idea behind supply-chain attestation systems like
+[SLSA](https://slsa.dev/spec/v1.0/provenance): a downstream consumer (a release
+gate, a security audit, a `"show me the provenance"` request) can verify the
+artifact's origin without trusting the person who handed it over.
+
+## What an attestation contains
+
+An attestation is a self-contained bundle holding three things:
+
+- An **in-toto SLSA v1.0 statement** describing the build: the subject artifact
+  (name + content digest) and the provenance predicate (source repository,
+  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.
+
+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
+signing keys with no per-attestation online lookup.
+
+## Attesting an artifact in a workflow
+
+Call `ctx.attestProvenance({ subject })` from a step after you have produced the
+artifact:
+
+```typescript
+import { workflow, job, step } from '@kici-dev/sdk';
+
+export default workflow('release', {
+  on: { push: { branches: ['main'] } },
+  jobs: [
+    job('publish', {
+      steps: [
+        step('build', async (ctx) => {
+          await ctx.$`npm pack`;
+        }),
+        step('attest', async (ctx) => {
+          const result = await ctx.attestProvenance({
+            subject: { name: 'my-pkg-1.2.3.tgz', path: 'my-pkg-1.2.3.tgz' },
+          });
+          ctx.log.info(`Attestation stored at ${result.storageKey}`);
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+The **subject is caller-supplied** — you name the artifact and give KiCI either a
+path or a precomputed digest:
+
+- `{ name, path }` — a path relative to the step working directory. KiCI reads
+  the file and computes its SHA-256 digest.
+- `{ name, digest }` — a precomputed digest. For a container image, pass the OCI
+  manifest digest your build tool emitted:
+
+  ```typescript
+  await ctx.attestProvenance({
+    subject: { name: 'ghcr.io/acme/app', digest: { sha256: '<manifest-digest>' } },
+  });
+  ```
+
+The identity token is fetched and masked in logs automatically — you never
+handle it. The call returns `{ storageKey, subjectDigest, bundleMediaType }`
+identifying the stored bundle.
+
+`ctx.attestProvenance` is only available inside a running job step. Calling it
+during local execution rejects with a clear error.
+
+### Requesting a raw identity token
+
+`ctx.attestProvenance` builds on a lower-level primitive you can call directly
+when you need the identity token for a different tool:
+
+```typescript
+step('mint', async (ctx) => {
+  const { token, expiresIn } = await ctx.kici.oidc.token({ audience: 'sigstore' });
+  ctx.log.info(`Got an ID token valid for ${expiresIn}s`);
+  // Hand `token` to a tool that exchanges it with a service trusting the issuer.
+});
+```
+
+The token is a short-lived (about 10 minutes) signed JWT scoped to the current
+run and job. Its identity claims (`repository`, `ref`, `sha`, `kici_run_id`,
+`kici_job_id`) are derived by the 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.
+
+## Verifying an attestation
+
+Verify a bundle with the `kici verify-attestation` command. It establishes the
+full chain offline: the identity token verifies against the trusted issuer's
+JWKS, the DSSE signature verifies against the bundled signing key, and the
+statement's build context must match the token's identity claims (a mismatch is
+a hard failure).
+
+```bash
+kici verify-attestation [artifact] --bundle <path-or-url> --trust-root <url-or-file>
+```
+
+You supply the trusted issuer out-of-band via `--trust-root` — the verifier
+never trusts the issuer named inside the token. There are two forms:
+
+- **Online — an HTTPS issuer URL.** The verifier fetches
+  `<url>/.well-known/openid-configuration`, reads its `issuer` and `jwks_uri`,
+  and fetches the JWKS. The token's `iss` is pinned to the discovery document's
+  `issuer`.
+- **Offline — a self-contained trust-root file.** A local JSON file with the
+  issuer and JWKS inlined, for air-gapped verification:
+
+  ```json
+  {
+    "issuer": "https://platform.example/issuer",
+    "jwks": {
+      "keys": [
+        { "kty": "EC", "crv": "P-256", "x": "...", "y": "...", "alg": "ES256", "kid": "..." }
+      ]
+    }
+  }
+  ```
+
+Pass an optional `[artifact]` to also digest-check the file against the
+attestation subject — this is what binds the attestation to a specific set of
+bytes. Omit it to verify the signatures and identity only. Use `--json` for a
+machine-readable result. The command exits `0` when everything verifies and `1`
+when it does not (or on an error such as a missing flag or unreachable trust
+root).
+
+```bash
+# Verify a bundle against a deployed issuer, digest-checking the artifact:
+kici verify-attestation ./dist/app.tgz \
+  --bundle ./app.tgz.kici.json \
+  --trust-root https://platform.example/issuer
+
+# Air-gapped: verify against a self-contained trust-root file:
+kici verify-attestation ./dist/app.tgz \
+  --bundle ./app.tgz.kici.json \
+  --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).
+
+## Viewing attestations in the dashboard
+
+<!-- help:run-attestations#viewing-attestations-in-the-dashboard -->
+
+The run detail page has an **Attestations** tab listing each artifact a run's
+steps attested (via `ctx.attestProvenance`), one row per artifact.
+
+Each row shows:
+
+- **Status** — a **verified** badge computed in your browser. It checks the
+  attestation's signature, the build identity, and the build context against the
+  trusted provenance issuer. **verified** (green) means all of those pass;
+  **failed** (red) shows why in a tooltip; **unverifiable** means the provenance
+  issuer is not configured; **keys unavailable** (amber) means the issuer is
+  configured but its verification keys could not be fetched.
+- **Job / Artifact / Digest / Created** — the producing job, the artifact name,
+  its content digest, and when it was recorded.
+- **Download** — saves the signed bundle as a `.sigstore.json` file.
+
+The badge does **not** re-hash the artifact bytes — the dashboard does not have
+the artifact. To bind the attestation to a specific file, run
+`kici verify-attestation <artifact> --bundle <bundle>`. A run with no
+attestations shows an empty state.
+
+<!-- /help:run-attestations -->
+
+## 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
+  `kici verify-attestation` flag and exit code.
+
+---
+
+## Secrets
+
+Source: https://docs.kici.dev/user/secrets/
+
+KiCI provides an explicit secrets API that gives workflow steps controlled access to secrets stored in the orchestrator's secret store. Secrets are never auto-injected into `process.env` -- you must explicitly request each secret by name.
+
+## 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.
+
+This design prevents accidental secret leakage through child processes, log output, or error messages. Only secrets you explicitly request are loaded into memory.
+
+## Where secret values come from
+
+Secret values are written either through the dashboard or through `kici-admin` running against the orchestrator. The orchestrator operator decides — per organization — which surface accepts secret writes. From the workflow author's perspective, the resolution path at run time is identical either way; the difference is where you (or your ops team) **enter** the value.
+
+### Default — dashboard or CLI
+
+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.
+
+Use whichever fits the workflow — most small teams stay on the dashboard; ops engineers and CI scripts use the CLI.
+
+### When the operator has disabled dashboard writes
+
+The orchestrator operator can flip `secrets.set` (and `variables.set`) to **CLI-only** as part of the [dashboard-write policy](https://docs.kici.dev/operator/security/dashboard-write-policy). When that flip is on:
+
+- The 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 secrets page still lists secret **names**, scopes, and bindings — only the value-entry path moves to the CLI.
+- `kici-admin secret set` becomes the single entry point for new and updated secret values.
+
+This configuration is common for SOC2-prep and regulated workloads, where the customer requirement is "the SaaS control plane process never receives plaintext customer secret values." The dashboard remains usable for everything else (read paths, name CRUD, environment bindings).
+
+### CLI input modes
+
+`kici-admin secret set` 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
+
+# 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
+
+# Read from a file (handy after `sops -d` to a tmpfile).
+kici-admin secret set --scope 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
+
+# Direct argv — discouraged. Prints a stderr warning ("visible in shell history").
+kici-admin secret set --scope production DB_PASSWORD --value "<plaintext>"
+```
+
+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.
+- `--dry-run` — parse and validate the value, print `[dry-run] would set <key> in scope <scope> sha256=<hex>`, exit without writing.
+
+`kici-admin variable set` uses the same flags for non-encrypted variables, plus `--locked` to mark a variable as immutable from subsequent dashboard writes.
+
+A full reference of input modes — including the default-mode resolution rules and the security trade-offs of each — lives in [Dashboard-write policy → CLI input modes](https://docs.kici.dev/operator/security/dashboard-write-policy#cli-input-modes-for-the-plaintext-path).
+
+## Accessing secrets
+
+Use `ctx.secrets.get(key)` to retrieve a secret value. The method is async to support process-level step isolation in future versions.
+
+```typescript
+import { workflow, job, step } from '@kici-dev/sdk';
+
+export default workflow('deploy', {
+  on: [push({ branches: ['main'] })],
+  jobs: [
+    job('deploy', {
+      runsOn: 'default',
+      environment: 'production',
+      steps: [
+        step('deploy', async (ctx) => {
+          const token = await ctx.secrets.get('DEPLOY_TOKEN');
+          await ctx.$`deploy --token ${token}`;
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+If the secret does not exist, `get()` throws a `SecretNotFoundError` with a descriptive message.
+
+## Exposing secrets to shell commands
+
+When you need a secret available as an environment variable for shell commands (e.g., tools that read `$API_KEY` from the environment), use `ctx.secrets.expose(key)`:
+
+```typescript
+step('run-tool', async (ctx) => {
+  // Injects MY_API_KEY into process.env for this step only
+  await ctx.secrets.expose('MY_API_KEY');
+
+  // Now child processes can read it from the environment
+  await ctx.$`some-tool --use-env-auth`;
+});
+```
+
+`expose()` sets `process.env[key]` to the secret value. This is scoped to the step's child process -- it does not leak to other steps or jobs.
+
+## Checking secret existence
+
+Use `ctx.secrets.has(key)` to check whether a secret is available without retrieving its value:
+
+```typescript
+step('conditional-notify', async (ctx) => {
+  if (ctx.secrets.has('SLACK_WEBHOOK')) {
+    const webhook = await ctx.secrets.get('SLACK_WEBHOOK');
+    await ctx.$`curl -X POST ${webhook} -d '{"text": "Deploy complete"}'`;
+  } else {
+    console.log('Slack webhook not configured, skipping notification');
+  }
+});
+```
+
+`has()` is synchronous and does not load the secret value.
+
+## Mounting secrets as files
+
+Some tools refuse to read credentials from environment variables and require a file path on disk (for example, `sops` reads `SOPS_AGE_KEY_FILE`, `kubectl` reads `KUBECONFIG`, and `gcloud` reads `GOOGLE_APPLICATION_CREDENTIALS`). The secrets API materialises one or more existing string secrets to a tmpfile for the lifetime of the step.
+
+### list()
+
+`ctx.secrets.list()` returns every secret key available to the step, sorted alphabetically. It is synchronous, never throws, and returns names only — call `getMeta(key)` to inspect the backend and scope for a specific key.
+
+```typescript
+step('discover-keys', async (ctx) => {
+  // Pick up every age key the operator has provisioned.
+  const ageKeys = ctx.secrets.list().filter((k) => k.startsWith('AGE_KEY_'));
+  ctx.log.info(`Found ${ageKeys.length} age keys`);
+});
+```
+
+### mountFile(opts)
+
+`ctx.secrets.mountFile(opts)` writes the concatenation of one or more existing secrets to a tmpfile inside a per-step tmpdir and returns the absolute path. The file is removed automatically when the step completes (success, failure, or timeout).
+
+Options:
+
+- `sources: string[]` — secret keys to concatenate (in order). Required.
+- `divider?: string` — separator written between concatenated values. Default: no divider.
+- `mode?: number` — permission bits to chmod the file to. Default: `0o600` (owner read/write only).
+- `name?: string` — filename inside the per-step tmpdir. Default: auto-generated.
+
+If any source key is missing, `mountFile` rejects with `SecretNotFoundError` listing every missing key.
+
+```typescript
+step('decrypt', async (ctx) => {
+  const ageKeys = ctx.secrets.list().filter((k) => k.startsWith('AGE_KEY_'));
+  const keyFile = await ctx.secrets.mountFile({
+    sources: ageKeys,
+    divider: '\n',
+  });
+  await ctx.$`sops --age-key-file ${keyFile.path} -d secrets.enc.yaml`;
+});
+```
+
+### exposeFile(envVar, opts)
+
+`ctx.secrets.exposeFile(envVar, opts)` is `mountFile` plus `process.env[envVar] = path`. The env var is unset and the file is removed when the step completes. The customer controls every env var name — there is no implicit `KICI_SECRET_FILE_*` naming.
+
+```typescript
+step('deploy', async (ctx) => {
+  await ctx.secrets.exposeFile('SOPS_AGE_KEY_FILE', {
+    sources: ctx.secrets.list().filter((k) => k.startsWith('AGE_KEY_')),
+    divider: '\n',
+  });
+
+  // sops reads SOPS_AGE_KEY_FILE from the environment.
+  await ctx.$`sops -d secret.enc.yaml`;
+});
+```
+
+### Lifecycle and cleanup
+
+- **Lazy allocation:** no tmpdir is created until the first `mountFile` / `exposeFile` call. Steps that never mount pay nothing.
+- **Per-step tmpdir:** allocated under the OS temp directory and bound to a single step. Two mounts in the same step share the same tmpdir; the runtime auto-suffixes filenames when no `name` is supplied.
+- **Automatic cleanup:** when the step returns (success), throws (failure), or times out, the runtime removes the tmpdir and unsets any env var set via `exposeFile`. There is nothing to clean up by hand.
+- **Sandbox container:** when the agent runs the step inside a container or microVM, the tmpdir lives on the sandbox's `/tmp` (a fresh tmpfs in the production sandbox profile). The file is gone when the sandbox is torn down.
+
+### Log masking
+
+Mounted file contents are registered with the log masker, so a subprocess that echoes the credential (e.g. a tool that prints its loaded credential on `--debug`) sees `***` in the streamed log instead of the raw value. This covers the case where `mountFile` joins two source secrets into a brand-new byte sequence neither original value would mask on its own.
+
+### Canonical sops example
+
+```typescript
+import { workflow, job, step, push } from '@kici-dev/sdk';
+
+export default workflow('deploy', {
+  on: push({ branches: ['main'] }),
+  jobs: [
+    job('decrypt-and-deploy', {
+      runsOn: 'default',
+      environment: 'production',
+      steps: [
+        step('decrypt', async (ctx) => {
+          const ageKeys = ctx.secrets.list().filter((k) => k.startsWith('AGE_KEY_'));
+          await ctx.secrets.exposeFile('SOPS_AGE_KEY_FILE', {
+            sources: ageKeys,
+            divider: '\n',
+          });
+          await ctx.$`sops -d secret.enc.yaml > config.yaml`;
+          // No cleanup -- the tmpdir + the SOPS_AGE_KEY_FILE env var
+          // are removed automatically when this step returns.
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+### Injecting decrypted sops values into the environment
+
+KiCI does **not** scan your repository for `*.enc.yaml` files and auto-decrypt them into the environment at job init — nothing in a job runs `sops` on your behalf, and resolved secrets are never auto-injected as environment variables (see [Security notes](https://docs.kici.dev/user/sdk/runtime/#security-notes)). Decryption is always something your workflow does explicitly: provision the age (or other) decryption key as a KiCI secret, expose it for the step, run `sops -d`, and decide what to do with the output.
+
+When you want the decrypted values available as environment variables — not just written to a file — decrypt early and export the values through `$KICI_ENV` (or `ctx.setEnv`). Anything appended to `$KICI_ENV` becomes an environment variable for every later step in the same job, so a single decrypt step can populate the environment for the whole job:
+
+```typescript
+import { workflow, job, step, push } from '@kici-dev/sdk';
+
+export default workflow('deploy', {
+  on: push({ branches: ['main'] }),
+  jobs: [
+    job('decrypt-and-deploy', {
+      runsOn: 'default',
+      environment: 'production',
+      steps: [
+        step('decrypt-to-env', async (ctx) => {
+          await ctx.secrets.exposeFile('SOPS_AGE_KEY_FILE', {
+            sources: ctx.secrets.list().filter((k) => k.startsWith('AGE_KEY_')),
+            divider: '\n',
+          });
+          // Decrypt to dotenv format, then append every KEY=value line to
+          // $KICI_ENV so subsequent steps see them as environment variables.
+          await ctx.$`sops -d --output-type dotenv secrets.enc.yaml >> "$KICI_ENV"`;
+        }),
+        step('deploy', async (ctx) => {
+          // Values decrypted above are now ordinary env vars here.
+          await ctx.$`./deploy.sh`;
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+Decrypted values exported this way follow the same rules as any other `$KICI_ENV` / `ctx.setEnv` export: last-write-wins on a repeated key, and a key that collides with an operator-injected secret is ignored (the operator value wins). See [Exporting env from shell commands](https://docs.kici.dev/user/sdk/runtime/#exporting-env-from-shell-commands-kici_env--kici_path) for the full `$KICI_ENV` contract.
+
+If you only need the decrypted material as a file on disk (the common `kubectl` / `gcloud` case), skip the env hop and redirect to a file instead — see the [canonical sops example](https://docs.kici.dev/user/secrets/#canonical-sops-example) above.
+
+## API reference
+
+| Method       | Signature                                                                | Description                                                                        |
+| ------------ | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
+| `get`        | `get(key: string): Promise<string>`                                      | Retrieve a secret value. Throws `SecretNotFoundError` if not found.                |
+| `expose`     | `expose(key: string): Promise<void>`                                     | Set `process.env[key]` to the secret value for child process access.               |
+| `has`        | `has(key: string): boolean`                                              | Check if a secret key is available (synchronous).                                  |
+| `getMeta`    | `getMeta(key: string): SecretMeta \| undefined`                          | Get metadata (backend name, scope) for a secret. Returns `undefined` if not found. |
+| `list`       | `list(): string[]`                                                       | Sorted array of every secret key available to the step. Synchronous, never throws. |
+| `mountFile`  | `mountFile(opts: SecretFileOptions): Promise<{ path: string }>`          | Materialise one or more secrets as a tmpfile. Auto-cleanup at step end.            |
+| `exposeFile` | `exposeFile(envVar: string, opts: SecretFileOptions): Promise<{ path }>` | `mountFile` plus `process.env[envVar] = path`. Env var unset at step end.          |
+
+## Migration from property access
+
+If upgrading from a previous version that used property access (`ctx.secrets.KEY`), update your workflow code:
+
+```typescript
+// Before (old API)
+const token = ctx.secrets.DEPLOY_TOKEN;
+
+// After (new API)
+const token = await ctx.secrets.get('DEPLOY_TOKEN');
+```
+
+For conditional access:
+
+```typescript
+// Before (old API)
+if (ctx.secrets.DEPLOY_TOKEN) { ... }
+
+// After (new API)
+if (ctx.secrets.has('DEPLOY_TOKEN')) { ... }
+```
+
+Note that `get()` is async -- you must `await` the result.
+
+## Typed secrets
+
+When you run `kici types`, the compiler generates a `.kici/secrets.d.ts` file that provides type-safe autocompletion for your secret keys. The generated types augment the `StepSecrets` interface so that `ctx.secrets.get('...')` and `ctx.secrets.has('...')` offer suggestions for known keys.
+
+See [CLI reference](https://docs.kici.dev/user/cli) for the `kici types` command.
+
+---