@iowarp/clio-coder 0.4.8 → 0.4.9

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

@@ -21,6 +21,9 @@ For process exit codes, stdout deliverable guarantees, and machine-readable JSON
 | `clio-coder --help [--all]` | Print the command list. `--all` appends every command under `clio-coder dev`. |
 | `clio-coder --api-key <key>` | Override the active target API key for one invocation. |
 | `clio-coder --no-context-files` / `clio-coder -nc` | Skip `CLIO-CODER.md` project-context injection for one invocation. |
+| `clio-coder --with-panes` | Activate guest pane integration for this invocation when Clio is inside a reachable herdr session. |
+| `clio-coder --no-panes` | Keep panes off even when settings turn them on. |
+| `clio-coder --autonomy <level>` | Start this interactive session at `read-only`, `suggest`, `auto-edit`, or `full-auto` without modifying `settings.yaml`. Passing `--autonomy` before a subcommand is refused with exit 2 (`clio-coder run --autonomy` remains the headless form). |
 | `clio-coder --no-skills` | Disable skill discovery for one invocation while still honoring explicit `--skill` paths. |
 | `clio-coder --skill <path>` | Load one explicit skill file or directory for one invocation (repeatable). |
 | `clio-coder configure` | Run the configuration wizard. Ctrl+C reports `configuration cancelled`, writes no target, and exits 130; when first-run onboarding is cancelled, startup stops instead of opening the TUI with no usable target. |
@@ -42,16 +45,19 @@ For process exit codes, stdout deliverable guarantees, and machine-readable JSON
 | `clio-coder auth status [target-or-runtime]` | Inspect auth state. |
 | `clio-coder auth login [target-or-runtime] [--api-key <value>]` | Add credentials through the supported flow. |
 | `clio-coder auth logout [target-or-runtime]` | Remove stored credentials. |
-| `clio-coder doctor [--fix] [--json]` | Diagnose state. Plain `doctor` is read-only and leaves even a partially initialized home byte-for-byte untouched. With `--fix`, create missing structure and templates, repair credential permissions, and refresh install metadata. Settings remain strict; lifecycle migrations belong to `upgrade`, not `doctor --fix`. |
+| `clio-coder doctor [--fix] [--json]` | Diagnose state. Plain `doctor` is read-only and leaves even a partially initialized home byte-for-byte untouched. With `--fix`, create missing structure and templates, repair credential permissions, refresh install metadata, and record fleet preflight results. Settings remain strict; lifecycle migrations belong to `upgrade`, not `doctor --fix`. |
+| `clio-coder mcp list\|trust\|untrust` | List configured MCP servers or manage explicit project trust with `trust <id> [--action-class read\|execute\|unknown]` and `untrust <id>`. |
 | `clio-coder tools list [--json]` | List the pinned external tool registry and whether each program resolves from `PATH`, Clio's vendored data directory, or nowhere. |
 | `clio-coder tools status <id> [--json] [--reset-profile]` | Inspect one registered tool. `--reset-profile` applies only to yazi's generated profile. |
 | `clio-coder tools install <id> [--force] [--json]` | Download the platform asset, verify every declared checksum, and atomically vendor it. |
 | `clio-coder tools remove <id>\|--all [--json]` | Remove Clio-vendored copies without touching a program found on `PATH`. |
 | `clio-coder panes install` | Alias for `clio-coder tools install herdr`. |
 | `clio-coder panes theme` | Print Clio's theme tokens as a herdr `[theme.custom]` block to paste into herdr's `config.toml`; Clio never edits that file itself. See [Panes and the Files Pane](panes-and-files.md). |
-| `clio-coder reset [--state\|--data\|--cache\|--auth\|--config\|--all] [--dry-run] [--force]` | Reset selected Clio Coder state. `--state` is the default level. |
-| `clio-coder uninstall [--dry-run] [--remove-binary] [--force]` | Remove Clio Coder state and print uninstall guidance. |
-| `clio-coder upgrade [--dry-run] [--channel=<latest\|beta\|dev>] [--skip-migrations]` | Refresh state metadata, apply migrations, and update npm installs when applicable. |
+| `clio-coder tasks [list\|add\|hand\|done\|drop]` | List, add, hand, finish, or drop project operator tasks. |
+| `clio-coder verifiers discover\|inspect\|author\|validate\|edit\|dry-run` | Discover, inspect, author, validate, edit, or dry-run project checks. |
+| `clio-coder reset [--state\|--data\|--cache\|--auth\|--config\|--all] [--dry-run] [--force] [--json]` | Reset selected Clio Coder state. `--state` is the default level. |
+| `clio-coder uninstall [--dry-run] [--remove-binary] [--keep-config] [--keep-data] [--force] [--json]` | Remove Clio Coder state and print uninstall guidance. |
+| `clio-coder upgrade [--dry-run] [--channel=<latest\|beta\|dev>] [--skip-migrations] [--json]` | Refresh state metadata, apply migrations, and update npm installs when applicable. |
 | `clio-coder agents [--json] [--all]` | List discovered agent specs. |
 | `clio-coder fleet list\|run\|status\|drain\|resume` | List fleet contracts, run one, show dispatch state, or control admission. `drain` denies new execution starts for up to one hour and preserves running work; `resume` reopens admission immediately. `run <name>` takes `[--var k=v ...]` and `[--json]`; `status`, `drain`, and `resume` each take `[--json]`. |
 | `clio-coder fleet view <runId\|fleetRootId> [--follow]` | Read the append-only run journal after verifying receipt trust. A fleet root prints its durable step index. Without `--follow`, the width-bounded snapshot is plain text with no ANSI control bytes. `--follow` requires an interactive terminal and one run id; `fleet view --help` prints this subcommand's own usage, including `--watch`. |
@@ -173,7 +179,8 @@ The registry table below lists the available interactive slash commands. On a ba
 | `/library` | `/library [inspect \| install \| remove <ref>] [import <path-or-url>] [reload]` | Open the full-screen Library with Skills, Agents, Prompts, Fleets and Plugins tabs. A named reference opens the browser on that row; `install`, `remove` and `import` show a reviewed plan first and write nothing until it is accepted. `reload` refreshes installed recipe resources. Alt+L opens the same browser. |
 | `/skills` | `/skills` | Open the Library on Skills. |
 | `/prompts` | `/prompts` | Open the Library on Prompts. |
-| `/extensions` | `/extensions [reload]` | Inspect harness extensions or reload their hooks and operator runtimes. |
+| `/mcp` | `/mcp [list] \| /mcp trust <id> [class] \| /mcp untrust <id>` | List MCP servers or manage explicit trust for project MCP servers with optional action class |
+| `/extensions` | `/extensions [reload]` | Inspect harness extensions or reload their commands, hooks and operator UI |
 | `/interop` | `/interop` | Inspect another local coding agent and review adoption of supported resources. |
 | `/share` | `/share [runId]` | Share a worker result with the main agent |
 | `/archive` | `/archive export <path> \| /archive import [--dry-run] [--force] <path>` | Export or import a full Clio archive |
@@ -185,10 +192,10 @@ The registry table below lists the available interactive slash commands. On a ba
 | `/agents` | `/agents` | Open the Library on Agents. |
 | `/cost` | `/cost` | Show session token and cost totals |
 | `/context` | `/context compact [instructions] \| /context recall <ref> \| /context init \| /context refresh \| /context reset` | Context hub: window overlay plus compact, recall, init, refresh, and reset |
-| `/fleet` | `/fleet run [--var <key=value>] <name>` | Open Settings → Fleet, or run a fleet contract with an approval preview |
+| `/fleet` | `/fleet [run [--var <key=value>] <name>]` | Open Fleet Runs, or run a fleet contract with an approval preview. Configure fleets with `/settings fleet`. |
 | `/decisions` | `/decisions` | Show settled interview decisions and operator revisions |
 | `/tasks` | `/tasks add [--expect <path>] [--verify <checkId>[:timeoutMs]] <text> \| /tasks hand <id> \| /tasks done <id> \| /tasks drop <id>` | Show the session board or manage project operator tasks |
