@iowarp/clio-coder 0.4.0 → 0.4.2

package/docs/{commands-and-modes.md → guide/commands-and-modes.md}

@@ -1,12 +1,12 @@
 # Commands and Modes
 
-> [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/commands_blueprint.html](html/commands_blueprint.html) (Version: 0.4.0).
+> **Visual blueprint:** The source checkout includes the complete
+> [Commands and Modes visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/commands_blueprint.html).
 
-
-Clio Coder is a terminal-first alpha harness. This page keeps the command
-reference, interaction modes, dispatch surface, verification lanes, and common
-operator guidance out of the README so the release entry point stays short.
+Clio Coder is a terminal-first coding agent. This page is the detailed command
+reference for interactive sessions, headless runs, dispatch, verification, and
+common operator workflows; the README remains an approachable product and
+onboarding guide.
 
 Source of truth: `src/cli/index.ts`, `src/interactive/slash-commands.ts`,
 `src/domains/dispatch/**`, `src/tools/registry.ts`, and the current test suite.
@@ -26,14 +26,14 @@ For process exit codes, stdout deliverable guarantees, and machine-readable JSON
 | `clio-coder --no-context-files` / `clio-coder -nc` | Skip `CLIO-CODER.md` project-context injection for one invocation. |
 | `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. |
+| `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. |
 | `clio-coder configure --interop` | Review other coding agents detected on this machine and connect one as a delegation peer. Without a TTY it prints the proposals and writes nothing. |
 | `clio-coder configure --list` | List user-facing runtime ids. |
 | `clio-coder configure --list --all` | List every registered runtime, including aliases. |
 | `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. `--worker-target` and `--worker-model` are accepted aliases from before the worker/fleet rename. |
+| `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 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. |
@@ -45,18 +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; with `--fix`, create missing structure and templates, repair credential permissions, and refresh install metadata. Settings remain strict and are not migrated. |
+| `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 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 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. `--follow` requires an interactive terminal and one run id. |
+| `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`. |
 | `clio-coder fleet view --watch <selection-file>` | Follow the run id currently named by the selection file and retarget when it changes. This is the operator-pulled watch surface used by the pane integration. |
 | `clio-coder dev components [list] [--json]` | List behavior-affecting harness components. |
 | `clio-coder dev components snapshot --out <path>` | Write a component snapshot JSON file. |
@@ -65,9 +66,12 @@ For process exit codes, stdout deliverable guarantees, and machine-readable JSON
 | `clio-coder eval validate\|run\|report\|compare\|gate` | Validate, run, report, compare, and gate local evaluation suites (Suite v2). |
 | `clio-coder memory list\|propose\|promote\|approve\|reject\|prune` | Manage scoped, evidence-linked memory records. |
 | `clio-coder trace runs [--db PATH] [--limit N] [--json]` | List runs recorded in the durable trace mirror beside the ledger. |
+| `clio-coder trace inspect --json` | Emit the fixed, bounded recent accounting projection used by the Workbench. It accepts no path, identifier, or limit and omits request text, error prose, event payloads, process commands, PIDs, and hosts. |
 | `clio-coder trace phases <runId> [--db PATH]` | Show one run's recorded phases. |
 | `clio-coder trace tail <runId> [--follow] [--db PATH]` | Tail one run's recorded events; `--follow` streams as they land. |
 | `clio-coder trace procs <runId> [--db PATH]` | Show the processes one run spawned. |
+| `clio-coder trace code-steps <rootId> [--json]` | Show the deterministic code-step records one fleet root wrote (argv, cwd, env names, exit code, duration, output digest, artifact paths). They are files beside the ledger, not rows in the mirror, so `--db` does not apply. |
+| `clio-coder trace prune [--max-age-days N] [--max-bytes N] [--db PATH] [--json]` | Apply the trace-retention policy while protecting queued and running runs; JSON reports the resolved policy, rows, runs and bytes removed, protected runs, and whether vacuum ran. |
 | `clio-coder trace sql <SELECT query> [--db PATH]` | Run one read-only query against the mirror. Only a single `SELECT` or read-only `WITH` statement is accepted; anything else exits 2. |
 | `clio-coder trace ui [--db PATH] [--port N]` | Serve the localhost-only waterfall viewer. The viewer is not part of the published package. |
 | `clio-coder dev evolve manifest init\|validate\|summarize` | Create and check typed harness change manifests. |
@@ -112,8 +116,8 @@ For process exit codes, stdout deliverable guarantees, and machine-readable JSON
 | `--tool-profile <name>` | Restrict dispatched-agent tools: `minimal-local`, `science-local`, or `full-agent`. |
 | `--require <capability>` | Require a target capability for dispatch. Repeatable. |
 | `--steer-channel <path>` | Read live steering lines from a FIFO or an appended regular file to steer the active run. |
-| `--with-panes` | Activate guest pane integration for this invocation when Clio is already inside a reachable herdr session. It overrides `panes.enabled`. |
-| `--no-panes` | Disable pane integration for this invocation. It overrides `panes.enabled`. |
+| `--with-panes` | Activate guest pane integration for this invocation when Clio is already inside a reachable herdr session. It overrides `interface.panes.enabled`. |
+| `--no-panes` | Disable pane integration for this invocation. It overrides `interface.panes.enabled`. |
 
 `--with-panes` is an explicit first-class launch mode, not permission to start a
 pane server. Clio confirms `HERDR_ENV=1`, connects to an existing socket, and
@@ -121,6 +125,10 @@ pings it before registering pane tools. The fleet watch pane runs
 `fleet view --watch` against a selection file. Clio writes only the selected run
 id, while the viewer reads journals itself, so dispatch remains independent of
 the pane host and a second terminal can use the same journal surface directly.
+`interface.panes.enabled: embedded` does not start a host: it is an accepted but
+unimplemented rung that resolves to no panes, prints a refusal during boot, and
+is labelled `NOT IMPLEMENTED` in Settings. Use `auto` or `--with-panes` only
+when Clio is already inside a reachable herdr session.
 
 ### Headless Session Continuity
 
@@ -161,18 +169,15 @@ The registry table below lists the available interactive slash commands. On a ba
 | `/quit` | `/quit` | Exit Clio Coder |
 | `/help` | `/help [query]` | Open the interactive help center showing commands and keys |
 | `/skill` | `/skill [name] [task]` | Open the Skills Hub or invoke a skill |
-| `/library` | `/library [kind]` | Open the Skills Hub on a resource library tab |
-| `/prompts` | `/prompts` | List prompt templates |
-| `/extensions` | `/extensions` | List installed extensions |
-| `/interop` | `/interop` | Review other coding agents detected on this machine |
-| `/share` | `/share [runId] \| /share export <path> \| /share import [--dry-run] [--force] <path>` | Share a worker result with the main agent, or export and import Clio archives |
+| `/resources` | `/resources [skills\|prompts\|library [kind]\|extensions [reload]]` | Browse installed resources and private library entries; `extensions reload` commits a new extension generation |
+| `/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 |
 | `/run` | `/run [--agent-profile <profile>] [--runtime <runtimeId>] [--target <id>] [--model <id>] [--thinking <level>] [--tool-profile <minimal-local\|science-local\|full-agent>] [--require <cap>] [--share] <agent> <task>` | Run a fleet agent |
 | `/delegate` | `/delegate [--share] <agent-id> <task>` | Run an ACP delegation agent |
 | `/btw` | `/btw <question>` | Ask a side question that never enters the session transcript |
 | `/oracle` | `/oracle <question>` | Ask a read-only advisor to challenge a question against this session's settled decisions |
 | `/council` | `/council [--roster <name>] [--rounds <n>] [--synthesis <judge\|vote\|none>] <task>` | Ask a roster of read-only members the same task, with an optional vote or judge synthesis |
