@iowarp/clio-coder 0.4.4 → 0.4.5

package/docs/guide/commands-and-modes.md

@@ -33,7 +33,7 @@ For process exit codes, stdout deliverable guarantees, and machine-readable JSON
 | `clio-coder config [inspect] [--json]` | Print the effective customization graph across settings, context files, rules, skills, prompts, agents, extensions, safety, memory, hooks, and operator profile. |
 | `clio-coder targets [--json] [--probe] [--target <id>]` | List configured targets, health, auth, runtime, model, and capabilities. |
 | `clio-coder targets add` | Add a target interactively or through configure flags. |
-| `clio-coder targets use <id> [--model <id>] [--orchestrator-model <id>] [--background-model <id>] [--fleet-target <id>] [--fleet-model <id>]` | Point the orchestrator at one target. Without `--fleet-target` the fleet default follows it; with `--fleet-target` the fleet runs on a different node. |
+| `clio-coder targets use <id> [--model <id>] [--orchestrator-model <id>] [--background-model <id>] [--fleet-target <id>] [--fleet-model <id>]` | Select the named roles only when any role flag is present. `--background-model` selects memory; `--orchestrator-model` selects chat; `--fleet-model` or `--fleet-target` selects fleet. Other roles and thinking levels are preserved. Without role flags, chat and fleet use the target default (or shared `--model`), while memory is preserved. Confirmation names only roles whose settings changed. Model IDs must match a nonempty discovered or cached inventory exactly; unavailable discovery is reported explicitly. |
 | `clio-coder targets fleet [--json]` | List the configured fleet profiles with their target, runtime, model, and thinking level. `targets workers` is an accepted alias. |
 | `clio-coder targets profile list\|set\|remove\|rename\|bind\|unbind\|bindings` | Manage named fleet profiles and agent bindings. `clio-coder targets profile <name> <id>` is the short form of `profile set`, and `targets worker` is an accepted alias for `targets profile`. |
 | `clio-coder targets convert <id> --runtime <runtimeId>` | Convert older local target definitions to a runtime-specific target. |
@@ -86,9 +86,10 @@ For process exit codes, stdout deliverable guarantees, and machine-readable JSON
 | `clio-coder context` | Show project context status, preload class, codewiki freshness, and the codewiki digest when present. |
 | `clio-coder context init [--preview] [--heuristic] [--yes] [--json] [--adopt] [--global] [--propose\|--apply\|--rewrite] [--target <id> [--model <id>] [--thinking <level>]]` | Explore the repo and bootstrap or update project context: `CLIO-CODER.md`, `.clio-coder/codewiki.json`, and `.clio-coder/state.json`. |
 | `clio-coder context refresh [--wiki]` | Rebuild the codewiki and state without touching `CLIO-CODER.md`; with `--wiki`, update an existing Markdown wiki. |
-| `clio-coder context wiki [--update] [--status] [--depth auto\|simple\|medium\|detailed] [--target <id>] [--model <id>] [--thinking off\|low\|medium\|high]` | Generate, update, or inspect the agent-authored Markdown wiki under `.clio-coder/wiki/`. |
+| `clio-coder context wiki [--update\|--retry-pending] [--status] [--depth auto\|simple\|medium\|detailed] [--target <id>] [--model <id>] [--thinking off\|low\|medium\|high]` | Generate, update, or inspect the agent-authored Markdown wiki under `.clio-coder/wiki/`. |
 | `clio-coder context reset [--all] [--yes]` | Clear accumulated project context artifacts; `--all` also removes `CLIO-CODER.md`. `--yes` (or `-y`) answers every confirmation and is required when stdin is not a terminal. |
 | `clio-coder context index [--json]` | Build the structural codewiki index without model calls; writes `.clio-coder/codewiki.json` and `.clio-coder/state.json` and prints coverage plus a structural hash. |
+| `clio-coder context map [--out <path>] [--json]` | Write an archify architecture seed from the structural index without model calls. |
 | `clio-coder context replay (--sessions <path>... \| --synthetic <ids>) [--policies <ids>] [--budgets <tokens>] [--threshold <ratio>] [--target <ratio>] [--protect-last-turns <n>] [--min-evictable-tokens <n>] [--seed <n>] [--no-filter] [--json <out>] [--md <out>]` | Replay working-set policies over Clio session ledgers or the seeded procedural corpora and report retention, precision, token savings, recall cost, cold-prefix cost, saturation, and summary headroom. |
 | `clio-coder context working-set --session <id\|path>` | Inspect one session's durable working-set fold and path-index summary without modifying the ledger. |
 