-| `/memory` | `/memory seed` | Inspect, promote, or seed task memory |
+| `/memory` | `/memory [seed]` | Inspect, promote, or seed task memory |
 | `/view` | `/view [filter] \| /view verify <runId>` | Browse session artifacts and verify receipts |
 | `/panes` | `/panes show <run-or-agent> \| /panes open <preset-or-argv> \| /panes zoom [target] \| /panes close [target]` | Inspect the pane layer, watch a live run in a pane, or open a utility pane (`files`, `logs`, `shell`, `files --once`, or a command); a second open focuses the pane already there |
 | `/files` | `/files [open\|close\|pick]` | Toggle the files pane docked below the session; picks land in the composer as `@` mentions. See [Panes and the Files Pane](panes-and-files.md) |
@@ -198,7 +205,7 @@ The registry table below lists the available interactive slash commands. On a ba
 | `/resume` | `/resume` | Resume a past session |
 | `/new` | `/new` | Start a fresh session |
 | `/handoff` | `/handoff <goal>` | Hand this session's working state to a fresh session for a stated goal |
-| `/tree` | `/tree` | Open session tree navigator |
+| `/tree` | `/tree` | Open session tree navigator. Press `p` to filter by current cwd and `s` to cycle tree order or most recent first. |
 | `/fork` | `/fork` | Fork from an assistant turn |
 | `/export` | `/export [path]` | Export a self-contained HTML transcript by default; a `.md` path writes Markdown |
 
@@ -220,6 +227,14 @@ completion note alone does not satisfy acceptance. `clio-coder tasks list`,
 
 Retired commands are rejected before model submission. Old Library browsing forms, including `/resources`, `/library <kind>` and `/agents connect`, explain the canonical route. Browse with `/library`, `/skills`, `/agents` or `/prompts`; use `/interop` for local-agent adoption and `/extensions` for harness extensions.
 
+In `/library`, `b` switches between Browse packages and Installed entries. Agents and Fleets may show `[plugin]` provider packages with category-specific catalog hints; use Installed to find loaded recipes. Status and footer counts distinguish packages, entries and members with correct singular/plural forms, and do not imply every entry is runnable. `s` chooses User or Project as the destination for package actions; it does not filter the inventory by execution scope. Install, import and removal still require their existing review. Narrow layouts open with the selected detail visible, and Tab toggles it.
+
+Library discovery notices have their own searchable `n` view and independent count. From browse focus, `n` opens notices or returns from notices to resources. While search has edit focus, `n` types into the filter. Esc clears a filter or leaves search focus before returning to the parent browser. Your resource selection, filter draft, browse focus and detail position survive the visit. Notices are evidence to inspect and have no package action. Enter opens members only for a package that supports that operation; otherwise it opens detail.
+
+`/view [filter]` searches resource identity and available provenance with case-insensitive literal terms. Every whitespace-separated term must occur; fuzzy abbreviations do not match. A category prefix such as `dispatch:<runId>` limits the search to that category, while an ordinary query searches across the supplied categories. Left/Right moves between categories with matches without clearing the query. Match/total counts describe the current filter without hiding global evidence at the provider level. The filter persists through preview, back and refresh within the open overlay, and an initial query starts with its cursor at the end. While editing the filter, Ctrl+U clears the whole query even with customized movement keys; undo restores its full text and cursor, and clearing an already empty filter does not consume an undo step.
+
+Workspace output rows show their basename before the relative path. In View preview, press `i` for scrollable provenance with the full backing path and available session/run/correlation identities; press `i` again for content. This toggle resets the pane's scroll position. `o` reports the backing path, and `v` verifies resources that support verification. Enter or Tab opens a selected preview; Esc returns to the list, then closes. Empty results keep focus in the list. View's literal search is separate from the shared ListOverlay fuzzy search described below.
+
 `/context` with no arguments opens the context-window ledger overlay, including
 the working-set section (policy, evicted items and tokens, events, recalls, churn).
 The subcommands own the durable project-context noun: `compact` summarizes older
@@ -313,7 +328,7 @@ bank. `/handoff` during an in-flight turn is refused with a notice rather than
 queued, because a document summarizing a session that is still moving would be
 wrong by the time it was read.
 
-The `/resume` picker accepts Page Up and Page Down to move by its 12 visible rows. Arrow keys continue to move one session at a time, and typing continues to filter the list.
+The `/resume` picker accepts Page Up and Page Down to move by its 12 visible rows. Arrow keys continue to move one session at a time, and typing continues to filter the list. Task identity occupies the primary column, with the session name or ID as a fallback; metadata yields as the terminal narrows. Filtering preserves the selected session when it still matches, and undo from an empty result restores that selection. Confirmation resumes the visibly selected session, including with customized list bindings.
 
 Only active commands run. Typing anything command-shaped that the registry does
 not own checks the loaded prompt templates across native and foreign prompt roots.
@@ -351,7 +366,7 @@ Configuration lives in one place: the `/settings` overlay. `/settings <section>`
 
 Settings → Targets presents an operational console table (`HEALTH`, `ID`, `ROLES`, `RUNTIME`, `LATENCY`) with an in-place action/detail drawer for URL, default model, last probe error, and reachability. `Enter` opens actions for `Use` (switches active chat target and rebases model), `Connect` (runs the API-key or OAuth flow then probes), `Probe`, and `Remove` (with preflight analysis of affected routes/profiles). Probing runs live when the overlay opens or when explicitly requested. Target creation is initiated via `clio-coder targets add`.
 
-Settings → Fleet is an entity workbench organized with dim group headers (`Defaults`, `Profiles`, `Agent routes`, `Placement`). Dispatched worker defaults and profile rows render as compact summaries (`fast-local node-a/example-coder-model  high  auto`), drilling into fields (`target`, `model`, `thinkingLevel`, `node`) on `Enter`. Profile removal is a named destructive action with affected-route preflight. Running and retrying dispatches live in the `Alt+W` Fleet Runs board, which also steers and cancels them. `Enter` opens the selected run's worker detail: the phase, the running call with its redacted action descriptor, and the bounded tail of the worker's own prose.
+Settings → Fleet is an entity workbench organized with dim group headers (`Defaults`, `Profiles`, `Agent routes`, `Placement`). Dispatched worker defaults and profile rows render as compact summaries (`fast-local node-a/example-coder-model  high  auto`), drilling into fields (`target`, `model`, `thinkingLevel`, `node`) on `Enter`. Profile removal is a named destructive action with affected-route preflight. Running and retrying dispatches live in the `/fleet` or `Alt+W` Fleet Runs board. Its default cards show task previews, route, status, trust/evidence, telemetry and the current operation when available. `Enter` expands the selected card to show its full task and route, policy and budget, and bounded answer. Long task previews explicitly point to Enter detail. Empty boards offer `/run` or `/delegate` and no selection action. An ordinary sealed completion without validation shows `unverified; no validation observed`; Enter restores the full provenance summary. Unknown or failed trust facts remain visible by default. Completion is not scientific validation.
 
 `/run` and `/delegate` put the worker's answer on screen. Both echo the typed
 line dim above the block, then stream the run into the transcript as an attributed
@@ -360,7 +375,7 @@ or `◇ codex (acp) · run 7hq2ab` for ACP peers), the worker's prose down a rai
 one coalesced line of tool names, and a one-line footer carrying the outcome glyph,
 token count, duration, and contract status (such as `└ ✓ ok · 8.4k tok · 18s · contract unmeasured`),
 with the failure reason printed on the rail above the footer when a run fails.
