@iowarp/clio-coder 0.3.0 → 0.3.1

package/docs/built-in-agents.md

@@ -3,7 +3,7 @@
 Clio Coder dispatches focused fleet agents from Markdown recipes. Recipes are data files, not hidden code plugins: YAML frontmatter declares identity, mode, tools, optional target/model hints, and thinking level; the Markdown body is the agent instruction text.
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard for the agent registry and dispatch admission check gates is located at [docs/html/agents_blueprint.html](html/agents_blueprint.html) (Version: 0.3.0).
+> **Interactive Spec Available:** An interactive dashboard for the agent registry and dispatch admission check gates is located at [docs/html/agents_blueprint.html](html/agents_blueprint.html) (Version: 0.3.1).
 
 The source of truth is `src/domains/agents/**`. Clio's agent dispatch engine and execution boundaries are built upon the [@earendil-works/pi-agent-core](https://www.npmjs.com/package/@earendil-works/pi-agent-core) library.
 
@@ -72,6 +72,8 @@ Grounding is checked against the run's own reads, not just against the file. The
 
 Every contract-bearing agent gets bounded in-worker repair. When the terminal result misses its contract, the worker replays the validator's own reason, the exact accepted shape, and the `path:line` locations this run actually read, then asks for the result again. Two repair rounds is the whole allowance; after that the run fails with `result_contract_exhausted`. This is what keeps a small local model that gathered the right evidence from being failed for a shape mistake nobody told it about.
 
+Two rounds only help when the reason is actionable, so a validator reason names the mistake and shows the value that would have passed. A `mutation-report` with `"validations":[]` is told the array was empty and is given one entry shaped like `{"name":"npm test","passed":true,"evidence":"exit 0"}`, and a report whose entries are malformed is told which keys each entry carries. Naming the requirement alone left a small model re-emitting the same empty array through both rounds.
+
 ---
 
 ## Frontmatter schema
@@ -115,7 +117,7 @@ Skills are knowledge attachments declared under `skills: [...]` in the YAML fron
 
 *   **Visibility**: Normal `clio-coder agents` lists user-visible (base/custom) agents. The `/agents` slash command shows both Clio fleet agents and ACP delegation agents. The command `clio-coder agents --all` includes shadow/internal specs reserved for Clio orchestration.
 *   **Invocation limits**: User-origin `/run` and `clio-coder run --agent` **cannot** invoke shadow/internal agents.
-*   **Orchestrator dispatch**: Internal main-agent dispatch can invoke shadow agents through the `dispatch` tool. The operating contract and Scout's catalog description steer the model to dispatch Scout for broad repository reconnaissance, while narrow file or symbol inspection remains local to the main agent. If a turn reaches 9 or more manual read-only exploration calls without completing Scout dispatch, a threshold nudge advises delegation on the continuation.
+*   **Orchestrator dispatch**: Internal main-agent dispatch can invoke shadow agents through the `dispatch` tool. The operating contract and Scout's catalog description steer the model to dispatch Scout for broad repository reconnaissance, while narrow file or symbol inspection remains local to the main agent. If a turn reaches 9 or more manual read-only exploration calls without completing Scout dispatch, a threshold nudge advises delegation once, as a transcript notice. It never carries the turn onward into another model round.
 *   **TUI rendering and control**: Shadow dispatch rows are marked with an `sh:` prefix. The Fleet Runs island and board show the bounded task, run ID, live tools, tokens, priced cost, retry state, and terminal outcome. Select an HTTP/SDK run to steer it or cancel any active worker/retry timer.
 *   **ACP Delegation**: The `/delegate` command is reserved for ACP delegation only, which is separate from Clio fleet subagents.
 

package/docs/capacity-and-scheduling.md

@@ -1,6 +1,6 @@
 # Capacity Leases & Fleet Scheduling
 
-This document specifies the multi-process capacity leasing protocols, node scheduling models, cross-process transaction locks, and failure recovery mechanics implemented in Clio Coder `v0.3.0`.
+This document specifies the multi-process capacity leasing protocols, node scheduling models, cross-process transaction locks, and failure recovery mechanics implemented in Clio Coder `v0.3.1`.
 
 Source implementations: `src/domains/scheduling/` and `src/domains/dispatch/capacity-lease.ts`.
 

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.1).
 
 
 Clio Coder is a terminal-first alpha harness. This page keeps the command
