@iowarp/clio-coder 0.4.5 → 0.4.7

package/docs/architecture/tui-design.md

@@ -9,6 +9,32 @@ The governing principle: **the user reads state from color, structure from frame
 
 ---
 
+## Output styles
+
+**Alt+O** cycles **Compact → Standard → Detailed → Compact**. Standard is the default, so the first press reveals Detailed. The current style appears in the footer. Cycling applies immediately to the current session, including streaming output and history. Save a preferred startup style through **/settings interface → Output style → Apply and save globally**, or `clio-coder configure --section panes`.
+
+| Content | Compact | Standard | Detailed |
+| --- | --- | --- | --- |
+| Answers and user messages | Complete | Complete | Complete |
+| Supplied reasoning | Marker | 3 rows | 12 rows |
+| Reads and searches | Consecutive successful observations grouped | Action and outcome | 8 result rows |
+| File changes | Paths and change facts | 8 diff rows | 20 diff rows |
+| Agent shell commands | Command and outcome | Command and outcome | 12 output rows |
+| Your `!` / `!!` shell commands | 3 output rows | 6 output rows | 12 output rows |
+| Workers | Identity, execution and validation outcome | 3 summary rows | 8 summary rows and bounded tool activity |
+| Failures and refusals | Actionable reason, up to 4 rows | Actionable reason, up to 4 rows | Up to 12 rows |
+| Turn receipt | None | Completion and available duration | Usage and model-call facts |
+
+Preview budgets count terminal rows **after wrapping**, including the `/view` overflow hint, and shrink on short terminals. Reasoning previews retain the newest text when streaming stops. Detailed remains bounded: a successful `cat` or file read cannot fill the transcript with the entire file.
+
+Use **/view transcript** to select full available reasoning, tool arguments/results, local shell output, or worker details. Search the list, press Enter to inspect, and Escape to return. Offloaded tool and dispatch output remains available in the other `/view` categories; missing or truncated captured content is identified. Inspection applies secret redaction, and `!!` output remains excluded from model context.
+
+Output style changes presentation only. **Shift+Tab** still changes the model's thinking effort. It does not reveal unavailable reasoning; Clio shows only reasoning supplied by the provider. The previous Alt+R, Alt+P, and expand-all rendering shortcuts are retired. `/output` now explains how to reach Alt+O and Settings. Existing `minimal`, `default`, and `verbose` preferences map to `compact`, `standard`, and `detailed` without rewriting other preferences.
+
+The footer owns live activity. Transcript actions have static running or outcome markers and update in place. Background workers add a count without replacing the main agent's current phase; a completed worker cannot clear a sibling's active state. Approval and user-input waits do not spin. Failed and cancelled turns retain their actual outcome, and an elapsed wait is described as silence rather than proof that a process is stuck. A worker's successful execution remains separate from its validation result.
+
+---
+
 ## 1. Color System
 
 All color styling is defined in [src/interactive/theme/tokens.ts](../../src/interactive/theme/tokens.ts). No raw SGR sequences, `38;2;`/`38;5;` ANSI escape fragments, or hardcoded hex colors are allowed outside this theme module.