-| `/agents` | `/agents` | List Clio agents and ACP delegation agents |
-| `/targets` | `/targets` | Open Settings → Targets: health, use, connect, probe, remove |
+| `/agents` | `/agents [list\|connect]` | List native and external agents, or review detected external-agent proposals |
 | `/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 |
@@ -180,12 +185,12 @@ The registry table below lists the available interactive slash commands. On a ba
 | `/tasks` | `/tasks add <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 |
 | `/view` | `/view [filter] \| /view verify <runId>` | Browse session artifacts and verify receipts |
-| `/panes` | `/panes show <run-or-agent> \| /panes open <preset-or-argv> \| /panes close [target]` | Inspect the pane layer, watch a live run in a pane, or open a utility pane |
+| `/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) |
 | `/thinking` | `/thinking [level]` | Set the chat thinking level, or open Settings → Orchestrator |
 | `/output` | `/output [verbosity]` | Set transcript detail (minimal, default, verbose), or open Settings → Terminal |
 | `/model` | `/model [pattern]` | Open model selector or set a model |
-| `/scoped-models` | `/scoped-models` | Open Settings → Models: the Alt+J / Alt+K cycle set and favorites |
-| `/settings` | `/settings [section]` | Open interactive settings |
+| `/settings` | `/settings [chat\|fleet\|targets\|context\|safety\|interface\|integrations] [group]` | Open interactive settings, optionally at a durable area and UI group |
 | `/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 |
