@iowarp/clio-coder 0.3.0 → 0.3.2

package/docs/commands-and-modes.md

@@ -1,7 +1,7 @@
 # Commands and Modes
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/commands_blueprint.html](html/commands_blueprint.html) (Version: 0.3.0).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/commands_blueprint.html](html/commands_blueprint.html) (Version: 0.3.2).
 
 
 Clio Coder is a terminal-first alpha harness. This page keeps the command
@@ -19,19 +19,23 @@ For process exit codes, stdout deliverable guarantees, and machine-readable JSON
 | `clio-coder` | Launch the interactive terminal UI. |
 | `clio-coder run "<task>" [flags]` | Run one headless main-agent turn. Use `--json` for JSONL events. |
 | `clio-coder run "<task>" --agent <id> [flags]` | Dispatch one explicit fleet agent non-interactively and write a receipt. |
-| `clio-coder acp` | Serve Clio as an ACP v1 agent over stdio for ACP frontends. |
-| `clio-coder --version` | Print the installed version. |
+| `clio-coder acp [--cwd PATH] [--permission-timeout MS]` | Serve Clio as an ACP v1 agent over stdio for ACP frontends. |
+| `clio-coder --version` | Print the installed version. `clio-coder version` is the subcommand form. |
+| `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 --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 --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 profile list\|set\|remove\|rename\|bind\|unbind\|bindings` | Manage named fleet profiles and agent bindings. |
+| `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. |
 | `clio-coder targets remove <id>` | Remove a target. |
 | `clio-coder targets rename <old> <new>` | Rename a target id. |
@@ -46,30 +50,32 @@ For process exit codes, stdout deliverable guarantees, and machine-readable JSON
 | `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` | List fleet contracts, run a contract, or show dispatch state. |
+| `clio-coder fleet list\|run\|status\|drain\|resume` | List `.clio-coder/fleets/*.md` 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 dev components [list] [--json]` | List behavior-affecting harness components. |
 | `clio-coder dev components snapshot --out <path>` | Write a component snapshot JSON file. |
 | `clio-coder dev components diff --from <a> --to <b> [--json]` | Compare component snapshots. |
 | `clio-coder evidence build\|inspect\|list` | Build and inspect deterministic evidence artifacts. |
 | `clio-coder eval validate\|run\|report\|compare\|gate` | Validate, run, report, compare, and gate local evaluation suites (Suite v2). |
 | `clio-coder memory list\|propose\|approve\|reject\|prune` | Manage scoped, evidence-linked memory records. |
-| `clio-coder trace runs [--db PATH] [--limit N]` | List runs recorded in the durable trace mirror beside the ledger. |
+| `clio-coder trace runs [--db PATH] [--limit N] [--json]` | List runs recorded in the durable trace mirror beside the ledger. |
 | `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 sql <SELECT query> [--db PATH]` | Run one read-only SELECT against the mirror. Only SELECT is accepted. |
+| `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. |
-| `clio-coder extensions list\|discover\|install\|enable\|disable\|remove` | Manage installed extension packages and resource roots. |
+| `clio-coder extensions list\|discover\|install\|enable\|disable\|remove` | Manage installed extension packages and resource roots. `clio-coder ext` is an accepted alias. |
 | `clio-coder skills list\|search\|inspect\|validate\|install\|update\|sync\|eval` | Manage discovered skills, Clio-native skills, and local marketplace installs. |
-| `clio-coder docs [topic] [--no-open]` | Serve bundled HTML docs on 127.0.0.1. |
+| `clio-coder docs [topic] [--no-open]` | Serve the interactive HTML docs of a source checkout on 127.0.0.1; the npm package ships the Markdown guides only. |
+| `clio-coder usage report [--repo <path>] [--days <n>] [--json]` | Cross-session usage facts and opportunities from the session and run ledgers. The window defaults to 30 days and the JSON schema is marked experimental. |
 | `clio-coder dev share export --out <path> [--project\|--user\|--both] [--context] [--prompts] [--skills] [--settings] [--extensions]` | Export project context, prompts, skills, settings fragments, and extension bundles. |
 | `clio-coder dev share import <path> [--dry-run] [--force] [--project\|--user] [--json]` | Import a share archive with conflict reporting. |
 | `clio-coder dev share inspect <path> [--json]` | Inspect a share archive without importing it. |
+| `clio-coder export --out <path> ...` / `clio-coder import <path> ...` | Top-level aliases for `dev share export` and `dev share import`. Each `dev` command also resolves without the `dev` prefix. |
 | `clio-coder context` | Show project context status, preload class, codewiki freshness, and the codewiki digest when present. |
-| `clio-coder context init [--preview] [--heuristic] [--yes] [--json] [--adopt] [--propose\|--apply\|--rewrite] [--target <id> [--model <id>] [--thinking <level>]]` | Explore the repo and bootstrap or update project context: `CLIO-CODER.md`, `.clio-coder/codewiki.json`, and `.clio-coder/state.json`. |
+| `clio-coder context init [--preview] [--heuristic] [--yes] [--json] [--adopt] [--global] [--propose\|--apply\|--rewrite] [--target <id> [--model <id>] [--thinking <level>]]` | Explore the repo and bootstrap or update project context: `CLIO-CODER.md`, `.clio-coder/codewiki.json`, and `.clio-coder/state.json`. |
 | `clio-coder context refresh [--wiki]` | Rebuild the codewiki and state without touching `CLIO-CODER.md`; with `--wiki`, update an existing Markdown wiki. |
-| `clio-coder context wiki [--update\|--status]` | Generate, update, or inspect the agent-authored Markdown wiki under `.clio-coder/wiki/`. |
+| `clio-coder context wiki [--update] [--status] [--depth auto\|simple\|medium\|detailed] [--target <id>] [--model <id>] [--thinking off\|low\|medium\|high]` | Generate, update, or inspect the agent-authored Markdown wiki under `.clio-coder/wiki/`. |
 | `clio-coder context reset [--all] [--yes]` | Clear accumulated project context artifacts; `--all` also removes `CLIO-CODER.md`. `--yes` (or `-y`) answers every confirmation and is required when stdin is not a terminal. |
 | `clio-coder context index [--json]` | Build the structural codewiki index without model calls; writes `.clio-coder/codewiki.json` and `.clio-coder/state.json` and prints coverage plus a structural hash. |
 
@@ -128,38 +134,40 @@ clio-coder run \
 
 ## Interactive Slash Commands
 
-Slash commands are available inside the TUI. Type `/` at the start of the prompt to open autocomplete.
+Slash commands are available inside the TUI. Type `/` at the start of the prompt to open the grouped command palette autocomplete.
 
-The registry table below lists the available interactive slash commands. The "Aliases" column shows alternative command triggers that invoke the same command. The "Usage" column details the expected arguments and options, with brackets `[]` indicating optional arguments and angle brackets `<>` indicating required arguments.
+The registry table below lists the available interactive slash commands. On a bare `/`, commands are presented in groups (`Run`, `Inspect`, `Configure`, `Sessions`) with compact argument hints. Each operation has one canonical spelling; autocomplete, help, and parsing all read the same registry. The "Usage" column details expected arguments, with brackets `[]` indicating optional arguments and angle brackets `<>` indicating required arguments.
 
-| Command | Aliases | Usage | Purpose |
-| --- | --- | --- | --- |
-| `/quit` | `/exit` | `/quit` | Exit Clio Coder |
-| `/help` | - | `/help [query]` | Open the interactive help center showing commands and keys |
-| `/skill` | `/skill:`, `/skills:` | `/skill [name] [task]` | Open the Skills Hub or invoke a skill |
-| `/prompts` | - | `/prompts` | List prompt templates |
-| `/extensions` | - | `/extensions` | List installed extensions |
-| `/share` | - | `/share export <path> \| /share import [--dry-run] [--force] <path>` | Export or import Clio archives |
-| `/run` | - | `/run [--agent-profile <profile>] [--runtime <runtimeId>] [--target <id>] [--model <id>] [--thinking <level>] [--tool-profile <minimal-local\|science-local\|full-agent>] [--require <cap>] <agent> <task>` | Run a fleet agent |
-| `/delegate` | - | `/delegate <agent-id> <task>` | Run an ACP delegation agent |
-| `/agents` | - | `/agents` | List Clio agents and ACP delegation agents |
-| `/targets` | - | `/targets` | Show target hub for health, auth, models, and actions |
-| `/cost` | - | `/cost` | Show session token and cost totals |
-| `/context` | `/ctx`, `/compact` | `/context compact [instructions] \| /context init \| /context refresh \| /context reset` | Context hub: window overlay plus compact, init, refresh, and reset |
-| `/fleet` | - | `/fleet` | Show in-process dispatch running/retry status |
-| `/tasks` | - | `/tasks` | Show the session task board the agent tracks with the tasks tool |
-| `/memory` | - | `/memory seed` | Inspect task memory or seed it from the newest handoff |
-| `/view` | - | `/view [filter] \| /view verify <runId>` | Browse session artifacts and verify receipts |
-| `/thinking` | - | `/thinking [level]` | Open thinking-level selector, or set a level directly |
-| `/output` | - | `/output <verbosity>` | Set transcript detail: minimal, default, or verbose |
-| `/model` | `/models` | `/model [pattern]` | Open model selector or set a model |
-| `/scoped-models` | - | `/scoped-models` | Edit the Alt+J / Alt+K model cycle set |
-| `/settings` | `/config` | `/settings` | Open interactive settings |
-| `/resume` | - | `/resume` | Resume a past session |
-| `/new` | - | `/new` | Start a fresh session |
-| `/tree` | - | `/tree` | Open session tree navigator |
-| `/fork` | - | `/fork` | Fork from an assistant turn |
-| `/export` | - | `/export [path]` | Export the session transcript to Markdown |
+| Command | Usage | Purpose |
+| --- | --- | --- |
+| `/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 |
+| `/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 |
+| `/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 |
+| `/agents` | `/agents` | List Clio agents and ACP delegation agents |
+| `/targets` | `/targets` | Open Settings → Targets: health, use, connect, probe, remove |
+| `/cost` | `/cost` | Show session token and cost totals |
+| `/context` | `/context compact [instructions] \| /context init \| /context refresh \| /context reset` | Context hub: window overlay plus compact, init, refresh, and reset |
+| `/fleet` | `/fleet` | Open Settings → Fleet: defaults, profiles, agent bindings, nodes |
+| `/decisions` | `/decisions` | Show settled interview decisions and operator revisions |
+| `/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 task memory or seed it from the newest handoff |
+| `/view` | `/view [filter] \| /view verify <runId>` | Browse session artifacts and verify receipts |
+| `/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 |
+| `/resume` | `/resume` | Resume a past session |
+| `/new` | `/new` | Start a fresh session |
+| `/tree` | `/tree` | Open session tree navigator |
+| `/fork` | `/fork` | Fork from an assistant turn |
+| `/export` | `/export [path]` | Export a self-contained HTML transcript by default; a `.md` path writes Markdown |
 
 `/context` with no arguments opens the context-window ledger overlay. The
 subcommands own the durable project-context noun: `compact` summarizes older
@@ -171,23 +179,30 @@ context artifacts (`.clio-coder/codewiki.json`, `.clio-coder/state.json`,
 deletes `CLIO-CODER.md`; cancellation makes no changes. Session reset stays `/new`;
 there is deliberately no `/context clear`. The spellings `/context-init`,
 `/context-clear`, and `/context-view` are gone and are not aliased to anything.
-`/compact` is an alias for `/context compact` and carries the same optional
-instructions, so `/compact drop the old turns` runs the compaction the operator
-asked for instead of reporting that the spelling does not exist. `/exit` and
-`/config` are aliases of `/quit` and `/settings` on the same grounds: the
-command exists and the spelling is the one other tools in this class use.
-`/clear` has no counterpart here, so it stays an error that names `/help`.
+There are no slash-command aliases. `/context compact`, `/quit`, `/model`,
+`/settings`, and `/skill <name>` are their only spellings. Retired or foreign
+spellings stay errors that name `/help` instead of guessing which operation the
+operator intended.
 
-Only active commands run. Typing anything command-shaped that the registry does
-not own 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 behavior where an unrecognized
-spelling reached the model as prose and was answered conversationally, which left
-the operator believing a command had run when nothing had.
+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.
 
-Command-shaped means one word of letters, digits, and hyphens after the slash, so
+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
+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
+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
+behavior where an unrecognized spelling reached the model as prose and was answered
+conversationally, which left the operator believing a command had run when nothing had.
+
+Command-shaped means one word of letters, digits, hyphens, or colons after the slash, so
 paths such as `/home/user/notes.md` still reach the model unchanged. One word
-followed by prose is treated as a command, because `/compact tidy up` and `/tmp is
+followed by prose is treated as a command, because `/status please` and `/tmp is
 full` are indistinguishable. To send such a line as text, escape the slash:
 `\/tmp is full` reaches the model as `/tmp is full`. The escape claims a single
 backslash and only in front of a slash, so `\\server\share` is unchanged, and it
@@ -195,68 +210,176 @@ works on a real command too, so `\/help` is a question about `/help` rather than
 the help overlay.
 
 A rejected command stays in the input line. The error names the spelling and the
-text is still there to correct, rather than having to be retyped.
-
-
-The `/targets` hub is the only interactive target command. Use `j`/`k` or the arrow keys to browse targets, `Enter` to expand or collapse details, `u` to use the selected target for chat, `f` to set the selected target as the fleet default, `c` to connect, `r` to probe the selected target, and `R` to probe all targets. Worker-only targets such as `claude-sdk` and `claude-code` are selected for dispatch through fleet defaults or profiles, not through the chat target action.
-
-The `/fleet` overlay displays current running and retrying fleet state. It includes four tabs: Status, Nodes, Profiles, and Bindings; cycle with `Tab`. Status shows active runs, aggregate execution stats, and scheduled retries with backoff times. Nodes shows fleet placement health. Profiles supports creating, editing, renaming, and deleting worker profiles. Bindings supports binding or unbinding agents to profiles. Recent terminal run cards live in the `Alt+W` Fleet Runs board.
-
-The `/tasks` overlay shows the session task board the agent maintains through
-the `tasks` tool: every task with its status, the evidence note recorded when
-it was completed, and the reason recorded when it was blocked or dropped. The
-board persists in the session ledger as `taskLedger` entries, so it survives
-`/resume` and `/fork` and can be audited from the JSONL alone.
+text is still there to correct, rather than having to be retyped. Retired spellings (such as `/status`, `/receipts`, `/context-init`, `/context-clear`, `/context-view`, and `/skill:<name>`) are not recognized and fail closed with `/<token> is not a command. Type /help for the list.`
+
+The accepted spelling of every command is the table under [Interactive Slash Commands](#interactive-slash-commands); there is exactly one per operation, and nothing else is parsed as a command.
+
+Configuration lives in one place: the `/settings` overlay. `/settings <section>` reaches every section directly. `/thinking <level>`, `/output <verbosity>`, and `/model <pattern>` stay as quick setters that apply without opening anything.
+
+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.
+
+`/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
+block: a header (`◇ coder · node-a/example-coder-model · run 2mkas6s` for fleet workers,
+or `◇ codex (acp) · run 7hq2ab` for ACP peers), the worker's prose down a rail,
+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.
+Runs the model itself asked for through the dispatch tool render as folded `◆`
+cards under the spawning tool segment; operator-typed runs are `◇` and open.
+The footer chip in the status line splits them (such as `◇1 ◆3`). `Alt+O` toggles
+the newest foldable item (tool call or worker block), while `Ctrl+Alt+O` or
+`Alt+Shift+O` toggles every one. Memory workers on the background target never
+appear as transcript blocks. A run that fails over keeps one block and gains an
+`↻ failed over → attempt 2 on node-b/example-coder-model` line inside it.
+
+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
+will say it has not seen one. `--share` on either command hands the result over
+when the run finishes, and `/share [runId]` does it afterwards for a run already
+on screen. Bare `/share` takes the newest finished run the operator started
+themselves (never a model-asked `◆` run), while `/share <runId>` may name a
+model-asked run explicitly. What crosses is the receipt's own bounded text under a
+`[worker result] coder · run 2mkas6s · ok · shared by the operator` header,
+entering the session through the ordinary user-turn path so replay and
+compaction treat it as operator text. The header names the operator as the
+origin, and the system prompt tells the main agent that such a note is
+operator steering whose run id names a receipt it can read, so a model that
+never dispatched the run does not discard it as unattributed output. A turn
+that only relays a shared note does not trip the unbacked-worker-claim
+advisory.
+`/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.
+
+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
+entry plus the sealed receipt under `<state>/receipts/<runId>.json`. The session
+file's `workerRun` entries carry ids, origins, and runtime references only, without
+prose; the replayed answer is bounded from the receipt exactly like the live one.
+A run whose receipt is gone replays with a `receipt unavailable` footer rather
+than a header with nothing under it. The entries are bookkeeping: they cost nothing
+in the context window and never become model context, so resuming a session full
+of side runs does not spend the window on them.
+
+The `/tasks` overlay combines the live session board, terminal task history,
+successful workspace artifacts, and the project-scoped operator task inbox.
+The live board shows every task with its status, operator provenance, completion
+evidence, or block/drop reason. It persists as full `taskLedger` snapshots, so
+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):
+calls remain audited as `read` and do not grant workspace mutation authority.
+
+The `/decisions` overlay shows completed and cancelled `ask_user` interviews
+from the active branch. It retains settled and superseded values from
+`decisionLedger` snapshots, expands the source question and answer, and lets the
+operator supersede a decision or enter a correction. A correction is submitted
+to the model as an ordinary operator turn after the durable snapshot changes.
 
 The read-only `/memory` overlay keeps durable and session memory attributable
 in one place. It lists approved evidence-backed lessons, then the live task
 bank by private status, knowledge, and procedural class, including each
-entry's injection count and the last memory-step outcome. The welcome island
+entry's injection count and the last memory-step outcome. The welcome launchpad
 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.
 
+The `/interop` 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
+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
+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.
+
+`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
+configured, one `warn` row for a configured peer whose command no longer resolves
+on PATH, and one aggregate row counting the skills loaded from foreign roots. A
+machine with no other agents installed emits no interop rows at all. Reachability
+for a stdio peer means the command resolves; doctor never starts a session with
+one, and plain `doctor` writes nothing.
+
 ## Keybindings
 
 App bindings use `Alt + <key>` as the primary scheme, plus `Shift+Tab`,
-`Ctrl+D`, and a portable `Ctrl+G` leader. Modern terminals and Linux/meta
+`Ctrl+D`, `Shift+Enter` / `Ctrl+J`, and a portable `Ctrl+G` leader. Modern terminals and Linux/meta
 setups send Alt directly. Stock macOS Terminal.app needs **Use Option as Meta
 key** enabled in Settings > Profiles > Keyboard for native Alt; otherwise use
 `Ctrl+G` then the Alt binding letter.
 
+`Alt+B` and `Alt+D` are approved application-input boundary overrides of Pi's
+editor word-back and word-delete chords. Clio routes those two bindings before
+the editor sees them so the task and decision boards remain global shortcuts.
+They are intentional exceptions to the other app bindings' avoidance of Pi
+editor reserves and can be rebound through `settings.yaml.keybindings`.
+
 | Binding | Action |
 | --- | --- |
-| `Shift+Tab` | Cycle thinking level. |
-| `Alt+T` | Open the session tree navigator. |
-| `Alt+U` | Toggle the footer dashboard between compact and expanded layouts. |
+| `Enter` | Send draft prompt (when idle) or deliver it at the next slot of the active run (when streaming). |
+| `Shift+Enter` / `Ctrl+J` | Insert a newline into multiline editor input. |
+| `Ctrl+P` / `Ctrl+N` | Browse backward / forward through prompts accepted in this interactive process; returning past the newest entry restores the unfinished draft. |
+| `Alt+Enter` | End of turn: queue the current draft for delivery when the active run settles. |
+| `Alt+I` | Interrupt: cancel the active run and deliver the current draft now. Refused while an attached dispatch runs or a permission ask is parked; the draft then queues for the next slot. |
+| `Alt+Up` | Restore queued next-slot and end-of-turn messages to the editor. |
+| `Shift+Tab` | Cycle orchestrator thinking level (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`). |
+| `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 through the scoped model set (when empty, displays a notice directing the operator to run `/scoped-models`). |
+| `Alt+J` / `Alt+K` | Cycle forward / backward through the scoped model set (when empty, displays a notice directing the operator to `/scoped-models`). |
 | `Alt+W` | Toggle the Fleet Runs board (task, run ID, live telemetry, retry, and terminal history). |
+| `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. |
-| `Alt+O` | Toggle the latest tool segment between collapsed and full body. |
-| `Ctrl+Alt+O` / `Alt+Shift+O` | Toggle all tool segments between collapsed and full bodies. |
-| `Alt+P` | Toggle live partial tool output in expanded tool bodies. |
+| `Alt+O` | Toggle the newest tool call or worker block between collapsed subline and full body. |
+| `Ctrl+Alt+O` / `Alt+Shift+O` | Toggle all tool calls and worker blocks between collapsed sublines and full bodies. |
+| `Alt+P` | Toggle streaming partial tool output in expanded tool bodies. |
 | `Alt+R` | Toggle the latest thinking block between hidden marker and full body. |
 | `Ctrl+Alt+R` / `Alt+Shift+R` | Toggle all thinking blocks between hidden markers and full bodies. |
 | `Alt+G` | Open the current input in an external editor. |
 | `Alt+X` | Dismiss footer notifications. |
-| `Alt+Enter` | Queue the current input as a follow-up message. |
-| `Alt+Up` | Restore queued follow-up messages to the editor. |
 | `Ctrl+G`, then a letter | Portable leader fallback for Alt-letter actions. |
-| `Ctrl+C` | With no overlay, cancel a stream, clear input, or press twice to exit. With an overlay open, close/cancel that overlay only. |
-| `Ctrl+D` | Exit when the editor is empty; otherwise delete the next character (pi-compatible). It never exits from inside an overlay. |
-| `Esc` | With an overlay open, stays inside it (list filters clear first, then close). With no overlay, cancel a stream/bash operation or collapse the dashboard. |
+| `Ctrl+C` | With no overlay: cancel stream, clear input, or press twice to exit. With an overlay open: close/cancel that overlay only. |
+| `Ctrl+D` | Exit when the editor is empty; otherwise delete the next character. It never exits from inside an overlay. |
+| `PageUp` / `PageDown` | In `/resume` and list overlays: scroll the selection by one full page (12 rows). |
+| `Esc` | With an overlay open: clear non-empty filter first, move up drill-down level, then close/cancel. With no overlay: cancel stream/operation or collapse dashboard. |
 
 When scripting Clio inside tmux, prefer `tmux send-keys C-m` for submit/confirm keys instead of the literal `Enter` token; some tmux/terminal combinations do not deliver `Enter` reliably.
 
 ## Live Steering
 
-During an active assistant stream, pressing `Enter` sends the current editor
-text as steering for the active run instead of waiting for the turn to finish.
-The input is delivered through `agent.steer` before the next model turn.
-`Alt+Enter` keeps the after-run follow-up behavior.
+While a run is active, the key that submits a message chooses when it lands.
+There are three modes, chosen per message; the default is next slot.
+
+| Mode | Key | Delivery |
+| --- | --- | --- |
+| Next slot | `Enter` | Between tool batches, mid-run, through `agent.steer`. The agent keeps going and reads the message before its next model call. |
+| End of turn | `Alt+Enter` | When the whole run settles and Clio would hand control back, through `agent.followUp`. A turn is the whole run, not one model round. |
+| Interrupt | `Alt+I` (or `Ctrl+G`, `i`) | Cancels the in-flight work the way `Esc` does (generation aborts; a running bash child gets SIGTERM, then SIGKILL), waits for the cancelled run to seal its tool results in ledger order, then submits the message as a fresh prompt. Anything already queued returns to the editor. |
+
+Interrupt is refused in two states and the message is queued for the next slot
+instead, with a notice saying why: while an attached dispatch is running (the
+abort would kill the worker's run with no receipt; steer it with `@<agent>` or
+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.
 
 For running dispatches, the editor also accepts:
 
@@ -328,19 +451,18 @@ after 9 or more manual read-only exploration calls in one turn.
 Agent recipes are the Markdown source files. The normalized agent spec is the
 catalog/runtime view: category, capability class, latency class, tags, mode, and
 tool set. This keeps Clio's product vocabulary stable while dispatch continues
-to execute through the existing Pi-backed worker path, the sanctioned Claude Code worker runtimes (`claude-sdk` and `claude-code`), or external ACP delegation agents.
+to execute through the existing engine worker path, the sanctioned Claude Code worker runtimes (`claude-sdk` and `claude-code`), or external ACP delegation agents.
 
 ## Verification Lanes
 
 | Command | Purpose |
 | --- | --- |
-| `npm run ci` | Local and GitHub PR gate: typecheck, Biome check, skills pin check, build, and deterministic tests. |
+| `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 test:live` | Local manual live-model smoke. Requires `CLIO_CODER_LIVE_SMOKE=1` and a configured real model target. Add `-- --delegation` for `opencode` and `copilot` ACP delegation checks. |
 | `npm run typecheck` | Strict TypeScript pass. |
-| `npm run lint` | Biome checks; warnings are reported in the release gate output. |
-| `npm run test` | Contract, smoke, and boundary tests. |
-| `npm run check:boundaries` | Boundary invariants only. |
+| `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 run build` | Production bundle through `tsup`. |
 | `npm run dev` | `tsup --watch`. |
 | `npm run clean` | Remove `dist/`. |
@@ -472,18 +594,22 @@ Clio Coder features direct, interactive controls for model reasoning and thinkin
 - **Thinking Level (`Shift+Tab`):** Allows operators to cycle through available thinking configurations. This is useful for dialing model reasoning budgets up or down in real time.
 - **Thinking Blocks Toggle (`Alt+R`):** Toggles the latest assistant thinking block between a compact, single-line folded marker and an expanded, full-body view.
 - **All Thinking (`Ctrl+Alt+R` / `Alt+Shift+R`):** Toggles every thinking block in the transcript.
-- **Tool Body Toggle (`Alt+O`) / All Tools (`Ctrl+Alt+O` / `Alt+Shift+O`):** Expand the latest tool or every tool body.
+- **Tool Body Toggle (`Alt+O`) / All Tools (`Ctrl+Alt+O` / `Alt+Shift+O`):** Expand the latest tool or every tool body. The single-target key takes the newest foldable thing of either kind, so a worker card that just landed opens before the tool call above it; exactly one surface advertises the chord at a time.
 - **Live Tool Output (`Alt+P`):** Pause or resume cumulative partial tool output in expanded live tool bodies; the tool still executes.
 - **Live Streaming:** During active assistant turns, thinking increments stream live into the chat panel down a rail-prefixed segment. Reasoning totals marked `≈` are approximations from visible text; provider-reported totals are shown without that marker. Neither implies complete or cryptographically verified hidden reasoning.
 - **Thinking Replay:** When continuing a conversation, prior thinking is preserved and replayed in the history according to target-specific rules.
 
 ## TUI Surface Refinements
 
-The Clio TUI has been enhanced to maximize readability and command discovery:
+The Clio TUI has been enhanced to maximize readability, operational focus, and command discovery:
 
-- **Redesigned Compact Footer:** The footer dashboard displays real-time token, cost, and target indicators in a single-row layout. Use `Alt+U` to toggle the footer between compact and expanded widgets.
-- **Relocated Telemetry:** Per-turn telemetry is surfaced in the footer activity area, keeping token consumption and execution costs visible without adding extra transcript noise.
-- **Overlay Navigation:** Standardized overlays are available for settings, model selection, `/help` key reference, target health, and session tracking.
+- **Adaptive Welcome Launchpad:** Before the first prompt, renders a compact launchpad with bold CAPS section tags (`WORKSPACE`, `ROUTE`, `NEXT`), honest readiness indicators, and context-sensitive next actions. Upon first prompt submission, it deliberately collapses into a single-line session header (`>C_ Clio Coder vX.Y.Z · <workspace · git branch> · <target·model · ready> · ctx ready · type a task`) so the conversation transcript owns the viewport.
+- **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 · Shift+Enter 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 default-output tags). Line 1 displays workspace location, git branch/dirty state, and active phase only when meaningful; Line 2 displays the context window gauge and best current/last-turn receipt. `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 `[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.
 
 ## Overlay and Presentation Conventions
 
@@ -503,9 +629,9 @@ Diagnostic writes in the transcript use the themed notice channel instead of raw
 
 | Level | Glyphs | Color Token | Purpose |
 | --- | --- | --- | --- |
-| `info` | `·` | `dim` | General system information and usage |
+| `info` | `ℹ` | `info` | Informational notices and general system status |
 | `success` | `✓` | `success` | Operation completed successfully |
-| `warn` | `!` | `warning` | Non-fatal issue or precaution |
+| `warn` | `⚠` | `warning` | Non-fatal issue or precaution |
 | `error` | `✗` | `error` | Fatal issue or operation failure |
 
 ### ListOverlay Behavior
@@ -523,6 +649,7 @@ The detail pane displays structured descriptions, usage, or state metadata using
 
 All TUI overlays fluidly adapt to narrow terminals down to 40 columns:
 - Split overlays such as `/view` gracefully fall back to a single-pane presentation with `[Tab]` switching between list and content 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.
 
 ## Troubleshooting

package/docs/config-knobs-audit.md

@@ -31,7 +31,7 @@ Every runtime-tunable value needs both halves; the pair is one knob, not two. Th
 | `CLIO_CODER_MAX_TOOL_CALLS` | 50 | `src/engine/loop-guard.ts` → `src/engine/worker-runtime.ts` | Worker lifetime tool-call cap for a dispatched run. Different axis than the orchestrator budget despite the near-identical name. |
 | `CLIO_CODER_MAX_RUNS` | 1000 | `src/domains/dispatch/state.ts` | Dispatch run-ledger retention cap. |
 | `CLIO_CODER_MAX_CONTEXT_TOKENS` | unset | `src/domains/providers/runtime-resolution.ts` | Context-window override for local runtimes. Also set internally by `clio-coder run --max-context-tokens` (see §6). |
-| `CLIO_CODER_KV_CACHE_MODE` | unset | `src/engine/apis/lmstudio-native.ts` | KV-cache quantization mode. Also set internally by `clio-coder run --kv-cache-mode`. |
+| `CLIO_CODER_KV_CACHE_MODE` | unset | retired | KV-cache quantization mode. Also set internally by the former `clio-coder run --kv-cache-mode` path. |
 | `CLIO_CODER_SAMPLING_OVERRIDES` | unset | `src/engine/apis/sampling-overrides.ts` | JSON sampling-parameter override. Set internally by print-mode sampling flags. |
 | `CLIO_CODER_READ_MAX_BYTES` | 51200 (50 KB) | `src/tools/read.ts` | Per-call byte cap for the read tool. |
 | `CLIO_CODER_OBSERVATION_TURN_BUDGET_BYTES` | 196608 (192 KB) | `src/tools/observation.ts` | Shared per-turn byte pool across all observation tools. |
@@ -70,8 +70,6 @@ All default off; all enabled with `1`.
 | `CLIO_CODER_TRACE_BOOT` | `src/core/boot-trace.ts` | Boot-phase timing trace. |
 | `CLIO_CODER_TIMING` | `src/entry/orchestrator.ts` | Startup timing report to stdout. |
 | `CLIO_CODER_DEBUG_SHUTDOWN` | `src/core/domain-loader.ts`, `src/core/termination.ts` | Shutdown-path diagnostics. |
-| `CLIO_CODER_DEBUG_LMSTUDIO` | `src/domains/providers/runtimes/common/lmstudio-logger.ts` | LM Studio wire logging. |
-| `CLIO_CODER_RUNTIME_VERBOSE` | `src/engine/apis/lmstudio-native.ts` | Verbose runtime logging. |
 | `CLIO_CODER_HOOK_BUDGET_DEBUG` | `src/domains/middleware/runtime.ts` | Per-overrun hook-budget diagnostics. |
 
 ## 4. Internal plumbing (Pre-consolidated State)