-Model-launched workers use `◆` and operator-launched workers use `◇`; both follow the same Output style. Standard shows a short reported summary, Detailed adds bounded activity, and Compact keeps identity and outcome. The footer shows the active worker count alongside the main agent's phase. Use `/view transcript` or `/view dispatch:<runId>` for full available details. Memory workers do not appear as transcript blocks. A failover keeps one block with an attempt annotation.
+Model-launched workers use `◆` and operator-launched workers use `◇`; both follow the same Output style. Standard shows a short reported summary, Detailed adds bounded activity labeled `now:` for current work and `last:` for completed calls, and Compact keeps identity and outcome. Pending checkpoint questions remain visible in Compact. The footer shows the active worker count alongside the main agent's phase. Use `/view transcript` or `/view dispatch:<runId>` for full available details. Memory workers do not appear as transcript blocks. A failover keeps one block with an attempt annotation.
 
 That block is the only place a `/run` answer goes. The main agent is not told
 about it, which is what makes a side run a side run; asked about the answer, it
@@ -388,8 +403,8 @@ rather than dropped, because the operator named that run.
 
 `/new` resets the transcript and the pool bare `/share` draws from, so a run
 from the previous session cannot be shared into the new one. Worker tool
-arguments never cross at all: the transcript carries tool names only, the same
-rule the dispatch board follows.
+arguments never cross as raw input: transcript and board activity can show tool
+names and their redacted action descriptors.
 
 Blocks survive a resume. Each attempt writes a `workerRun` session entry naming
 the run, its origin, and its runtime, and `/resume` rebuilds the block from that
@@ -600,6 +615,11 @@ cancel it with `Esc`) and while a permission ask is parked (it is already
 waiting on you). A steer that arrives as the run ends is resubmitted as a fresh
 prompt. Headless `--steer-channel` lines are always next-slot steers.
 
+Explicitly addressed worker steering stays addressed to that worker. A stale,
+completed, ambiguous or unavailable target produces a notice and preserves the
+draft; it does not become a new main-agent prompt. The late-steer resubmission
+above applies to an unaddressed steer for the main agent.
+
 For running dispatches, the editor also accepts:
 
 ```text
@@ -614,7 +634,7 @@ do not accidentally become steering requests.
 The `Alt+W` Fleet Runs board makes this control path discoverable: use
 Up/Down or `j`/`k` to select a run, `s` to close the board and prefill its
 exact `@<runId> ` steering prefix, and `x` to cancel a live worker or queued
-retry. A steer first reports `queued`; only the worker's
+retry. At narrow widths, the footer prioritizes available steer/cancel actions over navigation and detail hints; Enter still expands the selected card. Completed runs offer no steer/cancel actions. A steer first reports `queued`; only the worker's
 `clio_coder_steer_received` acknowledgement reports `received`. Single-shot
 subprocess runtimes and ACP delegation do not expose a live steering channel
 and are labeled accordingly.
@@ -869,12 +889,12 @@ The footer owns live activity. Transcript actions have static running or outcome
 
 The Clio TUI has been enhanced to maximize readability, operational focus, and command discovery:
 
-- **Welcome header:** Before your first prompt the header is three rows and no box: a masthead (`>C_ Clio Coder v0.4.7` on the left, `~/iowarp/clio-coder · main*` on the right), the route (`✓ dynamo · qwen3.8-27b`), and one next step (`describe a task · Enter to send · / for commands`). The next step names whatever actually blocks work first: no route or model sends you to `/model`, an unavailable or degraded route to `/settings targets`, a missing or stale `CLIO-CODER.md` to `/context init` or `/context refresh`. A healthy route shows no latency; a failing one shows its reason. Your first submit collapses the header to one live row, `>C_ Clio Coder v0.4.7 · dynamo · qwen3.8-27b · ~/iowarp/clio-coder · main*`, which follows a mid-session model change. `/new` returns to the three-row form; `/resume`, `/tree`, `/fork`, `/handoff` and `--continue` open collapsed. See [tui-design.md](../architecture/tui-design.md#51-welcome-launchpad--session-header) for the width-degradation order and route vocabulary.
-- **Unmistakable Clio Composer:** The input editor features an explicit left section tag reflecting current prompt semantics (`MESSAGE` while idle, `FOLLOW-UP` while Clio runs, and orange `STEER` when Enter steers in-flight execution). Includes the dim placeholder `Ask Clio…  / for commands` and lower-rail hint `Enter send · Ctrl+J newline` at wider widths.
-- **Progressively Disclosed Footer:** The compact footer uses a quiet two-zone status layout that suppresses idle decoration (`tools none`, `◌ idle`, and duplicate turn receipts). Line 1 displays workspace location, git branch/dirty state, and active phase only when meaningful; Line 2 displays the context window gauge, current Output style, and session cost. `Alt+U` toggles the expanded dashboard, which orders information by operational urgency (Activity, Context, Session, Workspace).
+- **Welcome header:** Before your first prompt the header is three rows and no box: a masthead (`>C_ Clio Coder v0.4.7` on the left, `~/iowarp/clio-coder · main*` on the right), the route (`✓ dynamo · qwen3.8-27b`), and one next step (`describe a task · Enter to send · / for commands`). The next step names whatever actually blocks work first: no route or model sends you to `/model`, an unavailable or degraded route to `/settings targets`, a missing or stale `CLIO-CODER.md` to `/context init` or `/context refresh`. A healthy route shows no latency; a failing one shows its reason. Your first submit collapses the header to one live row, `>C_ Clio Coder v0.4.7 · dynamo · qwen3.8-27b · ~/iowarp/clio-coder · main*`, which follows a mid-session model change. `/new` returns to the three-row form; `/resume`, `/tree`, `/fork` and `/handoff` collapse it after a successful transition. Interactive resume uses `/resume`; `--continue` is a headless `clio-coder run` option. See [tui-design.md](../architecture/tui-design.md#51-welcome-launchpad--session-header) for the width-degradation order and route vocabulary.
+- **Unmistakable Clio Composer:** The input editor features an explicit left section tag reflecting current prompt semantics (`MESSAGE` while idle, `FOLLOW-UP` while Clio runs, and orange `STEER` when Enter steers in-flight execution). The hydrated composer keeps target/model fields separate until rendering. Narrow labels retain a recognizable family and variant, such as `blade… · qwopus3.…dense-q6 · low`. Includes the dim placeholder `Ask Clio…  / for commands` and lower-rail hint `Enter send · Ctrl+J newline` at wider widths.
+- **Progressively Disclosed Footer:** The compact footer uses a quiet two-zone status layout that suppresses idle decoration (`tools none`, `◌ idle`, and duplicate turn receipts). Line 1 displays workspace location, git branch/dirty state, and active phase only when meaningful, shortening workspace parents and dropping branch decoration before live activity or worker counts; Line 2 displays the context window gauge, current Output style, and session cost. `Alt+U` toggles the expanded dashboard, which orders information by operational urgency (Activity, Context, Session, Workspace).
 - **Footer Notification Degradation Ladder:** The footer notification badge reserves the severity head (`glyph count noun`) and `[Ctrl+G x] dismiss` tail first, allocating remaining width to an ellipsized message body. Under narrow terminal constraints, it degrades cleanly down the ladder without clipping action keys.
 - **Grouped Slash Command Palette:** Typing `/` opens an autocomplete command palette grouped by operational category (`Run`, `Inspect`, `Configure`, `Sessions`) with compact argument hints. Every suggestion is the command's one canonical spelling.
-- **Voice-First Transcript & Receipts:** User (`› `) and assistant (`✦ `) prose are formatted with a two-cell hanging indent, ensuring wrapped continuation lines remain visually tied to their voice prefix. Tool ledgers maintain full terminal width. Completed turn receipts honor output verbosity (`minimal` none, `default` compact dim `turn · in N · out M`, `verbose` full receipt with call counts, cache reads/writes, reasoning provenance, and verification caveats).
+- **Voice-First Transcript & Receipts:** User (`› `) and assistant (`✦ `) prose are formatted with a two-cell hanging indent, ensuring wrapped continuation lines remain visually tied to their voice prefix. Tool ledgers maintain full terminal width. Completed turn receipts honor Output style: Compact omits the separate receipt, Standard shows a small completion line with available duration, and Detailed includes available call counts, token usage and reasoning provenance.
 - **Transactional Settings Center:** Open `/settings` or deep-link to one of
   `chat`, `fleet`, `targets`, `context`, `safety`, `interface`, or
   `integrations`. Value edits construct change plans offering `Apply this
