@kici-dev/compiler 0.1.23 → 0.1.24

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

@@ -2,6 +2,99 @@
 
 This bundle covers: Running the CLI: compile, test, run local/remote, auth, hooks, lock-file drift.
 
+## 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/
@@ -284,7 +377,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"
   }
 }
 ```
@@ -379,6 +472,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`):**
 
@@ -520,6 +615,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:**
 
@@ -685,12 +784,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:**
@@ -717,19 +816,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:**
@@ -739,7 +838,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
 
@@ -1116,6 +1215,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.
@@ -1434,7 +1554,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:**
@@ -1445,14 +1565,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):
@@ -1471,7 +1591,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
@@ -1488,10 +1611,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
 
@@ -1533,7 +1656,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
@@ -1543,7 +1666,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.
@@ -1824,7 +1947,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. |
@@ -1947,7 +2070,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`).

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

@@ -802,6 +802,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:
@@ -841,7 +871,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
 
@@ -982,6 +1012,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:
@@ -2005,11 +2041,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`,
@@ -2037,7 +2096,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
@@ -2076,6 +2138,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
@@ -2097,6 +2197,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.