@kici-dev/compiler 0.1.27 → 0.3.0

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

@@ -101,13 +101,13 @@ When the run reaches this job, it is held instead of dispatched. The held run ap
 job('deploy', {
   runsOn: 'default',
   approval: true,
-  steps: [
-    /* ... */
-  ],
+  steps: [/* ... */],
 });
 ```
 
-`approval: true` holds the element until **any** org member who can act on approvals signs off — anyone with the `contexts:write` or `ci_trust:write` permission. Use it when you want a manual gate without restricting who may release it.
+`approval: true` holds the element until **any** org member who can act on approvals signs off — anyone with `contexts:write`, since an `approval` gate always raises a reviewer hold. Use it when you want a manual gate without restricting who may release it.
+
+A **security** hold is different: it is raised by the CI trust pipeline (an unknown contributor, a fork PR, a workflow-modifying PR), never by `approval`, and releasing one requires `ci_trust:write`. See [Approval gates (operator guide)](https://docs.kici.dev/operator/approvals/#who-may-approve).
 
 ### Approver list (AND)
 
@@ -135,15 +135,17 @@ approval: {
 },
 ```
 
-| Field       | Type                  | Description                                                                                                                                                                 |
-| ----------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `when`      | `'always' \| 'drift'` | When the gate fires. `'always'` (default) gates before the element; `'drift'` gates a check/apply step only when it finds drift. See [Drift gates](https://docs.kici.dev/user/approvals/#drift-gates-whendrift). |
-| `approvers` | `ApproverClause[]`    | The AND list of `{ team }` / `{ user }` clauses. An empty list means "any approval-capable member".                                                                         |
-| `reason`    | `string`              | A human-readable label shown in the dashboard queue and the held-for-approval status check.                                                                                 |
-| `timeout`   | `number`              | Per-gate expiry in **seconds**, overriding the org default. On expiry the element is rejected.                                                                              |
+| Field       | Type                  | Description                                                                                                                                                                                                      |
+| ----------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `when`      | `'always' \| 'drift'` | When the gate fires. `'always'` (default) gates before the element; `'drift'` gates a check/apply step only when it finds drift. See [Drift gates](https://docs.kici.dev/user/approvals/#drift-gates-whendrift).                                      |
+| `approvers` | `ApproverClause[]`    | The AND list of `{ team }` / `{ user }` clauses. An empty list means "any approval-capable member".                                                                                                              |
+| `reason`    | `string`              | A human-readable label shown in the dashboard queue and the held-for-approval status check.                                                                                                                      |
+| `timeout`   | `number`              | Per-gate expiry in **seconds**, overriding the org default. Must be a **positive integer** number of seconds; a non-positive or non-finite value is rejected at compile time. On expiry the element is rejected. |
 
 When `timeout` is omitted, the gate uses the org's default approval expiry (set by the operator). On expiry, the held element is rejected and the run fails — see [expiry](https://docs.kici.dev/operator/approvals/#expiry).
 
+A `timeout` that is zero, negative, or non-finite (for example a computed `minutes * 60` where `minutes` is `0`) fails `kici compile` with a clear author-facing error, so a misconfigured gate can never silently expire the moment it is created. If an orchestrator ever receives such a value from a hand-edited lock file, the run fails fast with an **Approval gate misconfigured** init-failure rather than dispatching ungated.
+
 ## Granularity
 
 The same `approval` field is accepted on a workflow, a job, and a step.
@@ -168,9 +170,7 @@ A job-level gate holds just that job; other jobs in the run proceed normally:
 job('publish', {
   runsOn: 'default',
   approval: [{ team: 'leads' }],
-  steps: [
-    /* ... */
-  ],
+  steps: [/* ... */],
 });
 ```
 
@@ -241,14 +241,14 @@ kici approve <run-id>
 # Approve a held job
 kici approve <run-id> --job deploy-production
 
-# Approve a held step
-kici approve <run-id> --job migrate-and-deploy --step apply-migration
+# Approve a held step (--step takes the step's zero-based index within the job)
+kici approve <run-id> --job migrate-and-deploy --step 1
 
 # Reject (a reason is required)
 kici reject <run-id> --job deploy-production --reason "Wrong release branch"
 ```
 
-You must be eligible for at least one unsatisfied clause — being a member of a named team or being a named user. The orchestrator verifies eligibility against the operator-defined teams, so naming a team in your workflow can never let an ineligible person release the gate. The command reports whether the element was released, how many clauses remain, or that it was rejected. See [`kici approve`](https://docs.kici.dev/user/cli-reference/#kici-approve) for the full command reference.
+You must be eligible for at least one unsatisfied clause — being a member of a named team or being a named user. The orchestrator verifies eligibility against the operator-defined teams, so naming a team in your workflow can never let an ineligible person release the gate. The command reports whether the element was released, how many clauses remain, or that it was rejected. See [`kici approve`](https://docs.kici.dev/user/cli/runs-and-approvals/#kici-approve) for the full command reference.
 
 ### Inline approval and `--approve-all` in `kici run remote`
 
@@ -357,9 +357,7 @@ workflow('deploy', {
     group: (ctx) => `deploy-${ctx.branch}`,
     cancelInProgress: true,
   },
-  jobs: [
-    /* ... */
-  ],
+  jobs: [/* ... */],
 });
 ```
 
@@ -383,9 +381,7 @@ workflow('migrate-db', {
     cancelInProgress: false,
     max: 1,
   },
-  jobs: [
-    /* ... */
-  ],
+  jobs: [/* ... */],
 });
 ```
 
@@ -403,9 +399,7 @@ workflow('test', {
     cancelInProgress: false,
     max: 3,
   },
-  jobs: [
-    /* ... */
-  ],
+  jobs: [/* ... */],
 });
 ```
 
@@ -425,9 +419,7 @@ workflow('deploy', {
     job('deploy-staging', {
       runsOn: 'linux',
       context: 'staging',
-      steps: [
-        /* ... */
-      ],
+      steps: [/* ... */],
     }),
   ],
 });
@@ -442,9 +434,7 @@ workflow('migrate', {
     group: () => 'db-migration',
     cancelInProgress: false,
   },
-  jobs: [
-    /* ... */
-  ],
+  jobs: [/* ... */],
 });
 ```
 
@@ -460,9 +450,7 @@ workflow('deploy', {
     },
     cancelInProgress: true,
   },
-  jobs: [
-    /* ... */
-  ],
+  jobs: [/* ... */],
 });
 ```
 
@@ -486,11 +474,11 @@ In addition to workflow-level concurrency, individual jobs can define their own
 
 ## Local execution
 
-`kici run <event> --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.
+`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 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.
+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.
 
-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 <event> --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.
+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.
 
 ---
 
@@ -645,9 +633,7 @@ job('deploy', {
   concurrencyGroup: 'production-api',
   // Or dynamic:
   // concurrencyGroup: (event) => `review-${event.payload.pull_request.number}`,
-  steps: [
-    /* ... */
-  ],
+  steps: [/* ... */],
 });
 ```
 
@@ -712,7 +698,7 @@ Require manual approval before a job can proceed:
 Required reviewers: alice, bob
 ```
 
-When reviewers are required, the job enters a "held" state. Reviewers can approve or reject via the dashboard, the [`kici approve`](https://docs.kici.dev/user/cli-reference/#kici-approve) command, or the API. Held runs expire after a configurable timeout.
+When reviewers are required, the job enters a "held" state. Reviewers can approve or reject via the dashboard, the [`kici approve`](https://docs.kici.dev/user/cli/runs-and-approvals/#kici-approve) command, or the API. Held runs expire after a configurable timeout.
 
 This operator-set rule is the **mandatory** form of an approval gate. Workflow authors can also declare gates in code with `approval` at step, job, or workflow level — see [Approval gates](https://docs.kici.dev/user/approvals/). Both forms use the same held-element mechanism and the same queue.
 
@@ -753,14 +739,16 @@ See the [CI security architecture docs](https://docs.kici.dev/architecture/secur
 
 ### Security approval queue
 
-When a PR is held for security review (unknown contributor, workflow modification, or trust policy violation), it enters the security approval queue. This is separate from context-level approval queues.
+When a PR is held for security review — the org trust policy held it (a non-trusted contributor modified `.kici/` files, the PR came from a fork, or the contributor could not be resolved to a known identity), or a `minimumTrust` gate blocked the contributor — it enters the security approval queue. This is separate from the context approval queue: a security hold asks "is it safe to run this contributor's code at all?", while a context approval hold asks "should this job be promoted?". The two never cross — releasing a security hold needs `ci_trust:write` or higher, releasing a context approval hold needs `contexts:write` plus eligibility for one of the gate's clauses. See [Approval holds vs security holds](https://docs.kici.dev/architecture/approvals/#approval-holds-vs-security-holds) for the full comparison.
 
 Held runs can be approved:
 
 - Via the **dashboard** in Settings > CI trust > Approval queue
 - Via a PR comment: `/kici approve` (commenter must have `ci_trust:write+`)
 
-Security holds expire after a configurable timeout (default 1 hour).
+A hold raised by the org trust policy covers the whole PR and uses the org's approval expiry (default 72 hours). A `minimumTrust` hold is raised by a context rather than by the org policy, so it uses that context's own hold expiry (default one hour).
+
+While the org trust policy is holding a pull request, your organization's global workflows do not run for it. Approving the hold releases that pull request's own workflows; it does not retroactively run the organization's global workflows for the event.
 
 ### Concurrency limits
 
@@ -771,6 +759,8 @@ Concurrency limit: 1
 Strategy: queue (or cancel-pending)
 ```
 
+The concurrency limit is a positive integer; leave it unset for unlimited concurrency.
+
 - **queue** -- new jobs wait in a FIFO queue (with configurable timeout, default 1 hour)
 - **cancel-pending** -- pending (queued) jobs are cancelled when the limit is reached
 
@@ -793,7 +783,7 @@ Each context has four tabs:
 
 2. **Secrets** -- view bound secret scopes and their resolved secret count. Add bindings by specifying scope glob patterns (e.g., `aws/prod/**`).
 
-3. **Protection** -- configure branch restrictions, required reviewers, wait timers, and concurrency limits with enable toggles for each section.
+3. **Protection** -- configure branch restrictions, required reviewers, wait timers, and concurrency limits with enable toggles for each section. Turning a section's toggle off and saving clears that rule on the context, so the gate stops applying to new runs. Emptying the hold expiry field clears it too, and held runs fall back to the default one-hour hold window.
 
 4. **History** -- view filtered runs targeting this context.
 
@@ -840,16 +830,17 @@ The KiCI dashboard is the browser interface for monitoring workflow runs, inspec
 
 This guide is split across the following pages:
 
-| Page                                                                                  | Covers                                                                  |
-| ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
-| [Getting started](https://docs.kici.dev/user/dashboard/getting-started/)                                     | Onboarding checklist and your organizations list                        |
-| [Navigation and layout](https://docs.kici.dev/user/dashboard/navigation/)                                    | Sidebar, mobile nav, theme, time display, shortcuts, error pages        |
-| [Runs and logs](https://docs.kici.dev/user/dashboard/runs/)                                                  | Run list, run detail, the log viewer                                    |
-| [Settings](https://docs.kici.dev/user/dashboard/settings/)                                                   | Members, roles, teams, keys, sources, billing, security, support access |
-| [Workflows, diagnostics, and orchestrators](https://docs.kici.dev/user/dashboard/workflows-and-diagnostics/) | Registered workflows, infra health, per-cluster views                   |
-| [Contexts, secrets, and approvals](https://docs.kici.dev/user/dashboard/contexts-and-secrets/)               | Contexts, secret scopes, approval queue                                 |
-| [Activity and DLQ](https://docs.kici.dev/user/dashboard/activity-and-dlq/)                                   | Forensic activity log and dead-letter queue                             |
-| [Account](https://docs.kici.dev/user/dashboard/account/)                                                     | Personal account settings                                               |
+| Page                                                                                  | Covers                                                                        |
+| ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| [Getting started](https://docs.kici.dev/user/dashboard/getting-started/)                                     | Onboarding checklist and your organizations list                              |
+| [Navigation and layout](https://docs.kici.dev/user/dashboard/navigation/)                                    | Sidebar, mobile nav, theme, time display, shortcuts, error pages              |
+| [Runs and logs](https://docs.kici.dev/user/dashboard/runs/)                                                  | Run list, run detail, the log viewer                                          |
+| [Settings](https://docs.kici.dev/user/dashboard/settings/)                                                   | Members, roles, teams, keys, sources, billing, security, support access       |
+| [Workflows, diagnostics, and orchestrators](https://docs.kici.dev/user/dashboard/workflows-and-diagnostics/) | Registered workflows, infra health, per-cluster views                         |
+| [Contexts, secrets, and approvals](https://docs.kici.dev/user/dashboard/contexts-and-secrets/)               | Contexts, secret scopes, approval queue                                       |
+| [Activity and DLQ](https://docs.kici.dev/user/dashboard/activity-and-dlq/)                                   | Forensic activity log and dead-letter queue                                   |
+| [Notifications](https://docs.kici.dev/user/dashboard/notifications/)                                         | Personal run notifications and org-wide channels, subscriptions, delivery log |
+| [Account](https://docs.kici.dev/user/dashboard/account/)                                                     | Personal account settings                                                     |
 
 ---
 
@@ -865,9 +856,7 @@ job('deploy', {
   context: (event) => event.targetBranch,
   env: (event) => ({ BRANCH: event.targetBranch }),
   concurrencyGroup: (event) => `deploy-${event.targetBranch}`,
-  steps: [
-    /* ... */
-  ],
+  steps: [/* ... */],
 });
 ```
 
@@ -876,9 +865,7 @@ job('deploy', {
   runsOn: 'default',
   // One shape everywhere: branch on the normalized event type.
   context: (event) => (event.type === 'pull_request' ? 'preview' : 'production'),
-  steps: [
-    /* ... */
-  ],
+  steps: [/* ... */],
 });
 ```
 
@@ -923,7 +910,7 @@ context: (event) => {
 
 ### 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:
+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
@@ -932,6 +919,8 @@ If the compiler determines a function is impure, it emits a warning during compi
 
 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
@@ -965,8 +954,9 @@ env: async (event) => {
 ## 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 tells you when a function is classified as impure and explains why.
+- **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`, …).
 
 ---
@@ -988,10 +978,10 @@ The KiCI CLI reads the following environment variables to customize its behavior
 
 ## 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                                  |
+| 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
 
@@ -1000,6 +990,35 @@ The KiCI CLI reads the following environment variables to customize its behavior
 | `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
@@ -1007,7 +1026,7 @@ The KiCI CLI reads the following environment variables to customize its behavior
 Authenticate with a pre-existing API key (no browser needed):
 
 ```bash
-kici login --token <<< "$KICI_API_KEY"
+kici login --token "$KICI_API_KEY"
 ```
 
 ### Targeting another environment or custom OIDC provider
@@ -1383,11 +1402,11 @@ export const deployComplete = defineEvent(
 );
 ```
 
-Then emit using the definition's name:
+Then emit using the definition — the payload is checked against the schema:
 
 ```typescript
 step('emit', async (ctx) => {
-  await ctx.emit(deployComplete.name, {
+  await ctx.emit(deployComplete, {
     env: 'prod',
     version: '1.2.3',
     services: ['api', 'web'],
@@ -1442,7 +1461,7 @@ If you've only ever used per-repo workflows so far, start with the mental model
 | Workflow repo  | The repo whose `.kici/workflows/*.ts` file **declares** the global workflow. Holds the steps. Also known as the _authoring_ repo.                      |
 | Source repo    | The repo that **emits** the event (push / PR / tag / ...) that causes the global workflow to fire. The agent checks out this repo as the working copy. |
 | Global         | A workflow whose trigger carries one or more `repos:` glob patterns. The presence of `repos:` is what classifies a workflow as global.                 |
-| Authoring axis | Policy that answers "which repos may **author** global workflows?" Controlled by the allow-list in the dashboard's _Workflow authors_ setting.         |
+| Authoring axis | Policy that answers "which repos may **author** global workflows?" Controlled by the allow-list in the dashboard's _Allowed author repos_ setting.     |
 | Source axis    | Policy that answers "which **source** repos' events are allowed to trigger global workflows?" Controlled by the deny-list in _Blocked source repos_.   |
 
 The two axes are independent. A global workflow fires only if it passes **both** — its authoring repo is allowed AND the source repo is not denied.
@@ -1497,7 +1516,7 @@ Global workflows are **opt-in per org**. In a fresh org, `repos:`-bearing workfl
 
 | Setting              | What it controls                                                                                                                                                                                     | Typical use                                                                                  |
 | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| Workflow authors     | Restricts which repos can **author** (register) global workflows. Globs matched against the authoring repo identifier. When OFF, any repo in the org may author globals.                             | Lock authoring to `myorg/ci-*` so random product repos can't ship org-wide automation.       |
+| Allowed author repos | Restricts which repos can **author** (register) global workflows. Globs matched against the authoring repo identifier. When OFF, any repo in the org may author globals.                             | Lock authoring to `myorg/ci-*` so random product repos can't ship org-wide automation.       |
 | Blocked source repos | Blocks dispatch for events emitted from these **source** repos, regardless of authoring. Globs matched against the event source repo identifier. When OFF, events from any repo may trigger globals. | Protect against fork spam — e.g. `!myorg/*` via `myorg/fork-*`.                              |
 | Elevated access      | Authoring repos listed here get **read access to source-repo secrets** during execution. Globs matched against the authoring repo identifier.                                                        | A `myorg/ci-deploy` repo that needs to read a source repo's `NPM_TOKEN` to publish releases. |
 
@@ -1513,7 +1532,7 @@ The page is a two-state editor — changes are local until you click **Save chan
 
 A global workflow fires only if:
 
-1. **The authoring repo is allowed.** If _Workflow authors_ is ON, the workflow's authoring repo must match at least one allow-list glob. If OFF, any repo may author. Enforced at two points:
+1. **The authoring repo is allowed.** If _Allowed author repos_ is ON, the workflow's authoring repo must match at least one allow-list glob. If OFF, any repo may author. Enforced at two points:
    - At registration time (extraction from the lock file — non-matching globals are dropped with a warning).
    - At dispatch time (defense-in-depth — policy changes after registration still take effect).
 2. **The source repo is not denied.** If the event's source repo matches any glob in _Blocked source repos_, the global workflow is skipped. Enforced at dispatch time.
@@ -1615,7 +1634,7 @@ const configureNginx = step('configure-nginx', {
 `summarize` is **required** whenever `check` is declared. `run` and `whenInSync`
 both produce the same output type — one output shape per step, whichever path
 runs. Every other step facet (`cache`, `rules`, `continueOnError`, `timeout`,
-`approval`, `onCancel`, `cleanup`, `outputs`) composes unchanged.
+`retry`, `approval`, `onCancel`, `cleanup`, `outputs`) composes unchanged.
 
 A plain `step()` without `check` keeps its exact current behavior — the check
 facet is fully optional.
@@ -1736,6 +1755,17 @@ The agent never writes the token bytes to your `.kici/.npmrc`. Each registry tok
 
 After the install completes (success or failure), the agent restores the original `.kici/.npmrc` — your committed file is never permanently modified.
 
+### Package managers
+
+The agent detects the package manager from the cloned repo — npm, pnpm, or yarn (classic and berry are both supported) — and applies the auth overlay the detected manager actually reads:
+
+| Detected manager        | Auth file the agent overlays | Notes                                                                                                                                       |
+| ----------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| npm, pnpm, yarn classic | `.kici/.npmrc`               | Auth lines carry `${VAR}` references to the job-scoped token env vars.                                                                      |
+| yarn berry (v2+)        | `.kici/.yarnrc.yml`          | Berry reads `.yarnrc.yml` instead of `.npmrc`, so the overlay uses berry's own registry/scope/auth keys with the same `${VAR}` indirection. |
+
+Either file is restored on cleanup, exactly as described above.
+
 ## Option C — committed `.kici/.npmrc` + `installEnv:`
 
 If you'd rather hand-craft the `.npmrc`, commit it under `.kici/.npmrc` with `${VAR}` placeholders, then list each variable in the workflow's `installEnv:` block using the same qualified syntax as `tokenSecret`.
@@ -1891,8 +1921,8 @@ 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 `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.
+- **Untrusted contributors get no tokens.** When a fork PR is dispatched and the contributor-trust resolution returns anything other than `trusted`, the orchestrator strips both `npmRegistries` and `installEnvSecrets` out of the dispatch. The install runs without auth and fails naturally on the first private dep — fork PRs cannot ever observe a registry token, even if a misconfigured context lacks an explicit [minimum trust](https://docs.kici.dev/user/contexts/#minimum-trust) rule.
+- **Lifecycle scripts disabled.** Whenever a private registry is in scope, the agent runs the install with `--ignore-scripts` (npm, pnpm, and yarn classic alike; yarn berry gets the equivalent `enableScripts: false`). A malicious `preinstall` / `postinstall` hook in committed `package.json` cannot read the synthesized token env vars, even though they exist in the install subprocess. For a pnpm or yarn workspace, the agent builds your in-repo dependency closure as a separate step **after** the install's auth is torn down, so build scripts never see the tokens either.
 - **Stderr is redacted.** If the install fails, the agent masks every token literal out of the surfaced stderr / stdout chunks before logging.
 - **Job-scoped env-var names.** The synthesized auth env var is `KICI_NPM_TOKEN_<jobIdShort>_<i>` where `jobIdShort` is the first 8 chars of the dispatched job id. The name is unguessable from outside the install subprocess and not reused across jobs.
 - **`.npmrc` restored.** Whatever the agent appended for one install is stripped (or the file unlinked) on cleanup, so the workspace is never permanently modified.
@@ -1956,13 +1986,20 @@ An attestation is a self-contained bundle holding three things:
   commit, ref, workflow, run/job identifiers, timestamps).
 - A **[DSSE](https://github.com/secure-systems-lab/dsse) signature** over that
   statement, made with an ephemeral signing key generated for the run.
-- A short-lived **OIDC identity token** issued by the KiCI platform that binds
-  the signature to the build identity. The token's identity claims
-  (`repository`, `ref`, `sha`, run/job ids) are derived by the platform from the
-  run itself — a step cannot forge them.
+- A short-lived **OIDC identity token** issued by your **orchestrator** that
+  binds the signature to the build identity. The token's identity claims
+  (`repository`, `ref`, `sha`, run/job ids) are derived by the orchestrator from
+  the run itself — a step cannot forge them.
+
+The orchestrator owns the provenance root of trust: it holds its own long-lived
+ES256 signing key, mints and signs the identity token **locally** from its own
+run records, and publishes its own OIDC discovery + public key set (JWKS). Builds
+therefore produce verifiable provenance with **no dependency on the hosted KiCI
+platform** — the availability, sovereignty, and air-gap story all follow from
+this.
 
 Because the bundle carries the identity token and the public signing key, it is
-**offline-verifiable**: a verifier checks it against the platform's published
+**offline-verifiable**: a verifier checks it against the orchestrator's published
 signing keys with no per-attestation online lookup.
 
 ## Attesting an artifact in a workflow
@@ -2011,8 +2048,11 @@ The identity token is fetched and masked in logs automatically — you never
 handle it. The call returns `{ storageKey, subjectDigest, bundleMediaType }`
 identifying the stored bundle.
 
-`ctx.attestProvenance` is only available inside a running job step. Calling it
-during local execution rejects with a clear error.
+`ctx.attestProvenance` is only available inside a running job step; calling it
+outside one rejects with a clear error. `kici run --local` runs are supported:
+the offline local dev plane signs with a dev identity under the
+clearly-non-production issuer `kici-local`, and those bundles verify against a
+trust root exported with `kici local trust-root`.
 
 ### Requesting a raw identity token
 
@@ -2029,11 +2069,11 @@ step('mint', async (ctx) => {
 
 The token is a short-lived (about 10 minutes) signed JWT scoped to the current
 run and job. Its identity claims (`repository`, `ref`, `sha`, `kici_run_id`,
-`kici_job_id`) are derived by the platform from the run context, so a step cannot
-spoof them. The returned token value is automatically masked in step logs, and
-the step never holds platform credentials — the request is relayed through the
-orchestrator, which mints the token on the step's behalf. Like
-`attestProvenance`, it is only available inside a running job step.
+`kici_job_id`) are derived by the orchestrator from the run context, so a step
+cannot spoof them. The returned token value is automatically masked in step logs,
+and the step never holds signing credentials — the orchestrator mints and signs
+the token on the step's behalf from its own run records. Like `attestProvenance`,
+it is only available inside a running job step.
 
 ## Verifying an attestation
 
@@ -2049,14 +2089,27 @@ kici verify-attestation [artifact] --bundle <path-or-url> [--trust-root <url-or-
 
 ### Which trust root do I use?
 
-The trust root is the **KiCI platform's provenance issuer** — the same hosted
-KiCI platform you `kici login` against. KiCI attestations are issued by, and
-verified against, that one issuer; there are no competing "roots" to choose
-between. So the answer to "shouldn't I just use KiCI as the trust root?" is yes
-— and that's the **default**: omit `--trust-root` and the verifier checks the
-bundle against the hosted KiCI platform automatically. You only pass
-`--trust-root` to verify against a different environment or, more commonly, an
-offline `{ issuer, jwks }` file for air-gapped checks.
+The trust root is **your orchestrator's provenance issuer** — the orchestrator
+you `kici login` against, which owns the provenance signing key and publishes its
+own JWKS. That is the **default**: omit `--trust-root` and the verifier checks the
+bundle against your configured orchestrator automatically. There are three ways to
+verify, and offline is always the primary one:
+
+1. **Offline against a JWKS / trust-root file (air-gap)** — export the
+   `{ issuer, jwks }` file once with `kici-admin signing-key export --public` and
+   verify against it with `--trust-root <file>`. No network needed at verify time.
+2. **Directly online against your orchestrator** — the default: the verifier
+   resolves your orchestrator's discovery → JWKS. You can also POST a bundle to
+   the orchestrator's native `POST /v1/verify-attestation` endpoint for a verdict
+   against its live keys (fresh rotations / revocations included).
+3. **Against the hosted KiCI platform** — bundles produced before your
+   orchestrator owned signing were signed by the hosted platform; those keep
+   verifying forever. When no orchestrator is configured, the default falls back
+   to the hosted platform's issuer so those historical bundles still verify with
+   no flag.
+
+You pass `--trust-root` to verify against a different environment or, most
+commonly, an offline `{ issuer, jwks }` file for air-gapped checks.
 
 ### Why you supply it out-of-band
 
@@ -2099,7 +2152,7 @@ when it does not (or on an error such as a missing flag or unreachable trust
 root).
 
 ```bash
-# Default: verify against the hosted KiCI platform (no --trust-root needed):
+# Default: verify against your configured orchestrator (no --trust-root needed):
 kici verify-attestation ./dist/app.tgz --bundle ./app.tgz.kici.json
 
 # Override the trust root to verify against a specific issuer:
@@ -2113,7 +2166,7 @@ kici verify-attestation ./dist/app.tgz \
   --trust-root ./kici-trust-root.json
 ```
 
-The full flag reference is in the [CLI reference](https://docs.kici.dev/user/cli-reference/#kici-verify-attestation).
+The full flag reference is in the [CLI reference](https://docs.kici.dev/user/cli/notifications-and-diagnostics/#kici-verify-attestation).
 
 ## Viewing attestations in the dashboard
 
@@ -2155,6 +2208,7 @@ The **Attestations** page lists every build-provenance attestation your organiza
 - **Search** by artifact digest (exact `sha256:…`) or name to trace a specific artifact.
 - **Filter** by verification status, repository, workflow, job, or date.
 - Each row's **status badge** is the verdict KiCI recorded when the attestation was produced (`verified`, `failed`, `unverifiable`, or `pending`).
+- **Retry** on a `pending` row asks your orchestrator to mint that run's outstanding attestations now; **Retry pending** does the same for every pending run at once.
 
 Open a row for the parsed provenance statement and a live re-verification.
 
@@ -2168,6 +2222,19 @@ the bundle did not pass; `unverifiable` means no verdict could be computed (no
 provenance issuer configured, or its keys could not be read — not a forgery
 signal); `pending` means the verdict has not been computed yet.
 
+A `pending` row is one still waiting to be minted — the attestation was signed
+at build time, but attaching its identity token has not completed yet. Those
+rows carry a **Retry** button that asks your orchestrator to mint that run's
+outstanding attestations immediately, and the page header offers **Retry
+pending** to do the same across every pending run. Only one retry runs at a
+time — the other retry buttons are unavailable until it finishes.
+
+Retrying is safe to repeat while the mint is only temporarily unavailable: the
+row stays pending and the next retry tries again. A mint that is definitively
+rejected — for example the run's records are no longer there to bind the
+attestation to — is terminal: the row stops being retried, and re-arming it is
+an operator action (`kici-admin attestations retry --include-rejected`).
+
 Opening a row leads to the **attestation detail page**:
 
 <!-- help:attestation-detail#browsing-attestations-across-runs -->
@@ -2177,13 +2244,14 @@ This page shows the parsed provenance for one attestation.
 - **Builder identity, source, and build type** come from the signed SLSA statement.
 - The **stored badge** is the verdict recorded at build time; **Re-verify** runs the check live in your browser against the current signing keys.
 - **Download** exports the signed bundle for offline verification with `kici verify-attestation`.
+
 <!-- /help:attestation-detail -->
 
 ## See also
 
 - [SDK runtime reference](https://docs.kici.dev/user/sdk/runtime/) — the `ctx.attestProvenance` and
   `ctx.kici.oidc.token` step APIs in full.
-- [CLI reference](https://docs.kici.dev/user/cli-reference/#kici-verify-attestation) — every
+- [CLI reference](https://docs.kici.dev/user/cli/notifications-and-diagnostics/#kici-verify-attestation) — every
   `kici verify-attestation` flag and exit code.
 
 ---
@@ -2211,7 +2279,7 @@ Secret values are written either through the dashboard or through `kici-admin` r
 A fresh orchestrator starts in **permissive** mode: both surfaces are available.
 
 - **Dashboard:** Settings → Secrets → pick a scope → enter the secret name and value.
-- **CLI:** `kici-admin secret set --scope <scope> <KEY>` against the orchestrator's HTTP admin API.
+- **CLI:** `kici-admin secret set <orgId> <scope> <KEY>` against the orchestrator's HTTP admin API.
 
 Use whichever fits the workflow — most small teams stay on the dashboard; ops engineers and CI scripts use the CLI.
 
@@ -2219,7 +2287,7 @@ Use whichever fits the workflow — most small teams stay on the dashboard; ops
 
 The orchestrator operator can flip `secrets.set` (and `variables.set`) to **CLI-only** as part of the [dashboard-write policy](https://docs.kici.dev/operator/security/dashboard-write-policy). When that flip is on:
 
-- The dashboard's "Add secret" / "Edit value" controls render with a lock icon. Clicking them shows a tooltip with the exact `kici-admin secret set` invocation needed.
+- The dashboard's "Add secret" / "Edit value" controls render with a lock icon. Hovering or keyboard-focusing the lock shows a tooltip with the exact `kici-admin secret set` invocation needed. The control itself is inert, so there is nothing to click.
 - The dashboard's secrets page still lists secret **names**, scopes, and bindings — only the value-entry path moves to the CLI.
 - `kici-admin secret set` becomes the single entry point for new and updated secret values.
 
@@ -2227,26 +2295,30 @@ This configuration is common for SOC2-prep and regulated workloads, where the cu
 
 ### CLI input modes
 
-`kici-admin secret set` accepts five input modes — pick the one that fits your workflow:
+`kici-admin secret set` takes the target as three positional arguments — `<orgId> <scope> <key>` — and accepts five input modes; pick the one that fits your workflow:
 
 ```bash
 # Interactive prompt (default when stdin is a TTY). No echo, no shell history.
-kici-admin secret set --scope production DB_PASSWORD --prompt
+kici-admin secret set my-org production DB_PASSWORD --prompt
 
 # Pipe from another tool (default when stdin is not a TTY).
-pass show prod/db | kici-admin secret set --scope production DB_PASSWORD --from-stdin
+pass show prod/db | kici-admin secret set my-org production DB_PASSWORD --from-stdin
 
 # Read from a file (handy after `sops -d` to a tmpfile).
-kici-admin secret set --scope production DB_PASSWORD --from-file ./db.pass
+kici-admin secret set my-org production DB_PASSWORD --from-file ./db.pass
 
 # Read from a named environment variable (CI-friendly).
 KICI_SECRET_VALUE=$(my-secrets-fetcher prod db) \
-  kici-admin secret set --scope production DB_PASSWORD --from-env KICI_SECRET_VALUE
+  kici-admin secret set my-org production DB_PASSWORD --from-env KICI_SECRET_VALUE
 
 # Direct argv — discouraged. Prints a stderr warning ("visible in shell history").
-kici-admin secret set --scope production DB_PASSWORD --value "<plaintext>"
+kici-admin secret set my-org production DB_PASSWORD --value "<plaintext>"
 ```
 
+When the scope is a deployment context, a flag-based sugar form is also accepted:
+`kici-admin secret set --org my-org --context production --key DB_PASSWORD --prompt`.
+The two forms are mutually exclusive — mixing them is refused.
+
 Two cross-cutting flags help every mode:
 
 - `--confirm-fingerprint <hex>` — pre-compute SHA-256 of the value and pass it. The CLI rejects the call if the value's fingerprint doesn't match. Catches paste corruption.