@kici-dev/compiler 0.1.23 → 0.1.24

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

@@ -26,7 +26,7 @@ Why the lock file must stay in sync with workflow source, how to commit both tog
 
 ### [CLI reference](https://docs.kici.dev/user/cli-reference/)
 
-All CLI commands provided by `@kici-dev/compiler`: `kici compile` (with watch mode and check mode), `kici run` (local and remote execution), `kici test` (event simulation with dry-run, filtering, debug output, and custom payloads), `kici login`/`logout`/`org` (authentication and org management), `kici diagnostics` (infrastructure tree) and `kici runs` (`list`/`show`/`logs`/`rerun`/`cancel` — run management), `kici secrets` (secret listing), `kici types` (type generation), `kici fixture` (generate test payloads), `kici init` (interactive project scaffolding), `kici hook` (pre-commit hook installation), `kici endpoints` (webhook entrypoints), and `kici workflows` (workflow listing). Includes environment variables and exit codes.
+All CLI commands provided by `@kici-dev/compiler`: `kici compile` (with watch mode and check mode), `kici run` (local and remote execution), `kici preview` (event simulation with dry-run, filtering, debug output, and custom payloads), `kici login`/`logout`/`org` (authentication and org management), `kici diagnostics` (infrastructure tree) and `kici runs` (`list`/`show`/`logs`/`rerun`/`cancel` — run management), `kici secrets` (secret listing), `kici types` (type generation), `kici fixture` (generate test payloads), `kici init` (interactive project scaffolding), `kici hook` (pre-commit hook installation), `kici endpoints` (webhook entrypoints), and `kici workflows` (workflow listing). Includes environment variables and exit codes.
 
 ### [Workflow patterns](https://docs.kici.dev/user/workflow-patterns/)
 
@@ -249,10 +249,10 @@ The lock file (`kici.lock.json`) is a JSON representation of your workflow that
 
 ## Preview trigger matching
 
-Use `kici test` to preview which workflows match a trigger event (dry-run, no execution):
+Use `kici preview` to preview which workflows match a trigger event (dry-run, no execution):
 
 ```bash
-npx kici test pr:open
+npx kici preview pr:open
 ```
 
 Expected output (simplified):
@@ -418,14 +418,14 @@ Or add the flag to your root `package.json`:
 
 ## Authoring KiCI workflows with LLM coding agents
 
-KiCI is LLM-ready by design. Because workflows are real, typed TypeScript, coding agents reason over the SDK's `.d.ts` signatures instead of guessing a bespoke YAML DSL — and they verify their own pipelines with the same `kici test` and `kici run local` loop you use, so there's no push-to-find-out round-trip. First-class agent context ships in the box, so an agent is briefed the moment it opens the project.
+KiCI is LLM-ready by design. Because workflows are real, typed TypeScript, coding agents reason over the SDK's `.d.ts` signatures instead of guessing a bespoke YAML DSL — and they verify their own pipelines with the same `kici preview` and `kici run local` loop you use, so there's no push-to-find-out round-trip. First-class agent context ships in the box, so an agent is briefed the moment it opens the project.
 
 KiCI ships first-class context for LLM coding agents (Claude Code, Cursor, Aider, etc.). When you scaffold a project with `kici init`, the CLI writes `.kici/AGENTS.md`, a one-page briefing that tells the agent:
 
 - where the SDK type declarations live (`node_modules/@kici-dev/sdk/dist/index.d.ts`)
 - the five canonical authoring patterns with runnable examples
 - the anti-patterns that catch agents off-guard (no YAML, no `/dist/...` imports, no top-level `await`)
-- the local commands the agent should drive (`kici compile --check`, `kici test`, `kici run local`, `kici docs llm`)
+- the local commands the agent should drive (`kici compile --check`, `kici preview`, `kici run local`, `kici docs llm`)
 
 If you don't want the file, pass `--no-agents-md` to `kici init`, or delete the file afterwards — KiCI never reads it at runtime.
 
@@ -516,7 +516,7 @@ If you're not sure, pick Docker / Podman.
 
 ## Looking for the laptop-only path?
 