@@ -193,6 +198,12 @@ The registry table below lists the available interactive slash commands. On a ba
 | `/fork` | `/fork` | Fork from an assistant turn |
 | `/export` | `/export [path]` | Export a self-contained HTML transcript by default; a `.md` path writes Markdown |
 
+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.
+
 `/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
@@ -243,8 +254,8 @@ member's label, target, model, node, round count, and synthesis mode before
 anything runs. Members are pinned to read-only autonomy and the council tool
 surface by admission, exactly as they are for a council the model asks for.
 
-`--roster` names a `workers.rosters` entry. Without it the command takes
-`workers.rosters.default` when that roster exists, and with neither it refuses
+`--roster` names a `fleet.rosters` entry. Without it the command takes
+`fleet.rosters.default` when that roster exists, and with neither it refuses
 and names the setting to declare. A roster that is the only one configured is
 still not the default: seating a council from whichever roster happens to be
 present would run models the operator never chose. `--rounds` accepts one to
@@ -291,11 +302,11 @@ The `/resume` picker accepts Page Up and Page Down to move by its 12 visible row
 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.
 Built-in command names are reserved across interactive and headless modes; a
-template with the same basename is omitted from `/prompts` with a collision
+template with the same basename is omitted from `/resources prompts` with a collision
 diagnostic instead of shadowing a command on one surface and expanding on another.
 If a matching template is found in an untrusted project root, Clio prints that the
 prompt template comes from an untrusted project root and directs the operator to set
-`skills.trustProjectCompatRoots`, sending nothing to the model. If the token names
+`integrations.projectResources.trustProjectImports`, sending nothing to the model. If the token names
 neither a command nor a template, it reports `is not a command` and points at `/help`;
 it is never sent to the model. That covers spellings removed outright, such as
 `/status` and `/receipts`, as well as ordinary typos. It replaces the earlier
@@ -388,7 +399,7 @@ stable board history and `userTaskId` pickup links survive `/resume` and `/fork`
 and can be audited from `current.jsonl`. Operator tasks persist separately in
 `.clio-coder/user-tasks.json`; the overlay can add, hand, finish, or drop them.
 The model-facing `tasks` tool's session-ledger and inbox bookkeeping is the
-documented read-class exception described in [the safety model](safety-model.md):
+documented read-class exception described in [the safety model](../architecture/safety-model.md):
 calls remain audited as `read` and do not grant workspace mutation authority.
 
 The `/decisions` overlay shows completed and cancelled `ask_user` interviews
@@ -405,24 +416,26 @@ and expanded dashboard summarize whether intervention is on, its rules or LLM
 tier, and current bank size.
 After `/resume`, Clio offers `/memory seed` when the newest handoff contains a
 structured snapshot. Seeding is explicit, deduplicated, and unavailable while
-`memory.intervention.enabled` is off.
+`context.memory.enabled` is false.
 
-The `/interop` overlay lists the other coding agents Clio found on this machine,
+The `/agents connect` overlay lists the other coding agents Clio found on this machine,
 grouped `Detected`, `Configured`, and `Declined`. A detected row's detail pane
-shows the exact `delegation.agents` entry that connecting it would append, plus
+shows the exact `integrations.externalAgents.entries` entry that connecting it would append, plus
 the two facts a new peer inherits: `projectContext: none`, so the peer receives
 the task text and never the project projection, and `toolGovernance:
-clio-policy`, so its tool calls are gated by Clio safety. Press `a` to connect
+clio-coder-policy`, so its tool calls are gated by Clio safety. Press `a` to connect
 one or `d` to decline; the overlay reads the report this process already produced
 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 shape `clio: codex detected on
-PATH and not configured. Run /interop to review.` It names only agents that are
-installed, unconfigured, and undecided, it appears at most once per set of facts,
-and it 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, 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.
 
 `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
@@ -458,8 +471,9 @@ editor reserves and can be rebound through `settings.yaml.keybindings`.
 | `Alt+T` | Open the session tree navigator (`/tree`). |
 | `Alt+U` | Toggle the footer dashboard between compact (quiet 2-zone) and expanded (4-zone urgency) layouts. |
 | `Alt+L` | Open the model and targets selector. |
-| `Alt+J` / `Alt+K` | Cycle forward / backward through the scoped model set (when empty, displays a notice directing the operator to `/scoped-models`). |
+| `Alt+J` / `Alt+K` | Cycle forward / backward through the configured model set (when empty, directs the operator to `/settings chat model-picker`). |
 | `Alt+W` | Toggle the Fleet Runs board (task, run ID, live telemetry, retry, and terminal history). Inside it, `Enter` opens the selected run's live worker detail, `s` steers, and `x` cancels. |
+| `Alt+E` | Toggle the files pane docked below the session in a `--with-panes` session inside herdr; the same as `/files`. Rebind through `clio-coder.files.toggle`. |
 | `Alt+B` | Open the composite session and operator task board (`/tasks`). Approved application-boundary override of editor word-back. |
 | `Alt+D` | Open the settled interview decision board (`/decisions`). Approved application-boundary override of editor word-delete. |
 | `Alt+S` / `Ctrl+Alt+B` | Convert an active attached dispatch to a detached background batch. |
@@ -511,7 +525,7 @@ 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
-`clio_steer_received` acknowledgement reports `received`. Single-shot
+`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.
 
@@ -522,7 +536,7 @@ Clio Coder operates with a single, unified tool surface. There are no separate t
 Tool and command execution is governed by:
 - **Target Capabilities:** What the selected model target actually supports (such as tools, streaming, and vision).
 - **Safety Net:** Granular rule packs loaded from `damage-control-rules.yaml`, project policies, and protected artifact paths; always on, identical at every autonomy level.
-- **Autonomy Mapping:** Once the net passes a call, the level decides whether it runs, asks, or is denied. See [safety-model.md](safety-model.md) for the full matrix.
+- **Autonomy Mapping:** Once the net passes a call, the level decides whether it runs, asks, or is denied. See [safety-model.md](../architecture/safety-model.md) for the full matrix.
 
 When an action asks for confirmation, whether from a safety-net rail or from the autonomy level, the call parks and three surfaces say so at once. The transcript row reads `⏸ awaiting approval` with `action ·`, `axis ·`, and `target ·` lines under it; the footer phase pill reads `⏸ confirm`; and a consequence-tier dialog opens with the tool, target, action, authenticated requester, one-shot authority, reversibility, and deny and stop effects. Titles distinguish workspace authority, outward consequences, safety-net confirmation, system changes, and worker escalations. The dialog sits at bottom center with five rows reserved for the composer and footer, and it re-anchors on resize. The composer rail switches to `CONFIRM` and repeats the keys while the prompt owns the keyboard.
 
@@ -547,6 +561,7 @@ Fleet dispatch runs focused agent recipes through configured targets. The final
 | `scout` | `explore` / `shadow` | Read-only repository exploration, symbol mapping, and context assembly. |
 | `researcher` | `research` / `shadow` | Documentation, literature, and web-grounded investigation. |
 | `provenance` | `operations` / `shadow` | Reading evidence files, receipts, diffs, and telemetry for handoffs. |
+| `oracle` | `plan` / `shadow` | Challenging one question against the session's settled decisions through `/oracle`. |
 | `context-bootstrap` | `internal` / `internal` | Bootstrap agent behind `clio-coder context init` that inspects the repository and returns `CLIO-CODER.md`. |
 
 Examples:
@@ -557,9 +572,11 @@ clio-coder run --agent architect "Plan a minimal change to add JSON output to th
 clio-coder run --agent verifier "Run tests and confirm the build passes."
 ```
 
-Shadow agents (`scout`, `researcher`, `provenance`) are internal orchestration
-helpers. They appear in `clio-coder agents --all` and the main prompt catalog, but
-user-origin `/run` and `clio-coder run --agent` requests are rejected for them.
+Dispatchable shadow helpers (`scout`, `researcher`, `provenance`) appear in
+`clio-coder agents --all`, the full agent catalog, and the compact fleet prompt,
+but user-origin `/run` and `clio-coder run --agent` requests are rejected for
+them. `oracle` also appears in `--all` and the full catalog, but it is deliberately
+excluded from the compact prompt and is reached only through `/oracle`.
 For broad repository reconnaissance, the operating contract and Scout catalog
 description steer the model to author a Scout dispatch. The chat harness does
 not mechanically route the request. A threshold nudge advises Scout delegation
@@ -576,33 +593,23 @@ to execute through the existing engine worker path, the sanctioned Claude Code w
 | --- | --- |
 | `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 live:smoke -- --target <id>` | One real headless turn against a configured target. Add `--delegation` for the `opencode` and `copilot` ACP agents. The other operator-run drivers (`live:fleet-dispatch`, `live:tui`, `live:home`) are listed in `benchmarks/internal/README.md`. |
 | `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 run test` | Contract and smoke tests through the sharded runner. |
+| `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/`. |
 
-Live drivers pick their model with `--target <id>`, naming one of the targets
-`clio-coder targets` lists; `--model <wireId>` and `--thinking <level>`
-override that target's defaults for the run. The run happens in a scratch Clio
-home holding only that target, so nothing touches the operator's real state:
-
-```bash
-npm run build
-npm run live:smoke -- --target local-lmstudio --model qwen3.8-27b
-npm run live:smoke -- --target anthropic --delegation
-```
-
-Live checks cost tokens or local GPU time and are not deterministic CI. They
-are useful for OpenAI-compatible local gateways such as llama.cpp, LM Studio
-with Dynamo-backed workers, vLLM, and SGLang, plus cloud targets when
-credentials are configured.
+Live provider checks cost tokens or local GPU time and are deliberately not
+part of deterministic CI. Maintainers perform them explicitly against an
+isolated Clio home and a named configured target, recording the target, wire
+model id, serving configuration, and result with the release evidence. This is
+the appropriate lane for local gateways such as llama.cpp, LM Studio, vLLM,
+and SGLang, and for cloud targets with operator-provided credentials.
 
 ## Environment Variables
 
-Clio Coder's behavior can be customized or overridden using various environment variables (such as `CLIO_CODER_RIGOR`, `CLIO_CODER_HOME`, and guardrail overrides). For the complete, detailed, and maintained inventory of environment variables, please refer to [environment-variables.md](environment-variables.md).
+Clio Coder also reads environment variables for platform paths, diagnostics, lifecycle integration, tests, and process-local behavior such as `CLIO_CODER_RIGOR`. Durable guardrail policy lives only in settings. For the complete maintained inventory, see [environment-variables.md](environment-variables.md).
 
 ---
 
@@ -752,7 +759,11 @@ The Clio TUI has been enhanced to maximize readability, operational focus, and c
 - **Footer Notification Degradation Ladder:** The footer notification badge reserves the severity head (`glyph count noun`) and `[Alt+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).
-- **Transactional Settings Center:** Open via `/settings` (or deep links `/targets`, `/fleet`, `/scoped-models`, `/thinking`, `/output`). Grouped into `CORE`, `ROUTING`, `RUNTIME`, and `EXPERIENCE` sections. Value edits are transactional: `Enter` opens value pickers/checklists and constructs immutable change plans offering `Apply this session`, `Apply and save globally`, or `Cancel`. Includes the Fleet entity workbench, Targets console table with in-place action drawer, scoped-model checklist, and narrow-terminal drill-down navigation below 72 columns.
+- **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
+  session`, `Apply and save globally`, or `Cancel`; narrow terminals use a
+  drill-down layout below 72 columns.
 
 ## Overlay and Presentation Conventions