@@ -22,7 +48,7 @@ All color styling is defined in [src/interactive/theme/tokens.ts](../../src/inte
 | `action` | `rgb(255, 126, 41)` (Orange) | Active autonomous operations: dispatching phase pills, active fleet badges, running fleet indicators, running connect/probe indicators, and user-steering queues. |
 | `success` | `rgb(87, 227, 137)` (Green) | Positive outcomes: success indicators (`✓`), ok health status, clean git trees, and output-token count updates. |
 | `warning` | `rgb(255, 180, 84)` (Amber) | Real warnings only: stale data, dirty trees, retry status, blocked tools, and truncation. |
-| `error` | `rgb(255, 92, 102)` (Red) | Failures: error indicators (`✗`), error rails, stuck states, and error message text. |
+| `error` | `rgb(255, 92, 102)` (Red) | Failures: error indicators (`✗`), error rails, failed outcomes, and error message text. |
 | `info` | `rgb(91, 168, 255)` (Blue) | Informational messages, notices, and system-prompt meters. |
 | `reason` | `rgb(157, 140, 255)` (Purple) | Reasoning-related status: thinking phases, thinking rails, reasoning-token metrics, and context compacting. |
 | `dim` | `rgb(106, 122, 133)` | Scaffolding elements: separators, key names, keyboard shortcut hints, durations, and timestamps. |
@@ -148,7 +174,7 @@ All TUI overlays and cards support compact widths down to 40 columns:
 
 ### 4.7 Decision Consequence Frames
 
-Permission confirmation and `ask_user` use one pure consequence presentation classifier while keeping separate input and execution protocols. The classifier supplies the tier title, semantic frame token, consequence and reversibility copy, requester attribution, and display actions. Permission keeps allow-once, deny, and stop behavior. `ask_user` keeps selection, free-text, cancellation, and its compact, panel, or interview layout chosen from question shape.
+Permission confirmation and `ask_user` use one pure consequence presentation classifier while keeping separate input and execution protocols. The classifier supplies the tier title, semantic frame token, consequence and reversibility copy, requester attribution, and display actions. Permission keeps allow-once, deny, and stop behavior. `ask_user` keeps selection, free-text, cancellation, and a single bottom-anchored, content-sized interview frame sized directly to the round.
 
 | Tier | Title | Token | Plain-text identity |
 | --- | --- | --- | --- |
@@ -167,7 +193,7 @@ The words carry the meaning when color is disabled. Permission copy states the e
 
 The Clio screen maintains a responsive, four-zone structure: the launchpad / session header, transcript, composer, and footer. `interface.mode` chooses the renderer at startup. The default `regular` mode uses terminal scrollback. Opt-in `fullscreen` mode uses the alternate screen: the launchpad/header and transcript occupy an independently scrollable viewport while the follow-up queue, composer, and footer remain docked at the bottom.
 
-In fullscreen mode, `PageUp` and `PageDown` scroll one viewport, `Home` and `End` jump to its bounds, `Ctrl+Shift+Up` and `Ctrl+Shift+Down` jump between semantic prompts, and the mouse wheel scrolls the transcript. Dragging the scrollbar thumb moves the viewport directly. `interface.fullscreenScrollbar` is `hidden`, `auto` (visible during interaction), or `always`. Manual scrolling suspends follow-end so new output does not steal the operator's position; returning to the bottom resumes it. Both fullscreen settings are restart-scoped because Clio constructs its terminal renderer and component graph once at startup.
+In fullscreen mode, `PageUp` and `PageDown` scroll one viewport, `Ctrl+G Home` and `Ctrl+G End` jump to its bounds, `Ctrl+Up` and `Ctrl+Down` jump between semantic prompts; plain Home/End edit the composer, and the mouse wheel scrolls the transcript. Dragging the scrollbar thumb moves the viewport directly. `interface.fullscreenScrollbar` is `hidden`, `auto` (visible during interaction), or `always`. Manual scrolling suspends follow-end so new output does not steal the operator's position; returning to the bottom resumes it. Both fullscreen settings are restart-scoped because Clio constructs its terminal renderer and component graph once at startup.
 
 `interface.smoothStreaming` controls presentation-only pacing of derived assistant text and thinking. The shipped `off` value uses the immediate 16 ms coalescer. `auto` paces only on a capable local TTY and bypasses pacing for non-TTY, SSH, multiplexers, CI, screen-reader/reduced-motion markers, or observed stdout backpressure. `on` explicitly requests grapheme-safe pacing, while still stopping frame production behind stdout backpressure. Raw provider wrappers never enter the panel, canonical events and persistence remain synchronous, and tool/message/turn/abort/retry/submit/teardown boundaries drain visible state before they continue.
 
@@ -175,8 +201,96 @@ Interactive startup uses one terminal lease across both boot stages. Stage 0 own
 
 ### 5.1 Welcome Launchpad & Session Header
 
-- **Pre-Submit Launchpad**: Before the first prompt, renders a compact launchpad at line 0 with bold CAPS section tags (`WORKSPACE`, `ROUTE`, `NEXT`), honest readiness state, and a context-sensitive next action (e.g. `ctx missing · /context init`, `ctx checking…`, or `ctx ready · type a task`). Asynchronous repository probes use height-stable dim placeholders (`factsPending`).
-- **Session Header Collapse**: On first user submission, the launchpad deliberately collapses into an immutable, 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 while the header keeps naming where Clio works, which route answers, and what the context is ready for.
+The header has two shapes and no box. Source: `src/interactive/welcome-dashboard.ts`;
+contracts: `tests/contracts/welcome-boot-header.test.ts`.
+
+- **Launchpad (before the first prompt): exactly three rows.** A masthead with
+  identity flush left and workspace flush right separated by a `frame`-token
+  rule, then the route, then one next step.
+
+  ```
+  >C_ Clio Coder v0.4.7 ──────────────────── ~/iowarp/clio-coder · main*
+    ✓ dynamo · qwen3.8-27b
+    describe a task · Enter to send · / for commands
+  ```
+
+  Under width pressure the identity drops its version, then its name; the
+  workspace drops its branch, then head-truncates the path keeping the leaf
+  (`…/clio-coder`). The product name outranks the version, and the branch is
+  given up before the path's leaf is obscured.
+
+- **Route row.** `✓ <target> · <model>` healthy, `! …` degraded, `✗ …`
+  unavailable, `◌ …` configured but not yet probed, `not configured` when
+  neither is set. A healthy route prints no probe latency; the glyph carries the
+  verdict and `/doctor` owns the timing. A failing route prints its reason,
+  sanitized to one line. The row reserves room for that reason where it can,
+  shrinking the route text to keep it, and drops it only when the width cannot
+  hold even the floors. The action row still names the route problem either way.
+
+- **Action row: one line, chosen by what actually blocks work.** First match
+  wins: no route (`no route selected · /model`), no model
+  (`no model selected · /model`), route unavailable or degraded
+  (`… · /settings targets`), `CLIO-CODER.md` malformed
+  (`CLIO-CODER.md malformed · /context to inspect`), no handbook
+  (`describe a task · /context init to index this repo`), stale handbook
+  (`describe a task · /context refresh to update it`), otherwise
+  `describe a task · <SubmitKey> to send · / for commands`. Missing project
+  context is guidance, not a blocker; the line still invites work. A *malformed*
+  handbook is pointed at inspection rather than regeneration, since the file
+  needs repair before it needs rebuilding. `<SubmitKey>` comes from the live
+  `tui.input.submit` binding and is omitted when that action is unbound.
+
+- **Session header (after the first prompt): exactly one row, and live.**
+
+  ```
+  >C_ Clio Coder v0.4.7 · dynamo · qwen3.8-27b · ~/iowarp/clio-coder · main*
+  ```
+
+  It follows a mid-session model change rather than freezing at collapse. It
+  carries identity, route and workspace and deliberately drops readiness,
+  latency, project-context state and onboarding text, which the footer and the
+  composer rail own. When the row will not fit, the survival order is the `>C_`
+  wordmark, then the route, then the workspace path, then the branch, then
+  `Clio Coder v<version>`. **The route is the last fact given up**, and it
+  outlives the workspace and the product name; below roughly the width of the
+  wordmark itself the row is the truncated wordmark alone.
+
+- **Transitions.** The first submit collapses the launchpad exactly once, before
+  any handler appends transcript output, on all three submit paths (ordinary
+  submit, admission of a queued boot submission, interrupt-submit). `/new`
+  returns to the launchpad. `/resume`, `/tree`, `/fork` and `/handoff` collapse
+  it, so a rebuilt transcript is never shown under fresh-start onboarding, and
+  `clio-coder --continue` / `--session <id>` opens directly in the collapsed
+  header once `session.resume()` has actually succeeded. Transitions are
+  idempotent.
+
+- **No filesystem work on the render path**, in any state, including the first
+  frame and render-cache hits. Project-context state comes from the context
+  domain's own reader, refreshed off the frame; until the first reading lands
+  the header shows `describe a task` rather than asserting a state it does not
+  know. A read that throws never becomes `ok` or `none` and never renews the
+  trust window, so once reads have been failing longer than the 10s window the
+  header stops asserting the last value, and a reading is only ever served for
+  the directory it was taken in. This is a change to per-frame render I/O; it is
+  not a claim that process startup got faster.
+
+- **Text safety.** Provider reasons, model ids, branch names and paths pass
+  through the project's one-line sanitizer (`sanitizeCallTargetText`,
+  `src/domains/safety/call-target.ts`) before styling: OSC and CSI stripped, C0
+  and DEL neutralized, whitespace collapsed. A hostile upstream error cannot
+  retitle the terminal, clear the screen, move the cursor, or inject colour
+  through the header. Wide Unicode, emoji and ZWJ sequences are preserved and
+  measured in terminal columns.
+
+Stage 0, before hydration, renders the same wordmark helper over three rows so
+the footprint matches the hydrated header, then the editor, then a footer line
+that stays blank until `Ctrl+C` arms the exit:
+
+```
+>C_ Clio Coder
+Starting Clio · you can type now
+
+```
 
 ### 5.2 Composer (ClioEditor)
 