@@ -26,6 +26,7 @@ For process exit codes, stdout deliverable guarantees, and machine-readable JSON
 | `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 targets [--json] [--probe] [--target <id>]` | List configured targets, health, auth, runtime, model, and capabilities. |
@@ -128,9 +129,9 @@ 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. Aliases are stem-gated: they are hidden by default and only surfaced when the typed stem matches the alias spelling. The "Usage" column details expected arguments, with brackets `[]` indicating optional arguments and angle brackets `<>` indicating required arguments.
 
 | Command | Aliases | Usage | Purpose |
 | --- | --- | --- | --- |
@@ -139,22 +140,23 @@ The registry table below lists the available interactive slash commands. The "Al
 | `/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 |
+| `/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` | Show target hub for health, auth, models, and actions |
+| `/targets` | - | `/targets` | Open Settings → Targets: health, use, connect, probe, remove |
 | `/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 |
+| `/fleet` | - | `/fleet` | Open Settings → Fleet: defaults, profiles, agent bindings, nodes |
 | `/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 |
+| `/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` | `/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 |
+| `/scoped-models` | - | `/scoped-models` | Open Settings → Models: the Alt+J / Alt+K cycle set and favorites |
+| `/settings` | `/config` | `/settings [section]` | Open interactive settings |
 | `/resume` | - | `/resume` | Resume a past session |
 | `/new` | - | `/new` | Start a fresh session |
 | `/tree` | - | `/tree` | Open session tree navigator |
@@ -179,11 +181,15 @@ 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`.
 
 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.
+not own checks the loaded prompt templates across native and foreign prompt roots.
+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, and hyphens after the slash, so
 paths such as `/home/user/notes.md` still reach the model unchanged. One word
@@ -197,10 +203,56 @@ 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.
+Configuration lives in one place: the `/settings` overlay. `/targets`, `/fleet`, `/scoped-models`, bare `/thinking`, and bare `/output` are deep links that open it focused on the matching section; `/settings <section>` reaches every other section the same way. `/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 shows the session task board the agent maintains through
 the `tasks` tool: every task with its status, the evidence note recorded when
@@ -211,43 +263,70 @@ board persists in the session ledger as `taskLedger` entries, so it survives
 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.
 
 | 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 steer active assistant run (when streaming). |
+| `Shift+Enter` / `Ctrl+J` | Insert a newline into multiline editor input. |
+| `Alt+Enter` | Queue the current draft as a follow-up message delivered after the active run finishes. |
+| `Alt+Up` | Restore queued steering and follow-up 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+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+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 (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. |
+| `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.
 
@@ -472,18 +551,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 · EXPERIMENTAL · 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. Aliases are stem-gated and only surface when the typed stem matches the alias.
+- **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 +586,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 +606,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/configuration-and-targets.md

@@ -1,7 +1,7 @@
 # Configuration, Targets, Runtimes, and Auth
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive configuration validator, target resolver, and CLI command generator is located at [docs/html/configuration_blueprint.html](html/configuration_blueprint.html) (Version: 0.3.0).
+> **Interactive Spec Available:** An interactive configuration validator, target resolver, and CLI command generator is located at [docs/html/configuration_blueprint.html](html/configuration_blueprint.html) (Version: 0.3.1).
 
 Clio Coder is target-first: chat and fleet dispatch resolve through configured targets in `settings.yaml`, not through provider-specific ad hoc flags. Chat and print targets are HTTP/native/pi-ai-backed runtimes. Fleet dispatch can also target the sanctioned Claude Code subscription runtimes described below.
 
@@ -29,7 +29,7 @@ Default config file:
 <configDir>/settings.yaml
 ```
 
-Role contents: config holds user-authored files (settings, credentials, agents, skills, prompts, extensions, runtimes); data holds durable artifacts (memory, evidence, evals); state holds machine-produced session state (sessions, audit, receipts, runs.json, recent-models.json, install.json, interviews, scratch); cache holds disposable derived files.
+Role contents: config holds user-authored files (settings, credentials, agents, skills, prompts, extensions, runtimes); data holds durable artifacts (memory, evidence, evals); state holds machine-produced session state (sessions, audit, receipts, runs.json, recent-models.json, install.json, interop.json, interviews, scratch); cache holds disposable derived files.
 
 `clio-coder paths --json` prints the resolved directories and is the single source of truth for scripts.
 
@@ -102,7 +102,7 @@ Inside the TUI, verify the local surface with:
 /skill
 ```
 
-The `/targets` overlay is the interactive target hub. It shows one compact row per configured target, streams live probe updates, and keeps target actions on the selected row. Use `Enter` to show details, `u` to use the target for chat, `f` to set the target as the fleet default, `b` to set an eligible target as the background-memory default, `c` to connect or authorize it, `r` to probe the selected target, and `R` to probe all targets.
+`/targets` opens Settings → Targets: one row per configured target with its roles (chat, fleet, memory) and probe health, probed live when the section opens. `Enter` on a row offers use for chat and fleet dispatch, connect (API key or OAuth, then a probe), probe, and remove. The chat, fleet, and memory targets are also individual rows in the Orchestrator and Fleet sections.
 
 Only add `--context-window <tokens>`, `--max-tokens <tokens>`, or `--reasoning true` when you have runtime/model-specific values that should override live probe results.
 
@@ -125,7 +125,6 @@ Terminology used in code and receipts:
 
 ```yaml
 version: 1
-identity: clio
 autonomy: auto-edit         # read-only | suggest | auto-edit | full-auto (enforced at tool admission; the safety net applies at every level)
 
 targets:
@@ -215,6 +214,7 @@ retry:
   maxRetries: 3
   baseDelayMs: 2000
   maxDelayMs: 60000
+  streamStallMs: 180000
 guardrails:
   turnToolCallBudget: 60
   workerToolCallCap: 150
@@ -274,6 +274,33 @@ budgets. Workers routed to the same local target share that target's remaining
 VRAM with the orchestrator and scout model, so the same co-residency rule
 applies.
 
+LM Studio targets get three extra rules, because LM Studio reports no VRAM
+figure anywhere and `gpuStrictVramCap` caps GPU offload rather than refusing a
+load that will not fit. An oversized load therefore succeeds and then generates
+at CPU speed instead of failing.
+
+- **Context fit before load.** While another model is resident on the same
+  server, Clio caps a just-in-time load at 131,072 tokens and says so in a
+  warning naming the co-resident models. Raise or disable the ceiling with
+  `CLIO_CODER_LMSTUDIO_CORESIDENT_CONTEXT`. A target serving one model alone is
+  never clamped.
+- **One instance per model.** A load config is never sent for a model that is
+  already resident, because LM Studio answers that with a second instance
+  holding another copy of the weights and KV cache. A resident model is reused
+  as loaded, and the output budget follows the window the server actually has
+  open. Duplicate instances found at load time are released.
+- **Roles are never evicted blind.** Every model the configuration references
+  carries the plane it serves (chat, memory, worker, target default). Clio
+  evicts an unprotected resident first, and an eviction that has to touch a
+  configured model names its role in the warning, so unloading the model serving
+  proactive memory can never read as freeing a spare.
+
+A turn whose token rate collapses below 2 tokens per second for 30 seconds
+surfaces a `degraded` notice listing what is resident on the target. That is
+what a spill to CPU looks like from outside, and it is reported while the turn
+is still running rather than left as an indefinite spinner. The notice never
+cancels the turn.
+
 
 ---
 
@@ -314,19 +341,29 @@ Supporting mechanics:
 
 ## Settings Center
 
-Open `/settings` in the TUI to edit session-visible defaults in a full-screen Center. Wide terminals show sections on the left and the selected section's rows on the right. Narrow terminals stack the same sections inline. Each row shows a human label, a dim config path, the current value, and a bottom description with the edit affordance.
+Open `/settings` in the TUI to edit session-visible defaults in a full-screen transactional Center. Wide terminals (≥72 columns) show sections in a left sidebar and the selected section's rows in the main pane; ultrawide terminals (≥112 columns) expand the layout to include a dedicated right-hand inspector. Below 72 columns, the Center switches to a modal drill-down stack (section list → section rows → detail drawer) with breadcrumbs, `/` search filtering, and `Esc` backtracking. Below 60 columns, side margins drop to zero for full-width presentation.
 
-Targets are managed in `/targets`; keybindings are documented in `/help`.
+Every value change in Settings is transactional: selecting an editable row and pressing `Enter` opens a dedicated value picker, text input dialog, or provider-backed checklist (rather than immediately cycling values). Clio constructs an immutable change plan with preflight impact analysis and presents explicit destination choices:
+- `Apply this session` (for live-capable settings)
+- `Apply and save globally`
+- `Cancel` (or `Esc`)
 
-| Section | Editable rows |
-| --- | --- |
-| Autonomy & Safety | Autonomy level, Worker permission asks, Delegation governance, Safety net (read-only) |
-| Orchestrator | Thinking level, Target, Model |
-| Fleet | Default target, Default model |
-| Budget | Session ceiling (USD), Model cycle set |
-| Compaction | Auto-compact, Protected recent turns, Compaction threshold |
-| Retry | Retry transient errors, Max retries, Base delay (ms), Max delay (ms) |
-| Terminal | Terminal progress badges |
+For restart-required settings (`budget.concurrency`, `runtimePlugins`), the session-only option is suppressed and global saving announces `Saved to settings.yaml · restart Clio to apply`. For destructive actions (removing a target or fleet profile), the confirmation preflight details affected chat, fleet, and memory routes before execution.
+
+The Settings Center organizes all configuration under four non-selectable group headers:
+
+| Group | Section | Purpose & Content |
+| --- | --- | --- |
+| **CORE** | Autonomy & Safety (`safety`) | Autonomy level (`autonomy`), Worker permission asks (`workers.onPermission`), Delegation governance (`delegation.defaults.toolGovernance`), and Safety net status (read-only fact). |
+| **CORE** | Orchestrator (`orchestrator`) | Active chat target (`orchestrator.target`), model (`orchestrator.model`), and thinking level (`orchestrator.thinkingLevel`). Changing target rebases model and thinking choices. |
+| **ROUTING** | Fleet (`fleet`) | Entity workbench with group headers for `Defaults` (target, model, thinking level), `Profiles` (one-row summaries with `◆ Edit` drill-down and destructive removal preflight), `Agent routes`, and `Placement` (node status). |
+| **ROUTING** | Targets (`targets`) | Operational console table (`HEALTH`, `ID`, `ROLES`, `RUNTIME`, `LATENCY`) with in-place action/detail drawer for URL, default model, last probe, and failure reason. Actions include `Use`, `Connect`, `Probe`, and `Remove`. |
+| **ROUTING** | Models (`models`) | Provider-backed scoped model checklist with target-level and target/model entries, `Space` toggle, capability inspector, and preserved `Unavailable` group. Deep link `/scoped-models`. |
+| **RUNTIME** | Budget (`budget`) | Session ceiling USD (`budget.sessionCeilingUsd`), max output tokens (`budget.maxOutputTokens`), and worker concurrency (`budget.concurrency`, restart-required). |
+| **RUNTIME** | Compaction (`compaction`) | Auto-compact toggle (`compaction.auto`), protected recent turns (`compaction.excludeLastTurns`), and compaction threshold (`compaction.threshold`). |
+| **RUNTIME** | Retry (`retry`) | Transient error recovery toggle (`retry.enabled`), max retries (`retry.maxRetries`), base delay (`retry.baseDelayMs`), and max delay (`retry.maxDelayMs`). |
+| **EXPERIENCE** | Terminal (`terminal`) | Terminal progress badges (`terminal.showTerminalProgress`), transcript output detail (`terminal.outputVerbosity`: `minimal`, `default`, `verbose`), and inline status lines (`terminal.showInlineStatus`). |
+| **EXPERIENCE** | Advanced (`advanced`) | Notification dismiss defaults, memory intervention toggles, and runtime extension settings. |
 
 Label to config path mapping:
 
@@ -340,8 +377,14 @@ Label to config path mapping:
 | Model | `orchestrator.model` |
 | Default target | `workers.default.target` |
 | Default model | `workers.default.model` |
+| Default thinking level | `workers.default.thinkingLevel` |
+| Dispatched worker profiles | `workers.profiles.*` |
+| Agent route bindings | `workers.agentBindings.*` |
+| Scoped model set | `scope` |
+| Model favorites | `modelSelector.favorites` |
 | Session ceiling (USD) | `budget.sessionCeilingUsd` |
-| Model cycle set | `scope` |
+| Output token budget | `budget.maxOutputTokens` |
+| Worker concurrency | `budget.concurrency` (restart required) |
 | Auto-compact | `compaction.auto` |
 | Protected recent turns | `compaction.excludeLastTurns` |
 | Compaction threshold | `compaction.threshold` |
@@ -418,6 +461,9 @@ Every one of these has an environment override for a single process; see [enviro
 | `retry.maxRetries` | `3` | integer ≥ 0 | next turn |
 | `retry.baseDelayMs` | `2000` | integer ≥ 0 | next turn |
 | `retry.maxDelayMs` | `60000` | integer ≥ 0 | next turn |
+| `retry.streamStallMs` | `180000` | integer ≥ 0, `0` disables | next turn |
+
+`retry.streamStallMs` covers the failure a request error never reports: the backend answers `/health` while the slot behind the stream is dead. A run whose stream produces nothing for that long is aborted and handed to the same retry ladder as any transient error, so a headless run or a fleet worker recovers without a human pressing Esc. Time inside a tool call and inside the post-tool compaction guard does not count against it, so a long build is never mistaken for a wedged stream. Set it to `0` to keep the old behavior, where a stalled stream waits forever.
 
 ### Proactive memory
 
@@ -439,6 +485,8 @@ Every one of these has an environment override for a single process; see [enviro
 | `delegation.defaults.permissionTimeoutMs` | `120000` | integer ≥ 1 | next dispatch |
 | `delegation.defaults.toolGovernance` | `clio-policy` | `clio-policy`, `runtime-native` | next dispatch |
 
+`delegation.agents` is the one settings key Clio itself appends to, and only after an explicit answer in `clio-coder configure --interop` or `/interop`. Everything else here is operator-authored.
+
 ### Interface
 
 | Key | Default | Validation | When it applies |
@@ -457,7 +505,6 @@ Recently selected models are runtime state and live in `recent-models.json` unde
 | Key | Default | Validation | When it applies |
 | --- | --- | --- | --- |
 | `version` | `1` | integer, currently `1` only | restart |
-| `identity` | `clio` | string | restart |
 | `targets` | `[]` | list of target descriptors, each with a unique id and a registered runtime | immediately for the catalog, next session for routing |
 | `runtimePlugins` | `[]` | list of plugin descriptors | restart |
 | `fleet.nodes` | `[]` | list of node descriptors | next dispatch |
@@ -500,6 +547,29 @@ clio-coder configure \
 
 Add capability overrides such as `--context-window <tokens>`, `--max-tokens <tokens>`, or `--reasoning true` only when live probes cannot infer the right values for your runtime/model.
 
+---
+
+## Interop with other coding agents
+
+Clio knows which other coding agents are installed on the machine and in the project, and it can propose connecting an ACP-capable one as a delegation peer. `src/domains/interop/registry.ts` holds one entry per known agent (`claude-code`, `codex`, `opencode`, `gemini`, `copilot`, `cursor`, `antigravity`, plus the `.agents` convention) carrying its binaries, the directories it owns, its skill and prompt roots, its instruction filenames, and its ACP launch recipe when it has one.
+
+Detection is bounded and fails open. It resolves binaries with `access(X_OK)` and no shell, checks install directories, and runs a `--version` with a two-second timeout only when the caller asks for it and only for a binary that already resolved. A probe that cannot answer reports `unknown` rather than `absent`, and detection never throws. It never spawns a foreign agent's work command, and it never reads under a foreign agent's `sessions`, `history`, `cache`, `projects`, or `state` directory: it records that a foreign session store exists, never its contents.
+
+Review and connect detected agents with:
+
+```bash
+clio-coder configure --interop
+```
+
+On a terminal this walks the pending proposals one at a time, showing the exact YAML entry before it asks, and writes only what you answer yes to. Without a TTY it prints the proposals and exits 0 with `settings.yaml` byte-identical, which is what `scripts/install-local.sh` runs after `doctor --fix`. The interactive `clio-coder configure` wizard ends with the same review, and `/interop` in the TUI is the same flow as an overlay.
+
+No code path writes `delegation.agents` without an operator decision, and `doctor --fix` is not such a path. An accepted proposal appends exactly one entry through the serialized settings writer, which re-reads the file under its lock, so two processes accepting different agents cannot drop each other's entry. The appended entry carries `toolGovernance: clio-policy` and no `projectContext` key, so the peer inherits `projectContext: "none"` and receives your task text rather than the project projection. Both facts are shown before you are asked.
+
+Decisions are recorded in `<CLIO_CODER_HOME>/state/interop.json`, schema v1, written atomically only when an explicit decision is taken; `doctor` and non-TTY `configure --interop` write nothing at all. Each decision is keyed by agent kind plus a fingerprint of the facts it was made against (version and path), so a declined agent stays silent while its binary path and version hold, and comes back as a fresh proposal when either moves. Accepting and declining in one review persists both decisions. A file this version cannot parse degrades to "no report" rather than acting on a half-read decision record. Project-scoped facts stay where they already live, in `.clio-coder/state.json` under `contextSources`.
+
+Clio never writes into a foreign agent's directory. The safety path policy carries a `noWritePaths` class populated from the same registry; see [safety-model.md](safety-model.md) for the enumerated classes.
+
+---
 
 ## Subscription-based Targets and Runtimes
 
@@ -668,7 +738,7 @@ The command `clio-coder targets profile` supports several subcommands to manage
 - **unbind**: Unbind an agent from its profile. Use `clio-coder targets profile unbind <agentId>`.
 - **bindings**: List active agent-to-profile bindings. Use `clio-coder targets profile bindings [--json]` to output details in JSON format.
 
-Inside the TUI, `/targets` is the target management surface. The hub lists health, auth, runtime, model, capabilities, ready or unavailable reason, URL, and discovered models. Press `u` on a row to switch the active orchestrator target; the model is rebased to that target's default, matching `/settings` and `clio-coder targets use`. Press `f` to set the selected target as the fleet default. Press `c` on a row for the same API-key, OAuth, or no-auth connection flow used by the auth system.
+Inside the TUI, `/targets` opens Settings → Targets, the operational target console. Targets are rendered in a compact console table with columns for `HEALTH`, `ID`, `ROLES`, `RUNTIME`, and `LATENCY`, paired with an in-place action/detail drawer for URL, default model, last probe timestamp, and failure reason. Available actions include `Use` (switches active orchestrator target and rebases model to target default), `Connect` (executes API-key, OAuth, or no-auth setup then probes), `Probe` (runs immediate reachability probe with live activity indicator), and `Remove` (with preflight analysis of affected chat, fleet, and memory routes). Adding a target is performed via `clio-coder targets add`.
 
 ### Context-Window Provenance
 

package/docs/context-engine.md

@@ -1,7 +1,7 @@
 # Context Engine
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/context_blueprint.html](html/context_blueprint.html) (Version: 0.3.0).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/context_blueprint.html](html/context_blueprint.html) (Version: 0.3.1).
 
 Clio Coder tracks context pressure, records per-turn snapshots, and protects the provider context with bounded tool results plus single-threshold compaction.
 
@@ -9,10 +9,14 @@ Source of truth lives in `src/domains/session/context-accounting.ts`, `src/domai
 
 ## Context window resolution
 
-Each target has a declared, desired, and effective context window. The effective window is the operating ceiling used by budget checks and compaction. It can come from a live loaded model config, a probe, a target override, a model hint, catalog knowledge, a local-native default, or a descriptor default.
+Each target has a declared, desired, and effective context window. The effective window is the operating ceiling used by budget checks and compaction. Sources rank most-live first: the window discovery reports the model is loaded at, then a probed window, then a target override, then a model hint, catalog knowledge, a local-native default, and finally a descriptor default.
+
+The loaded window outranks the declared one because it is the only figure describing what the backend will serve. LM Studio routinely opens a model well below its `max_context_length`, and a run planned against the larger number overruns the server before compaction ever fires. Discovery carries that number per model in `discoveredModelStates[<model>].contextLength`, and the residency notice reads the same entry, so a model Clio is budgeting a loaded window for is never announced as absent.
 
 Local-native runtimes use a recommended minimum desired window of 128,000 tokens. If the live model reports a smaller loaded context window, Clio re-resolves the target so accounting uses the actual ceiling.
 
+The `/context` overlay states which layer answered, next to the token total: `loaded`, `probed`, `configured`, `declared`, or `assumed`.
+
 ## Token accounting and snapshots
 
 The estimator in `context-accounting.ts` uses a four-characters-per-token family for hot-path accounting. It estimates system prompt, tools, messages, pending input, and runtime categories without calling a model tokenizer on every TUI refresh.