@iowarp/clio-coder 0.4.3 → 0.4.5

package/docs/guide/configuration-reference.md

@@ -191,11 +191,13 @@ Read from the process environment at boot unless the row says otherwise.
 | `APPDATA` | `~\AppData\Roaming` | Windows-only base directory for the config and data roots (`%APPDATA%\clio-coder\config`, `%APPDATA%\clio-coder\data`); ignored on other platforms. |  |
 | `CI` | `unset` | Any non-empty value marks a CI run and makes smooth-streaming `auto` fall back to the immediate coalescer instead of paced animation; explicit `on` is unaffected. |  |
 | `CLIO_CODER_ALLOW_EXTERNAL_FULL_ACCESS` | `unset (disabled)` | Exactly `1` lets a `full-auto` dispatch to the claude-code or antigravity-code subprocess runtime pass their dangerous skip-permissions flag; any other value keeps the bypass closed. |  |
+| `CLIO_CODER_ANTHROPIC_CACHE_RETENTION` | `unset` | Read per native Anthropic provider call: `none`, `short`, or `long` cache retention. Long TTL requires model compatibility; unset preserves SDK defaults. | explicit call option > env > SDK default |
 | `CLIO_CODER_BIN_DIR` | `~/.local/bin` | Directory holding the `clio-coder` launcher symlink that uninstall removes and the install script creates; a path, defaulting to `~/.local/bin`. |  |
 | `CLIO_CODER_BUS_TRACE` | `unset (disabled)` | Exactly `1` subscribes a tracer to the shutdown, session-end, and domain lifecycle bus channels and writes one `[clio-coder:bus]` line per event to stderr. |  |
 | `CLIO_CODER_CACHE_DIR` | `platform default (`$XDG_CACHE_HOME/clio-coder`, else `~/.cache/clio-coder`)` | Absolute path for the cache root; beats `CLIO_CODER_HOME/cache` and the platform default, and the fleet-view pane child re-pins it from argv. | env > `CLIO_CODER_HOME/cache` > `XDG_CACHE_HOME` or platform default |
 | `CLIO_CODER_COMMIT_ASSISTED` | `unset` | Set by Clio to `1`/`0` per spawn from the run's attribution evidence; the managed `prepare-commit-msg` hook reads it to append the assisted trailer, and nested seams strip it. |  |
 | `CLIO_CODER_COMMIT_AUTHORED` | `unset` | Set by Clio to `1`/`0` per spawn from the run's attribution evidence; the managed `prepare-commit-msg` hook reads `1` to add the co-authored trailer, and nested seams strip it. |  |
+| `CLIO_CODER_COMMIT_DECISIONS` | `unset` | Set by Clio per spawn to the space-separated decision refs (`<interviewId>/<key>`) active on the session decision board; the managed `prepare-commit-msg` hook writes one `Clio-Decision:` trailer per well-formed ref, and nested seams strip it. |  |
 | `CLIO_CODER_CONFIG_DIR` | `platform default (`$XDG_CONFIG_HOME/clio-coder`, else `~/.config/clio-coder`)` | Absolute path for the config root; beats `CLIO_CODER_HOME/config` and the platform default, and the fleet-view pane child re-pins it from argv. | env > `CLIO_CODER_HOME/config` > `XDG_CONFIG_HOME` or platform default |
 | `CLIO_CODER_DATA_DIR` | `platform default (`$XDG_DATA_HOME/clio-coder`, else `~/.local/share/clio-coder`)` | Absolute path for the data root; beats `CLIO_CODER_HOME/data` and the platform default, and the fleet-view pane child re-pins it from argv. | env > `CLIO_CODER_HOME/data` > `XDG_DATA_HOME` or platform default |
 | `CLIO_CODER_DEBUG_SHUTDOWN` | `unset (disabled)` | Exactly `1` prints timed `[clio-coder:shutdown]` phase lines and full stack traces of failing domain `stop()` hooks to stderr during shutdown. |  |
@@ -219,13 +221,16 @@ Read from the process environment at boot unless the row says otherwise.
 | `CLIO_CODER_LMSTUDIO_CORESIDENT_CONTEXT` | `131072` | Positive integer ceiling on the context length requested when loading an LM Studio model next to another resident model; `off`, `0`, or `false` disables the clamp. |  |
 | `CLIO_CODER_MEMORY_TRACE` | `unset (disabled)` | File path for a JSONL trace of proactive task-memory step envelopes including up to 8000 chars of model text per step; off when unset or empty. |  |
 | `CLIO_CODER_MODEL_CATALOG_DIRS` | `unset` | PATH-delimited list of extra model-catalog overlay directories, applied after the user and project overlays with the highest precedence. |  |
-| `CLIO_CODER_NO_NETWORK_TOOLS` | `unset (disabled)` | Exactly `1` removes the network (RETRIEVE) tools from every registry built in the process; `clio-coder skills-eval` sets it for hermetic arms and `--allow-network` deletes it. | `skills-eval --allow-network` clears it for child arms; otherwise env only |
+| `CLIO_CODER_DISABLE_RETRIEVE_TOOLS` | off | Exactly `1` removes RETRIEVE tools from registries; `clio-coder skills-eval` sets it for child arms. Bash, hooks, external CLIs, and provider networking remain available; OS isolation is required for hermetic runs. Legacy `CLIO_CODER_NO_NETWORK_TOOLS=1` remains accepted. | `skills-eval --allow-network` clears both spellings for child arms |
+| `CLIO_CODER_NO_NETWORK_TOOLS` | off | Legacy alias of `CLIO_CODER_DISABLE_RETRIEVE_TOOLS`; disables retrieval tools only, with no shell network isolation. | env only |
+| `CLIO_CODER_PROVIDER_DUMP_PATH` | `unset` | Read per native provider call: absolute path for private JSONL request-body and terminal-response diagnostics. Parent must exist; the file must be operator-owned, regular, mode `0600`, and not a symlink. Known credentials are redacted; prompt and tool content remain. | env only |
+| `CLIO_CODER_WEB_FETCH_ALLOW_PRIVATE_NETWORK` | off | Exactly `1` allows web_fetch to reach private and local services. This operator process opt-in is not accepted from model arguments or project settings. | env only |
 | `CLIO_CODER_PACKAGE_ROOT` | `auto-detected` | Path used as the package root for bundled assets and docs instead of walking up to package.json; the docs engine re-reads it live, other callers cache the first answer. |  |
 | `CLIO_CODER_REDUCE_MOTION` | `unset (disabled)` | Exactly `1` makes smooth-streaming `auto` use the immediate coalescer; explicit `on` is unaffected. |  |
 | `CLIO_CODER_RENDER_TRACE` | `unset (disabled)` | File path for the versioned JSONL render-pipeline trace (timing only, no conversation text), truncated on open; off when unset or empty. |  |
 | `CLIO_CODER_REQUIRE_HOME_PREFIX` | `unset (disabled)` | Exactly `1` aborts startup when any resolved Clio directory lies outside `CLIO_CODER_HOME`; a test-harness guardrail that does nothing when `CLIO_CODER_HOME` is unset. |  |
-| `CLIO_CODER_RIGOR` | `repo-derived` | `high` or `normal` (case-insensitive) overrides the finish-contract evidence bar for the orchestrator and dispatched workers; any other value means no override. | env > workspace validation contract file (`.clio-coder/validation.yaml`, `validation.yaml`, `VALIDATION.md` raise it to `high`) > `normal`; no settings key |
-| `CLIO_CODER_RUN_OVERRIDES` | `unset` | JSON object (`maxContextTokens`, `kvCacheMode`, `sampling`) that `clio-coder run` and print modes write via `withRunOverrides` for the run's scope; workers inherit it and malformed input is dropped. |  |
+| `CLIO_CODER_RIGOR` | `repo-derived` | `high` or `normal` (case-insensitive) overrides the finish-contract evidence bar for the orchestrator and dispatched workers; any other value means no override. | env > a parsed workspace validation contract (`.clio-coder/validation.yaml` or `validation.yaml`, version 1) raises it to `high`; an invalid contract or a Markdown-only `VALIDATION.md` leaves `normal` > `normal`; no settings key |
+| `CLIO_CODER_RUN_OVERRIDES` | `unset` | JSON object (`maxContextTokens`, `sampling`) that `clio-coder run` and print modes write via `withRunOverrides` for the run's scope; workers inherit it and malformed input is dropped. |  |
 | `CLIO_CODER_SCREEN_READER` | `unset (disabled)` | Exactly `1` makes smooth-streaming `auto` use the immediate coalescer so a screen reader gets the low-motion update behavior; explicit `on` is unaffected. |  |
 | `CLIO_CODER_SHUTDOWN_HOOK_MS` | `500` | Positive integer milliseconds each shutdown and domain `stop()` hook may run before the coordinator moves on; non-positive or unparsable values use the default. |  |
 | `CLIO_CODER_SKILL_CATALOG_DIR` | `unset` | Path to a local skill catalog used by the marketplace and the provenance pin manifest; beats `<cwd>/skills` and the packaged catalog but not an explicit catalogDir option. | explicit catalogDir option > env > `<cwd>/skills` > packaged catalog |
@@ -337,8 +342,10 @@ Grouped by command. Global flags appear under `global`.
 
 | Flag | Controls |
 |---|---|
+| `--hash` | For `config trust safety\|hooks\|settings`, approve the exact full SHA-256 digest returned by a prior review; a changed review is refused. |
 | `--help` | Print the command's usage and exit. |
-| `--json` | For `config inspect`, emit the customization graph as JSON. |
+| `--json` | For `config inspect`, emit the customization graph; for `config trust safety\|hooks\|settings`, emit a read-only source and trust preview. |
+| `--revoke` | For `config trust safety\|hooks\|settings`, withdraw this workspace's approval for that configuration surface. |
 | `-h` | Short form of --help. |
 
 ### `configure`
@@ -614,7 +621,6 @@ Grouped by command. Global flags appear under `global`.
 | `--help` | Print the command's usage and exit. |
 | `--json` | Stream JSONL events for the main-agent turn (dispatch streams events plus the receipt JSON) instead of text output. |
 | `--json-events` | Main-agent JSON stream mode: `full` or `terminal`; implies `--json`. |
-| `--kv-cache-mode` | One-run KV-cache override for supported local runtimes: `f16`, `f32`, `none`, `false`, `q8_0`, `q4_0`, `q4_1`, `iq4_nl`, `q5_0`, or `q5_1`. |
 | `--max-context-tokens` | One-run context-window override (positive integer tokens) for supported local runtimes. |
 | `--min-p` | One-run min-p override (0 to 1) when the selected runtime supports it. |
 | `--model` | Wire model id for this run's main agent or dispatched worker instead of the target's default. |
@@ -774,6 +780,7 @@ Grouped by command. Global flags appear under `global`.
 
 Keys read from files under `.clio-coder/` in the repository.
 
+Project safety, hooks, and settings are ignored until the operator reviews them with `clio-coder config trust safety|hooks|settings` and approves the printed digest with `--hash`. Consent binds one canonical workspace and one surface's content and source location. Changes, local override additions, and safety-policy relocation require a new review. Startup names skipped files; `config inspect` shows effective safety provenance and trust. Settings and safety apply on restart; new hooks apply after extension reload, while changed or revoked published hooks stop before their next execution. `CLIO-CODER.md` remains project text and does not grant configuration authority.
 
 ### `.clio-coder/agents`
 
@@ -855,7 +862,7 @@ Keys read from files under `.clio-coder/` in the repository.
 | `commands[].requireConfirmation` | `true` parks the command for operator approval even at an autonomy level that would otherwise run it. |  |
 | `commands[].shellOperators` | `allow` admits pipes, redirects, and chaining in the command line; `deny` refuses them. |  |
 | `commands[].timeoutMs` | Wall-clock cap for the command; overrides the bash call's own `timeout_ms`. |  |
-| `disableDefaultPathPolicy` | `true` drops the built-in path policy (protected dotfiles, secrets, build outputs) so only the file's own path lists apply. |  |
+| `disableDefaultPathPolicy` | In an approved safety policy, `true` drops project-default path rules. Operator credentials, settings, skills, trust records, and host authority paths remain protected. |  |
 | `noDeletePaths` | Globs tools may read and write but never delete. |  |
 | `noWritePaths` | Globs tools may read and delete but never write. |  |
 | `readOnlyPaths` | Globs tools may read but never write or delete. |  |
@@ -885,7 +892,7 @@ Keys read from files under `.clio-coder/` in the repository.
 
 | Key | Controls | Precedence |
 |---|---|---|
-| `(presence)` | The file's presence (also `validation.yml`, root `validation.yaml`, or `VALIDATION.md`) raises the repo-derived rigor default from `normal` to `high`; its content is not read. | `CLIO_CODER_RIGOR` > presence of a validation contract > `normal` |
+| `version`, `task`, `runtime`, `artifacts`, `validators`, `notes` | The version-1 scientific validation contract (also `validation.yml`, root `validation.yaml`, or `validation.yml`). A contract that parses raises the repo-derived rigor default from `normal` to `high`; one that does not parse is diagnosed by `clio-coder doctor` and at interactive startup and leaves `normal`. `VALIDATION.md` is advisory prose and never raises rigor. Schema in [Scientific Validation](../process/scientific-validation.md). | `CLIO_CODER_RIGOR` > parsed validation contract > `normal` |
 
 ### `.clio-coder/verifiers.yaml`
 
@@ -898,7 +905,12 @@ Keys read from files under `.clio-coder/` in the repository.
 | `checks[].id` | Check id, at most 64 bytes; `frontend` is reserved for the built-in artifact check. |  |
 | `checks[].tags` | Free-form labels, at most 16 of 32 bytes, shown in the listing. |  |
 | `checks[].timeoutMs` | Required wall-clock cap for the check in ms, a positive integer at most 900000; a `verify` call may shorten it with `timeout_ms` but not exceed it. |  |
-| `version` | Catalog schema version; must equal the version this build speaks. |  |
+| `checks[].kind` | `command` (default, exit code), `numeric-compare` (stdout JSON judged against `reference` under `tolerance`), or `perf-budget` (wall time judged against `budget` or `baseline`). Requires `version: 2`. |  |
+| `checks[].reference` | `numeric-compare` only: repository-relative JSON file of `string -> number \| number[]` the command output is compared against. |  |
+| `checks[].tolerance` | `numeric-compare`: at least one of `relative`, `absolute`, `ulp`; every named bound must hold. `perf-budget` with `baseline`: `{relative}` headroom over the recorded time. |  |
+| `checks[].budget` | `perf-budget` only: `{wallTimeMs, tolerance?: {relative}}`; exclusive with `baseline`. |  |
+| `checks[].baseline` | `perf-budget` only: repository-relative JSON `{wallTimeMs}` written by `clio-coder verifiers baseline <id>`; exclusive with `budget`. |  |
+| `version` | Catalog schema version, `1` or `2`; version 1 files load with every check as `kind: command`. |  |
 
 ## Agent recipe frontmatter
 
@@ -924,6 +936,7 @@ Keys the recipe loader reads from `.clio-coder/agents/<id>.md` and the builtin r
 | `projectContextTier` |  | Enum `none \| bounded`; `bounded` injects the capped project name/conventions/invariants projection as a dynamic message and `none` skips the CLIO-CODER.md read. |
 | `resultContract` |  | Required object naming the typed result shape the worker must return; the terminal output is validated and repaired against it. |
 | `resultContract.kind` |  | One of twelve recipe-declarable report kinds (`scout-report`, `mutation-report`, `delegation-plan`, ...) or `architect-plan`; `council-ballot` may only arrive as a coordinator override. |
+| `resultContract.maxSummaryBytes` | 16384 | Optional integer between 1 and 32768 allowed only for `mutation-report`; sets the inline summary byte allowance before model dispatch. |
 | `resultContract.path` |  | Workspace-relative plan file path required only by `architect-plan` and refused for any other kind; absolute or `..` paths are rejected. |
 | `skills` |  | Array of unique skill names bound to files at registry load; they inject knowledge into the prompt, require the `context` tool, and never widen tool authority. |
 | `tags` |  | Array of unique lowercase routing hints shown in the catalog and matched against task signals when ranking candidate agents. |
@@ -1016,6 +1029,7 @@ Arguments the model can send on `dispatch`, `bash`, `context`, and `verify`, gro
 | `dispatch.model` | policy | Default model override. |
 | `dispatch.node` | policy | Default fleet node pin (omit for automatic placement). |
 | `dispatch.persona` | task | Default persona for the batch, max 8000 chars. |
+| `dispatch.result_summary_max_bytes` | policy | Sets the inline summary byte allowance for `mutation-report` contracts (1 to 32768, default 16384). Inherited by mutating tasks; ignored by non-mutation steps. |
 | `dispatch.review` | policy | Reviewer gate for one task: a read-only reviewer verdicts pass, revise, or fail, and revise re-runs the builder with the findings. |
 | `dispatch.review.max_cycles` | policy | Review/revise cycles before an operator decision (default 2, max 4). |
 | `dispatch.review.model` | policy | Model for the reviewer. |
@@ -1043,6 +1057,7 @@ Arguments the model can send on `dispatch`, `bash`, `context`, and `verify`, gro
 | `dispatch.tasks[].intent` | policy | Per-task intent (`$defs.intent`); it must fit inside the batch `intent`. |
 | `dispatch.tasks[].model` | policy | Per-task model override. |
 | `dispatch.tasks[].node` | policy | Fleet node pin: local or a fleet.nodes id. |
+| `dispatch.tasks[].result_summary_max_bytes` | policy | Per-task summary allowance override for `mutation-report` contracts (1 to 32768). Fails validation on non-mutation steps. |
 | `dispatch.tasks[].target` | policy | Per-task target id override. |
 | `dispatch.tasks[].task` | task | The assignment, with expected output and constraints. |
 | `dispatch.tasks[].worktree` | policy | Run this writer in an isolated git worktree. |

package/docs/guide/environment-variables.md

@@ -5,7 +5,7 @@
 
 This page inventories Clio-specific runtime variables and the ambient variables that materially change documented operator behavior. `settings.yaml` is the durable home for operator policy; environment variables support per-process overrides, directory layout, debugging, credentials, terminal integration, and internal plumbing. When prose and source disagree, prefer the cited read site.
 
-The `environment-variable-inventory` check in `scripts/check-hygiene.ts`, run by `npm run lint`, enforces coverage for Clio's `CLIO_*` variables and `NO_COLOR`. It intentionally does not treat every operating-system or provider convention as a Clio knob. Examples outside that enforced family include `PATH`, `HOME`, terminal capability variables, and provider API-key names selected dynamically by `src/engine/env-api-keys.ts`.
+The `environment-variable-inventory` check in `scripts/check-hygiene.ts`, run by `pnpm run lint`, enforces coverage for Clio's `CLIO_*` variables and `NO_COLOR`. It intentionally does not treat every operating-system or provider convention as a Clio knob. Examples outside that enforced family include `PATH`, `HOME`, terminal capability variables, and provider API-key names selected dynamically by `src/engine/env-api-keys.ts`.
 
 ## Behavior knobs without a settings key
 
@@ -14,6 +14,8 @@ The `environment-variable-inventory` check in `scripts/check-hygiene.ts`, run by
 | `NO_COLOR` | unset | Set to any non-empty value to drop every foreground and background color. Bold, dim, italic, and underline stay, because they are what is left to read the interface by (`src/interactive/theme/tokens.ts`). |
 | `CLIO_CODER_RIGOR` | repo-derived | Finish-contract evidence bar, `normal` or `high`, layered over the repo-derived default (`src/domains/safety/rigor.ts`). |
 | `CLIO_CODER_ALLOW_EXTERNAL_FULL_ACCESS` | off | `1` lets full-auto pass through to external CLI runtimes with their own full access (`src/engine/claude/subprocess-runtime.ts`, `src/engine/antigravity/subprocess-runtime.ts`). |
+| `CLIO_CODER_ANTHROPIC_CACHE_RETENTION` | unset | Native engine requests using `anthropic-messages` accept `none`, `short`, or `long`. Long requests ask for a one-hour cache TTL when the model's compatibility metadata supports it. An explicit per-call preference wins; unset preserves SDK defaults, and other APIs are unchanged (`src/engine/provider-diagnostics.ts`). |
+| `CLIO_CODER_PROVIDER_DUMP_PATH` | unset | Absolute path for opt-in native-provider JSONL diagnostics. One record per completed call contains payloads after caller callbacks and the terminal response. The parent directory must exist; the file must be operator-owned, regular, mode `0600`, and not a symlink. New files use that mode. Auth options and headers are omitted, known provider credentials are redacted, and prompt/message/tool content is retained. Keep this diagnostic private and delete it when finished. Ledger events are unchanged; external CLI transports are not captured (`src/engine/provider-diagnostics.ts`). |
 | `CLIO_CODER_FORCE_COMPACT` | off | `1` forces compaction before every interactive turn for as long as it is set (`src/interactive/chat-loop.ts`). |
 | `CLIO_CODER_LEGACY_MASK` | off | `1` temporarily restores the destructive stale-observation mask before summary compaction; remove it after compatibility diagnosis. |
 | `CLIO_CODER_STATUS_STUCK_MS` | 180000 | Stuck-turn watchdog threshold (`src/interactive/status/watchdog.ts`). |
@@ -28,7 +30,9 @@ The `environment-variable-inventory` check in `scripts/check-hygiene.ts`, run by
 | `CLIO_CODER_SKILL_MARKETPLACE_INDEX` | unset | Skill-marketplace index path override (`src/domains/resources/skills/marketplace.ts`). |
 | `CLIO_CODER_MODEL_CATALOG_DIRS` | unset | Extra model-catalog directories (`src/domains/providers/knowledge-base-path.ts`). |
 | `CLIO_CODER_ENDPOINT_SLOTS_TTL_MS` | 86400000 | How long a persisted endpoint slot count answers for an endpoint nothing has probed in this process. A record past the bound is ignored and pruned rather than allowed to over-admit (`src/domains/providers/endpoint-slots-store.ts`). |
-| `CLIO_CODER_NO_NETWORK_TOOLS` | off | `1` strips network tools from every registry in the process; the skills-eval harness sets it for hermetic arms; `--allow-network` clears it (`src/tools/network-policy.ts`). |
+| `CLIO_CODER_DISABLE_RETRIEVE_TOOLS` | off | `1` strips RETRIEVE tools from registries. Bash, hooks, external CLIs, and provider networking remain available; hermetic runs require OS isolation. Legacy `CLIO_CODER_NO_NETWORK_TOOLS=1` is accepted; `skills-eval --allow-network` clears both spellings. |
+| `CLIO_CODER_NO_NETWORK_TOOLS` | off | Legacy alias of `CLIO_CODER_DISABLE_RETRIEVE_TOOLS`; disables retrieval tools only, with no shell network isolation. |
+| `CLIO_CODER_WEB_FETCH_ALLOW_PRIVATE_NETWORK` | off | `1` permits web_fetch to reach private and local services; operator process setting only, never a tool argument or project setting (`src/tools/network-policy.ts`). |
 | `CLIO_CODER_REDUCE_MOTION` | off | `1` makes smooth-streaming `auto` use the immediate coalescer. Explicit `on` remains an operator request, while stdout backpressure still pauses frame production. |
 | `CLIO_CODER_SCREEN_READER` | off | `1` makes smooth-streaming `auto` use the immediate coalescer so a screen reader receives the existing low-motion update behavior. |
 | `CLIO_CODER_INSTANT_SHELL` | on | `0` disables the single-owner Stage 0 interactive shell for immediate rollback. Unset or `1` mounts one terminal/editor owner before service hydration; ACP, headless, ordinary non-TTY, and subcommand paths never mount it. An explicit `CLIO_CODER_INTERACTIVE=1` keeps its force-interactive non-TTY behavior. |
@@ -96,10 +100,10 @@ Set by Clio for its own processes; not operator knobs.
 | --- | --- |
 | `AI_AGENT` | Clio sets this generic child-process attribution marker to `clio-coder` at both shipped entry points and reinforces it for bash tools, fleet workers, registered code steps, and command hooks. Child tooling may read it to identify the agent that launched it (`src/cli/index.ts`, `src/worker/entry.ts`, `src/core/bash-exec.ts`). |
 | `CLIO_CODER_GIT_COMMITS_ENABLED` | Carries the effective `integrations.git.commitAttribution` setting to Clio-controlled child-process seams. It is set from validated settings and is not an operator override (`src/core/git-commit-attribution.ts`). |
-| `CLIO_CODER_COMMIT_ASSISTED`, `CLIO_CODER_COMMIT_AUTHORED` | Per-spawn inputs to the managed `prepare-commit-msg` hook, which also requires `AI_AGENT=clio-coder` and `CLIO_CODER_GIT_COMMITS_ENABLED=1`; normal external shells never receive this set. Only assistance and authorship cross the environment. Testing, review, and receipt trailers are composed in process by the fleet seam, so a child shell cannot forge them by exporting a variable (`src/core/git-commit-attribution.ts`). |
+| `CLIO_CODER_COMMIT_ASSISTED`, `CLIO_CODER_COMMIT_AUTHORED`, `CLIO_CODER_COMMIT_DECISIONS` | Per-spawn inputs to the managed `prepare-commit-msg` hook, which also requires `AI_AGENT=clio-coder` and `CLIO_CODER_GIT_COMMITS_ENABLED=1`; normal external shells never receive this set. Only assistance, authorship, and the space-separated decision refs the spawn was made under cross the environment. Testing, review, and receipt trailers are composed in process by the fleet seam, so a child shell cannot forge them by exporting a variable (`src/core/git-commit-attribution.ts`). |
 | `CLIO_CODER_GIT_CONFIG_BASE_COUNT`, `CLIO_CODER_GIT_DEFAULT_HOOKS_EQUIVALENT` | Bookkeeping that lets each managed hook wrapper remove only Clio's command-scope `core.hooksPath` pair before chaining the repository's own hook of the same name. Existing `GIT_CONFIG_COUNT` entries remain in force; an explicit `core.hooksPath` is treated as composable only when it resolves exactly to the repository's default hooks directory (`src/core/git-commit-attribution.ts`). |
 | `CLIO_CODER_INTERACTIVE` | Marks the interactive TUI process; scrubbed from bash-tool children so nested invocations do not inherit it (`src/cli/clio.ts`, `src/core/bash-exec.ts`). |
-| `CLIO_CODER_RUN_OVERRIDES` | JSON envelope for run-scoped CLI options (`--max-context-tokens`, `--kv-cache-mode`, sampling flags). One typed variable instead of one env var per option; worker subprocesses inherit it (`src/core/run-overrides.ts`). |
+| `CLIO_CODER_RUN_OVERRIDES` | JSON envelope for run-scoped CLI options (`--max-context-tokens`, sampling flags). One typed variable instead of one env var per option; worker subprocesses inherit it (`src/core/run-overrides.ts`). |
 | `CLIO_CODER_EVAL_RUNNER_STDOUT_FILE` | Set by the eval runner for the `clio-coder run` child it spawns; the child appends its stdout to that path so the runner can read it after exit (`src/domains/eval/suites/run.ts`). |
 | `CLIO_CODER_YAZI_PICK_TOKEN` | Per-session token the yazi file-pane integration hands its yazi child and expects back on a pick, so a pick from another session is ignored (`src/domains/mux/yazi/session.ts`, `src/domains/mux/yazi/profile.ts`). |
 | `CLIO_CODER_WORKER_LABELS` | Comma-separated labels a dispatched worker reports as its own (`src/domains/dispatch/transport.ts`, `src/worker/entry.ts`). |

package/docs/guide/fleet-dispatch.md

@@ -962,3 +962,15 @@ the contract explicitly with `clio-coder fleet run <name>` and retain its
 receipts. The [fleet demo runbook](../process/fleet-demo-runbook.md) provides a bounded
 end-to-end scenario, including reviewer gates and verification commands. Live
 fleet execution is not hidden inside deterministic CI.
+
+## Bounded result delivery
+
+Documenter and Coder use a structured report (`mutation-report`). Explicit recipe selections remain in force. For a read-only explanation, its `summary` carries the requested explanation and citations, with `mutatedPaths` empty. The inline `summary` allows up to 16,384 UTF-8 bytes by default, configurable up to a ceiling of 32,768 UTF-8 bytes via recipe `maxSummaryBytes` or dispatch `result_summary_max_bytes`. In batch dispatches, a top-level `result_summary_max_bytes` default is inherited by mutating tasks and safely ignored by non-mutation steps; setting an explicit per-task `result_summary_max_bytes` on a non-mutation step fails validation before model dispatch. Authored `commitMessage` and `architect-plan` authorship remain bounded at 1,000 UTF-8 bytes. Coder and Documenter explanations have no global 15-line limit. If worker output exceeds the sealed output bound, capture fails explicitly naming the bound rather than reporting an ambiguous JSON syntax error. If the requested answer cannot fit within the summary allowance or cannot be grounded, the summary must state the specific limitation. A longer artifact requires authorization to write it; a shortened answer or validation log does not satisfy an unmet length requirement.
+
+Documenter exposes no arbitrary shell commands; it relies on declared verifier checks or grounded source reads. In validation reporting, unexecuted checks must never be recorded as failures (`passed: false` applies only to checks that actually ran and failed). Unexecuted checks or execution limitations belong in the `summary` deliverable as stated limitations.
+
+The Scout recipe instructs the model to return structured findings with source paths and exact lines checked against live reads. A search hit alone does not establish a citation. On repair, unsupported findings should be removed rather than moved to convenient range endpoints. Inline delivery and schema conformance do not establish semantic citation accuracy.
+
+Ordinary dispatcher, council, and wiki planning time and tool estimates are advisory during execution rather than automatic aborts. Enforced bounds are explicit caller deadlines (`timeout_ms`), operator cancellation, contract output bounds, and capacity rules. The fleet tool-call cap limits tool use. The `fleet.limits.internalRunTimeoutMs` setting bounds internal CLI dispatch; it does not impose a wall-clock deadline on ordinary TUI dispatch workers.
+
+A pipeline stops before admitting a dependent when a completed step reports failed quality. Execution success, result conformance, and deliverable quality remain separate facts. An independent recovery has its own receipt and does not replace the failed pipeline result. When delivery is missing or incomplete, report the terminal result and limitation; a successful process exit alone does not establish the requested deliverable.

package/docs/guide/installation-and-lifecycle.md

@@ -3,7 +3,17 @@
 > **Visual blueprint:** The source checkout includes the complete
 > [Installation and Lifecycle Operations visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/lifecycle_blueprint.html).
 
-Clio Coder is designed to be self-contained and platform-compliant. This document outlines the default directory paths, file purposes, permission levels, and lifecycle commands (`install`, `reset`, `upgrade`, and `uninstall`). Clio Coder installs from npm as `@iowarp/clio-coder` (`npm install -g @iowarp/clio-coder`, published since v0.3.0) or from a source checkout with a deterministic local symlink; the CLI classifies both install kinds and `clio-coder upgrade` handles each.
+Clio Coder installs from the npm registry as `@iowarp/clio-coder` using npm,
+pnpm, or Bun, or from a source checkout using the pinned pnpm workflow. The
+[README installation guide](../../README.md#install) covers global installs,
+cached runners (npm exec/npx, pnpm dlx, bunx, and Yarn dlx), release tarballs,
+and manager-specific update and removal commands. All routes require Node.js
+`>=22.19.0`, including installations managed by Bun.
+
+Repository development uses pnpm 10.34.5 and `pnpm-lock.yaml`. Registry
+consumers install the built package and do not need the repository toolchain.
+This guide describes the default directories, file purposes, permissions, and
+lifecycle operations.
 
 ### Optional dependency: the Claude Agent SDK
 
@@ -11,6 +21,8 @@ Clio Coder is designed to be self-contained and platform-compliant. This documen
 
 ```bash
 npm install -g @iowarp/clio-coder --omit=optional
+# Or: pnpm add -g @iowarp/clio-coder --no-optional
+# Or: bun add -g @iowarp/clio-coder --omit=optional
 ```
 
 Measured on Linux x64 with a production install (`--omit=dev`): 387MB across 118 packages with the SDK, 143MB across 109 packages without it. That is 244MB and nine packages saved, a 63% smaller tree, and what remains is fully open-licensed.
@@ -119,7 +131,7 @@ Use the local source installer from the cloned repository:
 ```bash
 git clone https://github.com/iowarp/clio-coder.git
 cd clio-coder
-npm run install:local
+pnpm run install:local
 hash -r
 clio-coder --version
 ```
@@ -127,8 +139,8 @@ clio-coder --version
 `scripts/install-local.sh` is idempotent and auditable:
 
 - verifies `node` satisfies `package.json` `engines.node`;
-- runs `npm ci` unless `node_modules` satisfies the lockfile or `--skip-deps` is passed;
-- runs `npm run build` unless `--no-build` is passed;
+- runs `pnpm install --frozen-lockfile` to sync dependencies with the workspace lockfile unless `--skip-deps` is passed;
+- runs `pnpm run build` unless `--no-build` is passed;
 - verifies `dist/cli/index.js` exists and is executable;
 - creates `${CLIO_CODER_BIN_DIR:-$HOME/.local/bin}` and links `clio-coder` there;
 - warns if that bin dir is not on `PATH`, and warns when another `clio-coder`
@@ -195,11 +207,25 @@ Refreshes state metadata and applies pending lifecycle migrations, which may upd
 ```bash
 clio-coder upgrade [--dry-run] [--channel=<latest|beta|dev>] [--skip-migrations] [--json]
 ```
-The command detects the install method from the running binary. On a source
-checkout it never runs `npm install -g`: it performs its safe local duties
-(migration check, `install.json` refresh) and prints the real update steps,
-`git pull`, `npm run install:local`, `hash -r`. The npm reinstall path applies
-only to a genuinely npm-installed binary.
+On a source checkout, the command applies pending migrations, refreshes
+`install.json`, and prints the source update steps (`git pull`,
+`pnpm run install:local`, `hash -r`). An npm global installation can be
+reinstalled through npm when a newer version or pending work requires it.
+
+For pnpm, Bun, Yarn, repository-local, and cached installations, first update
+with the package manager that owns that installation, then run:
+
+```bash
+clio-coder upgrade --post-install
+clio-coder doctor
+```
+
+`--post-install` applies local migration and metadata checks without querying
+the registry or reinstalling a package. Its `--dry-run` previews only those
+local operations. Automatic package replacement without this flag currently
+assumes npm for packaged installations; use the owning manager's removal
+command as well. Package removal preserves Clio's user configuration and
+sessions; the uninstall operation below deliberately removes those roots.
 
 #### Current migration contract
 

package/docs/guide/proactive-memory.md

@@ -560,7 +560,7 @@ The source-level harness remains available to a runner adapter, and the eval
 platform remains active. Its former dedicated contract test was retired, and
 the current test tree has no direct reference to `runProactiveMemoryEval`.
 There is therefore no maintained direct test coverage or standalone
-`npm run test:file` invocation for this harness. Treat a live comparison as an
+`pnpm run test:file` invocation for this harness. Treat a live comparison as an
 explicit measurement campaign.
 
 For a live local comparison, an adapter should route only the `llm` variant

package/docs/guide/skills-marketplace.md

@@ -18,7 +18,7 @@ This is a tool-admission boundary, not an operating-system sandbox. Shell inspec
 There is one source, `discoverMarketplaceSkills()` in `src/domains/resources/skills/marketplace.ts`, and it reads two kinds of real local data:
 
 1. **A catalog directory** of actual `SKILL.md` packages. Resolution order: `CLIO_CODER_SKILL_CATALOG_DIR`, then a `skills/` directory in the working tree when it holds packages, then the `skills/` catalog the installed clio-coder package carries. Metadata comes from the packages themselves through the skill loader, so a row's version, category, and audit state are the package's own.
-2. **A JSON index** whose entries name a `sourceUrl` that `clio-coder skills install` accepts. Resolution order: `CLIO_CODER_SKILL_MARKETPLACE_INDEX`, then `<configDir>/skill-marketplace.json`, then the package's own `skills/skill-marketplace.json`. `npm run skills:pin` publishes that file's `version`, `audit`, and `category` fields.
+2. **A JSON index** whose entries name a `sourceUrl` that `clio-coder skills install` accepts. Resolution order: `CLIO_CODER_SKILL_MARKETPLACE_INDEX`, then `<configDir>/skill-marketplace.json`, then the package's own `skills/skill-marketplace.json`. `pnpm run skills:pin` publishes that file's `version`, `audit`, and `category` fields.
 
 The package fallbacks mean a fresh npm install has a marketplace with no configuration: `clio-coder skills search grill` lists `grill-me` from the shipped catalog, `clio-coder skills install grill-me` copies it out of the package into `.clio-coder/skills/`, and `/skill grill-me` offers that install before running. The shipped catalog is a marketplace source only, never a discovery root: nothing from it is loadable until the operator installs it, which keeps the install-then-activate contract and the per-skill scope choice in the operator's hands.
 
@@ -72,7 +72,7 @@ Hub and marketplace behavior.
 
 ## Remote entries and overlays
 
-Some skills are worth carrying in the catalog without vendoring their content. `skills/remote.yaml` lists them: each entry names a skill, its category, a `sourceUrl` that must be a GitHub tree URL at a pinned tag, an `overlay` package inside the catalog, and an optional `exclude` list of upstream top-level members. `npm run skills:pin` publishes such an entry into `skills/skill-marketplace.json` with `origin: "remote"`, the upstream URL as its `sourceUrl`, and the `overlay` and `exclude` fields attached. The overlay's `SKILL.md` is pinned in `skills/registry.yaml` like every other catalog skill, so `npm run skills:check` fails when it drifts.
+Some skills are worth carrying in the catalog without vendoring their content. `skills/remote.yaml` lists them: each entry names a skill, its category, a `sourceUrl` that must be a GitHub tree URL at a pinned tag, an `overlay` package inside the catalog, and an optional `exclude` list of upstream top-level members. `pnpm run skills:pin` publishes such an entry into `skills/skill-marketplace.json` with `origin: "remote"`, the upstream URL as its `sourceUrl`, and the `overlay` and `exclude` fields attached. The overlay's `SKILL.md` is pinned in `skills/registry.yaml` like every other catalog skill, so `pnpm run skills:check` fails when it drifts.
 
 `archify` is the worked example. Its entry points at `https://github.com/tt-a1i/archify/tree/v2.16.0/archify`, overlays `skills/planning/archify`, and excludes `test` and `package-lock.json`. Running `clio-coder skills install archify --project` clones that tag, drops the excluded members, copies the overlay over the clone so Clio's wrapper `SKILL.md` replaces the upstream one, validates the shaped tree, and swaps it into `.clio-coder/skills/archify/` with the usual provenance stamps. The renderer, its schemas, and its brand-mark notices come from upstream at install time and never enter the npm tarball. The wrapper omits upstream's update-awareness step on purpose: that step performs a network request during a chat turn, and no Clio chat turn depends on the network.
 
@@ -80,6 +80,14 @@ Discovery treats the overlay folder as part of the remote entry rather than as a
 
 Two operational notes. A copy dropped into a project-scope `.claude/skills/archify` is a compat import and stays untrusted until `integrations.projectResources.trustProjectImports` is on; install through Clio to get a trusted, provenance-stamped copy. And since the skill's authoring loop is several `bash` calls (validate, deliver, verify), `auto-edit` is the sensible permission posture for a mapping session; full manual approval works but prompts on every command.
 
+Architecture mapping through Archify follows a structured pipeline across distinct stages: deterministic structural seed generation (`clio-coder context map`), model-authored refinement, deliverable validation (`validate`, `deliver`, profile checks, and Clio verifiers), and review. Clio derives the deterministic architecture seed from the structural codewiki without model calls; Archify validates and renders the model's semantic refinements. Standard validation checks schema conformance and layout composition, while verification commands check path and symbol citations against the workspace. Mechanical validation passes do not establish semantic claims or visual layout quality: source review assesses semantic claims, while visual review in a browser assesses layout presentation. Custom model-authored maps can remain layout-invalid until iteratively refined.
+
 ## Publishing a skill
 
-Add a directory under `skills/<category>/<name>/` (or `skills/<name>/`) in the repo containing a `SKILL.md` with `name` and `description` frontmatter. The directory name must match `[A-Za-z0-9][A-Za-z0-9._-]*`. Run `npm run skills:pin` to republish `skills/skill-marketplace.json`, which is the index consumers point `CLIO_CODER_SKILL_MARKETPLACE_INDEX` at or copy to `<configDir>/skill-marketplace.json`. Scientific and niche coding domains are the marketplace's focus; see the existing `skills/` tree for the house format.
+Add a directory under `skills/<category>/<name>/` (or `skills/<name>/`) in the repo containing a `SKILL.md` with `name` and `description` frontmatter. The directory name must match `[A-Za-z0-9][A-Za-z0-9._-]*`. Run `pnpm run skills:pin` to republish `skills/skill-marketplace.json`, which is the index consumers point `CLIO_CODER_SKILL_MARKETPLACE_INDEX` at or copy to `<configDir>/skill-marketplace.json`. Scientific and niche coding domains are the marketplace's focus; see the existing `skills/` tree for the house format.
+
+## Matching and offers
+
+Authored whole-phrase triggers rank before incidental description or name overlap. Matching remains lexical: interactive offer guidance asks the model to check installed alternatives and relevance before presenting an offer. A match does not guarantee that a model will offer or use the skill.
+
+Interactive offers require a bound operator answer before installation. Headless runs emit a passive installation hint; that reminder opens no interview and performs no installation or activation. Installing a skill makes it discoverable; listing it or supplying an explicit skill path makes it available, while loading its body remains subject to activation policy. At `read-only` and `suggest`, activation requires an operator request; `auto-edit` and `full-auto` may activate installed skills. A suggestion alone continues the task without activation.

package/docs/guide/tool-usage.md

@@ -237,7 +237,7 @@ Dispatches one or more tasks to Clio fleet agents and returns per-run receipt su
 Arguments:
 
 - `task` (required for the singular form unless `list:true`). One worker assignment/instruction string. It is distinct from briefing.
-- `tasks` (required for the batch form unless `list:true`). Array of task strings or `{task, agent, target, model, node, briefing, intent, gate, budget, worktree}` objects. Per-item fields override the top-level defaults below; `persona`, `tool_profile`, `cwd`, and `apply` come from the batch defaults (an item that carries one is still honored, but the schema no longer advertises them per item). The `intent` and `budget` schemas are serialized once under `$defs` and referenced from the top level and from each item. Supplying both `task` and `tasks` is an error.
+- `tasks` (required for the batch form unless `list:true`). Array of task strings or `{task, agent, target, model, node, briefing, intent, gate, budget, worktree, result_summary_max_bytes}` objects. Per-item fields override the top-level defaults below; `persona`, `tool_profile`, `cwd`, and `apply` come from the batch defaults (an item that carries one is still honored, but the schema no longer advertises them per item). The `intent` and `budget` schemas are serialized once under `$defs` and referenced from the top level and from each item. Supplying both `task` and `tasks` is an error.
 - `mode` (optional). `parallel` (default) runs items concurrently; `sequential` runs them one at a time, each completing before the next dispatches. `pipeline`, `compete`, and `council` select their named topologies. A single ordinary task always runs down the sequential path.
 - `roster` (council only). Names one `fleet.rosters` entry. Supply exactly one of `roster` or `members`.
 - `members` (council only). Supplies two to five inline `{label,target,model?,thinking?}` entries.
@@ -258,6 +258,7 @@ Arguments:
 - `intent` (object, top-level default or per-task override, and the default way to dispatch). Declares `read_roots`, `write_roots`, `relevant_paths`, `expected_outputs`, and `verification`. Path arrays contain normalized repository-relative POSIX paths. Verification entries contain a declared `check` id and optional `timeout_ms`; ids are resolved from package scripts and `.clio-coder/verifiers.yaml` before approval. Checks are ids, not shell commands. Declared paths select the project rules that apply to them and pin worker context; omitting `intent` falls back to reading path-like tokens out of the task and briefing, which can miss an applicable rule. In a batch, per-task `intent` shallow-merges over the top-level object and is then checked against it as a ceiling: a task may narrow the shared scope and is refused with `intent_scope_widening` if it reaches outside. Declaring `write_roots` that disagree with a legacy `writeRoots`, an `expected_outputs` entry outside every declared write root, or an `intent.version` other than 2 are each terminal refusals carrying a stable reason code. See [dispatch-typed-intent.md](../architecture/dispatch-typed-intent.md).
 - `gate` (optional string, top-level default or per-task override). Exact shorthand for `intent.verification=[{check: gate}]`. Supplying it together with `intent.verification` is refused.
 - `max_output_bytes` (optional). Summary byte budget; default 20000, split across runs with at least 1024 bytes each.
+- `result_summary_max_bytes` (optional integer between 1 and 32768, top-level default or per-task override). Sets the inline summary byte allowance for `mutation-report` contracts (default 16384 bytes). A top-level batch default is inherited by mutating tasks and safely ignored by non-mutation steps; setting an explicit per-task `result_summary_max_bytes` on a non-mutation step fails validation before model dispatch. Planner and tool-budget estimates are advisory during execution rather than automatic hard aborts; caller `timeout_ms` and operator cancellation remain authoritative.
 
 Argument tolerance: `tasks` sent as a JSON string is parsed and a single object or bare string is wrapped into an array. The top-level singular `task` is first-class. Briefing-only calls fail with guidance that briefing is context and cannot replace a task.
 
@@ -308,10 +309,12 @@ Arguments:
 
 ### Project verifier catalog
 
+Repository script checks require one-shot operator confirmation or an approved safety command declaration. Committing a verifier catalog defines the available checks; it does not grant execution authority.
+
 Projects may commit a versioned executable catalog at `.clio-coder/verifiers.yaml`:
 
 ```yaml
-version: 1
+version: 2
 checks:
   - id: rust-workspace
     description: Run the Rust workspace tests
@@ -319,9 +322,29 @@ checks:
     cwd: .
     timeoutMs: 600000
     tags: [rust, test]
+  - id: grid-metadata
+    description: Compare the regional grid statistics against the reference
+    kind: numeric-compare
+    command: [python, tools/grid_stats.py, out/region_west.nc]
+    reference: tests/reference/region_west.json
+    tolerance: { relative: 1.0e-6, ulp: 4 }
+    cwd: .
+    timeoutMs: 120000
+    tags: [scientific, netcdf]
+  - id: solver-time
+    description: Keep the solver inside its wall-time budget
+    kind: perf-budget
+    command: [python, tools/solve.py, --small]
+    baseline: .clio-coder/baselines/solver-time.json
+    tolerance: { relative: 0.25 }
+    cwd: .
+    timeoutMs: 600000
+    tags: [scientific, performance]
 ```
 
-Version 1 is strict. Every root and check field shown above is required, unknown fields fail, and duplicate IDs fail. A project ID uses lowercase letters, digits, `.`, `_`, `:`, or `-`, begins with a letter or digit, and is at most 64 UTF-8 bytes. `frontend` is reserved. Descriptions are trimmed single-line text capped at 512 bytes. `command` is a nonempty argv array with at most 64 entries and 4096 bytes per entry. A shell command string is invalid, and explicit shell executables such as `sh`, `bash`, `pwsh`, and `cmd` are rejected. `cwd` is a repository-relative existing directory capped at 512 bytes; absolute paths, `..` escapes, and symbolic-link escapes fail. `timeoutMs` is a positive integer capped at 900000. A check may carry at most 16 distinct lowercase tags of at most 32 bytes each. The whole file is capped at 262144 bytes and may contain at most 128 checks. YAML aliases are disabled.
+Every check has a `kind`, absent or `command` by default. A version 1 file still loads and every check there is `kind: command`; the kind fields require `version: 2`. `kind: command` reads the exit code. `kind: numeric-compare` runs the command, parses its stdout as a JSON object of `string -> number | number[]`, and judges it against `reference` (a repository-relative JSON file of the same shape) under `tolerance`, which names at least one of `relative`, `absolute`, or `ulp`; a value passes only when every named tolerance holds, a key missing on either side fails with the key named, arrays compare elementwise and fail on length mismatch, and `NaN` or infinity fails. `kind: perf-budget` runs the command and judges the wall time the harness measured against either `budget: {wallTimeMs, tolerance?: {relative}}` or `baseline`, a repository-relative JSON `{wallTimeMs}` that `clio-coder verifiers baseline <id>` records from one clean run, with an optional `tolerance: {relative}` of headroom over it. Exactly one of `budget` and `baseline` is present. A command that exits non-zero, times out, or is aborted fails before any judgement. Both kinds record a structured `report` on the `verify` result details and on the host-verification check of a dispatch receipt (per-key worst deviation and the failed tolerance, or measured time, effective budget, and ratio); a failing judgement is a check failure, not a new evidence category.
+
+Version 2 keeps version 1's strictness. Every root and check field shown above is required, unknown fields fail, and duplicate IDs fail. A project ID uses lowercase letters, digits, `.`, `_`, `:`, or `-`, begins with a letter or digit, and is at most 64 UTF-8 bytes. `frontend` is reserved. Descriptions are trimmed single-line text capped at 512 bytes. `command` is a nonempty argv array with at most 64 entries and 4096 bytes per entry. A shell command string is invalid, and explicit shell executables such as `sh`, `bash`, `pwsh`, and `cmd` are rejected. `cwd` is a repository-relative existing directory capped at 512 bytes; absolute paths, `..` escapes, and symbolic-link escapes fail. `timeoutMs` is a positive integer capped at 900000. A check may carry at most 16 distinct lowercase tags of at most 32 bytes each. The whole file is capped at 262144 bytes and may contain at most 128 checks. YAML aliases are disabled.
 
 Provider IDs share one namespace. If a catalog ID collides with a discovered package script, listing and execution fail and identify both source files. Catalog parsing also fails closed before any package or project check runs.
 
@@ -348,8 +371,11 @@ clio-coder verifiers author
 clio-coder verifiers author --exclude cmake-build-debug --rename go-test=go-suite
 clio-coder verifiers author --dry-run go-suite --yes
 clio-coder verifiers validate
+clio-coder verifiers baseline solver-time
 ```
 
+`author` also lists one incomplete `numeric-compare` check for every validation-contract artifact that declares `numerical_tolerances`, with the reference and tolerance filled in and the exact `verifiers add` line to complete; the command is the operator's to supply, so the proposal never enters the catalog on its own. `baseline <id>` runs a `perf-budget` check once and writes its wall time to the check's `baseline` path; a failing or timed-out command records nothing.
+
 `validate` reads the committed file with the same parser used by `verify()`. `dry-run <id>` is an explicit request to execute one admitted check through the production `verify` path. `author --dry-run <id> --yes` writes only after confirmation and starts the selected dry run only after the write is accepted by production discovery.
 
 Later changes use the same preview and confirmation boundary. `edit` preserves the ID unless `rename` is requested. Renames and additions reject collisions with catalog IDs and active package-script IDs. Removals state that the deleted command will no longer be executable through catalog authority. Generated IDs are stable for a stable ordered signal set; a collision receives the first available deterministic `-2`, `-3`, and later suffix.
@@ -362,7 +388,7 @@ clio-coder verifiers rename validate-grid validate-regional-grid --yes
 clio-coder verifiers remove validate-regional-grid --yes
 ```
 
-The `add` command is the explicit path for an unsupported or ambiguous project. `--command` must be a JSON argv array, so manual entry still cannot turn a shell command string into executable catalog authority.
+The `add` command is the explicit path for an unsupported or ambiguous project. `--command` must be a JSON argv array, so manual entry still cannot turn a shell command string into executable catalog authority. `--kind numeric-compare` takes `--reference <path>` and `--tolerance '<json>'`; `--kind perf-budget` takes either `--budget-ms <n>` with optional `--budget-relative <r>` or `--baseline <path>` with optional `--tolerance '{"relative": r}'`. `edit` accepts the same options to change a check's kind.
 
 `verify(check="frontend", path=<file>)` validates an HTML, CSS, or JavaScript artifact without shell access. The path must stay inside the workspace root and end in `.html`, `.htm`, `.css`, `.js`, `.mjs`, or `.cjs`. Checks per type: HTML tag balance (comment-aware, HTML5 optional end tags honored), inline and referenced script syntax (classic scripts parsed in-process, modules via `node --check`), inline and linked CSS brace/string/comment balance, local script and stylesheet references resolved and existence-checked (external and root-relative references are skipped), and an optional headless browser load. `browser="auto"` warns when no chromium/chrome/edge executable is on PATH, `"required"` fails, `"off"` skips. Each check reports pass, warn, fail, or skip; any fail makes the whole result an error. `details = {action: "verify", check: "frontend", path, browserMode, status, checks}`.
 
@@ -421,7 +447,7 @@ bundled Markdown tree under `docs/` plus README.md, CHANGELOG.md, and
 CLIO-CODER.md, indexed as heading-delimited sections with light stemming, Clio
 vocabulary aliases, phrase boosts, and BM25-style body scoring. The JSON payload carries `corpus`, the expanded `terms`, and ranked `results` with `file`, `heading`, `breadcrumb`, `anchor`, `lines`, `snippet`, `score`, `coverage`, `matchedTerms`, and `signals`, plus an `omitted` count. Follow the `followUp` guidance: read the cited file and line range when you need the full section. Empty results are still valid JSON with `next` populated (the closest vocabulary expansion, or `query=overview`). 16KB cap; an oversize payload is replaced by the parseable JSON stub. The old `docs_search` `file` filter was dropped in the consolidation. Omitting `query` returns the corpus listing (the file set plus doc and section counts, the same `corpus` shape a search carries) so the model can pick a term without wasting a round on a `requires query` error.
 
-`scope="skills"` with no `name` lists installed skills with descriptions; the listing asks the model to match the current task against the catalog and, on a fit, to open its reply with `Suggested skill: /skill <name>` (a comma-separated sequence when skills compose) and wait for the operator. Loading a body is policy-gated: a skill loads only after an explicit `/skill <name> [task]` operator request, including one picked from the Skills Hub, and recipe-bound workers may load only their declared skills. A load attempt without a pending request is denied with the model's compliant next move spelled out: do not retry, open the reply with the `Suggested skill: /skill <name>` line and wait for the operator, or continue without skills. On the first substantive turn of a session with model-visible skills installed, a once-per-session middleware reminder in the user message teaches the same protocol. A pending request's task text is surfaced with the body. Marketplace-installed skills are drift-checked against their pinned hash; a mismatch annotates the result with a `skill_drift` warning but never blocks. 50KB cap; a truncated body offloads in full.
+`scope="skills"` with no `name` lists installed skills with descriptions. A matching suggestion uses `Suggested skill: /skill <name>` and continues the task without activating a skill. At `read-only` and `suggest`, loading requires an explicit operator request; at `auto-edit` and `full-auto`, policy permits activation of installed skills without that request. Recipe-bound workers may load only their declared skills. Installation, availability, and activation are separate: even `full-auto` requires a bound operator acceptance for a marketplace installation. A pending request's task text is surfaced with the body. Marketplace-installed skills are drift-checked against their pinned hash; a mismatch annotates the result with a `skill_drift` warning but never blocks. 50KB cap; a truncated body offloads in full.
 
 ```text
 context(scope="workspace")
@@ -627,6 +653,58 @@ panes(action="open", preset="logs")
 panes(action="close", target="all")
 ```
 
+## evidence: inspect canonical evidence and trust status
+
+Reads evidence bundles as JSON. Source: `src/tools/evidence.ts`. Read class; sequential, because `run` mode may materialize a bundle under Clio's data directory. It shares the inventory and trust projections behind `clio-coder evidence inventory` and `clio-coder evidence inspect`, so the model and the operator read the same record.
+
+Arguments:
+
+- `mode` (required). `list`, `inspect`, or `run`.
+- `id` (required for `inspect`). An evidence bundle id.
+- `runId` (required for `run`). A dispatch run id; the bundle is built first when none exists.
+
+`list` returns the bounded newest-first inventory: provenance, tags, totals, and a worst-run trust verdict per bundle. `inspect` returns the bundle overview, the per-run trust axes and verdict, the gate decisions, and the findings. `run` resolves `run-<runId>` and builds the bundle when it is absent; a run with no ledger row is reported absent with `artifactAbsent: true` in the details. Results are capped at 16KB, and a truncated result stays valid JSON with a `preview`. Provenance requires this tool and Verifier may use it.
+
+```text
+evidence(mode="list")
+evidence(mode="inspect", id="run-r-42")
+evidence(mode="run", runId="r-42")
+```
+
+## limitation: record what a turn could not verify
+
+Records a typed limitation receipt for the finish contract. Source: `src/tools/limitation.ts`. Read class; parallel. The tool is pure: it touches no filesystem and runs no shell, so the successful receipt in the session ledger is its whole effect.
+
+Arguments:
+
+- `scope` (required). What could not be verified, in one sentence.
+- `reason` (required). `no-runner`, `blocked`, `out-of-scope`, `environment`, or `other`.
+- `paths` (optional). Repository-relative paths left unverified.
+
+Call it once, before the final reply, when files changed and validation could not run. The finish contract accepts a successful `limitation` receipt inside the same window as the mutation scan in place of validation evidence. A rejected call (empty scope, unknown reason) leaves no receipt and does not count, and the assistant's prose never does. The six mutating recipes carry the tool and the operating contract tells the model to call it; see [the finish gate](../architecture/safety-model.md#the-finish-gate-and-re-prompt-behavior).
+
+```text
+limitation(scope="CUDA kernels changed but no GPU is available here", reason="environment", paths=["src/kernels/solve.cu"])
+```
+
+## decide: record a design decision
+
+Appends the model's own design choice to the session decision board beside operator `ask_user` answers. Source: `src/tools/decide.ts`. Read class; sequential, so two decisions in one batch cannot race the supersede lookup. The call succeeds only in a session with a decision board; a worker's call is refused.
+
+Arguments:
+
+- `key` (required). Stable kebab-case name, at most 64 bytes.
+- `value` (required). The option chosen, at most 512 bytes.
+- `alternatives` (required). One to six rejected options, at most 256 bytes each.
+- `rationale` (required). Why the choice won, at most 1024 bytes.
+- `label` (optional). Short title, at most 128 bytes.
+
+The call appends one `decisionLedger` entry with `origin: "agent"` and returns the decision ref `<interviewId>/<key>`. A repeat key supersedes the earlier agent decision with the new rationale as its correction; an operator decision with the same key is never overwritten and the call fails. Dispatch seals every active ref onto the run request, envelope, and receipt, and Clio-controlled commits carry one `Clio-Decision:` trailer per ref; see [commit provenance](../process/git-commit-provenance.md).
+
+```text
+decide(key="cache-key-shape", value="capability tuple", alternatives=["node id"], rationale="matches the existing buckets and survives fleet changes", label="Cache key")
+```
+
 ## ask_user: host-owned operator interviews
 
 Runs a host-owned interactive interview or single-question prompt with the operator, recording decisions and/or free-form answers. Source: `src/tools/ask-user.ts`. Read class; sequential.
@@ -674,3 +752,7 @@ artifact(kind="plan", content="# Migration plan\n\n## Step 1 ...")
 artifact(kind="report", title="Benchmark results", path="docs/reports/bench.md", content="...")
 artifact(kind="review", content="# Review: toolkit-v2\n\n## Findings ...")
 ```
+
+## Headless declared verifier commands
+
+Declared checks still pass through the conservative action classifier and autonomy policy. A recognized `python` or `python3` command resolved through PATH can use an operator-prepared virtual environment, for example `python -m pytest` with the intended environment already on PATH. An absolute interpreter path requires confirmation; a headless run cannot answer it. Declaring a check does not bypass that gate. Prepare the environment before the run and inspect actual verifier receipts before claiming edit-and-verify success.

package/docs/history/config-knobs-audit.md

@@ -34,7 +34,7 @@ Every runtime-tunable value needs both halves; the pair is one knob, not two. Th
 | `CLIO_CODER_MAX_TOOL_CALLS` | 50 | `src/engine/loop-guard.ts` → `src/engine/worker-runtime.ts` | Worker lifetime tool-call cap for a dispatched run. Different axis than the orchestrator budget despite the near-identical name. |
 | `CLIO_CODER_MAX_DISPATCH_RUNS` | 1000 | `src/domains/dispatch/state.ts` | Dispatch run-ledger retention cap. |
 | `CLIO_CODER_MAX_CONTEXT_TOKENS` | unset | `src/domains/providers/runtime-resolution.ts` | Context-window override for local runtimes. Also set internally by `clio-coder run --max-context-tokens` (see §6). |
-| `CLIO_CODER_KV_CACHE_MODE` | unset | retired | KV-cache quantization mode. Also set internally by the former `clio-coder run --kv-cache-mode` path. |
+| `CLIO_CODER_KV_CACHE_MODE` | unset | retired | KV-cache quantization mode. Also set internally by the former `clio-coder run` path. |
 | `CLIO_CODER_SAMPLING_OVERRIDES` | unset | `src/engine/apis/sampling-overrides.ts` | JSON sampling-parameter override. Set internally by print-mode sampling flags. |
 | `CLIO_CODER_READ_MAX_BYTES` | 51200 (50 KB) | `src/tools/read.ts` | Per-call byte cap for the read tool. |
 | `CLIO_CODER_OBSERVATION_TURN_BUDGET_BYTES` | 196608 (192 KB) | `src/tools/observation.ts` | Shared per-turn byte pool across all observation tools. |
@@ -93,7 +93,7 @@ All default off; all enabled with `1`.
 
 ## 6. CLI flags that bridge through env vars (Pre-consolidated State)
 
-`clio-coder run --max-context-tokens` and `--kv-cache-mode` (`src/cli/run.ts:143-234`) and the print-mode sampling flags (`src/cli/modes/print.ts:306-333`) do not plumb their values through function arguments. They mutate `process.env` (`CLIO_CODER_MAX_CONTEXT_TOKENS`, `CLIO_CODER_KV_CACHE_MODE`, `CLIO_CODER_SAMPLING_OVERRIDES`), run the command, then restore the previous value in a `finally`. The env var is the transport between the CLI layer and deep engine code.
+`clio-coder run --max-context-tokens` (`src/cli/run.ts:143-234`) and the print-mode sampling flags (`src/cli/modes/print.ts:306-333`) do not plumb their values through function arguments. They mutate `process.env` (`CLIO_CODER_MAX_CONTEXT_TOKENS`, `CLIO_CODER_KV_CACHE_MODE`, `CLIO_CODER_SAMPLING_OVERRIDES`), run the command, then restore the previous value in a `finally`. The env var is the transport between the CLI layer and deep engine code.
 
 ## 7. Script- and benchmark-only vars (Pre-consolidated State)