-Both quickstarts deploy a real orchestrator + agent. If you only want to write a workflow and dry-run it on your laptop with no infrastructure, [Getting started](https://docs.kici.dev/user/getting-started/) covers `kici test` and `kici run local` instead.
+Both quickstarts deploy a real orchestrator + agent. If you only want to write a workflow and dry-run it on your laptop with no infrastructure, [Getting started](https://docs.kici.dev/user/getting-started/) covers `kici preview` and `kici run local` instead.
 
 ---
 
@@ -2650,7 +2650,7 @@ const deploy = job('deploy', {
 
 **Important:** `needs` must be declared explicitly. Output chaining does not auto-infer dependencies -- you must list job dependencies in `needs` even if you access their outputs via `.result`.
 
-Cross-job output chaining works in both local test mode (`kici test`) and remote pipeline execution. The orchestrator's needs-aware dispatch scheduler guarantees upstream jobs reach a terminal state before downstream jobs dispatch, and upstream outputs are transported to the downstream agent sandbox via the `upstreamJobOutputs` field on `job.dispatch`. See [needs-scheduler](https://docs.kici.dev/architecture/execution/needs-scheduler/) for the full dispatch semantics.
+Cross-job output chaining works in both local execution (`kici run local`) and remote pipeline execution. The orchestrator's needs-aware dispatch scheduler guarantees upstream jobs reach a terminal state before downstream jobs dispatch, and upstream outputs are transported to the downstream agent sandbox via the `upstreamJobOutputs` field on `job.dispatch`. See [needs-scheduler](https://docs.kici.dev/architecture/execution/needs-scheduler/) for the full dispatch semantics.
 
 ### Job dependencies (`needs`)
 
@@ -3316,6 +3316,88 @@ The caller never has to branch on outcome — `result.result` is always a `Bucke
 
 ---
 
+## SDK reference: parallel
+
+Source: https://docs.kici.dev/user/sdk/parallel/
+
+`parallel([...steps], opts?)` runs a group of independent steps **concurrently**
+within one job, behind a join barrier: execution continues past the group only
+once every child has settled. Each child is its own observable step — it gets its
+own logs, status, timing, and retry — instead of being hidden inside one step's
+`Promise.all`.
+
+```ts
+import { workflow, job, step, parallel, push } from '@kici-dev/sdk';
+
+export default workflow('ci', {
+  on: push(),
+  jobs: [
+    job('checks', {
+      runsOn: 'kici:os:linux',
+      steps: [
+        checkout,
+        // lint, typecheck, and the unit tests have no ordering between them,
+        // so they run together — the job's wall-clock is the slowest child,
+        // not the sum of all three.
+        parallel([lint, typecheck, unitTests], { failFast: true }),
+        deploy,
+      ],
+    }),
+  ],
+});
+```
+
+`parallel(...)` returns a `ParallelGroup` that sits in the ordinary flat
+`steps: [...]` array — there is no new `job` field. A group's children are
+**sequential steps only**; groups cannot be nested.
+
+## Options
+
+`parallel(steps, opts?)` accepts:
+
+- **`failFast?: boolean`** — default `true`. When a child fails, the in-flight
+  siblings are cancelled immediately and the job fails. With `failFast: false`
+  every child runs to completion first, then the job fails if any child failed.
+- **`maxParallel?: number`** — default unlimited. Caps how many children run at
+  once; children waiting for a slot report a `pending` status until they launch.
+- **`name?: string`** — a label for the group's dashboard band.
+
+A child marked `continueOnError: true` never trips fail-fast and never fails the
+job — it still shows a `failed` status badge, but the group treats it as
+non-fatal.
+
+## Statuses
+
+Parallel steps introduce two step statuses:
+
+- **`pending`** — a child queued behind `maxParallel`, not yet launched.
+- **`cancelled`** — a sibling aborted by fail-fast. A cancelled step is **not** a
+  failure: only the child that actually failed fails the job; the cancelled
+  siblings render in gray (distinct from the red failing step) on the dashboard.
+
+Children may also complete **out of order** — the fastest child finishes first
+regardless of array position. A later sequential step can read a parallel child's
+`.result` after the barrier; children within a group cannot read each other's
+results (there is no ordering inside the group).
+
+## Scope: nests inside job-level fan-out
+
+`parallel()`'s `failFast` / `maxParallel` are **step-group** scopes — they govern
+only the steps inside the group. They are a different layer from the **job-level**
+`failFast` / `maxParallel` on a matrix / `runsOnAll` fan-out, which govern how a
+job's child _jobs_ spread across the matrix or host roster. A `parallel()` group
+inside a fan-out job nests its concurrency inside each fan-out child.
+
+## Local vs remote execution
+
+Run remotely (the orchestrator + agent), parallel children execute concurrently
+and each surfaces as its own dashboard step. `kici run local` executes the same
+children in array order in its single-process model — the results are identical,
+only the wall-clock and the live fail-fast cancellation differ. Use a remote run
+to observe the concurrent timeline.
+
+---
+
 ## SDK reference: rules, matrix, dynamic jobs
 
 Source: https://docs.kici.dev/user/sdk/rules-matrix-dynamic/
@@ -4214,7 +4296,7 @@ interface StepContext<TInputs = Record<string, unknown>> {
   rawPayload?: Record<string, unknown>;
   /** Which git provider triggered this workflow (e.g. 'github', 'gitlab') */
   provider?: string;
-  /** Whether this execution was triggered by `kici test` (remote test run) */
+  /** Whether this execution was triggered by `kici run remote` (developer-initiated remote run) */
   isTestRun: boolean;
   /** The resolved deployment environment name for this job (undefined without environment) */
   environment?: string;
@@ -4611,7 +4693,7 @@ Tools that require a file path on disk (sops `SOPS_AGE_KEY_FILE`, kubectl `KUBEC
 
 ### Local test mode secrets
 
-When running `kici test`, you can provide secrets locally without an orchestrator.
+When running `kici preview`, you can provide secrets locally without an orchestrator.
 
 #### .kici/.secrets file
 
@@ -4639,10 +4721,10 @@ Override or supplement file-based secrets with CLI flags:
 
 ```bash
 # Inject flat secrets (repeatable)
-kici test push --secret DEPLOY_TOKEN=my-token --secret API_KEY=my-key
+kici preview push --secret DEPLOY_TOKEN=my-token --secret API_KEY=my-key
 
 # Inject context-scoped secrets (repeatable)
-kici test push --context production.DB_PASSWORD=prod-secret --context npm-publish.NPM_TOKEN=abc123
+kici preview push --context production.DB_PASSWORD=prod-secret --context npm-publish.NPM_TOKEN=abc123
 ```
 
 **Precedence:** CLI flags override `.kici/.secrets` file values. Context secrets are auto-flattened into `ctx.secrets` using the same merge logic as production (last context wins).
@@ -5197,6 +5279,7 @@ interface ScheduleConfigInput {
   cron: string; // Required: cron expression (5-field)
   timezone?: string; // Timezone for cron evaluation (default: 'UTC')
   description?: string; // Human-readable description of the schedule
+  inputs?: DispatchInputsMap; // Optional: defaults-only typed inputs (see below)
 }
 ```
 
@@ -5207,6 +5290,41 @@ schedule({ cron: '0 9 * * 1', timezone: 'America/New_York' }); // Monday 9am ET
 schedule({ cron: '*/15 * * * *', description: 'health check every 15 min' });
 ```
 
+#### Schedule inputs (defaults-only)
+
+A `schedule()` trigger may declare typed `inputs`. A cron or dashboard
+"run now" fire carries **no operator-supplied values**, so each input resolves
+from its declared **default** and is exposed to steps and rules as
+`ctx.dispatchInputs` — the same surface as [typed dispatch inputs](https://docs.kici.dev/user/sdk/triggers/#typed-dispatch-inputs).
+
+Because there is no operator to supply a value, every schedule input must
+declare a `.default()` **or** be `.optional()`. An input that is neither is
+rejected at `kici compile` time.
+
+```typescript
+import { workflow, job, schedule, z } from '@kici-dev/sdk';
+
+export default workflow('nightly', {
+  on: schedule({
+    cron: '0 3 * * *',
+    inputs: { mode: z.enum(['full', 'quick']).default('full') },
+  }),
+  jobs: [
+    job('build', {
+      runsOn: 'default',
+      run: async (ctx) => {
+        ctx.log(`mode = ${ctx.dispatchInputs.mode}`); // "full" on every fire
+      },
+    }),
+  ],
+});
+```
+
+You can also share a typed handle via `defineDispatchInputs(...)` and read it
+back with `.from(ctx)`, exactly as with `dispatch()`. The allowed input types
+are the same closed subset documented under
+[typed dispatch inputs](https://docs.kici.dev/user/sdk/triggers/#typed-dispatch-inputs).
+
 ### lifecycle()
 
 Create a lifecycle trigger for cross-workflow orchestration events. Returns a frozen `LifecycleTriggerConfig`.
@@ -5535,7 +5653,7 @@ If `check()` throws while polling, the error is logged and polling continues —
 
 Source: https://docs.kici.dev/user/sdk-reference/
 
-Reference documentation for `@kici-dev/sdk`. The reference is split across five pages by topic.
+Reference documentation for `@kici-dev/sdk`. The reference is split across the per-topic pages below.
 
 | Page                                                         | Covers                                                                                                                                                                                                                      |
 | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -5547,6 +5665,7 @@ Reference documentation for `@kici-dev/sdk`. The reference is split across five
 | [Runtime](https://docs.kici.dev/user/sdk/runtime/)                                  | Types index, `StepContext`, secrets, and fixtures.                                                                                                                                                                          |
 | [Idempotent helpers](https://docs.kici.dev/user/sdk/idempotent/)                    | `idempotent()`, `idempotentStep()`, and the check-mode-aware `checkStep()` — check / apply pattern with typed results on both the skipped and applied branches.                                                             |
 | [Wait-for helpers](https://docs.kici.dev/user/sdk/wait-for/)                        | `waitFor()` and `waitForStep()` — poll a condition on an interval, run an optional success action, recover gracefully on timeout.                                                                                           |
+| [Parallel steps](https://docs.kici.dev/user/sdk/parallel/)                          | `parallel()` — run independent steps concurrently within one job behind a join barrier, each as its own observable step, with `failFast` and `maxParallel` controls.                                                        |
 
 The `@kici-dev/sdk` package re-exports the entire surface from a single entry point. Pick what you need:
 
@@ -5569,6 +5688,99 @@ For the complete list of every named export (factory functions, triggers, rules,
 
 # CLI and authoring
 
+## Drive KiCI from your coding agent
+
+Source: https://docs.kici.dev/user/ai-agents/
+
+KiCI ships a hosted **MCP server** so a coding agent (Claude Code, or any MCP
+client) can drive your CI directly: trigger runs, read a structured result,
+fetch the failing step's logs, cancel, and re-run — all under your own identity,
+org-scoped, and audited. There are no per-tool tokens to configure: point the
+agent at one URL with one credential and it's done.
+
+The MCP exposes only what you can already do yourself through the `kici` CLI and
+the dashboard. It is not a new privileged surface — every tool maps to an
+existing user-facing operation and is gated by the same permissions your role
+grants.
+
+## 1. Mint an agent token
+
+The MCP accepts **only** an agent-kind personal access token (PAT). Mint one with
+the `kici` CLI (log in first with `kici login`):
+
+```bash
+kici pat create --agent --name "claude-code"
+```
+
+The `--name` value is the **agent label**. It is recorded on every action the
+agent takes, so your audit log shows exactly which agent did what (and on whose
+behalf). The token is printed once — save it now; it cannot be retrieved later.
+
+An agent PAT inherits your permissions unchanged — it carries provenance, not
+extra authority. Powerful operator capabilities (secret rotation, agent and peer
+management, draining) are intentionally **not** exposed here.
+
+## 2. Point your coding agent at the MCP server
+
+Configure your MCP client with the KiCI MCP endpoint and the agent PAT as a
+Bearer credential. The endpoint is the hosted Platform URL plus `/api/v1/mcp`.
+
+For Claude Code, add a remote MCP server whose URL is your KiCI Platform's
+`/api/v1/mcp` and whose `Authorization` header is `Bearer <your-agent-pat>`.
+
+That's the entire setup. The agent can now call the tools below.
+
+## 3. What the agent can do
+
+**Read**
+
+- `list_runs` — recent runs in your organization.
+- `get_run` — the structured, provenance-tagged result of a run: the typed job
+  graph, per-step statuses and exit codes, durations, and a derived failure
+  category.
+- `get_step_logs` — the log lines for a specific step.
+- `list_workflows` — your registered workflows.
+
+**Drive**
+
+- `trigger_run` — run a registered workflow ("run now").
+- `rerun_run` — re-run a completed run.
+- `cancel_run` — cancel an in-progress run.
+
+If you belong to a single organization, the org is resolved automatically. If
+you belong to several, pass an `orgId` argument to any tool.
+
+## 4. Why the structured result is agent-safe
+
+`get_run` and `get_step_logs` return a machine-first shape designed for an agent
+to reason over without being misled by repository content. Every field that
+comes from your repo, a contributor, or a process's output — workflow and job
+names, refs, error messages, log lines, job outputs — is wrapped in an
+`{ untrusted: true, value: … }` envelope. KiCI-generated values (ids, statuses,
+exit codes, durations, the derived failure category) are left plain. An agent can
+keep user-controlled content out of its instruction channel by refusing to act
+on anything tagged `untrusted`.
+
+Secret values are never returned — only the names of the secret keys a step
+accessed.
+
+## 5. The audit guarantee
+
+Because the MCP accepts only an agent-kind PAT, **every action that flows through
+it is agent-attributed by construction** — there is no path that produces an
+untagged, human-looking action. Each read and each drive operation is recorded in
+your orchestrator's access log under your identity plus the agent label, so you
+always have a complete trail of what your agent did.
+
+Inspect that trail with `kici-admin access-log list --json` (or
+`kici-admin access-log show <id>` for one entry). An agent-attributed row keeps
+`actor_type` as `user` and `actor_id` as your own identity — the agent provenance
+rides in the row's actor metadata as `agentLabel` (the `--name` you minted the
+PAT with) and `agentPatId` (the token that acted). The label is also stored in a
+dedicated `agent_label` column on every such row.
+
+---
+
 ## CLI authentication
 
 Source: https://docs.kici.dev/user/cli-auth/
@@ -5851,7 +6063,7 @@ Run commands with `npx kici` or add scripts to your `package.json`:
 {
   "scripts": {
     "kici:compile": "kici compile",
-    "kici:test": "kici test"
+    "kici:preview": "kici preview"
   }
 }
 ```
@@ -5946,6 +6158,8 @@ kici run local [event] [options]
 | `--kici-dir <path>`   | `.kici`   | Path to .kici directory                                                                                                                                                                                                                |
 | `--in-place`          | `false`   | Run against the real working directory instead of an isolated tmp checkout (see "Execution isolation" below)                                                                                                                           |
 | `--keep`              | `false`   | Always retain the isolated tmp checkout (default: keep only on failure)                                                                                                                                                                |
+| `--check`             | `false`   | Run in [check mode](https://docs.kici.dev/user/idempotent-steps/): each step reports drift instead of applying; the run still exits 0                                                                                                                           |
+| `--fail-on-drift`     | `false`   | In check mode, exit non-zero if any step reports drift (no effect without `--check`)                                                                                                                                                   |
 
 **Interactive workflow selection (`--pick` / `-p`):**
 
@@ -6087,6 +6301,10 @@ kici run remote [fixture] [options]
 | `--target-allow-empty`      | `false` | A `--target` that narrows a `runsOnAll` job to zero hosts skips it instead of failing                                                                                                                                                      |
 | `--debug`                   | `false` | Verbose internals                                                                                                                                                                                                                          |
 | `--kici-dir <path>`         | `.kici` | Path to .kici directory                                                                                                                                                                                                                    |
+| `--routing-key <key>`       | none    | Override the routing key for this run (advanced; selecting the org normally suffices — see [How the run is routed](https://docs.kici.dev/user/cli-reference/#how-the-run-is-routed))                                                                                                |
+| `--check`                   | `false` | Run in [check mode](https://docs.kici.dev/user/idempotent-steps/): each step reports drift instead of applying                                                                                                                                                      |
+| `--fail-on-drift`           | `false` | In check mode, fail the run if any step reports drift (no effect without `--check`)                                                                                                                                                        |
+| `--approve-all, --yes`      | `false` | Auto-approve every [approval gate](https://docs.kici.dev/user/approvals/) this run holds on (run-scoped; eligibility still enforced)                                                                                                                                |
 
 **Examples:**
 
@@ -6252,12 +6470,12 @@ kici orchestrators use us-east
 kici orchestrators use us-east --org xyz789ghi012
 ```
 
-### kici test
+### kici preview
 
 Preview which workflows match a trigger event (dry-run, no execution). Useful for verifying trigger configurations during development.
 
 ```bash
-kici test [event] [options]
+kici preview [event] [options]
 ```
 
 **Arguments:**
@@ -6284,19 +6502,19 @@ kici test [event] [options]
 
 ```bash
 # Preview which workflows match a push event
-kici test push
+kici preview push
 
 # Preview PR trigger matching
-kici test pr:open
+kici preview pr:open
 
 # Preview with branch override
-kici test push --branch develop
+kici preview push --branch develop
 
 # Filter to specific workflow
-kici test push --workflow ci
+kici preview push --workflow ci
 
 # Simulate changed files for path-filtered triggers
-kici test push --files src/index.ts --files README.md
+kici preview push --files src/index.ts --files README.md
 ```
 
 **Exit codes:**
@@ -6306,7 +6524,7 @@ kici test push --files src/index.ts --files README.md
 | 0    | Preview completed (including zero matches) |
 | 1    | Error                                      |
 
-**Migration from old `kici test <fixture>`:** If you were using `kici test <fixture-name>` for remote fixture execution, use `kici run remote <fixture-name>` instead. For local workflow execution, use `kici run local <event>`.
+**Migration from the old `test` command:** The dry-run preview command was renamed from `test` to `preview`. If you were using the old `test` command with a fixture name for remote fixture execution, use `kici run remote <fixture-name>` instead. For local workflow execution, use `kici run local <event>`.
 
 ### kici login
 
@@ -6683,6 +6901,27 @@ Only key names are shown — secret values are never returned over this endpoint
 
 **Prerequisites:** authenticate via `kici login` and select an active organization with `kici org use <name>`.
 
+### kici pat create
+
+Mint a personal access token under your own identity. Pass `--agent` to mint an
+**agent-kind** PAT — the credential a coding agent points the KiCI MCP server at.
+
+```bash
+kici pat create --agent --name "claude-code"
+```
+
+- `--agent` marks the token as agent-kind. An agent PAT inherits your
+  permissions unchanged (it carries provenance, not extra authority) and is the
+  **only** credential the MCP server accepts.
+- `--name <label>` sets the token name. For an agent PAT this is the **agent
+  label** recorded on every action the agent takes — required with `--agent`.
+- `--expires-in-days <n>` overrides the default expiry.
+
+The token is printed once — save it immediately; it cannot be retrieved later.
+See [Drive KiCI from your coding agent](https://docs.kici.dev/user/ai-agents/) for the full setup.
+
+**Prerequisites:** authenticate via `kici login` first.
+
 ### kici types
 
 Generate TypeScript declaration files from orchestrator environment metadata. The generated `.d.ts` file augments the SDK's `KnownSecretKeys` and `EnvironmentSecrets` interfaces, providing compile-time autocomplete and type checking for secret key names.
@@ -7001,7 +7240,7 @@ kici admin drain-worker --url http://worker-2.internal:10143
 Verify a KiCI build-provenance attestation bundle offline. A bundle is the signed package a workflow step produces via `ctx.attestProvenance(...)`: a DSSE-wrapped SLSA in-toto statement, the ephemeral public key that signed it, and the KiCI identity token that anchors the build context. For the end-to-end attest → verify → view journey, see the [build provenance guide](https://docs.kici.dev/user/provenance/). Verification establishes the full chain — the identity token verifies against the trusted issuer's JWKS, the DSSE signature verifies against the bundled key, and the statement's build context must match the token's claims (a mismatch is a hard failure). When an `[artifact]` is given, its SHA-256 digest is also matched against the attestation subject.
 
 ```bash
-kici verify-attestation [artifact] --bundle <path-or-url> --trust-root <url-or-file> [options]
+kici verify-attestation [artifact] --bundle <path-or-url> [--trust-root <url-or-file>] [options]
 ```
 
 **Arguments:**
@@ -7012,14 +7251,14 @@ kici verify-attestation [artifact] --bundle <path-or-url> --trust-root <url-or-f
 
 **Options:**
 
-| Option                       | Required | Description                                                                               |
-| ---------------------------- | -------- | ----------------------------------------------------------------------------------------- |
-| `--bundle <path-or-url>`     | yes      | Path or `http(s)` URL to the attestation bundle JSON.                                     |
-| `--trust-root <url-or-file>` | yes      | Trusted issuer (see below). The token issuer is pinned to it, never taken from the token. |
-| `--audience <aud>`           | no       | Expected token audience (defaults to the KiCI provenance audience).                       |
-| `--json`                     | no       | Print the structured verification result as JSON instead of human-readable output.        |
+| Option                       | Required | Description                                                                                                                     |
+| ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `--bundle <path-or-url>`     | yes      | Path or `http(s)` URL to the attestation bundle JSON.                                                                           |
+| `--trust-root <url-or-file>` | no       | Trusted issuer (see below). Defaults to the hosted KiCI platform. The token issuer is pinned to it, never taken from the token. |
+| `--audience <aud>`           | no       | Expected token audience (defaults to the KiCI provenance audience).                                                             |
+| `--json`                     | no       | Print the structured verification result as JSON instead of human-readable output.                                              |
 
-**Trust root:** the verifier never trusts the issuer named inside the token — you supply the trusted issuer out-of-band via `--trust-root`, in one of two forms:
+**Trust root:** `--trust-root` defaults to the hosted KiCI platform's provenance issuer — the same platform you `kici login` against (see [Which trust root do I use?](https://docs.kici.dev/user/provenance/#which-trust-root-do-i-use)), so the common case needs no flag. The verifier never trusts the issuer named inside the token; supplying it out-of-band is what prevents a forged bundle from self-attesting. To override the default, pass `--trust-root` in one of two forms:
 
 - **Online — an HTTPS issuer URL.** The verifier fetches `<url>/.well-known/openid-configuration`, reads its `issuer` and `jwks_uri`, and fetches the JWKS. The token's `iss` is pinned to the discovery document's `issuer`.
 - **Offline — a self-contained trust-root file.** A local JSON file with the issuer and JWKS inlined, so no network access is needed (air-gapped verification):
@@ -7038,7 +7277,10 @@ kici verify-attestation [artifact] --bundle <path-or-url> --trust-root <url-or-f
 **Examples:**
 
 ```bash
-# Online: verify a bundle against a deployed issuer, digest-checking the artifact
+# Default: verify against the hosted KiCI platform (no --trust-root needed)
+kici verify-attestation ./dist/app.tgz --bundle ./app.tgz.kici.json
+
+# Override: verify a bundle against a specific issuer, digest-checking the artifact
 kici verify-attestation ./dist/app.tgz \
   --bundle ./app.tgz.kici.json \
   --trust-root https://platform.example/issuer
@@ -7055,10 +7297,10 @@ kici verify-attestation --bundle ./app.tgz.kici.json \
 
 **Exit codes:**
 
-| Code | Meaning                                                                             |
-| ---- | ----------------------------------------------------------------------------------- |
-| 0    | Verified — signature, identity, build context (and digest, if checked) all pass     |
-| 1    | Not verified, or an error (missing flag, unreadable bundle, unreachable trust root) |
+| Code | Meaning                                                                                   |
+| ---- | ----------------------------------------------------------------------------------------- |
+| 0    | Verified — signature, identity, build context (and digest, if checked) all pass           |
+| 1    | Not verified, or an error (missing `--bundle`, unreadable bundle, unreachable trust root) |
 
 ## Workflow discovery
 
@@ -7100,7 +7342,7 @@ All commands follow a consistent exit code convention:
 
 ## Debug output
 
-Use `--debug` (on `kici run local`, `kici run remote`, `kici test`) or `--verbose` (on `kici compile`) for detailed output:
+Use `--debug` (on `kici run local`, `kici run remote`, `kici preview`) or `--verbose` (on `kici compile`) for detailed output:
 
 ```bash
 # Shows trigger matching, rule evaluation, decision traces
@@ -7110,7 +7352,7 @@ kici run local push --debug
 kici compile --verbose
 
 # Shows trigger matching preview
-kici test pr:open --debug
+kici preview pr:open --debug
 ```
 
 Set `KICI_DEBUG=true` for additional internal debug output across all commands.
@@ -7391,7 +7633,7 @@ The lock file (`kici.lock.json`) is a JSON file with the following top-level fie
 
 | Field           | Description                                                                                                                                                                                                                                                                                                                                           |
 | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `schemaVersion` | Lock file schema version (currently 20). Incremented on breaking format changes.                                                                                                                                                                                                                                                                      |
+| `schemaVersion` | Lock file schema version (currently 29). Incremented on breaking format changes.                                                                                                                                                                                                                                                                      |
 | `source`        | Reference to the source file and export (e.g., `{ file: “.kici/workflows/ci.ts”, export: “#default” }`).                                                                                                                                                                                                                                              |
 | `contentHash`   | SHA-256 of the serialized lock file content (excluding itself). Changes when any workflow, trigger, or job changes.                                                                                                                                                                                                                                   |
 | `lockfileHash`  | SHA-256 of the detected package manager's lockfile, used as the dependency cache key. The lockfile is `.kici/package-lock.json` for npm, or the repo-root `pnpm-lock.yaml` / `yarn.lock` for a pnpm/yarn workspace; the hash input is prefixed with the manager name so a manager change is a guaranteed cache miss. Omitted when no lockfile exists. |
@@ -7514,7 +7756,7 @@ Test your workflows remotely against the full CI pipeline from your local machin
 - Give test runs test-scoped secrets — your local secret files and `--env` values (uploaded encrypted) plus any environment flagged `allowLocalExecution: true` — while production environments stay unreachable
 - Detect test mode in workflow code via `ctx.isTestRun`
 
-The command is remote-only -- all execution happens on the orchestrator and agent. For local-only trigger matching previews, use `kici test <event>`.
+The command is remote-only -- all execution happens on the orchestrator and agent. For local-only trigger matching previews, use `kici preview <event>`.
 
 :::note[Orchestrator prerequisite: cache storage]
 `kici run remote` uploads your working-tree overlay to the orchestrator's **cache storage** via a pre-signed URL, and the agent fetches it from there (see [Repo state transfer](https://docs.kici.dev/user/testing-guide/#repo-state-transfer)). The target orchestrator must therefore have cache storage enabled (`KICI_STORAGE_TYPE` = `s3` or `filesystem`).
@@ -8754,6 +8996,36 @@ 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 environments that match a glob pattern (e.g., `review/*`) inherit the pattern's configuration, variables, and protection rules.
 
+### Multiple environments per job
+
+A job can bind more than one environment with `environments`, an ordered array. This lets a single job draw secrets and variables from several environments at once — for example a shared `staging` environment plus a `my-testing` environment that carries test-only variables:
+
+```typescript
+job('deploy', {
+  runsOn: 'default',
+  environments: ['staging', 'my-testing'],
+  steps: [
+    step('deploy', async (ctx) => {
+      // ctx.secrets and ctx.env carry the merged set from both environments
+      const dbUrl = await ctx.secrets.get('DB_URL');
+    }),
+  ],
+});
+```
+
+- `environment` (singular) and `environments` (array) are mutually exclusive — setting both is a compile error. `environment: 'staging'` is exactly equivalent to `environments: ['staging']`.
+- Each array entry is a static name or a function of the event, resolved per element exactly like a single dynamic environment.
+
+**Merge order — last wins.** All bound environments are resolved on every dispatch (webhook, scheduled, and test runs alike) and merged in array order. When the same secret or variable key is defined in more than one environment, the later entry in the array wins. With `environments: ['staging', 'my-testing']`, a key defined in both resolves to `my-testing`'s value; keys defined in only one are preserved. The longest-scope-path-wins rule still applies _within_ each environment.
+
+**Protection rules combine all-must-pass.** A job must satisfy **every** bound environment's gates — adding an environment can never loosen access. Branch restrictions, trigger-type filters, and repo patterns must pass for all environments; the minimum trust tier is the most restrictive across them; required reviewers are the union of all environments' reviewers; the wait timer is the longest; and the hold expiry is the shortest. If a run is gated out, the rejection names which environment and which rule rejected it (visible via `kici status` and the run's rejection reason), so a mutually-exclusive set of rules surfaces as a clear failure rather than a silent perpetual rejection.
+
+**Skip-on-test.** On a test or local run (`kici run remote`, `kici run local`), any bound environment that disallows local execution is skipped — its variables and secrets are omitted from the merge and its gates are not evaluated. This makes the test-only-variables pattern work: with `environments: ['staging', 'my-testing']` where only `my-testing` allows local execution, a test run resolves just `my-testing`'s variables. If every bound environment disallows test runs, the job runs with no environment variables and a clear warning.
+
+**Unconfigured environments contribute nothing at dispatch.** At dispatch time a bound environment name with no matching configured environment (and no matching glob environment) simply adds no variables, secrets, or protection rules — the job still runs, exactly as a single dynamic environment resolving to an as-yet-unconfigured name does today.
+
+**Registration rejects a provably-unsatisfiable binding.** When a workflow is registered, KiCI statically checks every multi-environment binding: a bound environment that does not exist, a disabled one, or two environments with mutually-exclusive fixed branch / trigger-type / repository restrictions (no value can satisfy both) makes the binding provably unsatisfiable, and the registration is rejected with a precise message naming the job, the environments, and the rule — for example `unsatisfiable environment binding: job 'deploy' binds environments [staging, my-testing] with mutually exclusive branch restrictions (no value satisfies all bound environments)`. Bindings whose restrictions use globs are undecidable at registration and fall through to the dispatch-time gate check instead.
+
 ### Job-level environment variables
 
 The `env` property on a job provides static or dynamic environment variables:
@@ -8793,7 +9065,7 @@ job('deploy', {
 });
 ```
 
-If no `concurrencyGroup` is specified, the environment name is used as the default concurrency group.
+If no `concurrencyGroup` is specified, the environment name is used as the default concurrency group. For a job bound to multiple environments, the default is the **first** bound environment's name.
 
 ### Step context
 
@@ -8934,6 +9206,12 @@ Each environment has four tabs:
 
 4. **History** -- view filtered runs targeting this environment.
 
+### Bound environments on runs
+
+A job's bound deployment environments are shown as chips on the run detail page (in the job metadata panel) in the order the job declared them, and the distinct set across a run's jobs appears as compact chips on the run list. For a multi-environment job the chips read left-to-right in merge order — later environments override earlier ones on key collisions. A `(dynamic)` chip marks an environment whose name is computed at runtime; it resolves to the real name once the run starts. A job that binds a single environment shows one chip; a job that binds none shows no chip.
+
+If a multi-environment binding is gated out, the run's failure banner names which environment and which rule rejected it (the same all-must-pass detail surfaced by `kici status`).
+
 ### Secrets management
 
 Secrets are individual encrypted values organized by scope paths (e.g., `aws/prod`, `databases/postgres`). Scopes are bound to environments via bindings:
@@ -9957,11 +10235,34 @@ statement's build context must match the token's identity claims (a mismatch is
 a hard failure).
 
 ```bash
-kici verify-attestation [artifact] --bundle <path-or-url> --trust-root <url-or-file>
+kici verify-attestation [artifact] --bundle <path-or-url> [--trust-root <url-or-file>]
 ```
 
-You supply the trusted issuer out-of-band via `--trust-root` — the verifier
-never trusts the issuer named inside the token. There are two forms:
+### 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.
+
+### 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
+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
+question.
+
+To override the default, supply the trusted issuer via `--trust-root`, in one of
+two forms:
 
 - **Online — an HTTPS issuer URL.** The verifier fetches
   `<url>/.well-known/openid-configuration`, reads its `issuer` and `jwks_uri`,
@@ -9989,7 +10290,10 @@ when it does not (or on an error such as a missing flag or unreachable trust
 root).
 
 ```bash
-# Verify a bundle against a deployed issuer, digest-checking the artifact:
+# Default: verify against the hosted KiCI platform (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:
 kici verify-attestation ./dist/app.tgz \
   --bundle ./app.tgz.kici.json \
   --trust-root https://platform.example/issuer
@@ -10028,6 +10332,44 @@ attestations shows an empty state.
 
 <!-- /help:run-attestations -->
 
+## Browsing attestations across runs
+
+The **Attestations** page (in the org sidebar) lists every build-provenance
+attestation your organization has produced — not just one run's. It is the
+supply-chain audit surface: look up "who built `sha256:…`?" by digest, or browse
+and filter every attestation across all runs.
+
+<!-- help:attestations-list#browsing-attestations-across-runs -->
+
+The **Attestations** page lists every build-provenance attestation your organization has produced.
+
+- **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`).
+
+Open a row for the parsed provenance statement and a live re-verification.
+
+<!-- /help:attestations-list -->
+
+The status badge here is the **server-side verdict**, computed once when the
+attestation was recorded (verify-at-ingest) — so the list stays fast at any
+size. `verified` means the signature, build identity, and build context all
+checked out against the provenance issuer; `failed` means verification ran and
+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.
+
+Opening a row leads to the **attestation detail page**:
+
+<!-- help:attestation-detail#browsing-attestations-across-runs -->
+
+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
@@ -10049,6 +10391,8 @@ Secrets are managed per-environment in the orchestrator (see [operator docs](htt
 
 This design prevents accidental secret leakage through child processes, log output, or error messages. Only secrets you explicitly request are loaded into memory.
 
+A job can bind several environments with `environments: ['staging', 'my-testing']`; the secret keys from all bound environments are merged in array order, with a later environment's value winning on a key collision. See [Multiple environments per job](https://docs.kici.dev/user/environments/#multiple-environments-per-job).
+
 ## Where secret values come from
 
 Secret values are written either through the dashboard or through `kici-admin` running against the orchestrator. The orchestrator operator decides — per organization — which surface accepts secret writes. From the workflow author's perspective, the resolution path at run time is identical either way; the difference is where you (or your ops team) **enter** the value.
@@ -11520,7 +11864,7 @@ Source: https://docs.kici.dev/architecture/data-flows/
 
 This document describes the key data flows through the KiCI architecture: webhook delivery, job execution, developer-initiated remote runs, dependency caching, re-run and cancel, trace ID propagation, internal event routing, and generic webhook ingestion.
 
-> **Lock file schema version:** The lock file uses schema version 21, which adds the `CheckMode` / `CheckStepOutcome` enums for check-mode step execution on top of v20's `LabelMatcher` (exact/regex) selectors for `runsOn`/`runsOnAll`/`excludeLabels`, v19's `maxParallel`/`failFast` fan-out concurrency, v18's `runsOnAll` host fan-out predicate and `onUnreachable` policy, v17's typed init presets (`mise` / `{ mise }`) and `auto` detection, v16's normalized approval config, v15's per-job init config, v14's declarative cache specs, v11's `LockInlineValue` for pure function inline evaluation, v10's simplified negative patterns (! prefix in repos/paths arrays), v9's global workflow repos matching, and v8's runsOn polymorphic type support.
+> **Lock file schema version:** The lock file uses schema version 29. The orchestrator rejects any fetched lock whose `schemaVersion` does not exactly match the engine version it was built against, so a stale lock must be recompiled with `kici compile` and pushed again after any SDK upgrade that bumps the schema.
 
 ## Webhook delivery flow
 
@@ -11726,7 +12070,7 @@ Dep cache misses alone do **not** trigger a build job. Deps are platform-specifi
 
 ### Cross-source / no-contentHash workflows
 
-- **Lock files without `contentHash`** (schema v1) skip the source cache entirely; agents compile from source. Regenerate lock files with `kici compile` to enable caching. The current lock file schema version is 21.
+- **Lock files without `contentHash`** (schema v1) skip the source cache entirely; agents compile from source. Regenerate lock files with `kici compile` to enable caching. The current lock file schema version is 29.
 - **Cross-source / global-workflow dispatch** (a workflow registered against source A fired by a webhook on source B) bypasses both caches. The registration's lock file entry still carries `contentHash`, but the cross-source path always clone-and-installs — the eval temp dir doesn't ship `@kici-dev/sdk`. The execution agent still verifies `contentHash` against the cloned source for drift detection.
 
 ### Build deduplication
@@ -12294,7 +12638,7 @@ The compiler processes the workflow definition:
 
 ### Execution time (local test runner)
 
-When `kici test` runs a workflow:
+When `kici run local` runs a workflow:
 
 1. **SDK module resolution:** The runner resolves `setStepOutputsMap` / `setJobOutputsMap` from the same `@kici-dev/sdk` module instance that the workflow uses (ensures the proxy reads from the same map)
 2. **Map injection:** Fresh `OutputsMap` and `StepRefMap` are created and injected via `setStepOutputsMap()` / `setStepRefMap()` before each job