@kici-dev/compiler 0.4.0 → 0.6.0

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

@@ -1,6 +1,6 @@
-# KiCI Workflow features
+# KiCI Workflow features: access and approval
 
-This bundle covers: Workflow features: concurrency, contexts, secrets, approvals, provenance, events.
+This bundle covers: Deployment contexts, scoped secrets, private registries, approvals, provenance, dashboard and account access.
 
 ## Account and sign-in
 
@@ -196,6 +196,10 @@ Here `build-plan` runs, then the job pauses for a `dba` approval. On approval, `
 
 Because a step-level hold keeps an agent and its workspace occupied for the whole human wait, prefer job- or workflow-level gates when you do not need prior-step state, and keep step-level timeouts short. See the [operator note on agent occupancy](https://docs.kici.dev/operator/approvals/#agent-occupancy-during-step-level-holds).
 
+### Not available on organization-wide workflows
+
+An `approval` gate applies to per-repository workflows only. A workflow whose trigger carries `repos:` — an [organization-wide workflow](https://docs.kici.dev/user/global-workflows/) — is dispatched by a path that never consults the gate, so the gate would not hold anything. `kici compile` refuses it with `error [E124]` at the workflow level and on any static job, rather than accepting a security control the workflow does not have. Drop the `approval`, or move the gated jobs into a workflow whose triggers carry no `repos:`. A job produced by a `dynamicJob` generator never passes through the compiler, so that one is caught at dispatch instead: the orchestrator logs an error naming the workflow and job, and runs it ungated.
+
 ## Drift gates (`when: 'drift'`)
 
 A `when: 'drift'` gate is **step-scope only** and requires a [check/apply step](https://docs.kici.dev/user/idempotent-steps/). Instead of pausing unconditionally, it fires **between the step's `check` and `run`, only when `check` finds drift in apply mode** — exactly Terraform's plan→apply, scoped to one step. When the step is already in sync (no drift), nothing pauses and the step skips.
@@ -228,7 +232,7 @@ A `when: 'drift'` gate on a step without a `check` facet, or at job/workflow sco
 
 ## Mandatory vs. explicit gates
 
-`approval` is the **explicit** gate — a deliberate "pause for a human here" written by the workflow author. It composes with the **mandatory** gate an operator can attach to a protected context via required reviewers (see [Contexts](https://docs.kici.dev/user/contexts/#required-reviewers)). When both apply to the same job, all clauses from both sources must be satisfied before the job is released. The two funnel into one held-element mechanism, so the dashboard queue and `kici approve` work the same way regardless of which source held the element.
+`approval` is the **explicit** gate — a deliberate "pause for a human here" written by the workflow author. It composes with the **mandatory** gate an operator can attach to a protected context via required reviewers (see [Contexts](https://docs.kici.dev/user/contexts/#required-reviewers)). When both apply to the same job, all clauses from both sources must be satisfied before the job is released. A workflow-level `approval` is one of those sources. It gates every root job, so a root job that also binds a context with required reviewers must satisfy the workflow clauses, its own job clauses, and the context's reviewers. The sources funnel into one held-element mechanism, so the dashboard queue and `kici approve` work the same way regardless of which source held the element.
 
 ## Approving from the CLI
 
@@ -250,6 +254,23 @@ kici reject <run-id> --job deploy-production --reason "Wrong release branch"
 
 You must be eligible for at least one unsatisfied clause — being a member of a named team or being a named user. The orchestrator verifies eligibility against the operator-defined teams, so naming a team in your workflow can never let an ineligible person release the gate. The command reports whether the element was released, how many clauses remain, or that it was rejected. See [`kici approve`](https://docs.kici.dev/user/cli/runs-and-approvals/#kici-approve) for the full command reference.
 
+### When a job is held twice
+
+A job can carry an `approval` gate **and** a [security hold](https://docs.kici.dev/user/contexts/#security-approval-queue) at the same time. Two setups reach it: a fork pull request on an organization whose fork policy is `hold`, and a context that sets both required reviewers and `minimumTrust`.
+
+The two are separate holds and **both** must be released before the job runs. They take different permissions: the approval hold needs `contexts:write` plus clause eligibility, the security hold needs `ci_trust:write`.
+
+`--job` names both at once, so pick one with `--hold-type`:
+
+```bash
+kici approve <run-id> --job deploy --hold-type reviewer
+kici approve <run-id> --job deploy --hold-type security
+```
+
+Pass `--hold <id>` when the command's error lists two holds that `--hold-type` still cannot separate. The pull request's `KiCI Security` check stays pending until both holds have ended, and its description names the second gate and the permission that clears it.
+
+Each hold carries its own expiry, so the job is cancelled when the **first** one runs out.
+
 ### 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.
@@ -272,217 +293,7 @@ You can also approve from the dashboard approval queue. See [Dashboard](https://
 - [Contexts](https://docs.kici.dev/user/contexts/) — operator-required reviewers on protected contexts.
 - [Approval gates (operator guide)](https://docs.kici.dev/operator/approvals/) — teams, the approval queue, expiry, and self-approval.
 - [Approval gates (architecture)](https://docs.kici.dev/architecture/approvals/) — the unified hold model and the step-level round-trip.
-
----
-
-## Concurrency groups
-
-Source: https://docs.kici.dev/user/concurrency/
-
-Concurrency groups prevent multiple workflow runs from executing in parallel when they target the same resource. Common use cases include preventing parallel deploys to the same environment or serializing database migrations.
-
-## Basic usage
-
-```typescript
-import { workflow, job, step, push } from '@kici-dev/sdk';
-
-export default workflow('deploy', {
-  on: push({ branches: ['main', 'staging'] }),
-  concurrency: {
-    group: (ctx) => `deploy-${ctx.branch}`,
-    cancelInProgress: true,
-    max: 1,
-  },
-  jobs: [
-    job('deploy', {
-      runsOn: 'linux',
-      steps: [
-        step('deploy', async ({ $ }) => {
-          await $`./deploy.sh`;
-        }),
-      ],
-    }),
-  ],
-});
-```
-
-## Configuration
-
-The `concurrency` option on a workflow accepts:
-
-| Field              | Type     | Default  | Description                                |
-| ------------------ | -------- | -------- | ------------------------------------------ |
-| `group`            | Function | Required | Returns the concurrency group key string   |
-| `cancelInProgress` | boolean  | `true`   | Cancel older runs when a newer run arrives |
-| `max`              | number   | `1`      | Maximum concurrent runs in the same group  |
-
-### Group key function
-
-The group key function receives a context with the branch name and event payload. Runs with the same group key are subject to concurrency limits.
-
-```typescript
-// Per-branch concurrency (most common)
-group: (ctx) => `deploy-${ctx.branch}`;
-
-// Global concurrency (across all branches)
-group: () => 'deploy';
-
-// Per-target-branch concurrency
-group: (ctx) => `deploy-${ctx.event.targetBranch ?? 'default'}`;
-```
-
-The workflow-level group function is always evaluated **agent-side** at runtime -- the lock file records only that a group function exists (`hasGroup: true`), not the function itself. The agent loads the workflow source, calls the group function with `{ branch, event }`, and reports the evaluated key back to the orchestrator before step execution begins. This differs from job-level `concurrencyGroup` (see [Contexts](https://docs.kici.dev/user/contexts/#concurrency-groups)), where the compiler performs purity analysis and can inline pure functions for orchestrator-side evaluation.
-
-## cancelInProgress mode
-
-When `cancelInProgress: true`, a newer run supersedes older runs in the same group:
-
-```
-Run #1 starts deploying to main        -> running
-Run #2 arrives for deploy-main group   -> Run #1 cancelled ("Superseded by run in concurrency group 'deploy-main'")
-Run #2 continues                       -> running
-```
-
-This is the most common mode for deploy workflows -- you want the latest code deployed, not an outdated version.
-
-The cancelled run:
-
-- Receives a cancellation with reason "Superseded by run in concurrency group 'deploy-main'"
-- Goes through the normal cancel flow (grace period, hooks if graceful)
-- GitHub Check status updated to `cancelled` with the superseded reason
-
-```typescript
-workflow('deploy', {
-  concurrency: {
-    group: (ctx) => `deploy-${ctx.branch}`,
-    cancelInProgress: true,
-  },
-  jobs: [/* ... */],
-});
-```
-
-## Queue mode
-
-When `cancelInProgress: false`, newer runs will wait until older runs complete:
-
-```
-Run #1 starts deploying                -> running
-Run #2 arrives for same group          -> queued ("Waiting for deploy-main (1 ahead)")
-Run #1 completes                       -> success
-Run #2 starts                          -> running
-```
-
-In queue mode, the agent that picked up the queued run **stays connected** to the orchestrator and parks on a long-poll wait. When the holder finishes (success, failure, or cancel), the orchestrator dequeues the FIFO-next entry and pushes a `proceed` notification over the same WebSocket; the queued agent then continues with normal step execution against the workspace it already has. The agent's slot is therefore held for the duration of the queue wait — bound by `KICI_CONCURRENCY_WAIT_TIMEOUT_MS` (default 1 hour).
-
-```typescript
-workflow('migrate-db', {
-  concurrency: {
-    group: () => 'migrations',
-    cancelInProgress: false,
-    max: 1,
-  },
-  jobs: [/* ... */],
-});
-```
-
-The dashboard will show a "Queued" badge with the reason: "Waiting for deploy-main (1 ahead)".
-
-## Max concurrent runs
-
-The `max` field controls how many runs can execute simultaneously in the same group:
-
-```typescript
-// Allow up to 3 parallel test runs per branch
-workflow('test', {
-  concurrency: {
-    group: (ctx) => `test-${ctx.branch}`,
-    cancelInProgress: false,
-    max: 3,
-  },
-  jobs: [/* ... */],
-});
-```
-
-When `max: 1` (default), runs are fully serialized within the group.
-
-## Group key examples
-
-### Deploy per environment
-
-```typescript
-workflow('deploy', {
-  concurrency: {
-    group: (ctx) => `deploy-${ctx.branch}`,
-    cancelInProgress: true,
-  },
-  jobs: [
-    job('deploy-staging', {
-      runsOn: 'linux',
-      context: 'staging',
-      steps: [/* ... */],
-    }),
-  ],
-});
-```
-
-### Global singleton
-
-```typescript
-// Only one migration can run at a time, regardless of branch
-workflow('migrate', {
-  concurrency: {
-    group: () => 'db-migration',
-    cancelInProgress: false,
-  },
-  jobs: [/* ... */],
-});
-```
-
-### Environment-aware groups
-
-```typescript
-// Serialize deploys per environment
-workflow('deploy', {
-  concurrency: {
-    group: (ctx) => {
-      const env = ctx.branch === 'main' ? 'production' : 'staging';
-      return `deploy-${env}`;
-    },
-    cancelInProgress: true,
-  },
-  jobs: [/* ... */],
-});
-```
-
-## Interaction with context protection
-
-When a workflow has both `concurrency` and `context` protection rules:
-
-1. Context protection gates (required reviewers, wait timer) apply first
-2. Concurrency group check happens after protection gates pass
-3. If the run is queued by concurrency, it keeps its protection approval
-
-This means a run that passed approval won't need re-approval if it gets queued by concurrency.
-
-## Cancelling queued runs
-
-Queued runs can be cancelled before they start executing. The cancel request removes them from the queue immediately -- they don't go through the grace period since no step is running.
-
-## Job-level concurrency groups
-
-In addition to workflow-level concurrency, individual jobs can define their own concurrency group via the `concurrencyGroup` property. This controls concurrent execution at the job level rather than the workflow level. See [Contexts — concurrency groups](https://docs.kici.dev/user/contexts/#concurrency-groups) for details.
-
-## Local execution
-
-`kici run <event> --local` is a real routed dispatch: your machine becomes an ephemeral agent behind the local dev plane, whose own orchestrator applies the same concurrency machinery described above. The `group` callback is evaluated agent-side against the simulated event, and `cancelInProgress` carries its usual semantics — `true` supersedes the older run in the group, `false` queues the newer one behind it.
-
-Coordination is scoped to that plane. The plane's state (including its database) lives under `~/.kici/local/`, so enforcement is per-machine and per-user: running the same workflow on two different machines does not serialize across them. For cross-host enforcement (queueing across agents, dashboard visibility), use `kici run remote` against a deployed orchestrator.
-
-See [`kici run <event> --local`](https://docs.kici.dev/user/cli/runs-and-approvals/#kici-run-event---local) for the rest of the local-run behavior, and [the local dev plane](https://docs.kici.dev/operator/orchestrator/local-dev-plane/) for the plane's state directory and lifecycle.
-
----
-
-_Source: `packages/sdk/src/types.ts` (WorkflowOptions.concurrency, JobOptions.concurrencyGroup)_
+- [Organization-wide workflows](https://docs.kici.dev/user/global-workflows/) — why an approval gate is refused there.
 
 ---
 
@@ -509,8 +320,6 @@ Available rules:
 
 <!-- /help:contexts-protection -->
 
-Contexts represent deployment targets like `staging`, `production`, or `review/PR-*`. Each context can have its own variables, bound secrets, and protection rules that control when and how jobs targeting that context can execute.
-
 ## Overview
 
 A context in KiCI provides:
@@ -568,7 +377,7 @@ job('deploy-review', {
 });
 ```
 