@@ -918,7 +938,7 @@ The detail pane displays structured descriptions, usage, or state metadata using
 ### Responsive Width Adaptation
 
 All TUI overlays fluidly adapt to narrow terminals down to 40 columns:
-- `/view` falls back to one pane on narrow terminals. Type to filter, use Enter to read, Escape to return to the list, and Escape again to close. Ctrl+U clears the filter; long text wraps and scrolls. Tab also switches panes.
+- `/view` falls back to one pane on narrow terminals. Type to filter, use Enter to read, Escape to return to the list, and Escape again to close. Ctrl+U clears the whole query while the filter has focus; long preview text wraps and scrolls. Tab also switches panes.
 - Settings provides a drill-down navigation stack below 72 columns (sections → rows → details) with breadcrumbs and `Esc` backtracking.
 - Text content and detail descriptions wrap cleanly without line truncation.
 

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

@@ -607,10 +607,11 @@ paths and stop startup so stale configuration does not silently change runtime
 behavior.
 
 Plain `clio-coder doctor` is read-only. `clio-coder doctor --fix` creates missing
-directories and template files, repairs credential permissions, and refreshes
-install metadata. It validates `settings.yaml` directly against the current
-schema but never rewrites removed keys or migrates an old settings shape. Any
-unknown or retired key remains a validation error on that doctor run.
+directories and template files, repairs credential permissions, refreshes
+install metadata, and records fleet preflight results. It validates
+`settings.yaml` directly against the current schema but never rewrites removed
+keys or migrates an old settings shape. Any unknown or retired key remains a
+validation error on that doctor run.
 Registered `clio-coder upgrade` migrations are the narrow exception. Upgrade
 moves a version-1 or unversioned settings document into the version-2 areas,
 records the migration, and keeps the byte-exact original as
@@ -714,6 +715,7 @@ This is the version-2 durable schema shipped in `DEFAULT_SETTINGS`. Validation i
 | `chat.retry.baseDelayMs` | `2000` | integer ≥ 0 | next turn |
 | `chat.retry.maxDelayMs` | `60000` | integer ≥ 0 | next turn |
 | `chat.retry.streamStallMs` | `180000` | integer ≥ 0; `0` disables the stall timer | next turn |
+| `chat.retry.firstTokenStallMs` | `600000` | integer ≥ 0; silence allowed before a call's first token; `0` never aborts before the first token | next turn |
 
 ### Fleet
 
@@ -809,7 +811,7 @@ The safety-limit leaves have no one-process `CLIO_CODER_*` overrides in the curr
 | `integrations.projectResources.trustProjectImports` | `false` | boolean | next turn |
 | `integrations.externalAgents.entries` | `[]` | list of validated ACP agent definitions | next dispatch |
 | `integrations.externalAgents.defaults.connectTimeoutMs` | `30000` | integer ≥ 1 | next dispatch |
-| `integrations.externalAgents.defaults.turnTimeoutMs` | `300000` | integer ≥ 1 | next dispatch |
+| `integrations.externalAgents.defaults.turnTimeoutMs` | `0` | integer ≥ 0; `0` disables the turn timeout | next dispatch |
 | `integrations.externalAgents.defaults.permissionTimeoutMs` | `120000` | integer ≥ 1 | next dispatch |
 | `integrations.externalAgents.defaults.toolGovernance` | `clio-coder-policy` | `clio-coder-policy`, `agent-managed`, `deny-all` | next dispatch |
 | `integrations.runtimePlugins` | `[]` | list of plugin package names | restart |

package/docs/guide/configuration-reference.md

@@ -22,7 +22,8 @@ Precedence, where several surfaces set the same value: a one-run CLI flag beats
 | `chat.retry.enabled` | `true` | Master switch for transient-provider retries in the interactive chat loop (boolean); dispatched workers use `fleet.retry.maxRetries` instead; applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `chat.retry.maxDelayMs` | `60000` | Ceiling in ms on the exponential backoff between chat-loop retries (integer >= 0); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `chat.retry.maxRetries` | `3` | Maximum retry attempts for one transient provider failure in the chat loop (integer >= 0); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `chat.retry.streamStallMs` | `180000` | Silence on an in-flight stream longer than this many ms is treated as a wedged backend and the turn is aborted and retried (integer >= 0, `0` disables the stall timer); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
+| `chat.retry.streamStallMs` | `180000` | Silence after a call's first token longer than this many ms is treated as a wedged backend and the turn is aborted and retried (integer >= 0, `0` disables the stall timer); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
+| `chat.retry.firstTokenStallMs` | `600000` | Silence allowed between sending a model call and its first token. It replaces `streamStallMs` for that window only, because a local server that slept reloads the model and prefills cold before it emits anything; the larger of the two values applies (integer >= 0, `0` never aborts a call that has not started streaming); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `chat.target` | `null` | Saved default chat target id (configured id or null); a dangling id normalizes to null and clears `chat.model`; seeds session routing at launch, so applies next session. | `run --target` > session routing (`/model`, `/thinking`, configured model-cycle actions, `/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `chat.thinkingLevel` | `low` | Saved default reasoning effort for the chat model: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, clamped to what the model supports at request time; applies next session. | `run --thinking` > session routing (`/model`, `/thinking`, configured model-cycle actions, `/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `context.compaction.auto` | `true` | Master switch for the pre-request compaction trigger when context pressure crosses `threshold` (boolean); manual `/context compact` still works when off; applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
@@ -57,7 +58,7 @@ Precedence, where several surfaces set the same value: a one-run CLI flag beats
 | `fleet.history.maxRuns` | `1000` | Retention cap on the durable dispatch run ledger (integer >= 1); applies next dispatch. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `fleet.limits.internalRunTimeoutMs` | `900000` | Wall-clock cap in ms for one internal generator dispatch such as the wiki documenter or the bootstrap scout (integer >= 1); applies next dispatch. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `fleet.limits.toolCallsPerRun` | `150` | Lifetime cap on admitted tool calls for one dispatched worker (integer >= 1); a recipe budget can only narrow it; read from effective settings at dispatch, so applies next dispatch. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `fleet.nodes` | `[]` | SSH-reachable worker nodes (the implicit `local` node is never listed); a node becomes dispatch-eligible only after the doctor fleet preflight passes; applies next dispatch. |  |
+| `fleet.nodes` | `[]` | SSH-reachable worker nodes (the implicit `local` node is never listed); a node becomes dispatch-eligible only after `clio-coder doctor --fix` records a passing fleet preflight for the project root (plain `doctor` probes and reports without recording); applies next dispatch. |  |
 | `fleet.nodes[].clioCoderEntry` | `clio-coder worker` | Remote worker-entry invocation run after `cd <projectRoot>`; also version-probed by the fleet preflight; defaults to `clio-coder worker` on the remote PATH. |  |
 | `fleet.nodes[].host` |  | SSH destination host (name or address); required. |  |
 | `fleet.nodes[].id` |  | Stable node id used in placement, receipts, and operator surfaces; required, `local` is reserved, duplicates are rejected. |  |
@@ -86,7 +87,7 @@ Precedence, where several surfaces set the same value: a one-run CLI flag beats
 | `integrations.externalAgents.defaults.connectTimeoutMs` | `30000` | Default ms an ACP agent has to answer `initialize` (integer >= 1, at most the max timer delay); never zero-disabled; applies next dispatch. |  |
 | `integrations.externalAgents.defaults.permissionTimeoutMs` | `120000` | Default ms an ACP permission request may wait for an operator (integer >= 1); applies next dispatch. |  |
 | `integrations.externalAgents.defaults.toolGovernance` | `clio-coder-policy` | Default governance for ACP agents without their own: `clio-coder-policy`, `agent-managed`, `deny-all` (legacy `clio-policy` is normalized with a warning); applies next dispatch. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `integrations.externalAgents.defaults.turnTimeoutMs` | `300000` | Default ms one ACP turn may take before it is cancelled (integer >= 1); applies next dispatch. |  |
+| `integrations.externalAgents.defaults.turnTimeoutMs` | `0` | Default ms one ACP turn may take before it is cancelled (integer >= 0; 0 disables); applies next dispatch. |  |
 | `integrations.externalAgents.entries` | `[]` | ACP delegation agents for `/delegate` and dispatch: list of stdio agent definitions with unique ids (`auto` reserved), each inheriting `defaults.*` where unset; applies next dispatch. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `integrations.externalAgents.entries[].args` | `[]` | Argument list for the ACP stdio command (list of strings, duplicates dropped); empty when absent. |  |
 | `integrations.externalAgents.entries[].command` |  | ACP stdio command spawned for the agent (newline-delimited JSON-RPC per ACP v1); required. |  |
@@ -99,7 +100,7 @@ Precedence, where several surfaces set the same value: a one-run CLI flag beats
 | `integrations.externalAgents.entries[].projectContext` | `none` | Project context sent to this agent as a dynamic message: `none` (default; repo conventions never leave the machine) or `bounded` (the bounded projection). |  |
 | `integrations.externalAgents.entries[].stallTimeoutMs` | `300000` | Event-inactivity stall window in ms: when no `session/update` arrives for this long the reconciler cancels the turn and finalizes the run as stalled; `<= 0` disables; 300000 when absent. |  |
 | `integrations.externalAgents.entries[].toolGovernance` |  | Who governs the agent's tool calls: `clio-coder-policy` (Clio's autonomy matrix), `agent-managed`, `deny-all`; absent inherits `defaults.toolGovernance`; `agent-managed` refuses `run --autonomy`. |  |