@@ -187,20 +301,20 @@ Interactive startup uses one terminal lease across both boot stages. Stage 0 own
   - When the draft scrolls, the active mode folds into the scroll indicator row so the orange warning remains visible.
 - **Top Rail Metadata**: The top rail right displays target/model and thinking level with two-step color hierarchy: `off` (dim), `minimal`/`low` (muted), `medium`/`high` (`reason` purple), and `xhigh`/`max`/`on` (bold `reason` purple).
 - **Empty-State Placeholder**: Displays dim prompt `Ask Clio…  / for commands`.
-- **Lower Rail Affordance**: On terminals at or above 60 columns, the bottom rail displays `Enter send · Shift+Enter newline` (or resolved keybindings).
+- **Lower Rail Affordance**: On terminals at or above 60 columns, the bottom rail displays `Enter send · Ctrl+J newline` (or resolved keybindings).
 
 ### 5.3 Progressively Disclosed Footer
 
-- **Compact Mode (Quiet Idle)**: Two always-on lines that eliminate idle telemetry noise (suppresses `tools none`, `◌ idle`, and default-output tags):
+- **Compact Mode (Quiet Idle)**: Two always-on lines that eliminate idle telemetry noise (suppresses `tools none`, `◌ idle`, and duplicate turn receipts):
   - **Line 1 (Workspace & Readiness)**: CWD path, git branch/dirty state, and active phase pill only when meaningful.
-  - **Line 2 (Context & Receipt)**: Context window meter and the best current/last-turn receipt.
+  - **Line 2 (Context & Style)**: Context window meter, Output style, and session cost.
 - **Expanded Mode (`Alt+U`)**: Four responsive sections ordered by operational urgency rather than a static telemetry grid:
   1. `Activity`: Live agent phase, active workers, running tool calls.
   2. `Context`: Context window gauge, breakdown, token headroom.
   3. `Session`: Session cost, throughput, total token breakdown, leader key state.
   4. `Workspace`: CWD, branch, target, git dirty status.
   Empty rows collapse rather than occupying blank grid space.
-- **Notification Badge & Degradation Ladder**: The footer notification badge reserves the severity head (`ℹ 1 notice`, `⚠ 1 warning`, `✗ 1 error`), separator, and `[Alt+X] dismiss` tail first, allocating the middle width to an ellipsized message. At narrow widths, it degrades gracefully down the ladder (`head · [Alt+X] dismiss` → `head · [Alt+X]` → `head` → glyph alone) without clipping the action key.
+- **Notification Badge & Degradation Ladder**: The footer notification badge reserves the severity head (`ℹ 1 notice`, `⚠ 1 warning`, `✗ 1 error`), separator, and `[Ctrl+G x] dismiss` tail first, allocating the middle width to an ellipsized message. At narrow widths, it degrades gracefully down the ladder (`head · [Ctrl+G x] dismiss` → `head · [Ctrl+G x]` → `head` → glyph alone) without clipping the action key.
 
 ### 5.4 State Choreography Table
 
@@ -210,15 +324,15 @@ State is signaled through the status pill in the footer and matches the followin
 |---|---|---|---|
 | idle | Quiet (phase omitted; line 1 shows workspace, line 2 shows context/receipt) | None; last-turn telemetry on line 2 | No |
 | preparing / waiting | spinner + `waiting` (info) | None | No |
-| thinking | spinner + `thinking` (reason) | Dim `Thinking (N tokens)…` marker | No |
+| thinking | spinner + `thinking` (reason) | Bounded supplied reasoning | No |
 | writing | spinner + `writing` (accent) | Streaming markdown text | No |
-| tool running | spinner + `tool <name>` (accent) | `▸` tool execution ledger line | No |
+| tool running | spinner + `Running <name>` (accent) | `▸` tool execution ledger line | No |
 | blocked | `⏸ blocked` (warning) | Permission prompt surface | No |
 | retrying | `↻ retry 2/5` (warning) | Dim retry details line | No |
 | compacting | spinner + `compacting` (reason) | None | No |
-| dispatching / fleet live | spinner + `dispatch` (action) | Task island status updates | Yes |
-| stuck | `⚠ stuck 12s` (error) | Inline watchdog warning | No |
-| done | `✓ done` (success), then quiet telemetry | Settled transcript blocks | No |
+| dispatching / fleet live | Main phase plus worker count | Task island status updates | Yes |
+| prolonged silence | `⚠ No output · 12s` (warning) | No duplicate status | No |
+| ended | Ready, Failed, Cancelled, or Output limit | Settled transcript blocks | No |
 
 ---
 
@@ -230,27 +344,18 @@ State is signaled through the status pill in the footer and matches the followin
 - **Two-Cell Hanging Indent**: User and assistant prose are rendered with a fixed two-cell gutter. The first line begins with the turn prefix (`› ` or `✦ `), while all wrapped continuation lines indent by two spaces (`PROSE_GUTTER = "  "`), keeping multiline text visibly attached to its voice glyph.
 
 ### 6.2 Thinking Blocks