@@ -137,6 +138,7 @@ A headless turn (`clio-coder run`) starts a fresh session unless `--session <id>
 - `--session` and `--continue` are mutually exclusive. Specifying both causes the invocation to fail with exit code 2 before execution.
 - Session continuity options apply strictly to main-agent execution. They are non-applicable to `--agent` fleet dispatches because dispatched agents execute in isolated worker processes with independent transcripts; specifying session flags alongside `--agent` exits with code 2.
 - A named session that cannot be resumed (such as an unknown session ID or unreadable history) fails the run with exit code 2 before any model call is initiated.
+- An explicit `--target <id>` resolves targets from layered project settings (`.clio-coder/settings.yaml`, `.clio-coder/settings.local.yaml`) as well as user settings before applying target-not-found validation.
 - The session ID is discoverable via the `session` event when running under `--json` mode and on stderr via the `clio-coder run: session <id>` line in text mode. Standard output remains reserved for the assistant answer alone.
 
 ### JSON Event Streaming and Wire Projection Promise
@@ -213,11 +215,7 @@ must record a passing validation receipt for every named check or a successful
 completion note alone does not satisfy acceptance. `clio-coder tasks list`,
 `hand <uN>`, `done <uN>`, and `drop <uN>` manage the same inbox as `/tasks`.
 
-Retired spellings fail closed and print their exact replacement. In particular,
-`/targets` points to `/settings targets`, `/scoped-models` points to
-`/settings chat model-picker`, and `/library`, `/prompts`, and `/extensions`
-point to the corresponding `/resources` subcommand. They never fall through to
-the model as prompt text.
+Retired spellings are unrecognized commands and use the standard unknown-command diagnostic; they do not print automatic replacement hints. Use supported spellings such as `/settings targets`, `/settings chat model-picker`, and the corresponding `/resources` subcommand. Unrecognized commands are not sent to the model as prompt text.
 
 `/context` with no arguments opens the context-window ledger overlay, including
 the working-set section (policy, evicted items and tokens, events, recalls, churn).
@@ -443,14 +441,7 @@ one or `d` to decline; the overlay reads the report this process already produce
 at boot and never probes on a keystroke. Accepting applies to the live session,
 because `delegation` hot-reloads.
 
-Boot adds at most one line about interop, in the current source shape
-`clio-coder: codex detected on PATH and not configured. Run /interop to review.`
-The `/interop` name is retained only as a retired-command tombstone and answers
-`Use /agents connect.`, so operators can open `/agents connect` directly. The
-hint names only agents that are installed, unconfigured, and undecided, appears
-at most once per set of facts, and is never emitted in headless or ACP mode.
-Declining an agent silences it until its binary version or path changes, at which
-point it becomes a fresh proposal.
+Boot adds at most one line about interop. The current hint can still say `Run /interop to review.`, but `/interop` is unrecognized and receives the standard unknown-command diagnostic. Open `/agents connect` directly. The hint names only agents that are installed, unconfigured, and undecided, appears at most once per set of facts, and is never emitted in headless or ACP mode. Declining an agent silences it until its binary version or path changes, at which point it becomes a fresh proposal.
 
 `clio-coder doctor` reports interop and never proposes anything. It emits one
 `ok` row per detected agent naming its version, its path, and whether it is
@@ -606,14 +597,14 @@ to execute through the existing engine worker path, the sanctioned Claude Code w
 
 | Command | Purpose |
 | --- | --- |
-| `npm run ci` | Local and GitHub PR gate: typecheck, lint, skills pin check, build, the deterministic test suite, and the trace-viewer suite. |
-| `npm run ci:release` | Maintainer release gate: `npm run ci`, then the `check-release` dist and packaging audit. |
-| `npm run typecheck` | Strict TypeScript pass. |
-| `npm run lint` | Biome checks plus `scripts/check-hygiene.ts`, which runs the boundary invariants, the skills pin check, and the README and docs drift rules. |
-| `npm test` | Focused contract and smoke files through plain `node --test`. |
-| `npm run build` | Production bundle through `tsup`. |
-| `npm run dev` | `tsup --watch`. |
-| `npm run clean` | Remove `dist/`. |
+| `pnpm run ci` | Local and GitHub PR gate: typecheck, lint, skills pin check, build, the deterministic test suite, and the trace-viewer suite. |
+| `pnpm run ci:release` | Maintainer release gate: `pnpm run ci`, then the `check-release` dist and packaging audit. |
+| `pnpm run typecheck` | Strict TypeScript pass. |
+| `pnpm run lint` | Biome checks plus `scripts/check-hygiene.ts`, which runs the boundary invariants, the skills pin check, and the README and docs drift rules. |
+| `pnpm test` | Focused contract and smoke files through plain `node --test`. |
+| `pnpm run build` | Production bundle through `tsup`. |
+| `pnpm run dev` | `tsup --watch`. |
+| `pnpm run clean` | Remove `dist/`. |
 
 Live provider checks cost tokens or local GPU time and are deliberately not
 part of deterministic CI. Maintainers perform them explicitly against an
@@ -651,6 +642,8 @@ structural hash. The same builder is used by `clio-coder context init`, `clio-co
 refresh`, session freshness checks, tool-demand backfill, and in-session
 incremental updates.
 
+`clio-coder context map` derives an archify architecture specification from the structural index without model calls and writes it to `.clio-coder/artifacts/maps/<repo>.architecture.json` (or `--out <path>`). Map generation reconciles the existing structural index before mapping; missing index refuses, naming `clio-coder context index`. Pinned source citations require that the workspace is clean at repository root and indexed file bytes match current files and Git blobs under a GitHub origin and full `HEAD` revision. Unknown or dirty source states fall back cleanly to usable uncited seeds; `--json` reports path, counts, repository metadata, reconciled index status, and source state (`clean`, `dirty`, or `unknown`). Clio produces the deterministic seed while Archify validates and delivers it. Standard validation checks schema conformance and layout composition, while source review assesses semantic claims and visual review in a browser assesses layout presentation. Custom model-authored maps can remain layout-invalid until refined.
+
 ### Working-set replay
 
 `clio-coder context replay --sessions <path>...` accepts individual session directories,
@@ -702,19 +695,31 @@ matter after the run, so no dispatch writes them. `.clio-coder/wiki/meta.json` r
 the page list, model label, content hash, git head, indexed source-tree hash,
 and the plan.
 
-Each page dispatch is bounded on its own wall clock, and the run is bounded
-between pages. Neither bound loses work: a page that fails or times out is
-recorded as still owed and the run continues to the next one, and every finished
-page is assembled and promoted. When `generation.pagesWritten` is below
-`generation.pagesPlanned`, run `clio-coder context wiki --update` to finish the rest;
-it resumes from the plan rather than starting over.
-
-`clio-coder context wiki --update` requests update mode explicitly. It rewrites the
-pages whose front-matter `sources` git reports as changed since the recorded
-wiki `gitHead`, and leaves the rest alone.
+Ordinary planner, page, and whole-run time and tool estimates are advisory across
+generation, not automatic aborts. An explicit caller deadline (`timeout_ms`) or
+operator cancellation remains authoritative. Failed writers remain pending; admission
+rejection does not consume a writer attempt. When `generation.pagesWritten` is below
+`generation.pagesPlanned`, run `clio-coder context wiki --update` to continue pending pages
+and refresh stale pages based on changed source dependencies, or run `clio-coder context wiki --retry-pending`
+to retry each pending page once, including exhausted pages, without erasing cumulative attempts
+or replanning at the same depth.
+
+Coverage depth is controlled by `--depth auto|simple|medium|detailed` and is harness-owned;
+explicit upgrades and downgrades requeue coverage while retaining existing prose, and
+default retries retain saved depth. Both original writer output and saved pages pass nonmutating
+mechanical validation (missing/escaping paths, invalid line ranges, malformed source/test
+metadata, or empty bodies keep pages pending); mechanical checks do not establish semantic
+accuracy or that the model read the source.
+
+`clio-coder context wiki --update` requests update mode explicitly. It revalidates
+pages against bounded source-byte evidence and recorded source and test dependencies
+rather than assuming unmentioned pages remain fresh. Pages with changed inputs or
+dependencies, as well as pages whose Git evidence is missing, unreadable, or changed,
+are re-queued for generation, while verified up-to-date pages are preserved; it is not a
+promise to overcome exhausted attempts.
 `clio-coder context wiki --status` is read-only: it prints whether wiki metadata is
 present, page count, `updatedAt`, recorded `gitHead`, whether that head differs
-from current `HEAD`, and how many planned pages remain unwritten. It dispatches
+from current `HEAD`, and retained failure diagnostics for unwritten planned pages. It dispatches
 nothing and spends no model tokens.
 
 `clio-coder context refresh` rebuilds only the structural codewiki and state. It does
@@ -825,11 +830,11 @@ All TUI overlays fluidly adapt to narrow terminals down to 40 columns:
 
 | Problem | Try this |
 | --- | --- |
-| `clio-coder: command not found` | Run `npm run install:local`, then `hash -r`; confirm `${CLIO_CODER_BIN_DIR:-$HOME/.local/bin}` is on `PATH`. |
+| `clio-coder: command not found` | Run `pnpm run install:local`, then `hash -r`; confirm `${CLIO_CODER_BIN_DIR:-$HOME/.local/bin}` is on `PATH`. |
 | No model target is available | Run `clio-coder configure`, then `clio-coder targets --probe`. |
 | Local model does not respond | Confirm the runtime is running and the target URL is correct. |
 | Cloud model auth fails | Check `clio-coder auth status <target>` and verify the relevant API key or login flow. |
-| Source changes do not appear | Re-run `npm run build`; linked CLI points at `dist/`. |
+| Source changes do not appear | Re-run `pnpm run build`; linked CLI points at `dist/`. |
 | Session replay looks incomplete | Confirm durable session entries exist for the relevant tool, bash, or display activity. |
 | Doctor reports stale state metadata | Run `clio-coder doctor --fix`; upgrades also refresh install metadata after reinstalling. |
 | You need a clean start | Use `clio-coder reset --state`, `--data`, `--cache`, `--auth`, `--config`, or `--all`. |
@@ -848,3 +853,11 @@ actual behavior. Redact secrets and private repository content.
 > CLI subcommands (`targets use/remove/rename/profile/convert`, `context refresh`,
 > `fleet list/run/status/drain/resume`, `auth login`), passing `--help` prints
 > usage instructions and exits with code 0.
+
+## Operator-task handoff and continuation
+
+`clio-coder tasks hand <uN>` prints the inbox record as JSON on stdout and an actionable pickup prompt on stderr. Submit that prompt to the intended session. Before task work, the model must pick the intended `uN`, confirm its durable session and board linkage, and use the returned `tN`. Handing a task does not itself pick it. Completion should be checked against the linked board and inbox with the actual IDs; manual CLI completion is an operator action, not evidence of model completion.
+
+Acceptance rows labeled Required declare expected checks and timeout limits; they are not pending executions or passing results. Inspect verification receipts for outcomes. Under high rigor, the finish gate requires the applicable passing checks or explicit limitations.
+
+Task-board guidance and ordinary continuation preserve proposal-only scope. Deferred implementation should be blocked or dropped while awaiting an explicit operator go-ahead. A skill-install decision is separate from implementation authorization, and full-auto capability does not expand the task. These are model instructions, not a guarantee of model adherence.

package/docs/guide/configuration-and-targets.md

@@ -52,8 +52,9 @@ From a source checkout:
 ```bash
 git clone https://github.com/iowarp/clio-coder.git
 cd clio-coder