-| `integrations.externalAgents.entries[].turnTimeoutMs` |  | Per-agent ms one ACP turn may take before cancellation (integer >= 1); absent inherits `defaults.turnTimeoutMs`. |  |
+| `integrations.externalAgents.entries[].turnTimeoutMs` |  | Per-agent ms one ACP turn may take before cancellation (integer >= 0; 0 disables); absent inherits `defaults.turnTimeoutMs`. |  |
 | `integrations.git.commitAttribution` | `true` | Evidence-aware role trailers on commits created through Clio (boolean); applies immediately for subsequent commits. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `integrations.library.catalog` | `null` | Path of the private resource-library catalog (string or null); null means `<configDir>/library.yaml`; applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `integrations.library.confirmedRemote` | `null` | Remote URL written by `clio-coder library remote confirm <url>`; must equal `remote` before sync or push may run (string or null); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
@@ -208,6 +209,7 @@ Read from the process environment at boot unless the row says otherwise.
 | `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. |  |
 | `CLIO_CODER_ENDPOINT_SLOTS_TTL_MS` | `86400000` | Positive integer milliseconds a persisted endpoint slot count stays valid for an endpoint this process has not probed; older records are ignored and pruned. | env > built-in default (no settings key) |
+| `CLIO_CODER_ENTRY` | `unset` | Exported by the eval suite runner into a task runner's environment with the path of the Clio entry under evaluation (`src/domains/eval/suites/run.ts`). Clio itself never reads it. |  |
 | `CLIO_CODER_EVAL_RUNNER_STDOUT_FILE` | `unset` | Set by the eval suite runner to the path of the captured runner stdout JSONL for a task's measure step; read only by external graders (evals/behavioral-corpus-grader.mjs), never by src. |  |
 | `CLIO_CODER_FORCE_COMPACT` | `unset (disabled)` | Exactly `1` on the interactive process forces the pre-submit compaction to run on every turn while set, regardless of the context threshold. |  |
 | `CLIO_CODER_GIT_COMMITS_ENABLED` | `unset (in-process reads treat it as enabled; the hook requires exactly `1`)` | Set by Clio to `1`/`0` from `integrations.git.commitAttribution` for itself and child seams; the managed hook exits unless it is exactly `1`, while absent counts as enabled in process. | `integrations.git.commitAttribution` writes it; env is the transport, not an operator override |
@@ -243,9 +245,6 @@ Read from the process environment at boot unless the row says otherwise.
 | `CLIO_CODER_SKILL_MARKETPLACE_INDEX` | `unset` | Path to a skill-marketplace index file consulted after the catalog; an explicit indexPath option beats it and the built-in index path is the fallback. | explicit indexPath option > env > default index path |
 | `CLIO_CODER_STATE_DIR` | `platform default (`$XDG_STATE_HOME/clio-coder`, else `~/.local/state/clio-coder`)` | Absolute path for the state root; beats `CLIO_CODER_HOME/state` and the platform default, and the fleet-view pane child re-pins it from argv. | env > `CLIO_CODER_HOME/state` > `XDG_STATE_HOME` or platform default |
 | `CLIO_CODER_STATUS_STUCK_MS` | `180000` | Positive number of milliseconds of elapsed turn time after which the status watchdog reports the turn as stuck (tier 4). |  |
-| `CLIO_CODER_TEST_STAGE1_DELAY_MS` | `0` | Under `NODE_ENV=test` only, integer milliseconds (clamped to 0..5000) to sleep between the Stage 0 shell mount and Stage 1 hydration for PTY tests. |  |
-| `CLIO_CODER_TEST_STAGE1_FAIL` | `unset (disabled)` | Under `NODE_ENV=test` only, exactly `1` throws an injected Stage 1 hydration failure after the instant shell mounts. |  |
-| `CLIO_CODER_TEST_UPGRADE_NO_NETWORK` | `unset (disabled)` | Any non-empty value makes `clio-coder upgrade` skip the npm install step so upgrade tests run offline. |  |
 | `CLIO_CODER_TIMING` | `unset (disabled)` | Exactly `1` prints the startup timer report after the banner, but only on the bannered non-interactive boot (not the TUI, headless, or ACP paths). |  |
 | `CLIO_CODER_TRACE_BOOT` | `unset (disabled)` | Exactly `1` writes a `[clio-coder:boot] +<ms> <phase>` line to stderr for every boot phase marker, including startup-timer marks. |  |
 | `CLIO_CODER_TRACE_MAX_BYTES` | `134217728` | Integer of at least 1048576 bytes the SQLite trace mirror may occupy before the oldest terminal runs are pruned; smaller or invalid values fall back. | env > built-in default (no settings key) |
@@ -275,7 +274,6 @@ Read from the process environment at boot unless the row says otherwise.
 | `NO_COLOR` | `unset` | Any non-empty value drops every foreground and background SGR color from the theme; bold, dim, italic, and underline stay. |  |
 | `NODE_COMPILE_CACHE` | `unset (Clio uses `<cache>/v8-compile-cache` once the cache root exists)` | Presence (even empty) means the operator owns the V8 compile cache: Clio calls `enableCompileCache()` with no directory and never injects its own cache into workers. |  |
 | `NODE_DISABLE_COMPILE_CACHE` | `unset` | Presence disables Clio's compile cache for this process and stops the worker spawn from injecting one. |  |
-| `NODE_ENV` | `unset` | Exactly `test` unlocks the Stage 1 interleaving seams (`CLIO_CODER_TEST_STAGE1_DELAY_MS`, `CLIO_CODER_TEST_STAGE1_FAIL`); no other value matters. |  |
 | `NODE_OPTIONS` | `unset` | Scanned for `--trace-warnings`; when present, the trace store stops suppressing Node's `node:sqlite` ExperimentalWarning. |  |
 | `OLLAMA_NUM_PARALLEL` | `1` | Positive integer parallel slot count assumed for a local Ollama server during discovery; anything else counts as 1. |  |
 | `PATH` | `unset` | Searched for executables by interop CLI detection, toolchain resolution, the uninstall shadow check, and editor probing; the bash tool's login-env capture is discarded without it. |  |
@@ -432,7 +430,7 @@ Grouped by command. Global flags appear under `global`.
 
 | Flag | Controls |
 |---|---|
-| `--fix` | Repair structure (missing directories and template files, credential file permissions) instead of the read-only diagnosis. |
+| `--fix` | Repair structure (missing directories and template files, credential file permissions) and record fleet preflight results instead of the read-only diagnosis. |
 | `--help` | Print the command's usage and exit. |
 | `--json` | Emit JSON instead of the human-readable rendering. |
 | `-h` | Short form of --help. |
@@ -523,6 +521,7 @@ Grouped by command. Global flags appear under `global`.
 | `--acp` | Startup alias for the `acp` subcommand: rewrites the rest of the line onto `clio-coder acp`, so every trailing option is parsed by the ACP parser. |
 | `--all` | With `--help`, appends the `clio-coder dev` command list (components, evolve, share) to the top-level help; no effect otherwise. |
 | `--api-key` | Startup flag taking a literal key that overrides the stored credential for the target this invocation resolves; must precede the subcommand. |
+| `--autonomy` | Startup flag setting the interactive session's autonomy to `read-only`, `suggest`, `auto-edit`, or `full-auto` without modifying `settings.yaml`. Passing `--autonomy` before a subcommand is refused with exit 2 (`clio-coder run --autonomy` remains the headless form). |
 | `--continue` | Refused before the subcommand: exits 2 with the hint that sessions are resumed from inside the app by typing /resume; nothing is parsed from it. `run --continue` is a separate flag. |
 | `--help` | Print the top-level command list and exit 0 when given before any subcommand. |
 | `--no-context-files` | Startup flag that skips CLIO-CODER.md project-context injection for this invocation; must precede the subcommand (run rejects it with a position hint). |
@@ -575,6 +574,19 @@ Grouped by command. Global flags appear under `global`.
 | `--with-requirements` | For `library install`, also install the entry's unsatisfied requirements instead of refusing. |
 | `-h` | Short form of --help. |
 
+### `mcp`
+
+Operator commands are `clio-coder mcp list [--json]`, `clio-coder mcp trust <id> [--action-class read|execute|unknown] [--json]`, and `clio-coder mcp untrust <id> [--json]`. `--help`/`-h` prints help even with `--json`. Interactive `/mcp list`, `/mcp trust <id> [read|execute|unknown]`, and `/mcp untrust <id>` use the same outcomes. These commands inspect configuration or mutate trust without launching a server.
+
+| JSON response | Shape |
+| --- | --- |
+| list | `{servers: [...], diagnostics: [...], trustDiagnostics: [...]}`; servers include declaration and `trust: {status, actionClass, reason?}` |
+| trust | `{ok: true, record: {projectRoot, id, digest, actionClass, trustedAt}}` |
+| untrust | `{ok: true, removed: boolean}` |
+| mutation or usage error | `{ok: false, message: string}` with a one-line reason |
+
+Exit codes are 0 for success, 1 for operational failure, and 2 for invalid usage. List keeps its list response shape and exits 1 when config or trust diagnostics exist. CLI trust/untrust requires a declared project id; user declarations are trusted by authorship. Trust-file corruption is reported without overwriting it. See [the configuration contract](#local-stdio-mcp-configuration-and-trust).
+
 ### `memory`
 
 | Flag | Controls |
@@ -605,7 +617,10 @@ Grouped by command. Global flags appear under `global`.
 
 | Flag | Controls |
 |---|---|
+| `--force` | For `panes install`, overwrite an existing installation without prompting. |
 | `--help` | Print the command's usage and exit. |
+| `--json` | Emit JSON instead of the human-readable rendering. |
+| `-f` | Short form of --force. |
 | `-h` | Short form of --help. |
 
 ### `paths`
@@ -628,6 +643,7 @@ Grouped by command. Global flags appear under `global`.
 | `--dry-run` | Print the listing of what each selected root holds and change nothing. |
 | `--force` | Required for destructive execution; without it the command lists and refuses. |
 | `--help` | Print the command's usage and exit. |
+| `--json` | Emit JSON instead of the human-readable rendering. |
 | `--state` | Reset the state root only (every session transcript and its audit trail); the default level when no level flag is given. |
 | `-f` | Short form of --force. |
 | `-h` | Short form of --help. |
@@ -704,6 +720,15 @@ Grouped by command. Global flags appear under `global`.
 | `--thinking` | For `targets profile set`, the profile's thinking level: off, minimal, low, medium, high, xhigh, or max. |
 | `-h` | Short form of --help. |
 
+### `tasks`
+
+| Flag | Controls |
+|---|---|
+| `--expect` | For `tasks add`, repeatable repository-relative output file path expected by the task. |
+| `--help` | Print the command's usage and exit. |
+| `--verify` | For `tasks add`, repeatable verification check id (with optional `:timeoutMs` suffix) declared in `package.json` or `.clio-coder/verifiers.yaml`. |
+| `-h` | Short form of --help. |
+
 ### `tools`
 
 | Flag | Controls |
@@ -736,6 +761,9 @@ Grouped by command. Global flags appear under `global`.
 | `--dry-run` | Print what would be removed, including the per-project directories, and change nothing. |
 | `--force` | Required for destructive execution; without it the command lists and refuses. |
 | `--help` | Print the command's usage and exit. |
+| `--json` | Emit JSON instead of the human-readable rendering. |
+| `--keep-config` | Preserve the configuration root (`settings.yaml`, credentials). |
+| `--keep-data` | Preserve the data root (`memory`, evidence, vendored tools). |
 | `--remove-binary` | Also remove the launcher symlink when it points at this installation; a real file or a link elsewhere is kept and reported. |
 | `-f` | Short form of --force. |
 | `-h` | Short form of --help. |
@@ -747,6 +775,7 @@ Grouped by command. Global flags appear under `global`.
 | `--channel` | npm dist-tag to install: `latest`, `beta`, or `dev`; only the `--channel=<chan>` form is parsed; npm installs only. |
 | `--dry-run` | Print the planned npm install, migrations, and state refresh and change nothing. |
 | `--help` | Print the command's usage and exit. |
+| `--json` | Emit JSON instead of the human-readable rendering. |
 | `--post-install` | Internal marker the upgrade passes to its re-exec of the newly installed binary: skip the npm install and run migrations and doctor checks. |
 | `--skip-migrations` | Skip the data-dir migrations after the install step. |
 | `-h` | Short form of --help. |
@@ -765,6 +794,9 @@ Grouped by command. Global flags appear under `global`.
 
 | Flag | Controls |
 |---|---|
+| `--baseline` | For `verifiers add`/`edit`, repository-relative baseline JSON path for a perf-budget check. |
+| `--budget-ms` | For `verifiers add`/`edit`, wall-time bound in milliseconds for a perf-budget check. |
+| `--budget-relative` | For `verifiers add`/`edit`, fractional headroom over the bound for a perf-budget check. |
 | `--command` | For `verifiers add` (required) and `edit`, the check's argv as a JSON string array. |
 | `--cwd` | For `verifiers add`/`edit`, repository-relative working directory of the check. |
 | `--description` | For `verifiers add` (required) and `edit`, the check's description text. |
@@ -773,17 +805,54 @@ Grouped by command. Global flags appear under `global`.
 | `--help` | Print the verifiers usage and exit. |
 | `--id` | For `verifiers add`, the new check's id (required). |
 | `--json` | For `verifiers inspect`, the only accepted argument; emits the fixed machine-readable catalog projection. |
+| `--kind` | For `verifiers add`/`edit`, check kind: `command`, `numeric-compare`, or `perf-budget`. |
+| `--reference` | For `verifiers add`/`edit`, repository-relative reference JSON path for a numeric-compare check. |
 | `--rename` | For `verifiers author`, an `<old>=<new>` rename of a discovered check id; repeatable. |
 | `--tags` | For `verifiers add`/`edit`, comma-separated catalog tags. |
 | `--timeout-ms` | For `verifiers add`/`edit`, positive integer timeout in milliseconds. |
+| `--tolerance` | For `verifiers add`/`edit`, tolerance JSON object specifying numeric or perf-budget bounds. |
 | `--yes` | For mutating verifiers commands, confirm the write after the preview prints; without it nothing changes. |
 | `-h` | Short form of --help. |
 
+## Local stdio MCP configuration and trust
+
+Source: `src/domains/gateway/mcp/config.ts`, `trust.ts`, and `client.ts`. The optional user file is `<Clio config directory>/mcp.yaml`; the project file is `<workspace>/.clio-coder/mcp.yaml`. `clio-coder paths` locates the config directory. A user declaration shadows a project declaration of the same id with a diagnostic. Malformed files contribute no servers. This release supports local stdio only, with no remote transport or OAuth fields.
+
+```yaml
+version: 1
+servers:
+  - id: analysis
+    command: node
+    args: [tools/mcp-server.mjs]
+    cwd: .
+    env:
+      ANALYSIS_MODE: readonly
+    timeoutMs: 60000
+```
+
+| Field | Contract |
+| --- | --- |
+| `version`, `servers` | Required root fields; version 1, at most 32 server declarations per file. |
+| `servers[].id` | Required, at most 32 characters, matches `[a-z0-9][a-z0-9_-]*`; duplicate ids fail within a file. |
+| `servers[].command` | Required executable basename on PATH or absolute path, at most 512 bytes. Relative executable paths, shell command strings, and explicit shell executables are refused. |
+| `servers[].args` | Optional string array, default empty; at most 64 entries of 4096 bytes each. |
+| `servers[].cwd` | Optional, at most 512 bytes. Project cwd defaults to the workspace and must remain inside it, including symlinks. User cwd defaults to the config directory; it may be config-relative or absolute. |
+| `servers[].env` | Optional string map, default empty; at most 64 keys matching `[A-Z_][A-Z0-9_]*`, with values at most 4096 bytes. Adds to the safe environment allowlist. |
+| `servers[].timeoutMs` | Optional positive integer at most 900000; overrides request timeout. Default client request timeout is 60000 ms; initialize is bounded at 15000 ms. |
+
+The YAML file is capped at 256 KiB; aliases and unknown fields are rejected. NUL-containing command/argument/environment/cwd values are refused. Launch-time canonical cwd checks are admission checks, not ongoing filesystem isolation.
+
+User-scope declarations are trusted by authorship and get action class `unknown`. Project servers require `clio-coder mcp trust analysis` or `/mcp trust analysis`; an optional `--action-class read|execute|unknown` selects authority, with `unknown` as default. Trust is stored in user `<config>/mcp-trust.json`, version 1, mode 0600, with at most 256 records and 1 MiB. Each record binds canonical `projectRoot`, `id`, declaration `digest`, `actionClass`, and `trustedAt`. Editing command, arguments, cwd, environment, or timeout makes the record stale and requires review and re-trust. Trust does not come from a server annotation or a model-authored claim.
+
+Gateway discovery is lazy and session-cached. Untrusted or stale project declarations never spawn; failed or cancelled discovery is not silently restarted in that session. Trust changes should be used by a new session, since the running source resolved configuration once. Cancelling discovery closes its shared connection and fails its waiters. Session shutdown awaits client-owned teardown; the exit backstop signals only a still-owned process group.
+
+Transport bounds are 4 MiB per incoming JSON-RPC line, 4 MiB pending outbound bytes, 16 KiB stderr tail, 1 MiB normalized result text, and at most 500 tools or 100 pages per server discovery. Gateway result shaping bounds one MCP result to 16 KiB in model context, offloading larger results to disk artifacts with preview and reference. Request timeout or per-call abort can fail one call without closing a ready server; discovery cancellation closes the shared connection. Teardown uses TERM, a 3000 ms grace, KILL, and 2000 ms bounded confirmation, reporting incomplete cleanup. Launching an MCP server is not sandboxing; remote MCP/OAuth and general OS isolation are deferred.
+
 ## Project files
 
 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.
+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, trust, and names ignored project settings under the Settings header. 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`
 