-A pure function like the one above (see [Dynamic values](https://docs.kici.dev/user/dynamic-values/)) is evaluated inline at dispatch with no init-job overhead. Dynamic contexts that match a glob pattern (e.g., `review/*`) inherit the pattern's configuration, variables, and protection rules.
+A dynamic context function like the one above (see [Dynamic values](https://docs.kici.dev/user/dynamic-values/)) is resolved on the eval agent's init step before the job runs. Dynamic contexts that match a glob pattern (e.g., `review/*`) inherit the pattern's configuration, variables, and protection rules.
 
 ### Multiple contexts per job
 
@@ -592,7 +401,7 @@ job('deploy', {
 
 **Merge order — last wins.** All bound contexts are resolved on every dispatch (webhook, scheduled, and test runs alike) and merged in array order. When the same secret or variable key is defined in more than one context, the later entry in the array wins. With `contexts: ['staging', 'my-testing']`, a key defined in both resolves to `my-testing`'s value; keys defined in only one are preserved. The longest-scope-path-wins rule still applies _within_ each context.
 
-**Protection rules combine all-must-pass.** A job must satisfy **every** bound context's gates — adding a context can never loosen access. Branch restrictions, trigger-type filters, and repo patterns must pass for all contexts; the minimum trust tier is the most restrictive across them; required reviewers are the union of all contexts' reviewers; the wait timer is the longest; and the hold expiry is the shortest. If a run is gated out, the rejection names which context and which rule rejected it (visible via `kici runs show <run-id>` and the run's rejection reason), so a mutually-exclusive set of rules surfaces as a clear failure rather than a silent perpetual rejection.
+**Protection rules combine all-must-pass.** A job must satisfy **every** bound context's gates — adding a context can never loosen access. Branch restrictions, trigger-type filters, and repo patterns must pass for all contexts. The minimum trust tier is the most restrictive across them, and required reviewers are the union of all contexts' reviewers. The wait timer is the longest, and the hold expiry is the shortest. If a rule rejects a job, that job is not dispatched. It still appears on the run, as a failed job whose reason names the context and the rule that rejected it. Read the reason with `kici runs show <run-id>`, or on the run detail page.
 
 **Skip-on-test (allow-and-warn).** On a test or local run (`kici run remote`, `kici run <event> --local`), a bound context never rejects the run. Any bound context that disallows local execution (`allowLocalExecution: false`) — or that is not configured — is **skipped**: its variables and secrets are omitted from the merge and its gates are not evaluated. The run proceeds, and a user-visible warning naming the skipped context(s) is shown both on the `kici run remote` CLI output and on the dashboard run view. This makes the test-only-variables pattern work: with `contexts: ['staging', 'my-testing']` where only `my-testing` allows local execution, a test run resolves just `my-testing`'s variables and warns that `staging` was skipped. If every bound context is skipped, the job runs with no environment variables. This is intentionally different from a fixture `secrets:` mapping, which is fail-closed — see the [testing guide](https://docs.kici.dev/user/testing-guide/).
 
@@ -690,6 +499,34 @@ Allowed branches: main, release/*
 
 Jobs from other branches are rejected immediately with an error message.
 
+**Most internally-triggered runs carry a branch.** KiCI starts these runs for itself: a [schedule](https://docs.kici.dev/user/sdk/triggers/) fire, a [custom event](https://docs.kici.dev/user/events/), a completion trigger, a failure batch, or an [invoke gate](https://docs.kici.dev/user/global-workflows/) summon. None comes from a branch push. A run with one source branch presents it:
+
+- A **schedule** fire executes the default branch's workflow, so it presents the repository's default branch.
+- A **`kiciEvent()` subscriber**, a **completion trigger** (`workflowComplete`, `jobComplete`) and an **invoke-gate summon** present the branch of the run behind them. That is the same branch the run behind them presented. For a pull-request run it is the branch the PR targets, not the contributor's own branch — so a subscriber of an event emitted by a PR against `main` presents `main`.
+
+A branch restriction compares that branch against your patterns like any other run. So a nightly deploy bound to a `production` context restricted to `main` runs.
+
+A branch restriction is not a trust control. It checks the branch a run presents, never where the code came from. A pull request against `main` presents `main`, whoever opened it. To gate on that, set a [minimum trust tier](https://docs.kici.dev/user/contexts/#minimum-trust) on the same context.
+
+A run with no single source branch presents no branch, and a branch restriction then rejects it:
+
+- A **failure batch** (`workflowsFailedBatch`). One accumulation window of failed runs causes it, on as many branches, so no one branch is its own.
+- A **scaler event** (`kici.scaler.scale-up`, `kici.scaler.scale-down`). The orchestrator mints these itself, with no run behind them. See [autoscaling workflows](https://docs.kici.dev/user/workflows/autoscaling-workflows/).
+- A **schedule** fire in a repository that has not pushed to its default branch since you upgraded KiCI. The default branch is captured when a push re-registers the workflows, so the first such push after the upgrade fixes it.
+- Any event whose emitting run is no longer on record.
+
+The rejection reason says so:
+
+```
+Context 'production' restricts branches: this internally-triggered run carries no
+branch, so no branch restriction can be satisfied - a scheduled run gains its
+branch after the next push to the default branch re-registers the workflow;
+alternatively bind a context without a branch restriction, or restrict by trigger
+type instead
+```
+
+To limit a context by how the run started instead of by branch, use a **trigger-type filter**: the trigger type is a real name (`schedule`, `kici_event`, `workflow_complete`, `job_complete`), so a filter that allows it works on these runs.
+
 ### Required reviewers
 
 Require manual approval before a job can proceed:
@@ -714,41 +551,44 @@ The job waits for the specified duration before proceeding. Useful for staged ro
 
 ### Minimum trust
 
-Gate job execution based on the contributor's trust tier for PR-triggered runs:
+Hold a job whose run came from a fork:
 
 ```
-Minimum trust: known
+Minimum trust: trusted
 ```
 
-| Value     | Effect                                              |
-| --------- | --------------------------------------------------- |
-| `known`   | Blocks unknown contributors; allows known + trusted |
-| `trusted` | Blocks unknown + known; allows only trusted         |
+| Value     | Effect                                                     |
+| --------- | ---------------------------------------------------------- |
+| `trusted` | Holds a run whose ref came from a fork                     |
+| `known`   | Same effect; the value is deprecated and removed at v1.0.0 |
+| (unset)   | No trust-based gating                                      |
+
+Both values block the same thing. Trust comes from the git ref, and that judgement has two answers: a ref in your repository is `trusted`, a ref from a fork is `unknown`. The value you declare still decides the wording of the hold reason.
+
+When the gate holds a job, it enters the security approval queue. Someone with `ci_trust:write` or higher must approve it before execution proceeds.
 
-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.
+A run that resolved **no** tier passes the gate. A pull request from a source with no fork model resolves none, and so does an internal run whose inheritance lookup failed. See [trust tiers on internal triggers](https://docs.kici.dev/user/events/#trust-tiers-on-internal-triggers) for the full table.
 
-Trust tier is determined by the contributor's identity link and CI trust RBAC level:
+The trust tier also affects which lock file a pull-request run uses: a trusted ref evaluates the head lock file, a fork ref evaluates the base branch's. A fork run additionally carries no install or registry secrets, and its build-cache writes are confined to that run. So a fork pull request cannot change what CI does, and cannot read a private-registry token, whether or not you set this gate.
 
-- **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
+Set the gate on any context that carries a credential a fork run must not reach. See the [deployment checklist](https://docs.kici.dev/operator/security/security/#deployment-checklist-which-contexts-need-it).
 
-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.
+An internally-triggered run carries a tier too. A schedule fire and the orchestrator's own lifecycle events are trusted. A `kiciEvent()` subscriber inherits the tier of the run that emitted the event, so a `minimumTrust` gate on the subscriber's context reads the **emitting** run's tier. See [trust tiers on internal triggers](https://docs.kici.dev/user/events/#trust-tiers-on-internal-triggers).
 
 See the [CI security architecture docs](https://docs.kici.dev/architecture/security/ci-security/) for the full trust resolution flow.
 
 ### Security approval queue
 
-When a PR is held for security review — the org trust policy held it (a non-trusted contributor modified `.kici/` files, the PR came from a fork, or the contributor could not be resolved to a known identity), or a `minimumTrust` gate blocked the contributor — it enters the security approval queue. This is separate from the context approval queue: a security hold asks "is it safe to run this contributor's code at all?", while a context approval hold asks "should this job be promoted?". The two never cross — releasing a security hold needs `ci_trust:write` or higher, releasing a context approval hold needs `contexts:write` plus eligibility for one of the gate's clauses. See [Approval holds vs security holds](https://docs.kici.dev/architecture/approvals/#approval-holds-vs-security-holds) for the full comparison.
+A pull request held for security review enters the security approval queue. Two things put it there: the organization's fork switch set to `hold`, and a `minimumTrust` gate blocking a fork run. This is separate from the context approval queue: a security hold asks "is it safe to run this contributor's code at all?", while a context approval hold asks "should this job be promoted?". The two never cross — releasing a security hold needs `ci_trust:write` or higher, releasing a context approval hold needs `contexts:write` plus eligibility for one of the gate's clauses. See [Approval holds vs security holds](https://docs.kici.dev/architecture/approvals/#approval-holds-vs-security-holds) for the full comparison.
 
 Held runs can be approved:
 
-- Via the **dashboard** in Settings > CI trust > Approval queue
+- Via the **dashboard** on the [Approval queue](https://docs.kici.dev/user/dashboard/contexts-and-secrets/#approval-queue) page, which lists security and context holds together
 - Via a PR comment: `/kici approve` (commenter must have `ci_trust:write+`)
 
-A hold raised by the org trust policy covers the whole PR and uses the org's approval expiry (default 72 hours). A `minimumTrust` hold is raised by a context rather than by the org policy, so it uses that context's own hold expiry (default one hour).
+A hold raised by the fork switch covers the whole pull request and uses the org's approval expiry (default 72 hours). A `minimumTrust` hold is raised by a context, so it uses that context's own hold expiry (default one hour). A job carrying both a reviewer approval hold and a security hold carries both expiries, and whichever comes first cancels the run.
 
-While the org trust policy is holding a pull request, your organization's global workflows do not run for it. Approving the hold releases that pull request's own workflows; it does not retroactively run the organization's global workflows for the event.
+While the fork switch is holding a pull request, your organization's global workflows do not run for it. Approving the hold releases that pull request's own workflows; it does not retroactively run the organization's global workflows for the event.
 
 ### Concurrency limits
 
@@ -764,6 +604,10 @@ The concurrency limit is a positive integer; leave it unset for unlimited concur
 - **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
 
+The children of a matrix job count individually against the limit. A three-child
+matrix bound to a context with a limit of two dispatches two children and applies
+the strategy above to the third.
+
 ## Dashboard management
 
 ### Creating contexts
@@ -791,7 +635,7 @@ Each context has four tabs:
 
 A job's bound deployment contexts are shown as chips on the run detail page (in the job metadata panel) in the order the job declared them, and the distinct set across a run's jobs appears as compact chips on the run list. For a multi-context job the chips read left-to-right in merge order — later contexts override earlier ones on key collisions. A `(dynamic)` chip marks a context whose name is computed at runtime; it resolves to the real name once the run starts. A job that binds a single context shows one chip; a job that binds none shows no chip.
 
-If a multi-context binding is gated out, the run's failure banner names which context and which rule rejected it (the same all-must-pass detail surfaced by `kici runs show <run-id>`).
+A job a bound context rejects keeps its chips, and shows as failed because it never ran. Its failure reason names the context and the rule that rejected it. `kici runs show <run-id>` prints the same reason.
 
 ### Secrets management
 
@@ -844,857 +688,6 @@ This guide is split across the following pages:
 
 ---
 
-## Dynamic values
-
-Source: https://docs.kici.dev/user/dynamic-values/
-
-Dynamic values let you compute `context`, `env`, and `concurrencyGroup` at runtime based on the incoming event. Instead of hardcoding static strings, you pass a function that receives the normalized event envelope and returns the resolved value.
-
-```typescript
-job('deploy', {
-  runsOn: ['default'],
-  context: (event) => event.targetBranch,
-  env: (event) => ({ BRANCH: event.targetBranch }),
-  concurrencyGroup: (event) => `deploy-${event.targetBranch}`,
-  steps: [/* ... */],
-});
-```
-
-```typescript
-job('deploy', {
-  runsOn: 'default',
-  // One shape everywhere: branch on the normalized event type.
-  context: (event) => (event.type === 'pull_request' ? 'preview' : 'production'),
-  steps: [/* ... */],
-});
-```
-
-## How it works
-
-When you define a dynamic value as a function, the compiler analyzes it at compile time to determine whether it is **pure** (can be evaluated without cloning the repo or running an init job).
-
-### Pure functions (inline evaluation)
-
-A pure function is one that:
-
-- Is synchronous (no `async`/`await`)
-- Only references its parameters and local variables
-- Does not import or require external modules
-- Does not access globals like `process`, `fetch`, `console`, `setTimeout`, etc.
-- Uses only safe built-in constructors: `String`, `Number`, `Boolean`, `Array`, `Object`, `JSON`, `Math`, `parseInt`, `parseFloat`, `isNaN`, `isFinite`, `encodeURIComponent`, `decodeURIComponent`, `encodeURI`, `decodeURI`
-- Does not use `this`, `new`, `class`, `throw`, `try`/`catch`, `delete`, `var`, `yield`, or mutation operators (`++`, `--`, `+=`, etc.)
-
-When the compiler detects a pure function, it serializes the function source directly into the lock file as an inline expression. At dispatch time, the orchestrator evaluates the expression in a sandboxed VM context (~0ms overhead) instead of dispatching an init job.
-
-**Examples of pure functions:**
-
-```typescript
-// Simple branch extraction
-context: (event) => event.targetBranch;
-
-// Object literal with string operations
-env: (event) => ({ BRANCH: event.targetBranch });
-
-// Concatenation with event data
-concurrencyGroup: (event) => `deploy-${event.targetBranch}`;
-
-// Using safe globals
-env: (event) => ({ UPPER: String(event.targetBranch).toUpperCase() });
-
-// Local variables are fine
-context: (event) => {
-  const parts = event.targetBranch.split('/');
-  return parts[parts.length - 1];
-};
-```
-
-### Impure functions (init-job evaluation)
-
-If the compiler determines a function is impure, it prints a `warning [W101]` naming the affected field (`context`, `env`, or `concurrencyGroup`), the reason the function was judged impure, and the ~5-10 second init-job cost — and compilation still succeeds. The function falls back to the two-phase init model. This means:
-
-1. The orchestrator dispatches a special `__init__` job to a builder agent
-2. The builder agent clones the repository and evaluates the function
-3. The resolved values are sent back to the orchestrator
-4. The orchestrator dispatches the real execution job with the resolved values
-
-This adds approximately 5-10 seconds of overhead for cloning and evaluation.
-
-`kici preview` lists the injected `__init__` job under each affected job, so you can spot the init-job cost before the first run.
-
-**Examples of impure functions (will use init job):**
-
-```typescript
-// Async functions cannot be inlined
-context: async (event) => await lookupEnv(event.targetBranch);
-
-// External module references
-env: (event) => {
-  const config = require('./config');
-  return config.env;
-};
-
-// Process/global access
-context: (event) => process.env.DEFAULT_ENV || 'staging';
-
-// Dynamic imports
-env: async (event) => {
-  const m = await import('./config.js');
-  return m.default;
-};
-```
-
-## Performance comparison
-
-| Evaluation path                      | Overhead | When used                                                       |
-| ------------------------------------ | -------- | --------------------------------------------------------------- |
-| Static value (string/object literal) | ~0ms     | `context: 'staging'`                                            |
-| Inline expression (pure function)    | ~0ms     | `context: (event) => event.targetBranch`                        |
-| Init job (impure function)           | ~5-10s   | `context: async (event) => await lookupEnv(event.targetBranch)` |
-
-## Tips
-
-- **Write pure functions whenever possible** to avoid the init-job delay. Most context and env computations only need the event payload data.
-- **Check compiler warnings** -- the compiler prints a `warning [W101]` when a function is classified as impure, naming the reason and the ~5-10s init-job cost. Run `kici preview` to see the injected `__init__` job listed under each affected job before your first run.
-- **Runtime errors in inline expressions cause immediate job failure.** There is no fallback to the init-job path. If your pure function throws at runtime (e.g., accessing a property on `undefined`), the job fails immediately.
-- **See [how your workflow code executes](https://docs.kici.dev/user/execution-model/)** for the full picture of where pure vs. impure functions run relative to rules, hooks, and step bodies.
-- **The event parameter is the normalized event envelope** — the same shape rules receive as `ctx.event`: `{ type, action, targetBranch, sourceBranch, changedFiles, payload, … }` (see the [event payload reference](https://docs.kici.dev/user/sdk/event-payloads/) for the complete schema). Narrow on `event.type` (`'push'`, `'pull_request'`, `'tag'`, …) to branch per trigger kind. The raw provider webhook body is nested at `event.payload` (for GitHub pushes: `payload.ref`, `payload.after`, `payload.repository`, …).
-
----
-
-## Environment variables
-
-Source: https://docs.kici.dev/user/env-vars/
-
-The KiCI CLI reads the following environment variables to customize its behavior. OAuth login (`kici login` without `--token`) defaults `KICI_PLATFORM_URL`, `KICI_OIDC_ISSUER`, and `KICI_OIDC_CLIENT_ID` to the hosted KiCI Platform, so `kici login` works with no configuration. Set them only to target another KiCI environment (e.g. a testing instance) or a custom OIDC provider.
-
-## Authentication
-
-| Variable              | Description                            | Default                                      |
-| --------------------- | -------------------------------------- | -------------------------------------------- |
-| `KICI_OIDC_ISSUER`    | OIDC issuer URL for authentication     | `https://auth.kici.dev/realms/kici-internal` |
-| `KICI_OIDC_CLIENT_ID` | OIDC client ID for the CLI application | `kici-cli`                                   |
-| `KICI_PLATFORM_URL`   | Platform API base URL                  | `https://api.kici.dev`                       |
-| `KICI_CONFIG_DIR`     | Override the KiCI config directory     | `~/.kici`                                    |
-
-## Browser behavior
-
-| Variable             | Description                                                                                                                                          | Default                         |
-| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
-| `KICI_BROWSER_CMD`   | Custom browser command for OAuth login. Supports `{url}` placeholder. Set to `none` to suppress browser opening and print the URL to stdout instead. | Uses the system default browser |
-| `KICI_CALLBACK_PORT` | Fixed port for the OAuth PKCE callback server. Useful when firewall rules require a known port.                                                      | Random available port           |
-
-## Development
-
-| Variable     | Description                                                                                                                                                                | Default |
-| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| `KICI_DEV`   | Enable development mode. When `true`, uses prerelease-compatible version ranges (`>=0.0.1-0`) for dev dependencies and skips npm version resolution.                       | unset   |
-| `KICI_DEBUG` | Enable debug logging. When `true`, prints verbose diagnostics (SDK alias resolution, step-level debug logs, stack traces on errors). Equivalent to the `--debug` CLI flag. | unset   |
-
-## Local dev plane
-
-Read by the [local dev plane](https://docs.kici.dev/user/cli/authoring-and-local/#kici-local) that `kici run <event> --local` dispatches through.
-
-| Variable                           | Description                                                                                                                                                                         | Default              |
-| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
-| `KICI_LOCAL_ORCH_PORT`             | Port the plane orchestrator listens on (HTTP + WebSocket). Change it when another process already holds the default.                                                                | `4319`               |
-| `KICI_LOCAL_PG_PORT`               | Port the plane's PostgreSQL listens on.                                                                                                                                             | `45432`              |
-| `KICI_LOCAL_PG_MODE`               | Set to `podman` to force the container PostgreSQL fallback instead of the embedded binary.                                                                                          | Embedded PostgreSQL  |
-| `KICI_LOCAL_ACCEPTANCE_TIMEOUT_MS` | How long a local run waits for an agent to claim its first job before failing fast. Raise it on a slow host; the run still fails quickly when no scaler label set matches `runsOn`. | `120000` (2 minutes) |
-
-## CI detection
-
-The CLI also reads the conventional CI markers your CI provider sets. They are not KiCI variables — KiCI only consumes them.
-
-| Variable         | Description                                  | Default |
-| ---------------- | -------------------------------------------- | ------- |
-| `CI`             | Generic CI marker. Set by most CI providers. | unset   |
-| `GITHUB_ACTIONS` | Set to `true` by GitHub Actions.             | unset   |
-| `GITLAB_CI`      | Set to `true` by GitLab CI/CD.               | unset   |
-
-### How `CI` is interpreted
-
-`kici` treats the environment as CI when `CI`, `GITHUB_ACTIONS`, or `GITLAB_CI` is set to any value other than an explicit opt-out. `0` and `false` are the opt-outs, compared case-insensitively, so `CI=0`, `CI=false`, and `CI=False` all mean "not CI". Surrounding whitespace is ignored, and a value that is empty or only whitespace (`CI=`) is treated as unset.
-
-A vendor marker outranks the generic opt-out: `CI=false GITHUB_ACTIONS=true` is still CI, because an explicit vendor marker names a real runner rather than a preference.
-
-This affects which login flow `kici login` chooses (browser vs device) and whether interactive commands such as `kici init` prompt.
-
-## Usage examples
-
-### CI/CD environment
-
-Authenticate with a pre-existing API key (no browser needed):
-
-```bash
-kici login --token "$KICI_API_KEY"
-```
-
-### Targeting another environment or custom OIDC provider
-
-`kici login` targets the hosted KiCI Platform by default. To point the CLI at another KiCI environment (e.g. a testing instance) or a custom OIDC provider, override the defaults:
-
-```bash
-export KICI_OIDC_ISSUER=https://your-idp.example.com
-export KICI_OIDC_CLIENT_ID=your-client-id
-export KICI_PLATFORM_URL=https://your-platform.example.com
-kici login
-```
-
-### Headless SSH session
-
-The CLI auto-detects headless environments and uses the device flow. To force PKCE with URL output instead:
-
-```bash
-export KICI_BROWSER_CMD=none
-kici login
-```
-
-This prints the authorization URL to stdout as `KICI_AUTH_URL=<url>`. Open the URL in any browser to complete authentication.
-
-### Fixed callback port
-
-When behind a firewall or using port forwarding:
-
-```bash
-export KICI_CALLBACK_PORT=19876
-kici login
-```
-
-### Custom config location
-
-Store the KiCI config in a non-default location:
-
-```bash
-export KICI_CONFIG_DIR=/tmp/kici-test
-kici login
-```
-
----
-
-## Event system
-
-Source: https://docs.kici.dev/user/events/
-
-KiCI supports two broad categories of workflow triggers: **git-based triggers** that work immediately, and **event-based triggers** that use a registration model. Understanding this distinction is key to working effectively with non-git triggers like schedules, custom events, and generic webhooks.
-
-## Overview
-
-Git-based triggers (`push()`, `pr()`, `tag()`, `comment()`, `review()`, `release()`, etc.) work immediately after you commit your lock file. When a GitHub webhook arrives, the orchestrator fetches your lock file and evaluates triggers on the spot -- no advance setup needed.
-
-Event-based triggers work differently. The orchestrator needs to know about them _before_ the event arrives. This is because event-based triggers are matched against a pre-built registration index rather than being evaluated per-event from a lock file fetch. The six event-based trigger types are:
-
-- `kiciEvent()` -- custom events emitted from workflow steps
-- `workflowComplete()` -- fires when a workflow finishes
-- `jobComplete()` -- fires when a specific job finishes
-- `genericWebhook()` -- HTTP webhooks from external services
-- `schedule()` -- cron-based time triggers
-- `lifecycle()` -- orchestrator lifecycle events (workflow completion, job failure, registration updates)
-
-All six require the **registration model** to function -- covered in detail below.
-
-## Event types
-
-### Custom events
-
-Custom events are user-defined events emitted from workflow steps using `ctx.emit()`. Use `kiciEvent()` to listen for them.
-
-```typescript
-import { kiciEvent } from '@kici-dev/sdk';
-
-// Listen for a custom event by name
-kiciEvent({ name: 'deploy-complete' });
-
-// With payload matching (JSONPath)
-kiciEvent({ name: 'deploy-complete', match: { '$.env': 'prod' } });
-
-// With negative filter
-kiciEvent({ name: 'deploy-complete', not: { '$.env': 'staging' } });
-
-// From a specific repository
-kiciEvent({ name: 'deploy-complete', source: 'org/infra-repo' });
-```
-
-**Config options:** `name` (required), `match`, `not`, `source`, `description`.
-
-### System events
-
-The orchestrator automatically emits completion events when workflows and jobs finish. No manual emission needed -- these fire automatically.
-
-**Workflow completion:**
-
-```typescript
-import { workflowComplete } from '@kici-dev/sdk';
-
-// Any workflow completion
-workflowComplete();
-
-// Specific workflow by name
-workflowComplete({ name: 'build' });
-
-// Only successful completions
-workflowComplete({ name: 'build', status: ['success'] });
-```
-
-**Config options:** `name`, `status` (`'success'`, `'failed'`, `'cancelled'`), `source`, `description`.
-
-**Job completion:**
-
-```typescript
-import { jobComplete } from '@kici-dev/sdk';
-
-// Any job completion
-jobComplete();
-
-// Specific workflow + job
-jobComplete({ workflow: 'build', job: 'test' });
-
-// Only failures
-jobComplete({ workflow: 'build', job: 'test', status: ['failed'] });
-```
-
-**Config options:** `workflow`, `job`, `status` (`'success'`, `'failed'`, `'cancelled'`, `'skipped'`), `source`, `description`.
-
-### External events
-
-Generic webhooks let you trigger workflows from any HTTP service -- Stripe, ArgoCD, Slack, Grafana, or your own internal services.
-
-```typescript
-import { genericWebhook } from '@kici-dev/sdk';
-
-// Match any event from a source
-genericWebhook({ source: 'stripe' });
-
-// Match specific event types
-genericWebhook({ source: 'stripe', events: ['invoice.paid'] });
-
-// With HMAC-SHA256 signature verification
-genericWebhook({
-  source: 'stripe',
-  events: ['invoice.paid'],
-  auth: {
-    method: 'hmac-sha256',
-    secret: 'stripe-signing-key',
-    signatureHeader: 'stripe-signature',
-  },
-});
-
-// With API key auth
-genericWebhook({
-  source: 'slack',
-  auth: { method: 'api-key', secret: 'slack-token' },
-});
-```
-
-**Config options:** `source` (required), `events`, `match`, `not`, `auth`, `path`, `description`.
-
-The `source` field MUST match the `--name` that an operator passed to `kici-admin source add generic --name <name>` when the source was created — that string is the source's identifier in the orchestrator. Generic webhook sources must be created by an operator before events can be received; see [Operator guide: event routing](https://docs.kici.dev/operator/event-routing/) for setup instructions.
-
-### Schedule events
-
-Cron-based triggers evaluated by the orchestrator on a periodic interval. Only the Raft leader evaluates schedules in a clustered deployment.
-
-```typescript
-import { schedule } from '@kici-dev/sdk';
-
-// Run every hour
-schedule({ cron: '0 * * * *' });
-
-// Run daily at 2 AM UTC
-schedule({ cron: '0 2 * * *' });
-
-// Run weekly on Mondays at 9 AM Eastern
-schedule({ cron: '0 9 * * 1', timezone: 'America/New_York' });
-```
-
-**Config options:** `cron` (required), `timezone` (defaults to `'UTC'`), `description`.
-
-### Lifecycle events
-
-Lifecycle triggers listen for orchestrator-level events related to workflow execution and system state changes.
-
-```typescript
-import { lifecycle } from '@kici-dev/sdk';
-
-// Trigger when any workflow completes
-lifecycle({ events: ['workflow_complete'] });
-
-// Trigger on job failures from a specific repo
-lifecycle({ events: ['job_failed'], sources: ['org/deploy-repo'] });
-
-// Trigger when registrations are updated
-lifecycle({ events: ['registration_updated'] });
-```
-
-**Available events:** `'workflow_complete'`, `'job_complete'`, `'job_failed'`, `'registration_updated'`.
-
-**Config options:** `events` (required), `sources`, `description`.
-
-## The registration model
-
-This is the most important concept for understanding event-based triggers.
-
-### Why registrations exist
-
-When a GitHub webhook arrives (push, PR, etc.), the orchestrator fetches your lock file from the repository and evaluates triggers on the spot. This works because the event itself tells the orchestrator _which repository_ to look at.
-
-Event-based triggers are different. When a cron timer fires or a custom event is emitted, there is no incoming webhook pointing to a specific repository. The orchestrator needs to know _in advance_ which workflows care about which events. That is what the registration model provides: a pre-built index of event-based workflows.
-
-### How registration works
-
-1. You define a workflow with an event-based trigger (e.g., `schedule()`, `kiciEvent()`, `genericWebhook()`)
-2. You compile the workflow (`kici compile`), which produces a lock file
-3. You push the lock file to your repository's **default branch** (e.g., `main` or `master`)
-4. The orchestrator receives the push webhook, detects it targets the default branch, and extracts all workflows with event-based triggers from the lock file
-5. Those workflows are stored in the orchestrator's registration database
-6. From that point on, matching events will trigger those workflows
-
-### Key implications
-
-- **Event-based workflows do not trigger until you push to the default branch.** If you add a new `schedule()` workflow, it will not start running until you merge to your default branch. This is by design -- the orchestrator cannot match events to workflows it does not know about.
-
-- **Registration is automatic.** There is no manual setup. Push your code, and the orchestrator handles the rest.
-
-- **Registrations refresh on every default-branch push.** If you add, remove, or modify event-based workflows and push to the default branch, the orchestrator updates its registration index automatically. Removed workflows stop triggering. New workflows start triggering.
-
-- **Git-based triggers are unaffected.** Triggers like `push()`, `pr()`, and `tag()` do not use registrations. They work immediately from any branch because the orchestrator evaluates them per-event from the lock file.
-
-### Practical example
-
-You create a nightly build workflow:
-
-```typescript
-import { workflow, job, step, schedule } from '@kici-dev/sdk';
-
-export default workflow('nightly-build', {
-  on: schedule({ cron: '0 2 * * *' }),
-  jobs: [
-    job('build', {
-      runsOn: 'linux',
-      steps: [
-        step('build', async ({ $ }) => {
-          await $`pnpm build`;
-        }),
-      ],
-    }),
-  ],
-});
-```
-
-You compile it, commit the lock file, and push to a feature branch. **Nothing happens** -- the cron will not fire because the orchestrator has not registered this workflow yet.
-
-You merge the feature branch into `main`. On the merge push, the orchestrator extracts the `nightly-build` workflow (it has a `ScheduleTrigger`) and registers it. Starting at the next 2 AM UTC, the workflow will trigger.
-
-## How events are matched
-
-When an event arrives, the orchestrator follows this flow:
-
-1. **Event received** -- a custom event is emitted by a step, a cron timer fires, or a generic webhook arrives
-2. **Registration lookup** -- the orchestrator queries its registration index for workflows matching the event type (e.g., all workflows with `ScheduleTrigger` for a cron fire, or all workflows with `KiciEventTrigger` for a custom event)
-3. **Trigger evaluation** -- for each candidate workflow, the orchestrator evaluates the trigger conditions: event name patterns, payload matching, status filters, source filters
-4. **Dispatch** -- matched workflows are dispatched to agents for execution, following the same job queue and agent routing as git-triggered workflows
-
-This lookup is fast because the registration index is held in memory and refreshed only when the registry version changes (on default-branch pushes).
-
-### Cross-source webhook delivery
-
-The catch-all `webhook()` trigger (see [SDK reference: webhook()](https://docs.kici.dev/user/sdk/triggers/#webhook)) participates in this same registration lookup, but with one twist: it fires for matching events arriving via **any** inbound webhook source in the same org, not just the source the workflow's repo is bound to. The orchestrator maintains a `(customerId, eventName)` index over webhook trigger registrations and consults it on every inbound generic webhook.
-
-The lookup is structurally org-isolated — a generic webhook delivered to org A can never reach a workflow registered against org B, because foreign-org rows live in a different bucket of the index. When a webhook fires across sources, the runtime clone token, repo URL, and check-status posting all come from the **registration's** source bundle, not the inbound source. The inbound source contributes only the event payload.
-
-## Circuit breaker
-
-Events can trigger workflows that emit more events, creating chains. The circuit breaker prevents runaway event storms.
-
-### Chain depth limit
-
-Each event carries a `chainDepth` counter. When a workflow triggered by an event emits a new event, the new event's chain depth increments. The orchestrator rejects events that exceed the maximum chain depth.
-
-- **Default limit:** 10 levels deep
-- **What happens when hit:** the event is dropped and logged. It is not queued for later delivery.
-
-For example: Workflow A emits event X (depth 0) -> Workflow B triggers, emits event Y (depth 1) -> ... -> at depth 10, any further emitted events are dropped.
-
-### Rate limiting
-
-Each workflow is rate-limited on how many events it can process per minute, using a sliding window.
-
-- **Default limit:** 100 events per workflow per minute
-- **What happens when hit:** additional events for that workflow are dropped and logged until the window clears.
-
-These defaults are hardcoded in the orchestrator and are not currently configurable via environment variables.
-
-## Delivery guarantees
-
-KiCI's event router delivers every accepted event with **at-least-once** semantics:
-
-- An event that passes the circuit breaker (chain depth + rate limit) and commits
-  to the `kici_events` table is guaranteed to dispatch to all matching workflows
-  at least once.
-- Each dispatch attempt acquires a short-lived lease (default 60 s) on the row.
-  If the dispatching node crashes or the handler throws, the lease expires (or
-  is released on failure) and the event is automatically retried.
-- The retry policy is exponential backoff with full jitter: base 5 s, cap 5 min,
-  up to 5 attempts before the event lands in the **DLQ** (dead-letter queue).
-  Operators triage DLQ entries via `kici-admin event-dlq list / count / retry / discard`.
-
-**What this means for workflow authors:**
-
-- **Make event handlers idempotent.** A retried dispatch may run a handler more
-  than once (e.g. if the first attempt threw after a partial side-effect).
-  Workflows that mutate external state should use idempotency keys, conditional
-  writes, or other deduplication patterns — same advice as for any distributed
-  CI system.
-- **Schedule fires are at-least-once too.** A cron schedule that fires while a
-  leader is being killed will commit (atomically with `cron_last_fired`) or roll
-  back together — never half. Recovery on the new leader does not backfill
-  multiple missed instants; if your workflow needs at-least-N guarantees across
-  outages, drive it from a different mechanism (e.g. a workflow that runs more
-  frequently and emits its own custom event).
-- **Drops are still possible — and visible.** Events rejected by the circuit
-  breaker (chain depth or rate limit exceeded) are dropped and logged, not
-  retried. That's a deliberate safety mechanism; the metric to watch is
-  `kici_orch_events_dropped_total{reason}`.
-
-## Emitting custom events
-
-Custom events are emitted from workflow steps using `ctx.emit()`. You can optionally define typed event schemas using `defineEvent()`.
-
-### Basic emission
-
-```typescript
-import { workflow, job, step, push } from '@kici-dev/sdk';
-
-export default workflow('build', {
-  on: push({ branches: 'main' }),
-  jobs: [
-    job('build', {
-      runsOn: 'linux',
-      steps: [
-        step('build', async ({ $ }) => {
-          await $`pnpm build`;
-        }),
-        step('notify', async (ctx) => {
-          await ctx.emit('build-complete', {
-            version: '1.0.0',
-            success: true,
-          });
-        }),
-      ],
-    }),
-  ],
-});
-```
-
-### Typed event definitions
-
-Use `defineEvent()` with Zod schemas to create a typed contract for event payloads:
-
-```typescript
-import { defineEvent, z } from '@kici-dev/sdk';
-
-export const deployComplete = defineEvent(
-  'deploy-complete',
-  z.object({
-    env: z.string(),
-    version: z.string(),
-    services: z.array(z.string()),
-  }),
-);
-```
-
-Then emit using the definition — the payload is checked against the schema:
-
-```typescript
-step('emit', async (ctx) => {
-  await ctx.emit(deployComplete, {
-    env: 'prod',
-    version: '1.2.3',
-    services: ['api', 'web'],
-  });
-});
-```
-
-And consume in another workflow:
-
-```typescript
-import { workflow, job, step, kiciEvent } from '@kici-dev/sdk';
-
-export default workflow('post-deploy', {
-  on: kiciEvent({ name: 'deploy-complete', match: { '$.env': 'prod' } }),
-  jobs: [
-    job('smoke-test', {
-      runsOn: 'linux',
-      steps: [
-        step('test', async ({ $ }) => {
-          await $`./scripts/smoke-test.sh`;
-        }),
-      ],
-    }),
-  ],
-});
-```
-
-Custom events are delivered immediately when emitted (mid-workflow, not queued until workflow completion). See the [SDK reference: emitting events](https://docs.kici.dev/user/sdk/validation-events/#emitting-events) section for the full `ctx.emit()` API.
-
-## See also
-
-- [SDK reference: event triggers](https://docs.kici.dev/user/sdk/triggers/#event-triggers) -- complete API signatures for all trigger builders
-- [SDK reference: emitting events](https://docs.kici.dev/user/sdk/validation-events/#emitting-events) -- `ctx.emit()` and `defineEvent()` API
-- [Workflow patterns: workflow chaining](https://docs.kici.dev/user/patterns/integrations/#workflow-chaining) -- examples of event-driven workflow chains
-- [Operator guide: event routing](https://docs.kici.dev/operator/event-routing/) -- configuring generic webhook sources, trust relationships, and event routing
-- [Architecture: event system](https://docs.kici.dev/architecture/webhooks/event-system/) -- internal event routing design, registration model, cluster synchronization
-
----
-
-## Global workflows
-
-Source: https://docs.kici.dev/user/global-workflows/
-
-Global workflows let one **workflow repo** define jobs that run on events from many **source repos** in the same org. They're the answer to "I want one CI policy / release pipeline / security scan to fire on every repo without copy-pasting `.kici/` folders everywhere."
-
-If you've only ever used per-repo workflows so far, start with the mental model section — global workflows add two new concepts (workflow repo vs. source repo, and authoring vs. source axes) that show up everywhere from SDK syntax to dashboard settings.
-
-## Mental model
-
-| Term           | Meaning                                                                                                                                                |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Workflow repo  | The repo whose `.kici/workflows/*.ts` file **declares** the global workflow. Holds the steps. Also known as the _authoring_ repo.                      |
-| Source repo    | The repo that **emits** the event (push / PR / tag / ...) that causes the global workflow to fire. The agent checks out this repo as the working copy. |
-| Global         | A workflow whose trigger carries one or more `repos:` glob patterns. The presence of `repos:` is what classifies a workflow as global.                 |
-| Authoring axis | Policy that answers "which repos may **author** global workflows?" Controlled by the allow-list in the dashboard's _Allowed author repos_ setting.     |
-| Source axis    | Policy that answers "which **source** repos' events are allowed to trigger global workflows?" Controlled by the deny-list in _Blocked source repos_.   |
-
-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                                                                                  |
-| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| Allowed author repos | Restricts which repos can **author** (register) global workflows. Globs matched against the authoring repo identifier. When OFF, any repo in the org may author globals.                             | Lock authoring to `myorg/ci-*` so random product repos can't ship org-wide automation.       |
-| Blocked source repos | Blocks dispatch for events emitted from these **source** repos, regardless of authoring. Globs matched against the event source repo identifier. When OFF, events from any repo may trigger globals. | Protect against fork spam — e.g. `!myorg/*` via `myorg/fork-*`.                              |
-| Elevated access      | Authoring repos listed here get **read access to source-repo secrets** during execution. Globs matched against the authoring repo identifier.                                                        | A `myorg/ci-deploy` repo that needs to read a source repo's `NPM_TOKEN` to publish releases. |
-
-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 _Allowed author repos_ is ON, the workflow's authoring repo must match at least one allow-list glob. If OFF, any repo may author. Enforced at two points:
-   - At registration time (extraction from the lock file — non-matching globals are dropped with a warning).
-   - At dispatch time (defense-in-depth — policy changes after registration still take effect).
-2. **The source repo is not denied.** If the event's source repo matches any glob in _Blocked source repos_, the global workflow is skipped. Enforced at dispatch time.
-
-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`,
-`retry`, `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` control drift reporting on `kici run remote`:
-
-```bash
-# Apply (default): converge the workflow.
-kici run push --local
-kici run remote my-fixture
-
-# Check: report drift, change nothing. Always exits 0.
-kici run remote my-fixture --check
-
-# Check + fail on drift: fail the run when any step reports drift. Use this as a
-# CI gate ("fail the build if prod has drifted").
-kici run remote my-fixture --check --fail-on-drift
-```
-
-`--fail-on-drift` only modifies check mode — passing it without `--check` is an
-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/
@@ -1744,7 +737,7 @@ export default workflow('build', {
 
 Per-field rules:
 
-- **`url`** — Must be HTTPS. HTTP is permitted only for `localhost` / `127.0.0.0/8` / `::1` / `*.local` hosts, or when an operator has flipped the org-level `allow_http_npm_registries` toggle (see [`kici-admin org-settings allow-http-npm`](https://docs.kici.dev/operator/kici-admin-cli#allow-http-npm--permit-non-https-private-npm-registries)).
+- **`url`** — Must be HTTPS. HTTP is permitted only for `localhost` / `127.0.0.0/8` / `::1` / `*.local` hosts, or when an operator has flipped the org-level `allow_http_npm_registries` toggle (see [`kici-admin org-settings allow-http-npm`](https://docs.kici.dev/operator/orchestrator/kici-admin/org-settings/#allow-http-npm--permit-non-https-private-npm-registries)).
 - **`scope`** — Optional. When present, the registry serves only that scope (`@my-org`). When absent, this entry becomes the **default** registry — at most one entry may omit `scope`.
 - **`tokenSecret`** — Mandatory `<context>:<secret-name>`. The orchestrator looks up the secret in the named context via the per-context secret resolver. The bare name **must not** contain a colon.
 - **`alwaysAuth`** — Defaults to `true`. Forces npm to send the token on every request (even GETs), which is what most managed-registry providers require.
@@ -1921,7 +914,7 @@ registries: [
 ## Security model
 
 - **Per-context scoping.** Every `tokenSecret` and `installEnv` entry is qualified with a context name. The orchestrator runs the same protection-rule pipeline (branch / trust / concurrency / reviewer / wait-timer) against each named context **before** resolving any secret, so a workflow that wants a `production` token from a feature branch is rejected exactly like a job that tries to deploy to `production` from a feature branch. A reviewer-gated install context **pauses** the whole workflow dispatch as a workflow-scoped held run instead of resolving the token — see [Reviewer-gated installs](https://docs.kici.dev/user/private-registries/#reviewer-gated-installs) below.
-- **Untrusted contributors get no tokens.** When a fork PR is dispatched and the contributor-trust resolution returns anything other than `trusted`, the orchestrator strips both `npmRegistries` and `installEnvSecrets` out of the dispatch. The install runs without auth and fails naturally on the first private dep — fork PRs cannot ever observe a registry token, even if a misconfigured context lacks an explicit [minimum trust](https://docs.kici.dev/user/contexts/#minimum-trust) rule.
+- **Untrusted refs get no tokens.** When the trust resolution returns anything other than `trusted` — every fork pull request does — the orchestrator strips both `npmRegistries` and `installEnvSecrets` out of the dispatch. The install runs without auth and fails naturally on the first private dep. A fork pull request cannot observe a registry token, even if a context lacks an explicit [minimum trust](https://docs.kici.dev/user/contexts/#minimum-trust) rule.
 - **Lifecycle scripts disabled.** Whenever a private registry is in scope, the agent runs the install with `--ignore-scripts` (npm, pnpm, and yarn classic alike; yarn berry gets the equivalent `enableScripts: false`). A malicious `preinstall` / `postinstall` hook in committed `package.json` cannot read the synthesized token env vars, even though they exist in the install subprocess. For a pnpm or yarn workspace, the agent builds your in-repo dependency closure as a separate step **after** the install's auth is torn down, so build scripts never see the tokens either.
 - **Stderr is redacted.** If the install fails, the agent masks every token literal out of the surfaced stderr / stdout chunks before logging.
 - **Job-scoped env-var names.** The synthesized auth env var is `KICI_NPM_TOKEN_<jobIdShort>_<i>` where `jobIdShort` is the first 8 chars of the dispatched job id. The name is unguessable from outside the install subprocess and not reused across jobs.
@@ -1958,7 +951,7 @@ The dashboard JSON lives at `infra/terraform/modules/grafana/dashboards/install-
 
 - [Secrets](https://docs.kici.dev/user/secrets/) — how to seed the `<context>:<secret-name>` values referenced by `tokenSecret` / `installEnv`.
 - [Contexts](https://docs.kici.dev/user/contexts/) — protection rules (`branch_restrictions`, `requires_review`, `minimum_trust`) that the install gate inherits.
-- [Operator: `kici-admin org-settings`](https://docs.kici.dev/operator/kici-admin-cli#org-settings----org-level-security-policy) — the `allow_http_npm_registries` toggle and other org-scoped knobs.
+- [Operator: `kici-admin org-settings`](https://docs.kici.dev/operator/orchestrator/kici-admin/org-settings/#org-settings----org-level-security-policy) — the `allow_http_npm_registries` toggle and other org-scoped knobs.
 
 ---
 
@@ -2113,11 +1106,12 @@ commonly, an offline `{ issuer, jwks }` file for air-gapped checks.
 
 ### Why you supply it out-of-band
 
-Given there's a single issuer, why pass it at all instead of letting the
-verifier read it from the token? Because the issuer named **inside** a token
-cannot be trusted: a forged bundle could carry a token that names
-`iss: https://attacker.example` _and_ bundle a key set that "verifies" it,
-making the whole signature chain circular and self-attesting. The verifier
+The verifier already resolves a sensible default, so why is naming the trust
+root a supported step at all -- why not let the verifier read the issuer from
+the token? Because the issuer named **inside** a token cannot be trusted. A
+forged bundle could carry a token that names `iss: https://attacker.example`
+_and_ bundle a key set that "verifies" it. That makes the whole signature chain
+circular and self-attesting. The verifier
 therefore pins to an issuer you supply out-of-band and checks the token against
 _that_ — the bundle is verified against a key set you trust, not one it shipped
 with. Naming the trust root is a security requirement, not a multiple-choice
@@ -2264,7 +1258,7 @@ KiCI provides an explicit secrets API that gives workflow steps controlled acces
 
 ## Overview
 
-Secrets are managed per-context in the orchestrator (see [operator docs](https://docs.kici.dev/operator/orchestrator/configuration) for setup). When a job runs with a `context` binding, the agent receives the secret keys available for that context but does **not** inject their values into the step's process environment. Instead, steps access secrets through the `ctx.secrets` API.
+Secrets are managed per-context in the orchestrator (see [operator docs](https://docs.kici.dev/operator/orchestrator/configuration/) for setup). When a job runs with a `context` binding, the agent receives the secret keys available for that context but does **not** inject their values into the step's process environment. Instead, steps access secrets through the `ctx.secrets` API.
 
 This design prevents accidental secret leakage through child processes, log output, or error messages. Only secrets you explicitly request are loaded into memory.
 
@@ -2285,13 +1279,13 @@ Use whichever fits the workflow — most small teams stay on the dashboard; ops
 
 ### When the operator has disabled dashboard writes
 
-The orchestrator operator can flip `secrets.set` (and `variables.set`) to **CLI-only** as part of the [dashboard-write policy](https://docs.kici.dev/operator/security/dashboard-write-policy). When that flip is on:
+The orchestrator operator can flip `secrets.set` (and `variables.set`) to **CLI-only** as part of the [dashboard-write policy](https://docs.kici.dev/operator/security/dashboard-write-policy/). When that flip is on:
 
 - The dashboard's "Add secret" / "Edit value" controls render with a lock icon. Hovering or keyboard-focusing the lock shows a tooltip with the exact `kici-admin secret set` invocation needed. The control itself is inert, so there is nothing to click.
 - The dashboard's secrets page still lists secret **names**, scopes, and bindings — only the value-entry path moves to the CLI.
 - `kici-admin secret set` becomes the single entry point for new and updated secret values.
 
-This configuration is common for SOC2-prep and regulated workloads, where the customer requirement is "the SaaS control plane process never receives plaintext customer secret values." The dashboard remains usable for everything else (read paths, name CRUD, environment bindings).
+This configuration is common for SOC2-prep and regulated workloads, where the customer requirement is "the SaaS control plane process never receives plaintext customer secret values." The dashboard remains usable for everything else (read paths, name CRUD, context bindings).
 
 ### CLI input modes
 
@@ -2326,7 +1320,7 @@ Two cross-cutting flags help every mode:
 
 `kici-admin variable set` uses the same flags for non-encrypted variables, plus `--locked` to mark a variable as immutable from subsequent dashboard writes.
 
-A full reference of input modes — including the default-mode resolution rules and the security trade-offs of each — lives in [Dashboard-write policy → CLI input modes](https://docs.kici.dev/operator/security/dashboard-write-policy#cli-input-modes-for-the-plaintext-path).
+A full reference of input modes — including the default-mode resolution rules and the security trade-offs of each — lives in [Dashboard-write policy → CLI input modes](https://docs.kici.dev/operator/security/dashboard-write-policy/#cli-input-modes-for-the-plaintext-path).
 
 ## Accessing secrets
 
@@ -2559,8 +1553,10 @@ Note that `get()` is async -- you must `await` the result.
 
 ## Typed secrets
 
-When you run `kici types`, the compiler generates a `.kici/secrets.d.ts` file that provides type-safe autocompletion for your secret keys. The generated types augment the `StepSecrets` interface so that `ctx.secrets.get('...')` and `ctx.secrets.has('...')` offer suggestions for known keys.
+When you run `kici types`, the compiler generates a `.kici/types/secrets.d.ts` file that provides type-safe autocompletion for your secret keys. The generated types augment the `StepSecrets` interface so that `ctx.secrets.get('...')` and `ctx.secrets.has('...')` offer suggestions for known keys.
+
+This file is a local development aid, not source: `kici init` gitignores `.kici/types/`, so each team member generates their own copy with `kici types` rather than committing it. When the Platform is unreachable, `kici types` keeps any existing copy untouched, or writes an empty stub if none exists, so type checking degrades to "no known keys" instead of failing.
 
-See [CLI reference](https://docs.kici.dev/user/cli) for the `kici types` command.
+See [CLI reference](https://docs.kici.dev/user/cli/authoring-and-local/#kici-types) for the `kici types` command.
 
 ---