-Drawn as a folded dim marker (`Thinking (N tokens)…` or `Thinking…`), which expands into a body using the `reason` color vertical `│` rail. Cap of 12 lines.
+
+Supplied reasoning stays in stream order on the `reason` color rail. Compact shows a historical marker; Standard and Detailed show the bounded tail defined in [Output styles](#output-styles). The footer alone reports current activity.
 
 ### 6.3 Tool Ledger
-Every tool call owns one stable transcript block for its complete lifecycle. Streamed
-`toolcall_*` message updates first expose the call as `forming call`, the completed argument block
-becomes `ready`, `tool_execution_start` changes the same row to `running`, and cumulative
-`tool_execution_update` results replace the live body until `tool_execution_end` settles it. Rapid
-tool updates are coalesced to terminal frame rate; settlement always renders immediately.
 
-The collapsed form is one composed ledger line:
-```
-▸ verb(object) · resource · facts · size ✓ · 230ms · full: path (Alt+O)
+Each call owns one stable action row. Argument fragments stay hidden until the call is formed. A formed call becomes ready, then running, then settles with its actual outcome. Cumulative output replaces the live preview; late partials cannot overwrite a settled result. The same policy applies during replay.
+
+```text
+▸ bash(cat README.md) · exit 0 ✓ · 230ms
 ```
-- Verb is bold `accent`, tail details are `dim`, status glyph is semantic (`✓`/`✗`), and the keyboard shortcut hint is appended at the end. Tool ledgers maintain full terminal width and bypass the prose hanging indent.
-- Expanded calls show the primary argument in the signature and every secondary argument as a typed field list. Multiline argument bodies become line and byte facts, nested objects retain structured rendering, and safety-sensitive values remain redacted.
-- Running calls label `live output` and replace the cumulative partial result in place. Settled calls label `output` and show available exit status, result or observation counts, line count, displayed and total byte sizes, truncation, timeout, tool-token usage, dynamically added tools, context exclusion, and the full-output path. A blocked or aborted admission instead labels its `decision` and does not claim that the tool ran.
-- A call parked for one-shot approval replaces its running timer with `awaiting approval` and shows the already-sanitized action class, asking safety axis, and target below the row. These facts are transient UI state: approval, denial, abort, or settlement clears them, and they are never reconstructed from the session ledger.
-- The live permission frame derives its consequence tier from those typed facts and the authenticated origin. It anchors at bottom center with five rows reserved for the composer and footer, and it recomputes that anchor on resize. Each queued frame retains its own tier and requester.
-- Text and image tool results keep their text while rendering images as MIME and byte-size placeholders; base64 image data is never written to the terminal.
-- Successful `edit` and `write` calls render the bounded diff produced by the tool result. Live regular-screen and fullscreen rows color removed and added lines with the `error` and `success` tokens and emphasize changed words; `/resume` replay and `/export` keep the same numbered diff as plain text.
-- Operator `!` and `!!` bash commands use the same running and settled block as model-initiated bash. The block appears before the process starts, streams the throttled cumulative stdout/stderr tail, and settles in place while the existing `bashExecution` session entry remains the durable record. `!!` continues to exclude that record from model context and says so in the block.
+
+Successful reads and shell commands keep raw content out of Standard. Mutations show bounded diffs, and failures keep actionable context in every preset. `/view transcript` exposes full available arguments and results. Approval rows show the sanitized action and target, with no running spinner. Truncation, context exclusion, offload paths, refusal, cancellation, and missing results remain visible.
 
 ### 6.4 Editor Rail
 The right-hand label shows `model · thinking`. Thinking level colors map as: `off` (dim), `minimal`/`low` (muted), `medium`/`high` (`reason` purple), and `xhigh`/`max`/`on` (bold `reason` purple).
@@ -258,11 +363,9 @@ The right-hand label shows `model · thinking`. Thinking level colors map as: `o
 ### 6.5 Transcript Notices
 Replay and system tags (e.g. `[retry]`, `[model]`) are wrapped in `dim` brackets with a `muted` message. Retry tags use `warning` amber.
 
-### 6.6 Output Verbosity Receipts
-Turn usage receipts rendered at the bottom of completed turns respect the output verbosity configuration:
-- `minimal`: Omits the turn usage receipt entirely.
-- `default`: Renders one compact dim receipt: `turn · in <N> · out <M>`.
-- `verbose`: Renders the full receipt with model call counts (`over N calls`), cache reads/writes (`cache R/W`), reasoning tokens with provenance (`reasoning N provider` or `reasoning ≈N estimated`), and the verification caveat (`· reasoning text is a UI excerpt, not a verification`).
+### 6.6 Output Style Receipts
+
+Compact omits the separate turn receipt. Standard shows a small completion line with available duration. Detailed includes model calls, input/output tokens, cache usage, and supplied reasoning usage with provenance. Reasoning text is an excerpt, not verification. The quiet footer keeps the style and session cost visible; detailed telemetry is available through Detailed or the expanded dashboard.
 
 ### 6.7 Code Ink (Syntax Highlighting)
 
@@ -323,9 +426,9 @@ Wrapping happens before the row cap, so the block is at most six rows tall at an
 
 ### 7.3 Task and Decision Boards
 
-- **Composite Tasks Board (`/tasks`, `Alt+B`)**: Presents four sections in one reopenable overlay: the live session board, terminal task history, successful workspace artifacts, and project-scoped operator tasks. Selecting a workspace artifact opens the filtered `/view` path. Operator rows support add, hand, done, and drop actions; refresh is explicit for captured history and artifacts, while lightweight repaint reads the current board snapshot.
-- **Settled Decisions Board (`/decisions`, `Alt+D`)**: Groups completed and cancelled interviews on the active branch, expands source questions and answers, and lets the operator supersede a value or submit a correction. Corrections travel through the ordinary operator-turn path after the durable decision snapshot is updated.
-- **Approved editor overrides**: `Alt+B` and `Alt+D` are deliberate application-input boundary overrides of Pi's editor word-back and word-delete chords. Clio routes them before the editor so the two global boards remain one chord away. They are explicit exceptions to the general rule that Clio app bindings avoid Pi editor reserves, and users may rebind the Clio actions in `settings.yaml`.
+- **Composite Tasks Board (`/tasks`)**: Presents four sections in one reopenable overlay: the live session board, terminal task history, successful workspace artifacts, and project-scoped operator tasks. Selecting a workspace artifact opens the filtered `/view` path. Operator rows support add, hand, done, and drop actions; refresh is explicit for captured history and artifacts, while lightweight repaint reads the current board snapshot.
+- **Settled Decisions Board (`/decisions`)**: Groups completed and cancelled interviews on the active branch, expands source questions and answers, and lets the operator supersede a value or submit a correction. Corrections travel through the ordinary operator-turn path after the durable decision snapshot is updated.
+- **Editing and focus**: Alt+B/D keep word movement/deletion. Ctrl+G shows a persistent contextual action menu. The application policy runs before viewport shortcuts; release events are discarded first. Search and modal children own cancellation. Permission deletions and local undo use semantic component operations. See the complete [keyboard contract](../guide/commands-and-modes.md#keybindings).
 
 ### 7.4 Slash Autocomplete Command Palette
 - **Grouped Palette**: Typing `/` opens a grouped command palette (ordered by `Run`, `Inspect`, `Configure`, `Sessions`) with compact argument hints and formatted descriptions.
@@ -364,3 +467,14 @@ Global scope requires a second `g` press on the same entry after the warning
 line appears. Status rows are labeled private and neither action can promote
 them. Both actions create unapproved durable proposals, show the resulting
 memory ID, and leave approval to the separate reviewed memory lifecycle.
+
+## Keyboard engine compatibility
+
+Clio pins pi-tui 0.85.1 with a tracked pnpm patch for one pre-viewport input
+policy, public existing search focus/operations, and semantic Editor/Input
+edits. Production consumes these only through src/engine. The patch adds no
+renderer, decoder or search implementation. Published dist bundles patched
+JavaScript and the pure JavaScript transitive dependencies; the pinned installed
+Pi package supplies native Darwin/Windows helpers through its package resolver.
+MIT notices ship beside the bundle. A frozen contributor install and an ordinary
+npm consumer install are separate acceptance checks.

package/docs/architecture/worker-context.md

@@ -0,0 +1,106 @@
+# Worker context inheritance
+
+> **Visual blueprint:** [Worker context visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/worker_context_blueprint.html).
+
+Clio dispatch separates **what a worker inherits** from **how workers are scheduled**. This implements the isolation, fork, and splice patterns discussed in [Organizing context in a multi-agent harness](https://www.langchain.com/blog/organizing-context-in-a-multi-agent-harness), using Clio's existing Pi agent loop and dispatch admission boundary.
+
+The default remains an isolated conversation. A native worker gets its own Pi Agent, worker system prompt, admitted tools, dynamic project context, task, and run-local accounting. Context inheritance does not grant additional tools, write roots, or autonomy. Conversation isolation is not a filesystem sandbox; use dispatch worktrees when filesystem isolation is required.
+
+## Dispatch API
+
+```json
+{
+  "agent": "researcher",
+  "task": "Investigate the parser failure and cite the relevant source lines.",
+  "intent": { "read_roots": ["src/parser"] },
+  "context": { "mode": "splice", "paths": ["src/parser"], "max_tokens": 8000 }
+}
+```
+
+`context` is independent of the top-level scheduling `mode` (`parallel`, `sequential`, `pipeline`, and so on). A batch's `context` is the default for each task; an object task can replace it, for example with `{ "mode": "isolated" }` for a separate check. Ordinary `briefing` and pipeline predecessor outputs remain separate dynamic inputs.
+
+| Context mode | Native HTTP/Pi worker | ACP and other runtimes | Selection |
+| --- | --- | --- | --- |
+| `isolated` | Fresh conversation | Fresh runtime conversation | No inherited session messages; existing project context and explicit briefing still apply |
+| `fork` | Existing history seeded into Pi | Rejected; use splice | Entire captured model-visible history, without silent trimming |
+| `splice` | Bounded historical evidence packet | Same packet through existing prompt delivery | Exact selected text, with source labels; no summarizer or extra model call |
+
+Fork accepts optional `max_tokens`. Splice also accepts `paths` and `refs`. The token limit is an estimate for the inherited portion, not the complete worker request. The final request must also fit the worker's system prompt, tool schemas, task, dynamic inputs, and output reserve. The allowed explicit token range is 256-262144; the default splice limit is 8000. A seed has a 512 KiB serialized cap, and the complete native WorkerSpec must fit the existing 1 MiB stdin frame. Larger contexts fail explicitly.
+
+Splice refs address the captured messages: `tool:<call-id>` for a tool result, or `message:<zero-based-index>` for a user or assistant message. Unknown refs fail. Ref indexes are snapshot-relative, not session turn IDs. Path selection is the practical default: explicit paths override the intent's read roots, relevant paths, and write roots. Matching uses lexical paths in tool arguments relative to the parent's workspace; it does not read files, follow symlinks, or perform semantic relevance search. Without paths, recent tool observations are candidates.
+
+All parent user/context text, tool errors, and explicit refs are required. If they cannot fit, dispatch refuses the splice and asks for a larger budget or an isolated task with an explicit briefing. Optional observations are selected newest first, then rendered in original order. Repeated calls with identical names and arguments use the newest optional observation; a smaller stale result cannot replace a newer result that did not fit. Assistant conclusions enter only through explicit refs and are labeled as parent claims. Private reasoning is omitted from splices. Required user images and explicitly selected image results require native fork; optional image observations are omitted and the packet discloses that it contains selected text only.
+
+## Capture, ownership, and reproducibility
+
+The chat loop captures its current Pi messages, or its prepared model replay when no runtime is active. This is the active branch's model-visible working set: existing compaction and eviction projections stay in effect. It does not reopen the raw parent ledger or resurrect sibling branches.
+
+Capture occurs synchronously when dispatch arguments are admitted, before asynchronous routing, metadata probes, permission handling, or execution. Every inheriting member of one dispatch call uses the same capture boundary. A final incomplete assistant tool-call batch, including any results already completed within that batch, is excluded as a unit. Capture also follows Pi's exclusion of aborted and errored assistant responses, drops results belonging to their partial tool declarations, and records the excluded count. User instructions survive that filtering. An orphaned result, duplicate tool-call ID, or incomplete older batch causes explicit refusal rather than constructing invalid provider history.
+
+The snapshot is deeply copied. Admission freezes selected requests, and retries and detached execution carry the selected seed rather than rereading the parent. Pipeline steps receive their upstream result separately; later parent turns do not become part of the already admitted seed. Separate dispatch calls have separate capture boundaries. Automatically constructed reviewers and judges retain their own fresh requests; do not use inherited author conclusions when an independent check is the purpose of a separately dispatched worker.
+
+Native forks enter `initialState.messages`. They are not replayed as new events, credited as worker token usage, or counted as reads and tests executed by the worker. Pi remains responsible for converting model-specific messages at the provider boundary. A splice enters once through dynamic prompt messages. The worker's own assignment comes after inherited context and dynamic inputs.
+
+The parent session writer is never forked or closed. Human `/tree`, `/fork`, and resume retain their existing semantics. Workers do not append their raw conversations to the parent; dispatch continues to return the normal sealed worker result.
+
+## Context pressure and recovery
+
+Every native worker checks context headroom before each provider request. The estimate includes actual system and tool surfaces and reserves output capacity. It honors the configured compaction threshold and automatic working-set eviction setting. Parent usage is never a sizing anchor for a child; after the worker's first completion, its own provider usage calibrates subsequent estimates.
+
+The first request is never automatically reduced: an oversized fork must be explicitly replaced by a smaller splice. During later requests, the guard preserves the two most recent assistant rounds and all user context, tool errors, mutations, and unknown tools. It may remove older private reasoning when visible assistant content remains, and replace large older successful observations from known read tools with stable markers. The original Pi history is not rewritten.
+
+Evicted observations are durably stored before replacement under `$XDG_STATE_HOME/clio-coder/context-observations/<digest>.json` (or Clio's configured state root). A marker provides an exact file location and a `worker:<digest>` recall ref. Native `context(scope="recall")` discovers only this run's evicted observations. Passing a ref retrieves the exact persisted result through the existing bounded observation envelope. The run-local allowlist rejects another worker's refs, arbitrary paths, and parent-session refs; stored bytes are digest-checked on recall. Recall does not count as rereading or validating the current source. Workers without an admitted context tool can use the marker's file through their admitted read tool.
+
+If protected context still cannot fit, the worker ends with `worker_context_exhausted`. Dispatch classifies that as deterministic and does not retry it unchanged. Backend token counts can differ from structural estimates; the guard is conservative headroom management, not a promise that every provider tokenizer or oversized individual tool response will fit.
+
+## Evidence and compatibility
+
+Non-isolated requests record context mode, parent session/leaf/workspace, snapshot digest, selected-content digest, estimated tokens, bytes, selected refs, omitted messages, the excluded unfinished tail, and excluded interrupted responses. The resolved plan displays the selection's digest and size; the run envelope and receipt carry the provenance under `workerContext`. Receipt integrity binds it, and context provenance remains separate from independent validation evidence.
+
+The host persists the selected seed at `$XDG_STATE_HOME/clio-coder/context-seeds/<contentHash>.json`, using mode 0600 and durable writes. These are exact historical artifacts with the same sensitivity as session history; no automatic garbage collection is introduced in this change. Native seeds are self-contained over the wire, including for remote workers. Their metadata and contents are validated before model use and are covered by the existing whole-spec attestation.
+
+WorkerSpec version **4** is required. Rebuild/update remote workers together with the orchestrator; an older worker must reject the new specification rather than silently ignore inherited history. ACP and other runtime adapters receive bounded splice text but do not implement native history forking or Clio's native pressure/recall loop.
+
+No extra LLM request is needed for capture or selection. Optional splice budgeting uses additive size estimates and one final serialization, rather than serializing the growing packet for every candidate. Stable projections help repeated requests retain an unchanged prefix, but provider cache reuse is measured behavior, not guaranteed: worker system prompts, tool surfaces, models, and provider cache rules can differ from the parent.
+
+## A worker's output token limit
+
+A worker is a separate process. It does not inherit the parent session's live
+settings; it reads layered settings from disk for its own working directory
+(`startWorkerRun`, `src/engine/worker-runtime.ts`). An unsaved `/settings` or
+`/model` override in the parent session therefore does not reach it. Those
+resolved settings also govern the worker's observation caps and working-set
+eviction, not just its output cap. External vendor runtimes, such as Claude CLI
+or Antigravity delegation, return before this native path and are not governed by
+the native request adapter at all.
+
+Precedence for `chat.maxOutputTokens`, highest first: `.clio-coder/settings.local.yaml`,
+`.clio-coder/settings.yaml`, the user `settings.yaml`, then the compiled default.
+**The compiled default is `0`** (`src/core/defaults.ts`), which is not a token
+count. `0` means "use the resolved model's advertised output limit", falling back
+to the product floor when the model does not advertise one.
+
+Both project layers are gated on workspace trust (`src/core/workspace-trust.ts`).
+An untrusted project, a project whose configuration changed after trust was
+recorded, or a malformed settings file all drop the project layers and fall back
+to user settings or the compiled default. This is why a worker can legitimately
+run with a different cap than the project file appears to ask for.
+
+Whatever the resolved number is, it is a request, not a promise. `remainingContextMaxTokens`
+(`src/engine/apis/output-budget.ts`) clamps it to the model's advertised output
+limit and to the remaining context window, and each provider then maps the budget
+onto its own wire contract. On the OpenAI-compatible LiteLLM path,
+`reasoning_effort` is forwarded under `allowed_openai_params` when thinking
+effort is enabled (`src/engine/apis/openai-completions.ts`); that is a LiteLLM
+compatibility allowance and not a universal provider contract. A per-response cap
+also caps one response, not a task: it does not bound total task tokens or
+guarantee the task finishes.
+
+`tests/contracts/worker-output-settings.test.ts` covers the eight combinations of
+trust state and layer (trusted project at low/medium/xhigh effort, trusted local
+override, untrusted, changed-after-trust, malformed, and user settings only).
+
+## Validation
+
+The worker-context contract tests cover incomplete multi-tool batches, copy isolation, path and explicit-ref selection, stale duplicate reads, mandatory constraints and errors, images, admission freezing, active-branch eviction replay, receipt tampering, scoped recall, and provider-usage reconciliation after eviction. Dispatch integration tests run the actual Pi worker against a controlled HTTP provider and verify single delivery, exclusion of later parent turns, absence of inherited fork events, wire validation, and rejection before a provider call when context is oversized. The normal full CI gate also exercises existing dispatch, session replay, worker transport, and operator behavior.
+

package/docs/guide/authoring-plugins.md

@@ -0,0 +1,160 @@
+# Authoring a portable agent plugin
+
+> **Visual blueprint:** See the [visual reference](../html/authoring_plugins_blueprint.html) in the source checkout.
+
+An agent plugin packages a workflow and its supporting resources as one versioned installation. Its canonical identity is the [Agent Plugins 1.0.0 manifest](https://agent-plugins.org/schemas/1.0.0/plugin.schema.json). Clio keeps the complete package together, verifies its full-tree digest, and discovers the resources supported by the current runtime.
+
+The minimal package has a root `plugin.json` and an immediate child skill directory:
+
+```text
+lab-research/
+  plugin.json
+  skills/
+    research/
+      SKILL.md
+```
+
+```json
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "lab-research",
+  "version": "1.0.0",
+  "description": "Research from supplied lab evidence"
+}
+```
+
+Portable identity and publisher metadata remain at the root. The root schema permits `$schema`, `name`, `version`, `description`, `author`, `homepage`, `repository`, `license`, `keywords`, and `extensions`. Names have 1 to 64 lowercase letters, digits, hyphens or periods, begin and end with an alphanumeric character, and contain neither `--` nor `..`. Clio reserves `state.json` as an installation bookkeeping name. Every package, including a local authoring install, requires an explicit Semantic Version. Numeric prerelease identifiers cannot contain leading zeros.
+
+## Native Clio components
+
+`extensions["ai.iowarp.clio"]` holds optional Clio metadata inside the portable manifest. A plugin containing `skills/<name>/SKILL.md` needs only the root identity fields above: Clio discovers the conventional `skills/` directory. A standalone skill package with a root `SKILL.md` declares `kind: "skill"`, `resources.skills: "."` and its one public skill component through the extension; the supplied skill template demonstrates that form. Clio prompts, strict agent recipes, fleets and explicit component graphs also use this metadata. The key does not select a directory: its `resources` map names the paths the package actually uses.
+
+Use `extensions["ai.iowarp.clio"]` as the manifest metadata key to declare Clio prompts, strict agent recipes, and fleets. In modern packages, resources use ordinary top-level directories (`agents/`, `prompts/`, `skills/`, `fleets/`), while `assets/` holds shared supporting files. (Historical bundles such as `materio` may nest resources under `ai.iowarp.clio/` for backward compatibility, but top-level directories are recommended for new packages.)
+
+```json
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "lab-research",
+  "version": "1.0.0",
+  "description": "Research from supplied lab evidence",
+  "extensions": {
+    "ai.iowarp.clio": {
+      "manifestVersion": 1,
+      "compatibility": { "clio": ">=0.4.7" },
+      "resources": {
+        "skills": "skills",
+        "prompts": "prompts",
+        "agents": "agents"
+      },
+      "components": [
+        {
+          "kind": "resource",
+          "id": "methods",
+          "path": "assets/methods.md"
+        },
+        {
+          "kind": "skill",
+          "id": "research",
+          "path": "skills/research/SKILL.md",
+          "requires": ["resource:methods"]
+        },
+        {
+          "kind": "agent",
+          "id": "researcher",
+          "path": "agents/lab-research-researcher.md",
+          "requires": ["skill:research"]
+        },
+        {
+          "kind": "prompt",
+          "id": "start",
+          "path": "prompts/lab-research/start.md",
+          "requires": ["agent:researcher"]
+        }
+      ]
+    }
+  }
+}
+```
+
+Create every declared directory and file before validation. Resource kinds are `skills`, `prompts`, `agents`, `fleets`, and `themes`. Component kinds are `skill`, `prompt`, `agent`, `fleet`, `script`, `resource`, and `tool`. A component has a stable `kind:id` identity, one contained file path, and optional `requires` references to other components in the same bundle. A skill points to its `SKILL.md`. Dependencies must exist and form an acyclic graph. Native discoverable components must live beneath their declared resource root. Component metadata records relationships; it does not execute scripts or register tool implementations.
+
+Clio text can refer to `${pluginRoot}/assets/methods.md` or `${component:resource:methods}`. Prompts, agent bodies, and skills recognize prose markers with portable, space-free slash suffixes. For a filename containing spaces or Unicode, declare a component and refer to its `kind:id`. The referenced target must exist within the declaring package. Fleet argument paths use a separate complete-path parser: the reference must occupy the whole argument, and containment is checked after expanding the entire suffix, including spaces and Unicode. A reference embedded in an option such as `--file=${pluginRoot}/data.csv` is rejected; pass the path as its own argument. These are Clio reference forms; peer exports translate instructions and paths for their native host. Portable skill text should use relative file references where practical.
+
+Prompt names follow their path beneath the prompts root. The example exposes `/lab-research:start`. Give agent and fleet filenames a package prefix to keep their registered identities unambiguous. Agent recipes retain the strict version 1 contract, including required and optional tool lists, custom audience, budget, and result contract. Recipes bind skills from their own package. Interviews belong to the orchestrator; a worker returns its need for input and is redispatched after the researcher answers.
+
+## Validation and lifecycle
+
+```bash
+clio-coder library validate ./lab-research --json
+clio-coder library inspect ./lab-research --json
+clio-coder library install ./lab-research --project
+clio-coder library list --all --json
+clio-coder library drift lab-research --project
+```
+
+`library validate <package-path> --json` performs a read-only content and payload validation before any installation or registration:
+- **Manifest validity**: Parses `plugin.json` against the schema, verifying identifiers, SemVer compliance, and declared resource roots.
+- **Payload & schema validation**: Validates agent recipes against strict v1 schemas, policy budgets, and custom audience rules; parses fleet DAGs, loop boundaries, and write boundaries; and checks prompt loadability.
+- **Package reference resolution**: Ensures all `${component:...}` and `${pluginRoot}` references point to existing files within the package boundary and form an acyclic graph.
+- **Prerequisite separation**: Reports required external commands or core agents as environment prerequisites rather than failing package content validity.
+- **Read-only**: Leaves package files, repository files, and installation state roots completely unchanged.
+
+Installation validates the exact manifest bytes included in the tree digest, copies into private staging, verifies that source and staging still match, and publishes the package and installation record with rollback on failure. Pins bind filenames, entry kinds, bytes, symlink targets and empty directories. Escaping links, hard links, unsupported filesystem entries and a root `state.json` are rejected. A catalog's expected identity, version and digest cannot be bypassed with `--force`.
+
+User installations live in the Clio configuration directory's `plugins/`; project installations live in `.clio-coder/plugins/`. State is outside the bundle, in the parent `state.json`. Installations also retain their source origin for updates. A valid project copy takes precedence over the user copy; disabling that project copy suppresses both. Changed or unverifiable content cannot load or be enabled. Update refuses local drift unless explicitly forced, and replacement or removal preserves changed files in a reported recovery copy.
+
+An active session observes additions and replacements after `/library reload` or restart. Removal, disabling and digest drift revoke subsequent resource discovery even when an earlier snapshot remains committed. Executable harness tool schemas have a separate lifecycle and require a new session after changes.
+
+## Host projections and runtime capabilities
+
+Agent Plugins 1.0.0 standardizes skills and MCP declarations. Clio currently consumes portable skills and its native manifest extension; it preserves MCP files but does not execute MCP servers. Claude Code and Gemini have their own native manifests and component formats. A package exporter must translate those formats and report which features are native, adapted as instructions, or unavailable. An exported skill workflow does not establish that a peer host executes Clio fleets.
+
+The bundled `materio` plugin includes a tested Python exporter for Codex, Claude Code and Gemini. See its package README for commands and capability reports. It also provides a complete worked example of explicit component relationships and shared domain references.
+
+Two layouts need no exporter at all, because Claude Code and Codex load them directly from the unchanged package:
+
+- A standalone skill package with a root `SKILL.md`, no `skills/` directory and no top-level `skills` manifest field. Claude Code loads it as a single-skill plugin and takes the invocation name from the `SKILL.md` frontmatter. Codex finds the same directory under any of its skills roots.
+- A bundle with a real `skills/` directory. Both hosts publish exactly those skills.
+
+What a peer host does *not* load matters just as much. Claude Code scans a plugin root for `agents/`, `commands/`, `hooks/`, `output-styles/` and `.mcp.json` with no manifest asking it to. A Clio strict-v1 recipe sitting in a top-level `agents/` directory is therefore picked up and shown as a native Claude agent, tools, model and budget fields included, none of which that host honors. Clio `prompts/` and `fleets/` are inert to it.
+
+That leaves a real choice when a package should serve both audiences. Ordinary top-level `agents/` and `prompts/` directories are the recommended Clio layout and stay a valid first-class library package; the repository marketplace simply does not publish such a package, and `pnpm run library:pin` prints the reason. To publish it as well, declare its Clio resource roots at paths no peer host scans, for example `"agents": "native/agents"` in the manifest's `resources` map, and put the recipes there. The bundled `materio` package does this with its own historical directory name.
+
+Keep the skill surface intact when you edit a package: adding a `skills/` directory to a standalone skill silently stops its root `SKILL.md` from loading. `tests/contracts/library-portability.test.ts` asserts all of this for every curated package, and `scripts/verify-portable-hosts.sh` re-measures it against the real host CLIs. See [coding agent interoperability](interop.md) for the exact install commands.
+
+Harness extensions register runtime tools through the [harness extension contract](harness-extensions.md). They use a separate extension manifest and installation state, and they cannot declare domain resources: prompts, agents, skills, fleets and reference files ship in a plugin. See [plugin library usage](plugins.md) for catalogs, updates, pins and terminal UI operations.
+
+## Authoring templates and contributor journey
+
+Clio Coder provides working, valid authoring templates for all five package kinds in `library/_authoring/templates/`:
+
+- `library/_authoring/templates/skill/`: Standalone skill with house conventions, triggers, and recorded eval scenarios.
+- `library/_authoring/templates/agent/`: Standalone agent recipe using strict v1 fields, `skills: []`, and `audience: custom`.
+- `library/_authoring/templates/prompt/`: Parameterized prompt with path-derived invocation (`/<name>`) and `$ARGUMENTS` expansion.
+- `library/_authoring/templates/fleet/`: Multi-agent coordination contract with a valid DAG and documented prerequisites.
+- `library/_authoring/templates/plugin/`: Composite bundle showing an agent binding a contained skill, prompts, and supporting assets.
+
+Templates are reference models and are excluded from `library/registry.yaml`. Follow this unified contributor journey:
+
+1. **Choose package kind**: Decide whether your package is a single-kind package (`skill`, `agent`, `prompt`, `fleet`) exposing exactly one public recipe, or a composite `plugin` bundle combining multiple resources.
+2. **Copy authoring template**: Copy from `library/_authoring/templates/<kind>/` into your project or repository.
+3. **Author resources**:
+   - Single-kind packages expose exactly one public resource file in their declared resource directory (`skills`, `agents`, `prompts`, or `fleets`).
+   - Keep `README.md` at the package root, outside the resource directory, so the loader does not discover it as a second public recipe.
+   - Packages may carry explicitly invoked scripts (e.g., for offline evaluation or verification tasks); these are declared metadata and are strictly distinct from harness extensions, which register runtime tools and hooks.
+4. **Validate**:
+   Run `clio-coder library validate ./lab-research --json` to verify manifest schemas, resource payloads, reference syntax, and loadability.
+5. **Pin and check**:
+   Maintainers run `pnpm run library:pin` and `pnpm run library:check` to refresh and verify full-tree distribution pins. For curated skills, maintainers also run `pnpm run skills:pin` and `pnpm run skills:check`.
+   - **Full-tree pins** (`library/registry.yaml`) cover every distributed byte to verify package integrity.
+   - **Normalized skill evidence** (`library/skills/registry.yaml`) records normalized skill body hashes as provenance evidence for reviewed instructions.
+6. **Try in isolated project**:
+   Register locally with `clio-coder library register ./lab-research --project`. Registration writes identity, version, source, and full-tree SHA-256 into the scoped `library.yaml`. Preview and install with `library install plugin:lab-research --project --dry-run`, then `library install plugin:lab-research --project`. Test invocation through `/skills`, `/run`, prompt slash commands, or `/fleet run`.
+7. **Submit a focused fork PR**:
+   Push your topic branch to your fork and submit a PR against `main`.
+
+Package dependencies live in `extensions["ai.iowarp.clio"].requires`, such as `["skill:ship"]`; copy the same requirements into the index. They name packages, while component `requires` names files within one package. Neither declares an execution hook.
+
+Declare runnable eval suites using `"evals": {"scripts": "evals/scripts.yaml"}` in the Clio extension. Paths must identify contained files. Validate with `clio-coder eval validate --package ./lab-research --eval scripts` and run with `clio-coder eval run --package ./lab-research --eval scripts`. Use the standard version-2 eval suite schema. Materio's [worked suite](../../library/plugins/materio/evals/scripts.yaml) runs Python contracts in a temporary package copy; package installation never runs evals.
+
+See [Library packages](resource-library.md) for every lifecycle command and [Library architecture](../architecture/library.md) for identity, trust, pin and namespace invariants.