@@ -977,11 +1046,43 @@ Arguments the model can send on `dispatch`, `bash`, `context`, and `verify`, gro
 | Argument | Class | Controls |
 |---|---|---|
 | `context.include_tree` | policy | scope=skills: list files under the skill base_dir. |
-| `context.limit` | policy | scope=docs: max sections (default 5, max 12). |
+| `context.limit` | policy | scope=recall discovery: max refs (default 8, max 12). |
 | `context.name` | task | scope=skills: skill name to load; omit to list. |
-| `context.query` | task | scope=docs: question or terms; omit to list the corpus. |
+| `context.query` | task | scope=recall discovery: path, tool, or ref terms; omit to list. |
 | `context.ref` | task | scope=recall: ref of the evicted item, as named in its marker. |
-| `context.scope` | policy | Context source. |
+| `context.scope` | policy | workspace, skills, or recall. |
+| `context.offset` | policy | Zero-based recall discovery offset; follow nextOffset. |
+
+### `gateway`
+
+| Argument | Class | Controls |
+| --- | --- | --- |
+| `gateway.op` | task | find, describe, or call. |
+| `gateway.query` | task | Case-insensitive find filter over name/description. |
+| `gateway.capability` | task | Name returned by find, required for describe/call. |
+| `gateway.args` | task | Capability arguments from its describe schema. |
+
+### `run_script`
+
+| Argument | Class | Controls |
+| --- | --- | --- |
+| `run_script.interpreter` | task | PATH name: python3, python, node, bash, sh, Rscript, julia, perl, ruby, octave. |
+| `run_script.script` | task | Regular script file inside the workspace; symlink escapes refused. |
+| `run_script.args` | task | Script argv, at most 64 entries, 4096 bytes each. |
+| `run_script.interpreter_args` | task | Pre-script argv with the same bounds; omitted defaults to Python -u or empty for other interpreters. |
+| `run_script.cwd` | task | Workspace-relative directory, default root. |
+| `run_script.timeout_ms` | policy | Positive integer, default 600000, clamped above 21600000. |
+| `run_script.inputs` | task | Up to 64 workspace-relative provenance references, not isolation. |
+| `run_script.outputs` | task | Up to 64 expected output references, observed after execution. |
+| `run_script.env` | task | Up to 32 uppercase/underscore keys, values at most 4096 bytes; manifest stores keys only. |
+
+### Gateway capability arguments
+
+`clio_docs` takes optional `query` and `limit` (default 5, max 12). `clio_library` takes `query`, `kind`, `ref`, `limit` (default 20, max 50), and zero-based `offset`. These replace context's docs/library scopes. `web_read` accepts `url`, `timeout_ms`, `max_bytes`, and `format`, without method, headers, or body. `web_fetch` retains the full HTTP surface.
+
+`data` requires `op: inspect|select|validate` and `path`, with optional `format: csv|tsv|json|jsonl`, `delimiter`, `header: auto|true|false`, `sample_rows` (10, max 1000), `max_rows` (100000, null for all), zero-based `offset`, `limit` (50, max 1000), `columns` (CSV names/indices), and RFC 6901 `pointer` (JSON). All are nested under `gateway.args`; the capability is read-only.
+
+`read.line_numbers` requests source line prefixes; tail numbering is refused above the 32 MiB line-count budget. For complete argument and result contracts, see [Tool usage](tool-usage.md).
 
 ### `dispatch`
 