-npm ci
-npm run install:local
+corepack enable pnpm
+pnpm install --frozen-lockfile
+pnpm run install:local
 hash -r
 clio-coder --version
 ```
@@ -1141,3 +1142,7 @@ clio-coder auth status <target-or-runtime>
 ```
 
 When opening issues, include the Clio version, Node version, target id/runtime, model id, whether the live model listing succeeds (or the target probe result), and a redacted receipt or command transcript.
+
+## Explicit Antigravity continuity
+
+Antigravity resumes a conversation only when a caller explicitly supplies its conversation ID through the worker runtime. The dispatch tool exposes no resume argument. A nonempty ID must be at most 4096 UTF-8 bytes and contain no Unicode control characters; it is passed as a literal `--conversation` argument. Clio requires the first init conversation ID to match the requested ID and fails the run if agy starts a different conversation. An absent or empty ID starts fresh. Antigravity runs are never retried automatically.

package/docs/guide/configuration-reference.md

@@ -191,6 +191,7 @@ 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 |
@@ -220,7 +221,10 @@ 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. |  |
@@ -338,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`
@@ -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. |  |
@@ -929,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. |
@@ -1021,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. |
@@ -1048,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. |

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,6 +309,8 @@ 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
@@ -444,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")
@@ -749,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/process/development-pipeline.md

@@ -74,10 +74,10 @@ replace Clio copies without crossing the product boundary:
 
 1. Read the release notes or package changelogs for `pi-ai`, `pi-agent-core`,
    and `pi-tui`.
-2. Run `npm run pi:surface-diff`. A changed or removed symbol that Clio imports
+2. Run `pnpm run pi:surface-diff`. A changed or removed symbol that Clio imports
    is an error; a new export is review input.
 3. Run the focused contracts in the
-   [Pi regression net](../architecture/pi-boundary.md#pi-regression-net), then run `npm run ci`.
+   [Pi regression net](../architecture/pi-boundary.md#pi-regression-net), then run `pnpm run ci`.
 4. Walk Pi's fixed-issue list against the
    [Pi SDK boundary table](../architecture/pi-boundary.md). For every fix in a surface Clio
    still owns, either delete Clio's copy in favor of Pi or add a dated reason
@@ -86,28 +86,28 @@ replace Clio copies without crossing the product boundary:
    worth a Clio ticket.
 
 After review, regenerate `docs/pi-surface.json` with
-`npm run pi:surface-snapshot`, inspect the symbol and signature changes, and
+`pnpm run pi:surface-snapshot`, inspect the symbol and signature changes, and
 commit the dependency pins, snapshot, boundary notes, and proving contracts
-together. `npm run lint` invokes the surface check automatically when the
+together. `pnpm run lint` invokes the surface check automatically when the
 installed Pi versions differ from the checked-in snapshot.
 
 ## Test lanes
 
-`npm test` uses Node's test runner over every `tests/contracts/*.test.ts` and
+`pnpm test` uses Node's test runner over every `tests/contracts/*.test.ts` and
 `tests/smoke/*.test.ts` file, with `tests/harness/tmp-root.ts` preloaded to
 isolate test state. Its `pretest` hook builds `dist/` when the CLI bundle is
 absent. Run one focused file while iterating with:
 
 ```bash
-npm run test:file -- tests/contracts/<name>.test.ts
+pnpm run test:file tests/contracts/<name>.test.ts
 ```
 
 There is no committed weighted-shard or special serial-lane runner. Keep timing
-claims within the focused contract that owns them, and use the full `npm run ci`
+claims within the focused contract that owns them, and use the full `pnpm run ci`
 gate before handoff.
 
 The release smoke script `scripts/smoke-real-home.sh` (invoked via
-`npm run smoke:real-home`) tests booting the built CLI binary against a copy of
+`pnpm run smoke:real-home`) tests booting the built CLI binary against a copy of
 the operator settings in a scratch home. An optional `--strict` flag makes doctor
 exit 1 fail the smoke run on failing rows instead of tolerating fleet state.
 
@@ -143,7 +143,7 @@ or bumped; the milestone closes when the tag is published.
 ## Dogfooding setup
 
 The marketplace copy under `skills/git/` is the committed source of truth,
-pinned in `skills/registry.yaml` by `npm run skills:pin`. Runtime roots are
+pinned in `skills/registry.yaml` by `pnpm run skills:pin`. Runtime roots are
 gitignored, so each developer installs locally:
 
 ```bash
@@ -152,6 +152,6 @@ cp -r skills/git/file-ticket .claude/skills/       # Claude Code
 ```
 
 The other pipeline skills are model-invoked from the marketplace catalog the
-same way. When a skill changes, re-run `npm run skills:pin` and re-copy;
+same way. When a skill changes, re-run `pnpm run skills:pin` and re-copy;
 drift between an installed copy and the pinned hash surfaces a warning at
 activation.

package/docs/process/documentation-guide.md

@@ -138,7 +138,7 @@ have a dedicated blueprint. `docs/html/index.html` groups those counterparts by
 the same Guide, Architecture, Process, and History tree, while a source meta tag
 provides the one-to-one machine-readable mapping. Every mapping must remain
 unique, complete, and free of orphaned Markdown or HTML pages.
-`npm run lint` rejects any absent named blueprint, enforces that mapping, and
+`pnpm run lint` rejects any absent named blueprint, enforces that mapping, and
 compares every extractable `clio-coder <command>` string and `CLIO_CODER_*`
 name in each counterpart.
 
@@ -154,7 +154,7 @@ When a feature changes:
 4. If behavior affects safety, sessions, receipts, prompts, targets, or dispatch, update both README-level user docs and the deeper guide.
 5. Run a lightweight link check for changed Markdown.
 6. For release docs, verify version badges/sections match `package.json` and `CHANGELOG.md`.
-7. Run `npm run lint` to verify Markdown and HTML blueprint parity.
+7. Run `pnpm run lint` to verify Markdown and HTML blueprint parity.
 
 Suggested local link check: