@iowarp/clio-coder 0.4.1 → 0.4.3

package/docs/{glossary.md → guide/glossary.md}

@@ -1,5 +1,8 @@
 # Clio Coder Glossary
 
+> **Visual blueprint:** The source checkout includes the complete
+> [Clio Coder Glossary visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/glossary_blueprint.html).
+
 This document defines the 50 core architectural concepts and terminology used throughout Clio Coder, mapped to their authoritative TypeScript type definitions in `src/`.
 
 ---
@@ -11,7 +14,7 @@ This document defines the 50 core architectural concepts and terminology used th
 - **Owning Type**: `DurableAssignmentRecord` in `src/domains/dispatch/assignment-store.ts`.
 
 ### 2. Run
-- **Definition**: A concrete execution attempt of an assignment. Every run possesses a unique UUIDv7 identifier, an isolated event stream, a designated execution node, and a final cryptographically sealed receipt.
+- **Definition**: A concrete execution attempt of an assignment. Dispatch creates a 12-character random base36 run identifier with `newRunId()`. Session ids use the same 12-character base36 generator, while appended session turn and entry ids use UUIDv7. Every run has an isolated event stream, a designated execution node, and a final cryptographically sealed receipt.
 - **Owning Type**: `RunEnvelope` in `src/domains/dispatch/types.ts`.
 
 ### 3. Attempt
@@ -28,7 +31,7 @@ This document defines the 50 core architectural concepts and terminology used th
 
 ### 6. Receipt
 - **Definition**: An immutable, cryptographically sealed record of a completed run containing full execution facts, tool telemetry, token accounting, validation grounding, and outcome codes.
-- **Owning Type**: `RunReceipt` in `src/domains/dispatch/types.ts` (`RUN_RECEIPT_INTEGRITY_VERSION = 19`).
+- **Owning Type**: `RunReceipt` in `src/domains/dispatch/types.ts` (`RUN_RECEIPT_INTEGRITY_VERSION = 20`).
 
 ### 7. Envelope
 - **Definition**: A bounded container enforcing byte-length limits and truncation indicators on a dynamic payload. Tool output carries shown and total byte counts plus a continuation fragment; a parent briefing carries byte count and SHA-256 content hash instead.
@@ -59,7 +62,7 @@ This document defines the 50 core architectural concepts and terminology used th
 - **Owning Type**: `FleetNodeSnapshot` in `src/domains/scheduling/cluster.ts`.
 
 ### 14. Route
-- **Definition**: An exact execution tuple composed of `{ agent, target, model, node }` evaluated by the active route planner for capability fit and cost readiness.
+- **Definition**: The complete execution candidate evaluated by the route planner for capability fit, readiness, and cost. Its operational identity includes agent, execution role, target, model, runtime, node, thinking level when present, tool and prompt composition, endpoint identity, and immutable spec/settings fingerprints.
 - **Owning Type**: `RouteCandidate` in `src/domains/dispatch/route-decision.ts`.
 
 ### 15. Posture (Autonomy Level)
@@ -71,7 +74,7 @@ This document defines the 50 core architectural concepts and terminology used th
 - **Owning Type**: `AgentCapabilityClass` in `src/domains/agents/spec.ts`.
 
 ### 17. Topology
-- **Definition**: The multi-agent structural orchestration pattern governing workflow execution. Three unions spell it for three different jobs and their value sets differ: `parallel`, `sequential`, `pipeline`, `review`, `compete`, and `fleet` in a compiled plan; the same set with `detached` and without `fleet` for a capacity reservation; both plus `detached` and `fleet` at the tool surface. The operator-facing argument is spelled `mode`, and `singular` (the one-task call shape) and `auto` are values of that argument, not topologies.
+- **Definition**: The multi-agent structural orchestration pattern governing workflow execution. Three unions spell it for three jobs. A compiled plan supports `parallel`, `sequential`, `pipeline`, `review`, `compete`, `council`, and `fleet`. A capacity reservation supports `parallel`, `detached`, `sequential`, `pipeline`, `review`, `compete`, and `council`. The dispatch-plan tool surface supports all eight values from those two sets. The operator-facing argument is spelled `mode`; `singular` (the one-task call shape) and `auto` are values of that argument, not topologies.
 - **Owning Types**: `ExecutionPlanTopology` in `src/domains/dispatch/execution-plan.ts`, `ReservationTopology` in `src/domains/dispatch/reservation-store.ts`, `DispatchPlanTopology` in `src/tools/dispatch-plan.ts`.
 
 ### 18. Worker Block
@@ -79,8 +82,8 @@ This document defines the 50 core architectural concepts and terminology used th
 - **Owning Type**: `WorkerEntryState` in `src/interactive/worker-stream.ts`.
 
 ### 19. Origin Glyphs (`◇`/`◆`)
-- **Definition**: Transcript and fleet board indicators that identify who requested a run. The glyph `◇` marks operator-typed runs, `◆` marks model-requested dispatches, and a dim dot marks internal Clio runs.
-- **Owning Type**: `WorkerRunOrigin` in `src/domains/session/entries.ts`.
+- **Definition**: Transcript and fleet board indicators that identify who requested a run. The glyph `◇` marks operator-typed runs, `◆` marks model-requested dispatches, and a dim dot marks internal Clio runs. Transcript worker entries admit only user and agent origins; internal runs can appear on dispatch surfaces but never become transcript worker entries.
+- **Owning Types**: `WorkerRunOrigin` in `src/domains/session/entries.ts` for transcript entries; `DispatchRequestOrigin` in `src/domains/dispatch/types.ts` for user, agent, and internal dispatches.
 
 ### 20. Share Note
 - **Definition**: A bounded operator note formatted as `[worker result] <agent> · run <id> · <outcome> · shared by the operator` that delivers a finished worker answer into the main agent context over the user-turn path.
@@ -115,7 +118,7 @@ This document defines the 50 core architectural concepts and terminology used th
 - **Owning Type**: `ResourceSourceInfo` in `src/domains/resources/collision.ts`.
 
 ### 28. Trust Gate
-- **Definition**: A security boundary requiring explicit operator opt-in via `skills.trustProjectCompatRoots` before prompt templates or skills from project-scope foreign roots can execute or expand.
+- **Definition**: A security boundary requiring explicit operator opt-in via `integrations.projectResources.trustProjectImports` before prompt templates or skills from project-scope foreign roots can execute or expand.
 - **Owning Type**: `PromptTemplate` in `src/domains/resources/prompts/loader.ts`.
 
 ### 29. Fleet
@@ -127,7 +130,7 @@ This document defines the 50 core architectural concepts and terminology used th
 - **Owning Type**: `DispatchRequest` in `src/domains/dispatch/contract.ts`.
 
 ### 31. Run Ledger
-- **Definition**: The durable dispatch run list at `runs.json` in the state directory, retention-capped by `guardrails.maxDispatchRuns`. It is what the fleet board, `clio-coder fleet status`, and eval linking read.
+- **Definition**: The durable dispatch run list at `runs.json` in the state directory, retention-capped by `fleet.history.maxRuns`. It is what the fleet board, `clio-coder fleet status`, and eval linking read.
 - **Owning Type**: `RunEnvelope` in `src/domains/dispatch/types.ts`, persisted by `src/domains/dispatch/state.ts`.
 
 ### 32. Agent Ledger
@@ -143,7 +146,7 @@ This document defines the 50 core architectural concepts and terminology used th
 - **Owning Type**: `TaskLedgerEntry` in `src/domains/session/entries.ts`.
 
 ### 35. Context Ledger
-- **Definition**: The accounting of how the model's context window is spent, bucketed into system, tools, agents, skills, memory, and the rest, and the input to compaction decisions.
+- **Definition**: The accounting of how the model's context window is spent and the input to compaction decisions. Current buckets are `system`, `tools`, `agents`, `skills`, `memory`, `project`, `messages`, `pending`, `reserve`, `free`, and `streaming`.
 - **Owning Type**: `ContextLedgerCategory` in `src/domains/session/context-ledger.ts`.
 
 ### 36. Dispatch Board
@@ -163,7 +166,7 @@ This document defines the 50 core architectural concepts and terminology used th
 - **Owning Type**: `ParsedClioMd` in `src/domains/context/clio-md.ts`.
 
 ### 40. Delegate
-- **Definition**: Another coding agent Clio drives over ACP stdio as if it were a worker, configured under `delegation.agents` and invoked with `/delegate`. A delegate is a foreign harness, not a model target.
+- **Definition**: Another coding agent Clio drives over ACP stdio as if it were a worker, configured under `integrations.externalAgents.entries` and invoked with `/delegate`. A delegate is a foreign harness, not a model target.
 - **Owning Type**: `DelegationAgentConfig` in `src/core/defaults.ts`.
 
 ### 41. Working Set
@@ -187,7 +190,7 @@ This document defines the 50 core architectural concepts and terminology used th
 - **Owning Type**: `renderMarker` in `src/domains/context/working-set/marker.ts`.
 
 ### 46. Canonical Trust Status
-- **Definition**: The six-axis record of what is known about one run: artifact integrity, validation grounding, independent review, context provenance, autonomy enforcement, and completion evidence. It is an algebra, not a score: no axis promotes another, every non-absent state names its source and authority, and `absent`, `unknown`, and `not_applicable` are states in their own right. See [docs/evidence-and-memory.md](evidence-and-memory.md#canonical-trust-status) for the full state table.
+- **Definition**: The six-axis record of what is known about one run: artifact integrity, validation grounding, independent review, context provenance, autonomy enforcement, and completion evidence. It is an algebra, not a score: no axis promotes another, every non-absent state names its source and authority, and `absent`, `unknown`, and `not_applicable` are states in their own right. See [docs/architecture/evidence-and-memory.md](../architecture/evidence-and-memory.md#canonical-trust-status) for the full state table.
 - **Owning Type**: `CanonicalTrustStatus` in `src/domains/evidence/trust-status.ts`.
 
 ### 47. Trust Projection

package/docs/{installation-and-lifecycle.md → guide/installation-and-lifecycle.md}

@@ -1,9 +1,9 @@
 # Installation and Lifecycle Operations
 
-Clio Coder is designed to be self-contained and platform-compliant. This document outlines the default directory paths, file purposes, permission levels, and lifecycle commands (`install`, `reset`, `upgrade`, and `uninstall`). Clio Coder installs from npm as `@iowarp/clio-coder` (`npm install -g @iowarp/clio-coder`, published since v0.3.0) or from a source checkout with a deterministic local symlink; the CLI classifies both install kinds and `clio-coder upgrade` handles each.
+> **Visual blueprint:** The source checkout includes the complete
+> [Installation and Lifecycle Operations visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/lifecycle_blueprint.html).
 
-> [!TIP]
-> **Interactive Spec Available:** An interactive dashboard with a path simulator and visual flowcharts is located at [docs/html/lifecycle_blueprint.html](html/lifecycle_blueprint.html) (Version: 0.4.0). You can open it directly in any web browser to view details dynamically.
+Clio Coder is designed to be self-contained and platform-compliant. This document outlines the default directory paths, file purposes, permission levels, and lifecycle commands (`install`, `reset`, `upgrade`, and `uninstall`). Clio Coder installs from npm as `@iowarp/clio-coder` (`npm install -g @iowarp/clio-coder`, published since v0.3.0) or from a source checkout with a deterministic local symlink; the CLI classifies both install kinds and `clio-coder upgrade` handles each.
 
 ### Optional dependency: the Claude Agent SDK
 
@@ -93,7 +93,7 @@ The core files are created automatically during the first run. `credentials.yaml
 | **Config** | `settings.yaml` | Target runtimes, model defaults, keybindings, and theme preferences. | `0o644` (rw-r--r--) | Removed by uninstall / `reset --config`. |
 | **Config** | `credentials.yaml` | Private keys and tokens managed via `clio-coder auth`. | `0o600` (rw-------) | Removed by uninstall / `reset --auth`. |
 | **Config** | `credentials.yaml.lock` | Lockfile used during credentials updates to prevent file corruption. | Ephemeral | Auto-removed. |
-| **State** | `install.json` | Install metadata: Clio version, node, platform, `installedAt` (written once at first install), `upgradedAt` and `upgradedFrom` (stamped on a version change), and `noticedVersion` (the version whose one-time upgrade notice the interactive launch has shown). | Writer/umask default | Removed by uninstall / `reset --state`. |
+| **State** | `install.json` | Install metadata: Clio version, node, platform, `installedAt` (written once at first install) or `repairedAt` (when metadata is reconstructed over a preexisting config, data, or state root), `upgradedAt` and `upgradedFrom` (stamped on a version change), and `noticedVersion` (the version whose one-time upgrade notice the interactive launch has shown). | Writer/umask default | Removed by uninstall / `reset --state`. |
 | **State** | `migrations.json` | Log of successfully applied schema/state migrations. | Writer/umask default | Removed by uninstall / `reset --state`. |
 | **Data** | `memory/records.json` | Long-term learning memories (up to 500 records) proposed/approved from runs. | Writer/umask default | Removed by uninstall / `reset --data`. |
 | **Data** | `tools/<id>/<version>/` | One pinned external program Clio downloaded on request (`clio-coder tools install <id>`), with its upstream license text and a `clio-install.json` recording url, sha256, platform and install time. Binaries `0o755`, documents `0o644`. Only the pinned version is kept: a successful install prunes the versions it supersedes. | `0o755` dir | `clio-coder tools remove <id>` deletes every version of one tool; removed by uninstall / `reset --data`. |
@@ -108,7 +108,7 @@ When Clio Coder boots (or after a reset), it calls `initializeClioHome()` (see `
 1.  **Directory Tree**: Recursively creates the four roots (`config`, `data`, `state`, `cache`) and their skeletons: `agents` under config, `memory`/`evidence`/`evals` under data, and `sessions`/`audit`/`receipts`/`interviews`/`scratch` under state.
 2.  **Settings Template**: If `settings.yaml` is absent, creates a fresh default config. An existing file is never read, validated, or rewritten by initialization.
 3.  **Credentials Security**: If `credentials.yaml` is absent, creates a YAML file containing a managed-file comment and an empty object (`{}`), then locks its permissions immediately to owner-only read-write (`0o600`).
-4.  **Install Metadata**: Writes `install.json` with `installedAt` exactly once at first install; a later version, platform, or node change preserves `installedAt` and stamps `upgradedAt`, and a version change also records the previous version as `upgradedFrom`.
+4.  **Install Metadata**: Writes `install.json` with `installedAt` exactly once when no config, data, or state root existed before initialization. If Clio reconstructs missing metadata over a preexisting config, data, or state root, it writes `repairedAt` instead of inventing an installation time. A cache-only root does not count as a preexisting home for this decision. A later version, platform, or node change preserves whichever original timestamp exists and stamps `upgradedAt`; a version change also records the previous version as `upgradedFrom`.
 
 ---
 
@@ -191,9 +191,9 @@ Runs a series of health sweeps across the environment:
 *   *Recovery:* Run `clio-coder doctor --fix` to create missing directories and templates, repair credential permissions, and refresh install metadata. Settings are always validated against the current schema; `--fix` does not rewrite removed keys or migrate an older settings file. Run `clio-coder upgrade` for registered lifecycle migrations, including removal of the retired `panes.agents` and `panes.keepFailed` keys; paths with no registered migration still require deliberate editing.
 
 ### B. Upgrades (`clio-coder upgrade`)
-Refreshes state metadata and applies pending data-dir migrations.
+Refreshes state metadata and applies pending lifecycle migrations, which may update settings, state, or extension data.
 ```bash
-clio-coder upgrade [--dry-run] [--channel=<latest|beta|dev>] [--skip-migrations]
+clio-coder upgrade [--dry-run] [--channel=<latest|beta|dev>] [--skip-migrations] [--json]
 ```
 The command detects the install method from the running binary. On a source
 checkout it never runs `npm install -g`: it performs its safe local duties
@@ -201,7 +201,28 @@ checkout it never runs `npm install -g`: it performs its safe local duties
 `git pull`, `npm run install:local`, `hash -r`. The npm reinstall path applies
 only to a genuinely npm-installed binary.
 
-#### Upgrading from 0.3.0
+#### Current migration contract
+
+The v0.4.2 source tree registers five migrations in execution order:
+
+1. `2026-09-01-settings-v2`
+2. `2026-09-01-extension-install-digests`
+3. `2026-09-01-clio-coder-naming`
+4. `2026-09-01-retire-panes-knobs`
+5. `2026-08-18-lmstudio-runtime-id`
+
+Applied IDs are recorded in `<stateDir>/migrations.json`. An ID already in that
+manifest is skipped, and each successful migration is recorded immediately so a
+later failure does not cause it to run again. `clio-coder upgrade --dry-run`
+lists every registered migration it would consider; it does not claim that
+every listed ID is pending. `--skip-migrations` is a recovery override that lets
+the independent install and metadata work proceed after a migration failure.
+Fix the migration's cause and rerun the ordinary upgrade afterward.
+
+#### Historical record: upgrading from 0.3.0 to 0.3.1
+
+The following behavior records the 0.3.0 and 0.3.1 release binaries. It is not
+the current migration inventory or current upgrade output.
 
 Nothing has to be done by hand. On an npm install, one command does it all:
 
@@ -234,9 +255,10 @@ next `clio-coder` launch refreshes it. `install.json` then reads
 `upgradedFrom: "0.3.0"`; doctor's row becomes
 `0.3.1 (installed ..., upgraded ... from 0.3.0)`.
 
-#### Upgrading to 0.3.3
+#### Historical record: 0.3.x release notes
 
-Upgrading from 0.3.1 to 0.3.3 is automated:
+The retained notes below span the 0.3.3 upgrade and later 0.3.7 operational
+changes. Upgrading from 0.3.1 to 0.3.3 was automated:
 
 ```bash
 clio-coder upgrade
@@ -245,20 +267,29 @@ clio-coder upgrade
 Key lifecycle and operational updates in v0.3.7:
 - Upgraded the underlying engine SDK libraries to 0.84.0 with signal-aware OAuth cancellation.
 - Hardened migration resilience: damaged `credentials.yaml` files no longer block upgrades when no renames are needed (#121); `--skip-migrations` is available as a recovery override.
-- Fullscreen TUI mode (`terminal.tuiMode`, `terminal.fullscreenScrollbar`) is available via Settings → Terminal (restart required). Adaptive presentation pacing is the live `terminal.smoothStreaming` setting; 0.3.3 defaults it to `off`, with conservative `auto` and explicit `on` available from the same section.
+- Fullscreen TUI mode (`interface.mode`, `interface.fullscreenScrollbar`) is
+  available through `/settings interface` and requires a restart. Adaptive
+  presentation pacing is the live `interface.smoothStreaming` setting; it
+  defaults to `off`, with conservative `auto` and explicit `on` available from
+  the same area.
 - Interactive launch paints a measured Stage 0 shell on the same terminal and editor that Stage 1 hydrates. Typing, queued submits, resize, and Ctrl+C remain live during hydration; set `CLIO_CODER_INSTANT_SHELL=0` for the legacy fully hydrated first-frame path.
 - Turn settlement is enforced on `/new`, `/resume`, `/tree`, and `/fork` to cleanly commit in-flight streams before session writer replacement (#114).
 - Resumed and forked session entry replays standardize message prefixes through `src/engine/messages.ts`.
 - `AI_AGENT=clio-coder` is set on all child processes for system attribution.
 
-The first interactive launch after upgrading shows the version notice:
+The first interactive launch after that upgrade showed this contemporary
+version notice:
 `clio: upgraded 0.3.1 → 0.3.3. What changed at the keyboard: ...`
 Recorded once per version in `install.json` as `noticedVersion`.
 
+Current launches use the `clio-coder:` prefix. Version 0.3.1 has specialized
+keyboard-facing text; all other target versions use the generic form
+`clio-coder: upgraded <from> → <to>. What changed is in CHANGELOG.md, section <to>.`
+
 ### C. System Resets (`clio-coder reset`)
 Selective recovery wipes:
 ```bash
-clio-coder reset [--state|--data|--cache|--auth|--config|--all] [--dry-run] [--force]
+clio-coder reset [--state|--data|--cache|--auth|--config|--all] [--dry-run] [--force] [--json]
 ```
 Levels are combinable except `--all`. Each level clears exactly the root or file it names and nothing else, then bootstraps the missing structure again unless `--dry-run` is present. `--force` is required only for destructive execution.
 
@@ -280,7 +311,7 @@ new artifact is written into a root.
 removes all four roots (config, data, state, cache):
 
 ```bash
-clio-coder uninstall [--remove-binary] [--dry-run] [--force]
+clio-coder uninstall [--remove-binary] [--keep-config] [--keep-data] [--dry-run] [--force] [--json]
 ```
 
 Preview first, then remove:
@@ -294,7 +325,9 @@ hash -r
 `--dry-run` prints the roots and the optional launcher action without changing
 anything, and enumerates the same resolved absolute paths the real run would
 remove. It prints binary-removal guidance for the active launcher, npm-global
-installs, npm links, and the local source symlink.
+installs, npm links, and the local source symlink. Use `--keep-config` to preserve
+`settings.yaml` and `credentials.yaml`, or `--keep-data` to preserve memory and
+evidence.
 
 #### Per-project `.clio-coder/` directories
 
@@ -348,6 +381,37 @@ commands are idempotent, so the recovery is always the same: fix the permission
 or release the handle, then run the identical command again and it resumes from
 whatever is left. A partial delete never reports global success.
 
+### E. Interactive Configuration (`clio-coder configure`)
+`clio-coder configure` provides a structured, multi-section configuration wizard
+for model targets, runtime defaults, fleet limits, permissions, panes, and
+integrations:
+
+```bash
+clio-coder configure [--section <name>] [--json] [--interop] [--list] [--all]
+```
+
+When run against an unconfigured home (or when launched interactively with no
+model target), it routes immediately to the target category selection menu. Once
+targets are configured, launching `clio-coder configure` presents the 8 top-level
+runtime sections:
+
+1. **Targets & Auth**: manage providers, endpoints, credentials, and models.
+2. **Models & Thinking**: default models, thinking levels, model favorites, cycle set.
+3. **Chat Defaults**: smooth streaming, terminal progress, token limits, compaction.
+4. **Fleet**: concurrency, retries, tool call caps, worker timeouts, profiles.
+5. **Permissions & Autonomy**: autonomy level, worker permissions, cost limits, review watchdog.
+6. **Panes & Layout**: terminal panes capability, dock layout, TUI display mode, notifications.
+7. **Skills & Extensions**: trust project imports, external ACP agents, plugins, library sync.
+8. **Diagnostics**: version information, resolved directories, doctor check, raw settings inspection.
+
+Every section header indicates the exact settings file path being modified
+(`Source: ~/.config/clio-coder/settings.yaml`), prints the current active values,
+and provides a safe back/exit option (`b` or `q`).
+
+The `--section <name>` flag jumps directly into any section (e.g.,
+`clio-coder configure --section models` or `clio-coder configure --section fleet`).
+The `--json` flag emits the active settings in formatted JSON for scripting.
+
 ---
 
 ## 6. Residues Checklist for Manual Purging
@@ -364,7 +428,7 @@ If you are removing Clio Coder completely from your system, verify that all cate
 3.  **Global Bin Links**:
     *   `clio-coder` executable in your global npm path (for source checkouts, avoid this path unless intentionally debugging npm link behavior).
 4.  **Per-Repository State**:
-    *   `.clio-coder/` in every repository Clio has worked in, and the generated `CLIO-CODER.md` beside it. See [The Project `.clio-coder/` Directory](#the-project-clio-directory) for what each entry is before deleting.
+    *   `.clio-coder/` in every repository Clio has worked in, and the generated `CLIO-CODER.md` beside it. See [The Project `.clio-coder/` Directory](#the-project-clio-coder-directory) for what each entry is before deleting.
     *   Remove `.clio-coder/worktrees/` with `git worktree remove` rather than `rm -rf`, so git does not keep stale worktree metadata.
 
 ---
@@ -375,5 +439,5 @@ Clio Coder supports headless operation for automation and continuous integration
 
 When executing tasks headlessly using `clio-coder run`, interactive permission prompting is unavailable. The engine resolves permission requests using a deterministic model:
 - **Main-agent auto-denial:** Any main-agent tool call that parks for operator authorization is denied with `clio-coder run cannot confirm permission requests; rerun interactively to approve this action.` The parked call is cancelled with that reason, and the headless turn finishes according to the resulting assistant outcome.
-- **Worker non-stall policy:** Dispatched workers use `workers.onPermission`. The default `deny` turns a permission ask into a structured tool denial and lets the worker continue. `fail` aborts the worker and records the dispatch outcome as `failed/permission_required`.
+- **Worker non-stall policy:** Dispatched workers use `fleet.permissions.mode`. The default `deny` turns a permission ask into a structured tool denial and lets the worker continue. `fail` aborts the worker and records the dispatch outcome as `failed/permission_required`.
 - **CI behavior:** Neither path waits for an interactive prompt. Exit status still reflects the final headless or dispatch result rather than the mere fact that a permission ask occurred.

package/docs/guide/panes-and-files.md

@@ -0,0 +1,290 @@
+# Panes and the Files Pane
+
+> **Visual blueprint:** The source checkout includes the complete
+> [Panes and the Files Pane visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/panes_files_blueprint.html).
+
+This page is the operator's path from a clean machine to a working files pane
+beside a Clio Coder session: what to install, how a session joins its pane
+host, the commands and keys, the settings that govern them, what `doctor`
+says at each stage, and what to do when something does not open. Every step
+below was run on Linux x64 against Clio Coder 0.4.2 with herdr 0.8.2 and the
+pinned files-pane engine; the outputs quoted are what those runs printed.
+
+Panes are optional. A session without them behaves exactly as before, and
+nothing on a startup path downloads, probes a socket, or writes a file unless
+panes were asked for.
+
+## What you get
+
+Inside a herdr session, Clio can open panes beside itself and close them
+when it quits:
+
+- **The files pane.** A file view docked below the session. `/files` or
+  `Alt+E` opens it and moves the keyboard into it; the same key or command
+  closes it. Picking a file sends it back to the composer as an `@file`
+  mention and returns the keyboard to the prompt. The engine behind it is a
+  vendored file manager, installed on request with
+  `clio-coder tools install yazi`; that program's name appears nowhere else in
+  the operator surface.
+- **The logs pane.** `/panes open logs` follows the newest dispatched run's
+  event journal with `tail -F`.
+- **The shell pane.** `/panes open shell` opens a login shell in the
+  workspace.
+- **The workers watch pane.** Enter on a live run in the `Alt+W` board renders
+  that run's stream in a pane to the right. It is documented with the fleet
+  in [Fleet Dispatch](fleet-dispatch.md); this page covers the utility panes.
+
+Outside herdr, `/files` still works: the file view takes over the terminal
+for one pick and returns to the session with the selection in the composer.
+The logs and shell panes need a pane host and say so.
+
+## Install, from a clean machine
+
+Clio bundles neither the pane host nor the files-pane engine. The npm
+package ships the engine's configuration (the profile under
+`src/domains/mux/yazi/assets/`), and the two programs are downloaded only
+when an operator asks, from a registry that pins each release's URL and
+sha256 per platform. A copy already on `PATH` wins over a vendored one when it
+clears the registry's minimum version.
+
+On-demand install is the decision, not a gap (#274). Bundling the two
+programs would add roughly 22 MB for herdr and 32 MB for yazi per platform
+across five platforms, and the release audit in `scripts/check-release.mjs`
+holds the tarball to 10 MB and the unpacked package to 50 MB as its tripwire
+against packaging defects; one bundled platform alone would trip it. Both
+programs also carry their own licenses and notices, which the package would
+then have to ship. So the first `/files` on a clean machine is a refusal that
+names the install command, `doctor` warns row by row with the same command,
+and the download happens only when you ask for it.
+
+```bash
+npm install -g @iowarp/clio-coder
+clio-coder configure
+clio-coder tools install herdr     # or: clio-coder panes install
+clio-coder tools install yazi
+```
+
+Both installs verified their checksums and finished in under a second on
+this machine:
+
+```text
+$ clio-coder tools install yazi
+  downloading https://github.com/sxyazi/yazi/releases/download/v26.8.15/yazi-x86_64-unknown-linux-gnu.zip
+  checksum verified (cc67eb7991550c2f9407cda52d3f5af0937627aa6884e7de99a04fcf059807e0)
+ok: installed yazi 26.8.15 (MIT) at ~/.local/share/clio-coder/tools/yazi/26.8.15
+```
+
+`clio-coder tools list` then shows where each program resolves. On the test
+machine a file manager from a distribution package sat on `PATH` below the
+registry floor, and the listing said exactly that rather than reporting it
+missing:
+
+```text
+TOOL   PIN      LICENSE     SOURCE    RESOLVED
+herdr  0.8.2    Apache-2.0  path      PATH /home/you/.local/bin/herdr (0.8.2, pin 0.8.2)
+yazi   26.8.15  MIT         vendored  vendored .../tools/yazi/26.8.15/yazi (26.8.15); PATH copy /home/you/.local/bin/yazi is 26.1.22, below the 26.8.15 floor, so Clio runs the vendored copy
+```
+
+The vendored programs live under the data root (`clio-coder paths`), so
+`clio-coder reset --data` removes them and `tools install` brings them back.
+`clio-coder tools remove yazi` removes only Clio's copy.
+
+## Turn panes on
+
+Two switches, both off by default:
+
+```yaml
+interface:
+  panes:
+    enabled: auto      # detect a herdr session and join it as a guest
+    files:
+      enabled: true    # allow the files pane
+```
+
+Or, for one session, start Clio with `clio-coder --with-panes` from a pane
+inside herdr; the flag beats the setting in both directions
+(`--no-panes` turns them off). `interface.panes.enabled: embedded` is
+accepted but not implemented yet: it behaves as `auto` and logs that at boot.
+
+Guest mode needs three things, checked in this order: `HERDR_ENV=1` in the
+environment (herdr sets it in every pane it opens), a herdr socket that
+connects, and a ping answered inside one second. `HERDR_SOCKET_PATH` and
+`HERDR_SESSION` name the socket when herdr's defaults do not apply.
+
+## What doctor says
+
+`clio-coder doctor` never fails an install for missing panes; the rows are
+warnings that name the next step. With the settings above and Clio started
+from a plain terminal rather than a herdr pane, the run on this machine
+printed:
+
+```text
+OK   external tool herdr    PATH /home/you/.local/bin/herdr (0.8.2, pin 0.8.2)
+WARN external tool yazi     PATH copy /home/you/.local/bin/yazi is 26.1.22, below the 26.8.15 floor, and nothing is vendored (install with `clio-coder tools install yazi`)
+WARN files pane profile     ~/.cache/clio-coder/yazi/profile (missing); user config ~/.config/yazi is separate and untouched
+WARN panes mode             none (panes.enabled=auto); HERDR_ENV is not 1, so Clio is not running inside a pane host
+WARN panes socket           no socket answered; tried /home/you/.config/herdr/herdr.sock
+WARN panes protocol         unknown; Clio's optional methods need protocol 17 or newer
+OK   panes binary           PATH /home/you/.local/bin/herdr (0.8.2, pin 0.8.2)
+OK   panes layout           off
+```
+
+With both settings off, the same rows read `experimental integration
+disabled by settings` and `panes mode: off by choice`, and doctor does not
+advertise setup work. The `files pane profile` row is `missing` until the
+first open generates it, then `current`; `stale` means the engine, Clio's
+version, or the theme changed since, and the next open regenerates it.
+
+## Commands and keys
+
+| Surface | What it does |
+| --- | --- |
+| `/files` | Toggle the files pane: open it below the session and move the keyboard into it, or close it and return the keyboard to the composer. |
+| `Alt+E` | The same toggle as a key (`clio-coder.files.toggle`; `Ctrl+G` then `e` on terminals without Alt). |
+| `/files open` | Open the pane, or focus it when it is already open. |
+| `/files close` | Close the pane. |
+| `/files pick` | Borrow the pane for one selection, then close it. Outside herdr, `/files` always behaves this way. |
+| `/panes` | Mode, socket, effective settings, the files pane's state, docks, and every Clio-owned pane. |
+| `/panes open files\|logs\|shell` | Open a preset pane; a second open focuses the pane that is already there instead of splitting again. `yazi` still parses as `files`. |
+| `/panes open files --once` | The same one-shot pick as `/files pick`. |
+| `/panes open <command…>` | Open an arbitrary command in a pane. Operator-only; the model's `panes` tool cannot do this. |
+| `/panes show <run-or-agent>` | Point the workers watch pane at a live run. |
+| `/panes zoom [target]` | Toggle zoom on a Clio-owned pane (default: the watch pane). |
+| `/panes close [target\|all]` | Close one Clio-owned pane by id, label, or purpose, or all of them. |
+
+The model has the same doors with one exception: its `panes` tool opens only
+the three presets (`files`, `logs`, `shell`) and never arbitrary argv. See
+[Tool Usage](tool-usage.md#panes-manage-clio-owned-terminal-panes).
+
+### Picking a file
+
+The pane opens on the workspace directory with the keyboard in it. Move with
+the arrow keys or `j`/`k`, enter a directory with `l` or `Enter`, go up with
+`h`, and mark several files with `Space`. `Ctrl+Y` sends the selection to
+Clio; in pick mode `Enter` on a file does the same and closes the pane.
+
+What arrives in the composer is appended to the draft, never submitted. A
+file becomes `@src/a.ts`; a directory or a path with spaces is inserted as
+plain backticked text, because those cannot be file mentions. Up to 32 paths
+and 4,096 characters land per pick, duplicates are skipped, and a notice
+counts what was inserted. The run on this machine, after picking
+`SECURITY.md` with `Ctrl+Y`, showed the composer holding `@SECURITY.md` with
+the keyboard back in it and the notice `1 path from the files pane added to
+the draft`.
+
+### What closes what
+
+- `/files`, `Alt+E`, and `/files close` close the files pane. A pane the
+  operator closed from herdr is treated as closed the moment herdr reports
+  it, so the next toggle opens rather than trying to close a pane that is
+  not there.
+- `/panes close shell`, `/panes close logs`, `/panes close all` close the
+  utility panes.
+- `/quit` closes the docks Clio manages, the files pane and the workers
+  watch pane, and leaves a shell or logs pane you opened. That is the
+  decided policy (#272): a dock is a Clio surface and goes with the session,
+  while a utility pane is a terminal you may be typing in, and Clio does not
+  kill it behind your back. The next session does not reclaim it either, so
+  `/quit` prints what it left, one line after the terminal is restored:
+
+  ```text
+  Clio left 1 pane open in herdr: bash in panes (wK:p2A). Utility panes stay when a session ends; the docks closed with it. Next time run `/panes close all` before `/quit` to take them with you, or close it now with `herdr pane close <paneId>`.
+  ```
+
+  Nothing is printed when only docks were open.
+
+## Settings
+
+| Key | Default | What it controls |
+| --- | --- | --- |
+| `interface.panes.enabled` | `off` | `auto` joins a detected herdr session; `off` skips detection; `embedded` is accepted and behaves as `auto` until implemented. |
+| `interface.panes.files.enabled` | `false` | Whether `/files`, its key, `/panes open files`, and the `panes` tool may open the files pane. Refused with the key's name otherwise. |
+| `interface.panes.files.mode` | `companion` | `companion` keeps the pane open across picks; `chooser` closes it after one selection. |
+| `interface.panes.files.profile` | `managed` | `managed` runs the engine on Clio's generated, themed profile; `user` runs it on the operator's own configuration, in which case picks use the one-shot chooser. |
+| `interface.panes.files.followCwd` | `true` | Reopening an open pane pushes the conversation's working directory into it. |
+| `interface.panes.files.ratio` | `0.3` | Share of the terminal height the files dock takes, `0.05` through `0.5`, floored at a usable number of rows. |
+| `interface.panes.layout` | `off` | `workers` opens the watch pane at boot; `cockpit` opens the watch pane and the files pane. Both close on `/quit`. |
+| `interface.panes.notifications` | `failures` | Which finished runs raise a herdr toast. |
+| `interface.keybindings."clio-coder.files.toggle"` | `alt+e` | Rebind the files toggle. |
+
+Every key is live through `/settings` under Terminal, files pane, and in the
+[Configuration Reference](configuration-reference.md).
+
+## Theme
+
+The files pane is themed from Clio's own palette. Every color in the
+engine's generated theme comes from the theme tokens in
+`src/core/theme-token-hex.ts` (accent, action, success, warning, error, info,
+frame, and the rest), rendered when the managed profile is generated on open
+and stamped into the profile, so a palette change regenerates the profile on
+the next open. Clio ships one palette; there is no separate light theme to
+mirror, and the pane follows whatever Clio itself uses.
+
+What is not themed by Clio is herdr's own chrome: the sidebar, tab bar,
+borders, and agent rows come from herdr's `config.toml`, and herdr has no
+per-pane styling on its socket. `clio-coder panes theme` prints Clio's tokens
+as a herdr `[theme.custom]` block to paste into that file; Clio does not edit
+another program's configuration. With `interface.panes.files.profile: user`,
+nothing is themed and the engine runs on your own configuration.
+
+That is the limit of what 0.4.2 can do, and it is herdr's, not Clio's. Checked
+against herdr 0.8.2: `herdr api schema --json` (protocol 21) has no method in
+the pane family that takes a color, accent, or style, and `herdr --help` has
+no theme command; herdr's theme is global and read from `[theme]` in its own
+`config.toml`. So Clio's chrome inside herdr (sidebar, tab bar, borders, agent
+rows) can only follow the block you paste. Writing or merging that block into
+herdr's config on your behalf would cross Clio's rule of writing nothing
+outside its own roots, and is not offered (#273). If a later herdr exposes a
+per-pane accent or a color field on `pane.report_metadata`, Clio can mark its
+own panes without touching the global theme.
+
+Clio's generated profile lives under the cache root at `yazi/profile` and
+never touches `~/.config/yazi`. `clio-coder tools status yazi --reset-profile`
+deletes it; the next open rebuilds it.
+
+## Troubleshooting
+
+**`panes are inactive: this session started without them`** on `/panes` or
+`/files`: the session booted without the panes extension. Restart with
+`clio-coder --with-panes` or set `interface.panes.enabled: auto`.
+
+**`the pane layer is not available in this session: HERDR_ENV is not 1 …`**
+on `/panes open logs` or `shell`: Clio has panes enabled but is not running
+inside a herdr pane. Start herdr, open a pane, run Clio there. `/files`
+still works as a one-shot pick in this state.
+
+**`the files pane is disabled by interface.panes.files.enabled`**: set that
+key to `true`, or flip Files pane under `/settings` Terminal.
+
+**`the files pane engine is not available: not found …`**: the message
+ends with the install command, `clio-coder tools install yazi`; run it. If a
+copy is on `PATH`, the message says which version it found and which floor it
+missed.
+
+**`no dispatched run has written a journal under … yet`** on
+`/panes open logs`: the logs pane follows a run's journal and no run has
+started in this state root. Dispatch something first.
+
+**The pane opened but nothing arrived after `Ctrl+Y`**: within five seconds
+of opening, Clio expects the pane to report its directory; if that never
+comes it says `the files pane did not report back in time; reopening it in
+pick mode` and retries with the one-shot chooser, whose picks arrive through
+a file instead of the event stream. `/panes` shows `file pane: … lastLine=`
+and a `dropped` count of lines that carried another session's token.
+
+**`doctor` warns `files pane profile … (stale)`**: nothing to do; the next
+open regenerates it. `tools status yazi --reset-profile` forces it.
+
+**A pane survived `/quit`**: it was a shell or logs pane. See "What closes
+what" above.
+
+## Where things live
+
+| Path | What |
+| --- | --- |
+| `<data>/tools/<id>/<version>/` | Vendored programs with their license files and an install marker. |
+| `<cache>/yazi/profile/` | Clio's generated engine profile: `yazi.toml`, `keymap.toml`, `theme.toml`, `init.lua`, a git-status plugin, and a stamp of the inputs. |
+| `<cache>/yazi/sessions/` | Per-pane transport files, removed when the pane closes; anything older than a day is swept on the next open. |
+| `<state>/runs/<runId>/events.ndjson` | The journal the logs pane follows. |
+
+Resolve `<data>`, `<cache>`, and `<state>` with `clio-coder paths`.