@@ -1176,6 +1277,8 @@ Keys of the local-model knowledge base in `src/domains/providers/models/local-mo
 | `quirks.thinking.mechanism` |  | One of `effort-levels`, `budget-tokens`, `on-off`, `always-on`, `none`; it picks the thinking payload shape, reasoning class and level labels, overriding inference from `thinkingFormat`. |
 | `quirks.thinkingControl` |  | Free-text note on how a family's template gates thinking (for example a `<\|think\|>` system token); provenance only; nothing in src reads it. |
 
+The measured `mini/qwopus3.8-27b-dense` LiteLLM route family has a narrow catalog entry for its reported `low`, `medium`, and `xhigh` effort vocabulary. On the `mini/qwopus3.8-27b-dense-q6` deployment, Clio omitted effort and the upstream template rejected `high`, behavior consistent with an incompatible deployment default; the precise upstream cause was not inspected. Clio maps configured `high` or `max` to `xhigh` and explicitly forwards the resolved effort through LiteLLM. This entry comes from the 2026-09-16 server diagnostic and same-route validation; it does not assign capabilities to other Qwopus models by name similarity or change the selected model.
+
 ## Bounding constants
 
 Compiled-in limits (context budgets, retry counts, cache sizes, timeouts) are code-owned invariants, not configuration. They live beside the code that enforces them and change only through a source change with a changelog line.

package/docs/guide/environment-variables.md

@@ -60,7 +60,7 @@ These names follow an upstream or operating-system convention. They are not subs
 | `SSH_CONNECTION`, `SSH_TTY`, `TMUX`, `STY` | Remote-session and terminal-multiplexer detection used by the adaptive stream-pacing policy (`src/interactive/stream-pacing-policy.ts`). |
 | `COLUMNS` | Fallback text width for non-TTY CLI output (`src/cli/text-layout.ts`). |
 | `TZ` | Local timestamp formatting and daily audit-log date boundaries (`src/interactive/format-time.ts`, `src/domains/safety/audit.ts`). |
-| `CI`, `NODE_ENV` | CI-sensitive presentation behavior and test/development-only seams. Neither grants tool authority. |
+| `CI` | CI-sensitive presentation behavior. It grants no tool authority. |
 
 ## Debug and trace toggles
 
@@ -102,6 +102,7 @@ Set by Clio for its own processes; not operator knobs.
 | `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`, 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_ENTRY` | Exported by the eval suite runner into a task runner's environment with the path of the Clio entry under evaluation (`src/domains/eval/suites/run.ts`). Clio itself never reads it. |
 | `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`). |
 | `CLIO_CODER_WORKER_PGID` | Process-group id the transport assigns a worker so its whole tree can be signalled (`src/domains/dispatch/transport.ts`, `src/worker/entry.ts`). |
@@ -113,10 +114,6 @@ Set by Clio for its own processes; not operator knobs.
 | Variable | Purpose |
 | --- | --- |
 | `CLIO_CODER_WORKER_FAUX` (+ `_MODEL`, `_TEXT`, `_STOP_REASON`, `_ERROR_MESSAGE`) | Fake worker model for tests (`src/engine/ai.ts`). |
-| `CLIO_CODER_TEST_UPGRADE_NO_NETWORK` | Skips npm install during upgrade tests (`src/cli/upgrade.ts`). |
-| `CLIO_CODER_TEST_UPGRADE_AVAILABLE` | Sets mock available version for upgrade tests; `unreachable` stands for a registry that answered nothing (`src/cli/upgrade.ts`). |
-| `CLIO_CODER_TEST_UPGRADE_FAIL` | Injects mock failures (`npm` or `migration`) for upgrade tests (`src/cli/upgrade.ts`). |
-| `CLIO_CODER_TEST_STAGE1_DELAY_MS`, `CLIO_CODER_TEST_STAGE1_FAIL` | `NODE_ENV=test`-only, bounded instant-shell interleaving and injected hydration failure seams for the built PTY acceptance suite (`src/cli/clio.ts`). |
 | `CLIO_CODER_REQUIRE_HOME_PREFIX` | Test guardrail: abort if resolved directories escape `CLIO_CODER_HOME` (`src/core/init.ts`). |
 
 Variables used only by external benchmark harnesses or install scripts are not

package/docs/guide/fleet-dispatch.md

@@ -128,10 +128,11 @@ the node's real SSH channel:
 Run it with `clio-coder doctor`. Plain doctor is diagnostic and read-only: it
 reports the live probe rows but does not create or refresh
 `fleet-preflight.json`, and therefore does not change dispatch eligibility.
+Run `clio-coder doctor --fix` to record passing preflight results into
+`fleet-preflight.json` and make verified nodes dispatch-eligible.
 Placement still reads a pre-existing record under the state directory, keyed by
 node and project root; a changed host, changed project root, or local
-`clio-coder` upgrade invalidates that record and admission fails closed. The
-current CLI exposes no mutating doctor preflight that refreshes it. Failing
+`clio-coder` upgrade invalidates that record and admission fails closed. Failing
 nodes are doctor warnings rather than a failure of the local installation.
 
 ## Placement and process-safe admission

package/docs/guide/glossary.md

@@ -28,7 +28,7 @@ This document defines the 50 core architectural concepts and terminology used th
 
 ### 6. Receipt
 - **Definition**: An immutable, cryptographically sealed record of a completed run containing full execution facts, tool telemetry, token accounting, validation grounding, and outcome codes.
-- **Owning Type**: `RunReceipt` in `src/domains/dispatch/types.ts` (`RUN_RECEIPT_INTEGRITY_VERSION = 20`).
+- **Owning Type**: `RunReceipt` in `src/domains/dispatch/types.ts` (`RUN_RECEIPT_INTEGRITY_VERSION = 20` in `src/domains/dispatch/receipt-integrity.ts`).
 
 ### 7. Envelope
 - **Definition**: A bounded container enforcing byte-length limits and truncation indicators on a dynamic payload. Tool output carries shown and total byte counts plus a continuation fragment; a parent briefing carries byte count and SHA-256 content hash instead.

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

@@ -19,7 +19,7 @@ lifecycle operations.
 | Set up a new installation | `clio-coder configure` | Quick Connect: endpoint, key if needed, model, Connect; then start `clio-coder`. |
 | Change a connection | `clio-coder configure --section targets` | Add or edit endpoints, credentials, and models; choose role defaults. |
 | Change any setting or repair YAML | `clio-coder configure --edit` | Edit a draft, validate, and save with a backup. |
-| Diagnose the installation | `clio-coder doctor` | Read-only diagnosis. `clio-coder doctor --fix` repairs structure and permissions. |
+| Diagnose the installation | `clio-coder doctor` | Read-only diagnosis. `clio-coder doctor --fix` repairs structure and permissions, and records fleet preflight results. |
 | Finish a package-manager update | `clio-coder upgrade --post-install` | Apply local migrations and installation checks. |
 | Start configuration over | `clio-coder reset --config` | Reset settings, preserve credentials and history, then run `clio-coder configure`. |
 | Emulate a fresh user | `clio-coder reset --all` | Remove all four user roots, recreate defaults, then run `clio-coder configure`. |
@@ -221,7 +221,7 @@ Runs a series of health sweeps across the environment:
 *   Asserts owner-only permissions on credentials (`0o600`).
 *   Reports the installed Clio, Node, platform, and engine package readiness.
 *   Checks config, data, state, cache, and state metadata freshness. It also warns when an OpenAI-compatible or Anthropic-compatible target appears to be a native LM Studio or Ollama server that should be converted.
-*   *Recovery:* Run `clio-coder doctor --fix` to create missing directories and templates, repair credential permissions, and refresh install metadata. Settings are always validated against the current schema; `--fix` does not rewrite removed keys or migrate an older settings file. Run `clio-coder upgrade` for registered lifecycle migrations, including removal of the retired `panes.agents` and `panes.keepFailed` keys; paths with no registered migration still require deliberate editing.
+*   *Recovery:* Run `clio-coder doctor --fix` to create missing directories and templates, repair credential permissions, refresh install metadata, and record fleet preflight results. Settings are always validated against the current schema; `--fix` does not rewrite removed keys or migrate an older settings file. Run `clio-coder upgrade` for registered lifecycle migrations, including removal of the retired `panes.agents` and `panes.keepFailed` keys; paths with no registered migration still require deliberate editing.
 
 ### B. Upgrades (`clio-coder upgrade`)
 Refreshes state metadata and applies pending lifecycle migrations, which may update settings, state, or extension data.