@iowarp/clio-coder 0.4.1 → 0.4.2

package/docs/{proactive-memory.md → guide/proactive-memory.md}

@@ -1,6 +1,7 @@
 # Proactive task memory
 
-> **Interactive Spec Available:** An interactive memory lifecycle dashboard and simulator is located at [docs/html/memory_blueprint.html](html/memory_blueprint.html) (Version: 0.4.0).
+> **Visual blueprint:** The source checkout includes the complete
+> [Proactive task memory visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/proactive_memory_blueprint.html).
 
 Clio's proactive task memory protects long-running work from behavioral state
 decay: a requirement, environment fact, failed attempt, or diagnosis can still
@@ -10,10 +11,10 @@ Long-Horizon Agents* (2026), adapted to Clio's visible middleware and local-mode
 routing.
 
 The rules-only tier is enabled by default and makes no model calls. An LLM memory
-tier is opt-in through the independent `background` route. The action agent's
-system prompt and tool surface do not change, and disabling
-`memory.intervention.enabled` removes observation, bank writes, model resolution,
-reminders, handoff offers, and handoff seeding.
+tier is opt-in through the independent `context.memory.target` and
+`context.memory.model` route. The action agent's system prompt and tool surface
+do not change, and disabling `context.memory.enabled` removes observation, bank
+writes, model resolution, reminders, handoff offers, and handoff seeding.
 
 ## Architecture
 
@@ -116,11 +117,11 @@ than discarding the writes that came with it. A timeout, provider failure,
 malformed response, or telemetry failure is silent and never blocks a tool.
 
 ### Intervention Defaults & Cadence Knobs
-- `memory.intervention.enabled` (default `true`): Enables observation, task bank writes, and reminder injection.
-- `memory.intervention.everyNTools` (default `10`): Minimum completed-tool interval between background interventions.
-- `memory.intervention.windowSteps` (default `8`): Completed tool-trajectory window analyzed during background evaluation.
-- `memory.intervention.maxTokens` (default `400`): Bounds the rendered memory-bank and reminder context budget; the policy model output cap is a separate fixed `4,000`-token contract in `task-memory-policy.ts`, sized so that a model which reasons anyway still reaches its envelope.
-- `memory.intervention.timeoutMs` (default `30000`): Wall-clock limit for one background memory-policy request. The step is detached, so this deadline never delays a turn, but it does hold a request slot on a real inference endpoint that your own turns and your dispatched workers queue against. The default is what a turn boundary can wait for rather than what a long-tailed route eventually answers in: on the reference route below, 23 of 60 steps ran past 30 seconds and 531 of the measured 1,666 seconds were spent beyond that mark. Raise it only if you have measured that your route's slow steps are the ones producing reminders, and read the trade in "Cost and the default decision" first.
+- `context.memory.enabled` (default `true`): Enables observation, task bank writes, and reminder injection.
+- `context.memory.cadenceToolCalls` (default `10`): Minimum completed-tool interval between background interventions.
+- `context.memory.trajectorySteps` (default `8`): Completed tool-trajectory window analyzed during background evaluation.
+- `context.memory.maxOutputTokens` (default `2000`): Bounds the rendered memory-bank context and the ordinary policy-model completion. An always-on-thinking model receives additional reasoning headroom, at least `4,000` tokens when its model cap permits, so it can still reach the strict envelope.
+- `context.memory.timeoutMs` (default `60000`): Wall-clock limit for one background memory-policy request. The step is detached, so this deadline never delays a turn, but it does hold a request slot on a real inference endpoint that your own turns and dispatched workers queue against. Raise it only after inspecting the timeout and hit-rate evidence for the selected route.
 
 ## Trigger semantics
 
@@ -130,7 +131,7 @@ it runs detached from it.
 
 | Trigger | Behavior |
 | --- | --- |
-| Interval | After `memory.intervention.everyNTools` completed tools since the last prompted step; default 10. This is the nondeterministic/citation-gated path. |
+| Interval | After `context.memory.cadenceToolCalls` completed tools since the last prompted step; default 10. This is the nondeterministic/citation-gated path. |
 | Tool-error streak | Two consecutive error outcomes. A successful tool resets the streak. |
 | Loop signal | Reuses the orchestrator loop guard's verdict; it does not infer a second competing loop detector. |
 | Repeated failure | The rules tier records failed operation fingerprints and annotates the failing tool result once the same failure appears twice in the bounded trajectory. |
@@ -163,9 +164,9 @@ records one telemetry row, not two.
 
 The agent loop does not become idle until every `agent_end` listener settles, so a
 memory step awaited at that boundary would add its full latency to the visible
-end of every triggered turn. Measured on the reference route below, step latency
-has a median of 18.6 seconds and ranges up to 220.8 seconds. This makes an awaited
-step intolerable as an end-of-turn pause.
+end of every triggered turn. Historical operator measurements below put a
+typical step in the tens of seconds. This makes an awaited step intolerable as
+an end-of-turn pause.
 
 The prompted step is therefore detached. `evaluateAsync` starts it and returns
 immediately; the turn ends on schedule. When the step resolves, its reminder is
@@ -217,8 +218,8 @@ hit rate.
 
 ### The measurement
 
-From one operator's `steps.jsonl`, 274 rows spanning 2026-08-14 to 2026-08-29 on
-a small local background route:
+From one operator's dated `steps.jsonl` export, 274 rows spanning 2026-08-14 to
+2026-08-29 on a small local background route:
 
 | Figure | Value |
 | --- | --- |
@@ -240,18 +241,19 @@ injections cost nothing.
 The default does not change, and it is a deliberate default rather than an
 unexamined one:
 
-- `memory.intervention.enabled` stays `true`. It runs the rules tier, which makes
+- `context.memory.enabled` stays `true`. It runs the rules tier, which makes
   no model calls, spends no tokens, and produced 4 of the 10 injections.
-- The LLM tier stays opt-in through `background.target` and `background.model`,
+- The LLM tier stays opt-in through `context.memory.target` and `context.memory.model`,
   which is already the case: an unset background role never resolves a client.
   A 10 percent hit rate at 22,868 tokens per injection does not earn a default-on
   position, and it is not so poor that it earns removal from an operator who has
   measured their own route and wants it.
-- The step deadline drops from 180 s to 30 s. This is the one behavioral change,
-  and it is a genuine trade: at 30 s, two of the six observed injections, at
-  53.6 s and 57.7 s, would have been cut, while 531 s of the 1,666 s spent would
-  not have been spent at all. The deadline is the bound on what one optional call
-  may hold a shared local server for, not a prediction of when a route answers.
+- `context.memory.timeoutMs` is `60000` in the current defaults. The dated study
+  considered a 30-second counterfactual: two of six observed injections, at
+  53.6 and 57.7 seconds, would have been cut, while 531 of 1,666 model seconds
+  would not have been spent. The current 60-second deadline is the source-backed
+  bound on what one optional call may hold a shared local server for, not a
+  prediction of when a route answers.
 - A step that would run on the endpoint the chat target is streaming against is
   skipped with reason `endpoint_busy`, and the skip is recorded. On a single-slot
   llama.cpp router the alternative is queueing behind the operator's own decoding
@@ -260,7 +262,7 @@ unexamined one:
 
 ### What a background target costs on a shared local server
 
-If `background.target` names the same server as `orchestrator.target`, that
+If `context.memory.target` names the same server as `chat.target`, that
 server's slots are shared. On a llama.cpp router started with `--parallel 1`
 there is exactly one, and the memory step and the operator's turn contend for it.
 
@@ -289,8 +291,8 @@ arrangement the tier is designed for.
 
 Memory reads a trajectory and writes a fixed envelope. It does not plan, and it
 does not need to be clever. A small non-reasoning model is the right choice, and
-Clio always requests the background route with thinking off regardless of
-`background.thinkingLevel`.
+Clio always requests the memory route with thinking off. Version 2 therefore
+has no configurable memory thinking-level key.
 
 That request reaches the wire wherever the runtime carries a thinking control:
 llama.cpp reads `chat_template_kwargs.enable_thinking`, and LM Studio reads
@@ -298,7 +300,8 @@ llama.cpp reads `chat_template_kwargs.enable_thinking`, and LM Studio reads
 
 A model that reasons anyway still works. Some genuinely cannot be silenced, and
 the catalog records those as always-on so the level reads `forced` rather than
-`off`; the shipped background model `qwopus3.5-9b-v3` is one of them. Reasoning
+`off`; the shipped model catalog classifies `qwopus3.5-9b-v3` that way. No model
+is selected for background memory by default. Reasoning
 blocks are discarded and only the envelope is kept, and the output budget is
 sized to let a reasoning preamble run its course first. The cost is latency,
 which the detached step absorbs.
@@ -328,52 +331,59 @@ KV caches, and parallel slots must all fit the target's available memory.
 The shipped defaults are:
 
 ```yaml
-background:
-  target: null
-  model: null
-  thinkingLevel: off
-
-memory:
-  intervention:
+context:
+  memory:
     enabled: true
-    everyNTools: 10
-    windowSteps: 8
-    maxTokens: 400
-    timeoutMs: 30000
+    target: null
+    model: null
+    cadenceToolCalls: 10
+    trajectorySteps: 8
+    maxOutputTokens: 2000
+    timeoutMs: 60000
 ```
 
-With `background.target` and `background.model` unset, Clio stays in the
+With `context.memory.target` and `context.memory.model` unset, Clio stays in the
 zero-cost rules tier. `/memory` shows the current tier, last decision, approved
 durable lessons, the live bank, and a bounded history of the last twenty memory
 steps with their trigger, decision, write count, cited-entry count, tier, and
 latency. That history is the only place a capture, a gate, or a timeout becomes
 visible, since those outcomes produce no transcript entry by design; only an
 actual injection reaches the transcript. It carries counts and outcomes only,
-never bank or trajectory text. `/settings` exposes every key above; the saved
+never bank or trajectory text. `/settings` exposes controls for every key above;
+its compact row labels retain shorter operator-facing names. The saved
 background-memory target is the Memory target row in Settings → Orchestrator,
 independent of the chat target and the fleet default. A running session owns
 its routing snapshot, while the saved
 selection becomes the default for new sessions.
 
-The reference live configuration is an LM Studio server on the `node-a` node with
-the wire model `example-background-model`:
+The reference topology separates chat from memory work:
+
+| Role | Target | Runtime and endpoint | Model | Capacity |
+| --- | --- | --- | --- | --- |
+| Chat | `dynamo` | LM Studio at `192.168.86.143:1234` | `qwen3.8-27b-dynamo` | Reported by the LM Studio probe |
+| Background memory | `mini` | llama.cpp router at `192.168.86.141:8080` | `ornith1.5-35b-moe` | 4 parallel slots, 262,144 context tokens per slot |
+
+The corresponding saved role selection is:
 
 ```yaml
-background:
-  target: node-a
-  model: example-background-model
-  thinkingLevel: off
+chat:
+  target: dynamo
+  model: qwen3.8-27b-dynamo
+context:
+  memory:
+    target: mini
+    model: ornith1.5-35b-moe
 ```
 
-A small model is the intended shape for this role. Across 60 measured steps on
-that route, latency ran 4.4 to 220.8 seconds with a median of 18.6, a 90th
-percentile of 79.9, and a 95th of 131.6. Capability is not the constraint;
-latency is, its spread is wide, and the detached step above is what makes the
-tier usable anyway.
+A smaller, efficient model is the intended shape for this role. The current
+reference uses a separate multi-slot endpoint so memory does not compete with
+the LM Studio chat stream. Capability is not the only constraint; latency and
+endpoint contention still matter, and the detached step above bounds their
+effect on the operator's turn.
 
 The deadline is a bound on what an optional call may hold that server for, not a
-figure sized to capture the tail. The shipped 30000 sits above the median and
-below the tail deliberately, and a step that exceeds it records `timeout` with
+figure sized to capture the tail. The shipped `60000` is a bounded compromise,
+and a step that exceeds it records `timeout` with
 its work discarded. A route whose steps mostly record `timeout` is a
 misconfigured deadline before it is a slow model, so read the ledger before
 raising it: `/memory` shows the hit rate the raise would be buying.
@@ -384,17 +394,19 @@ real target surfaces to verify the route:
 
 ```bash
 clio-coder targets --probe
-clio-coder models --target node-a
+clio-coder models --target mini
+clio-coder models --target dynamo
 clio-coder
 ```
 
-Then inspect `/targets`, `/settings`, and `/memory`. Local co-residency still
+Then inspect `/settings targets`, `/settings`, and `/memory`. Local co-residency still
 matters: the background model, action model, their KV caches, and parallel slots
-must fit the target's available memory. Increase `timeoutMs` for a deliberately
-slow local route; lowering `maxTokens` bounds the visible reminder but does not
-change the background model's strict output grammar.
+must fit the target's available memory. Increase `context.memory.timeoutMs` for
+a deliberately slow local route; lowering `context.memory.maxOutputTokens`
+bounds the visible reminder and ordinary completion budget but does not change
+the background model's strict output grammar.
 
-For an immediate kill switch, set `memory.intervention.enabled` to `false` in
+For an immediate kill switch, set `context.memory.enabled` to `false` in
 `/settings`. Removing the background target instead returns to rules-only
 operation while leaving deterministic protection active.
 
@@ -533,15 +545,16 @@ trial. The report provides:
 - total and baseline-relative added tokens and latency;
 - an `alwaysNoisyRegression` verdict.
 
-The deterministic end-to-end harness contract can be run directly:
-
-```bash
-npm run test:file -- tests/contracts/proactive-memory-eval.test.ts
-```
+The source-level harness remains available to a runner adapter, and the eval
+platform remains active. Its former dedicated contract test was retired, and
+the current test tree has no direct reference to `runProactiveMemoryEval`.
+There is therefore no maintained direct test coverage or standalone
+`npm run test:file` invocation for this harness. Treat a live comparison as an
+explicit measurement campaign.
 
 For a live local comparison, an adapter should route only the `llm` variant
-through the request's target/model (the reference is `node-a` /
-`example-background-model`), keep baseline memory telemetry empty, and run all
+through the request's target/model (the reference memory route is `mini` /
+`ornith1.5-35b-moe`), keep baseline memory telemetry empty, and run all
 nine trials in equivalent isolated workspaces. Do not promote the LLM tier from
 one anecdotal task. The evidence bar is a pass-rate gain from a small number of
 specific, usually cited reminders at acceptable added token and latency cost.

package/docs/{resource-library.md → guide/resource-library.md}

@@ -1,5 +1,8 @@
 # Resource Library
 
+> **Visual blueprint:** The source checkout includes the complete
+> [Resource Library visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/resource_library_blueprint.html).
+
 The resource library extends the existing local skills marketplace catalog to carry agent recipes, prompt templates, and fleet contracts. It does not change the Agent Skills format, discovery roots, trust gating, or existing skill installation sources.
 
 ## Catalog schema
@@ -21,11 +24,11 @@ skills:
 
 ## Private catalog and remote gating
 
-`library.catalog` selects a private catalog and defaults to `<configDir>/library.yaml`. Relative sources in that file resolve beside the catalog. `library.remote` records an optional git remote URL. `library.sync` defaults to false, and no git process is started while it remains false.
+`integrations.library.catalog` selects a private catalog and defaults to `<configDir>/library.yaml`. Relative sources in that file resolve beside the catalog. `integrations.library.remote` records an optional git remote URL. `integrations.library.sync` defaults to false, and no git process is started while it remains false.
 
-The private catalog repository must name its git remote `library`. Clio checks it with `git remote get-url library`. Run `clio-coder library remote confirm <url>` once after reviewing the configured URL. When `library.remote` is unset, confirmation records the URL as both the configured and confirmed remote. A confirmation that differs from an existing `library.remote` refuses with `library_remote_mismatch`. A missing confirmation or a later settings change refuses synchronization and publishing with `library_remote_unconfirmed`.
+The private catalog repository must name its git remote `library`. Clio checks it with `git remote get-url library`. Run `clio-coder library remote confirm <url>` once after reviewing the configured URL. When `integrations.library.remote` is unset, confirmation records the URL as both the configured and confirmed remote. A confirmation that differs from an existing `integrations.library.remote` refuses with `library_remote_mismatch`. A missing confirmation or a later settings change refuses synchronization and publishing with `library_remote_unconfirmed`.
 
-When `library.sync` is false, both `library sync` and `library push` refuse with `library_sync_disabled` before any process starts. When synchronization is enabled, `library sync` runs `git fetch library` followed by `git merge --ff-only FETCH_HEAD`, and `library push` runs `git push library`. Both commands execute git as an argument vector without a shell.
+When `integrations.library.sync` is false, both `library sync` and `library push` refuse with `library_sync_disabled` before any process starts. When synchronization is enabled, `library sync` runs `git fetch library` followed by `git merge --ff-only FETCH_HEAD`, and `library push` runs `git push library`. Both commands execute git as an argument vector without a shell.
 
 ## CLI
 
@@ -43,7 +46,13 @@ clio-coder library remote confirm <url>
 
 ## In the TUI
 
-The Skills Hub carries one tab per kind. `/library <kind>` opens it on that kind's tab and `/library` alone opens it on Skills, which is also where `/skill` opens. Each tab lists the entries this same discovery finds, with the requirements an entry still needs named in the warning token. Installing from a row runs the same plan-then-write pair `library add` runs, behind a confirmation that states every destination and hash and writes nothing when it is cancelled, and an entry with unresolved requirements is refused by name before an install-with-requirements confirmation offers to write them all. `Enter` on an installed row leads where that kind is invoked from: the composer for an agent, a prompt, or a skill, and the `/fleet run` approval preview for a fleet. See [skills-marketplace.md](skills-marketplace.md) for the key table.
+The Skills Hub carries one tab per kind. `/resources library <kind>` opens the
+requested tab, while `/skill` opens Skills. Each tab lists discovered entries
+and any unresolved requirements. Installing from a row uses the same
+plan-then-write path as `clio-coder library add`, behind a confirmation that
+states every destination and hash and writes nothing when cancelled. `Enter`
+on an installed row leads to its invocation surface. See
+[Skills Marketplace](skills-marketplace.md) for the key table.
 
 ## Installation roots and validation
 

package/docs/{skills-marketplace.md → guide/skills-marketplace.md}

@@ -1,7 +1,7 @@
 # Skills Marketplace
 
-> [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/skills_blueprint.html](html/skills_blueprint.html) (Version: 0.4.0).
+> **Visual blueprint:** The source checkout includes the complete
+> [Skills Marketplace visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/skills_blueprint.html).
 
 The Skills Hub (`/skill`) shows project skills, user skills, and the marketplace. Every marketplace row comes from the same local lookup that `clio-coder skills install <name>` and `/skill <name>` resolve through, so the hub lists nothing it cannot install.
 
@@ -45,7 +45,11 @@ Invoking an uninstalled marketplace skill with `/skill <name>` prompts before in
 
 ## Tabs
 
-The hub carries one tab per resource library kind: Skills, Agents, Prompts, and Fleets. `←` and `→` move between them, which is the key vocabulary the Settings Center already uses to move between sections. The frame title names the active tab and the footer states its row count, so the numbers on screen always describe the tab being read. `/skill` opens the hub on Skills. `/library <kind>` opens it on that kind's tab, and `/library` alone opens it on Skills.
+The hub carries one tab per resource-library kind: Skills, Agents, Prompts, and
+Fleets. `←` and `→` move between them. The frame title names the active tab and
+the footer states its row count, so the numbers on screen always describe the
+tab being read. `/skill` opens Skills; `/resources library <kind>` opens the
+requested library tab.
 
 The Skills tab is unchanged. The other three list the entries of their kind from `discoverLibrary()`, which is the same discovery `clio-coder library list --kind <kind>` reads, so the hub and the CLI never disagree about what exists. Each row carries the entry's origin and version, whether it is installed or available, the short form of its recorded pin hash, and, in the warning token, the names of any requirements it still needs. An entry the catalog refuses outright, because a requirement is missing, malformed, or cyclic, appears as a diagnostic row rather than being omitted.
 

package/docs/{tool-usage.md → guide/tool-usage.md}

@@ -1,17 +1,20 @@
 # Tool Usage Reference
 
-> [!TIP]
-> **Interactive Spec Available:** An interactive seven-plane tool atlas and observation envelope truncation/offload calculator is located at [docs/html/tool_usage_blueprint.html](html/tool_usage_blueprint.html) (Version: 0.4.0).
+> **Visual blueprint:** The source checkout includes the complete
+> [Tool Usage Reference visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/tool_usage_blueprint.html).
 
 This is the deep usage reference behind the deliberately terse tool descriptions in the prompt envelope. Toolkit v2 keeps rich guidance out of tool descriptions and puts it here, where `context(scope="docs", query=...)` retrieves it section by section. Each tool below has its own self-contained `##` section covering the argument surface, defaults, truncation and continuation behavior, and concrete calls. Source of truth is `src/tools/`.
 
-In Clio Coder v0.4.0, `src/tools/agent-tools.ts` serves as the single agent-tool adapter across both orchestrator and worker runtimes. Both surfaces resolve their executable tools through the exact same `effectiveToolNames` narrowing, ensuring that attested tool schemas never drift from the tools available at runtime. Tools are keyed strictly by the `ToolName` union with no alias table. Argument leniency for weak-model callers is provided exclusively by per-tool `prepareArguments` normalizers declared on `ToolSpec`.
+In the current source tree, `src/tools/agent-tools.ts` serves as the single agent-tool adapter across both orchestrator and worker runtimes. Both surfaces resolve their executable tools through the exact same `effectiveToolNames` narrowing, ensuring that attested tool schemas never drift from the tools available at runtime. Tools are keyed strictly by the `ToolName` union with no alias table. Argument leniency for weak-model callers is provided exclusively by per-tool `prepareArguments` normalizers declared on `ToolSpec`.
 
 ## Observation envelope: truncation notices, offload, next hints, and the turn budget
 
-The six OBSERVE tools (read, grep, find, ls, code_nav, context) share one result envelope, implemented in `src/tools/observation.ts`.
+The six envelope-backed OBSERVE tools (read, grep, find, ls, code_nav,
+context) share one result envelope, implemented in `src/tools/observation.ts`.
+The OBSERVE policy plane also contains `credential_present`, whose deliberately
+minimal result does not use that envelope.
 
-Per-call byte caps: read 50KB (env `CLIO_CODER_READ_MAX_BYTES`), grep 16KB for mode=content and 8KB for mode=files/count, find 8KB, ls 8KB, code_nav 16KB, context 16KB for scope=docs and 50KB for scope=skills/workspace.
+Per-call byte caps: read 50KB (`safety.limits.readBytesPerCall`), grep 16KB for mode=content and 8KB for mode=files/count, find 8KB, ls 8KB, code_nav 16KB, context 16KB for scope=docs and 50KB for scope=skills/workspace.
 
 Truncated text results append exactly one notice line:
 
@@ -25,7 +28,7 @@ Offload: when the byte cap cut content that was already collected, the complete
 
 JSON-format results (code_nav, context scope=docs/workspace) never get an appended notice. An oversize JSON payload is replaced whole by the parseable stub `{"error":"result exceeded <cap>","offloadPath":"...","next":"..."}` so the model never receives JSON cut mid-document. Empty results are also valid JSON with empty arrays and `next` populated.
 
-Turn budget: all six OBSERVE tools draw from one shared pool of 192KB per turn (env `CLIO_CODER_OBSERVATION_TURN_BUDGET_BYTES`, keyed on `sessionId:turnId`). When the remaining pool shrinks a call below its self cap, a note is appended naming the bytes already used. When the pool is exhausted, the call short-circuits with `[observation budget exhausted for this turn before <tool> ...]` instead of paying for a search whose output cannot be returned. Use narrower arguments or continue in a follow-up turn.
+Turn budget: all six OBSERVE tools draw from one shared pool of 192KB per turn (`safety.limits.observationBytesPerTurn`, keyed on `sessionId:turnId`). When the remaining pool shrinks a call below its self cap, a note is appended naming the bytes already used. When the pool is exhausted, the call short-circuits with `[observation budget exhausted for this turn before <tool> ...]` instead of paying for a search whose output cannot be returned. Use narrower arguments or continue in a follow-up turn.
 
 ## read: page through a file with offset, limit, and tail
 
@@ -38,7 +41,7 @@ Arguments:
 - `limit` (optional). Max lines to return.
 - `tail` (optional). Return the last N lines (jump to EOF). Overrides offset/limit.
 
-Each call is capped at 2000 lines or 50KB, whichever hits first (`CLIO_CODER_READ_MAX_BYTES` overrides the byte cap; the per-turn observation budget can shrink it further). Files larger than 20MB error outright; use grep/find to locate the relevant region instead. A missing file errors with a hint to locate it via code_nav, find, or ls.
+Each call is capped at 2000 lines or `safety.limits.readBytesPerCall`, whichever hits first; the per-turn observation budget can shrink it further. Files larger than 20MB error outright; use grep/find to locate the relevant region instead. A missing file errors with a hint to locate it via code_nav, find, or ls.
 
 Continuation: a truncated result's notice carries `next: offset=<first unshown line>`. read does not offload; the file itself is the continuation source. If a single line exceeds the byte cap, the result is that line's UTF-8 prefix plus an explanatory note suggesting grep with a narrower pattern or edit with exact surrounding text. An `offset` beyond EOF errors with the file's total line count.
 
@@ -234,26 +237,25 @@ Dispatches one or more tasks to Clio fleet agents and returns per-run receipt su
 Arguments:
 
 - `task` (required for the singular form unless `list:true`). One worker assignment/instruction string. It is distinct from briefing.
-- `tasks` (required for the batch form unless `list:true`). Array of task strings or `{task, agent, target, model, cwd, briefing, intent, gate}` objects. Per-item fields override the top-level defaults below. Supplying both `task` and `tasks` is an error.
+- `tasks` (required for the batch form unless `list:true`). Array of task strings or `{task, agent, target, model, node, briefing, intent, gate, budget, worktree}` objects. Per-item fields override the top-level defaults below; `persona`, `tool_profile`, `cwd`, and `apply` come from the batch defaults (an item that carries one is still honored, but the schema no longer advertises them per item). The `intent` and `budget` schemas are serialized once under `$defs` and referenced from the top level and from each item. Supplying both `task` and `tasks` is an error.
 - `mode` (optional). `parallel` (default) runs items concurrently; `sequential` runs them one at a time, each completing before the next dispatches. `pipeline`, `compete`, and `council` select their named topologies. A single ordinary task always runs down the sequential path.
-- `roster` (council only). Names one `workers.rosters` entry. Supply exactly one of `roster` or `members`.
+- `roster` (council only). Names one `fleet.rosters` entry. Supply exactly one of `roster` or `members`.
 - `members` (council only). Supplies two to five inline `{label,target,model?,thinking?}` entries.
 - `synthesis` (council only). Accepts `none`, `judge`, or `vote`; the default is `none`.
 - `rounds` (council only). Accepts an integer from 1 through 3; the default is 1.
 - `judge` (council only with judge synthesis, or compete). Accepts optional `agent`, `model`, `target`, and `node` route fields.
 - `detach` (optional boolean). For parallel fan-out, returns the durable batch id and assignment ids after registration while the shared event consumer continues in the background. An assignment id equals its first attempt's run id. This is the parent model's route to mid-run monitor/steer; ordinary synchronous, sequential, and pipeline calls auto-wait for each assignment's terminal attempt.
 - `list` (optional boolean). Returns the agent catalog instead of dispatching.
-- `agent` (optional). Default agent recipe for items that do not name one; default `coder`. `agent_id` is accepted as an alias inside items.
+- `agent` (optional). Default agent recipe for items that do not name one; default `coder`. The retired `agent_id` spelling is rejected with a message to use `agent`.
 - `target` (optional). Default configured target id.
 - `model` (optional). Default model override.
 - `node` (optional). Default fleet-node pin.
-- `failover` (optional). `none|approved|automatic`. Manual target/model/node pins default to `none`; `approved` requires `allowed_candidates`; `automatic` permits route-part-aware infrastructure failover.
-- `allowed_candidates` (optional). Ordered exact `{agent, target, model, node}` tuples. Valid only with `failover:"approved"`; retries cannot escape this envelope.
+- `routing` (optional). Hard route bounds include `maxCostUsd`, `deadlineMs`, and `requiredCapabilities`. When adaptive routing is configured, the schema also exposes `posture`, `minimumQuality`, `locality`, and `failover` (`none|approved`). Exact `target`, `model`, or `node` pins require manual posture and imply no failover. Top-level `failover`, `allowed_candidates`, and `allowedCandidates` are rejected; model-authored candidate envelopes are not accepted. Approved fallback candidates come from the admitted fleet route plan.
 - `thinking_level` (optional). One of `off|minimal|low|medium|high|xhigh|max`, applied to all items.
 - `cwd` (optional). Default agent working directory.
 - `timeout_ms` (optional). Aborts the whole dispatch; in sequential mode remaining tasks are skipped and the skip is reported.
 - `briefing` (optional string, top-level default or per-task override). Parent-composed context/data, not worker instructions: it cannot replace `task`. It is trimmed and omitted when blank, rejected above 12,000 UTF-8 bytes, sent as its own delimited untrusted dynamic message, and retained only as byte/hash provenance. The shared value applies to string tasks and object tasks without an override; an object-level briefing wins.
-- `intent` (object, top-level default or per-task override, and the default way to dispatch). Declares `read_roots`, `write_roots`, `relevant_paths`, `expected_outputs`, and `verification`. Path arrays contain normalized repository-relative POSIX paths. Verification entries contain a declared `check` id and optional `timeout_ms`; ids are resolved from package scripts and `.clio-coder/verifiers.yaml` before approval. Checks are ids, not shell commands. Declared paths select the project rules that apply to them and pin worker context; omitting `intent` falls back to reading path-like tokens out of the task and briefing, which can miss an applicable rule. In a batch, per-task `intent` shallow-merges over the top-level object and is then checked against it as a ceiling: a task may narrow the shared scope and is refused with `intent_scope_widening` if it reaches outside. Declaring `write_roots` that disagree with a legacy `writeRoots`, an `expected_outputs` entry outside every declared write root, or an `intent.version` other than 2 are each terminal refusals carrying a stable reason code. See [dispatch-typed-intent.md](dispatch-typed-intent.md).
+- `intent` (object, top-level default or per-task override, and the default way to dispatch). Declares `read_roots`, `write_roots`, `relevant_paths`, `expected_outputs`, and `verification`. Path arrays contain normalized repository-relative POSIX paths. Verification entries contain a declared `check` id and optional `timeout_ms`; ids are resolved from package scripts and `.clio-coder/verifiers.yaml` before approval. Checks are ids, not shell commands. Declared paths select the project rules that apply to them and pin worker context; omitting `intent` falls back to reading path-like tokens out of the task and briefing, which can miss an applicable rule. In a batch, per-task `intent` shallow-merges over the top-level object and is then checked against it as a ceiling: a task may narrow the shared scope and is refused with `intent_scope_widening` if it reaches outside. Declaring `write_roots` that disagree with a legacy `writeRoots`, an `expected_outputs` entry outside every declared write root, or an `intent.version` other than 2 are each terminal refusals carrying a stable reason code. See [dispatch-typed-intent.md](../architecture/dispatch-typed-intent.md).
 - `gate` (optional string, top-level default or per-task override). Exact shorthand for `intent.verification=[{check: gate}]`. Supplying it together with `intent.verification` is refused.
 - `max_output_bytes` (optional). Summary byte budget; default 20000, split across runs with at least 1024 bytes each.
 
@@ -261,7 +263,7 @@ Argument tolerance: `tasks` sent as a JSON string is parsed and a single object
 
 Output is one batch-shaped summary even for a single task: a header `dispatch (<mode>) total=N failed=M`, the assignment id list, then one terminal-attempt receipt line per assignment (run id, agent, exit code, target, model, tokens, receipt path, verification state, failure message if any) followed by the worker's final assistant text. `details = {mode, assignmentIds, receiptCount, failedCount, runs[]}`, and each `runs[]` entry carries distinct `assignmentId` and terminal `runId` fields plus the structured `verification` state and `receiptIntegrity` result. There is no `runIds` compatibility alias. Any terminal attempt with a nonzero exit turns the whole result into an error carrying the same summary. A run that succeeded without a single successful tool call carries a `note=` marker; do not treat such a run as validated work.
 
-The summary separates five things that must never be conflated: `receipt_integrity=verified/v19/sha256` comes only from verification against the ledger; `host_verification=<status>` describes orchestrator-executed declared checks; `evidence_verification=<state>/<basis>` describes worker-tool validation evidence; `briefing=bytes:<n> sha256:<hash>` authenticates parent-supplied data; and `project_context=...` authenticates the independently rendered bounded project message. A tampered receipt renders a head-anchored `RECEIPT INTEGRITY FAILED` banner. A read-only Scout can have verified integrity with `not_applicable/read-only-agent` evidence. Missing briefing is `briefing=none`, never a project-context hash.
+The summary separates five things that must never be conflated: `receipt_integrity=verified/v20/sha256` comes only from verification against the ledger; `host_verification=<status>` describes orchestrator-executed declared checks; `evidence_verification=<state>/<basis>` describes worker-tool validation evidence; `briefing=bytes:<n> sha256:<hash>` authenticates parent-supplied data; and `project_context=...` authenticates the independently rendered bounded project message. A pre-v20 receipt is retired and cannot count as evidence. A tampered v20 receipt renders a head-anchored `RECEIPT INTEGRITY FAILED` banner. A read-only Scout can have verified integrity with `not_applicable/read-only-agent` evidence. Missing briefing is `briefing=none`, never a project-context hash.
 
 Exit zero is insufficient without a durable deliverable. A successful native or ACP run must seal a nonempty `output.state="final"`. Otherwise it fails with `worker_final_output_missing`; any unfinished text remains partial diagnostics and automatic retry is suppressed. Live tool-use preambles never replace a missing receipt answer.
 
@@ -269,16 +271,16 @@ Sealed receipts are the durable evidence; worker prose remains advisory until ve
 
 ```text
 dispatch(list=true)
-dispatch(agent="debugger", task="Adversarially verify the strict v19 receipt boundary", briefing="Prior receipt R1 cited receipt-integrity.ts and left these claims unresolved", intent={read_roots: ["src/domains/dispatch/"]}, detach=true)
+dispatch(agent="debugger", task="Adversarially verify the strict v20 receipt boundary", briefing="Prior receipt R1 cited receipt-integrity.ts and left these claims unresolved", intent={read_roots: ["src/domains/dispatch/"]}, detach=true)
 dispatch(tasks=[
-  {task: "Run the contract tests in tests/contracts/dispatch.test.ts and report each failure with its assertion",
+  {task: "Run the contract tests in tests/contracts/dispatch-lifecycle.test.ts and report each failure with its assertion",
    intent: {read_roots: ["tests/contracts/", "src/domains/dispatch/"], verification: [{check: "test"}]}}
 ])
 dispatch(tasks=[
   {agent: "researcher", task: "Map every caller of finalizeObservation and summarize the envelope shapes",
    intent: {read_roots: ["src/domains/"]}},
-  {agent: "coder", task: "Fix the failing assertion in tests/contracts/safety.test.ts",
-   intent: {write_roots: ["tests/contracts/"], expected_outputs: ["tests/contracts/safety.test.ts"], verification: [{check: "test"}]}}
+  {agent: "coder", task: "Fix the failing assertion in tests/contracts/safety-gates.test.ts",
+   intent: {write_roots: ["tests/contracts/"], expected_outputs: ["tests/contracts/safety-gates.test.ts"], verification: [{check: "test"}]}}
 ], mode="parallel")
 dispatch(
   intent={read_roots: ["src/"], write_roots: ["src/domains/"]},
@@ -369,7 +371,7 @@ Prefer verify over bash for the verification family and project catalog: the typ
 ```text
 verify()
 verify(check="typecheck")
-verify(check="test", args=["tests/contracts/dispatch.test.ts"])
+verify(check="test", args=["tests/contracts/dispatch-lifecycle.test.ts"])
 verify(check="rust-workspace")
 verify(check="frontend", path="site/index.html", browser="off")
 ```
@@ -414,7 +416,10 @@ Arguments:
 
 `scope="workspace"` returns the session's git/project snapshot as JSON, probing and caching it on first call. When model-visible skills are installed, the payload carries a one-line `skills` pointer (count plus the suggest protocol) so orientation surfaces the catalog; the pointer never includes catalog entries and never changes the load gate. It requires a bound session; worker registries without one get a clean error. 50KB cap.
 
-`scope="docs"` runs deterministic, offline retrieval over Clio's bundled docs (every `docs/*.md` plus README.md, CHANGELOG.md, and CLIO-CODER.md), indexed as heading-delimited sections with light stemming, Clio vocabulary aliases, phrase boosts, and BM25-style body scoring. The JSON payload carries `corpus`, the expanded `terms`, and ranked `results` with `file`, `heading`, `breadcrumb`, `anchor`, `lines`, `snippet`, `score`, `coverage`, `matchedTerms`, and `signals`, plus an `omitted` count. Follow the `followUp` guidance: read the cited file and line range when you need the full section. Empty results are still valid JSON with `next` populated (the closest vocabulary expansion, or `query=overview`). 16KB cap; an oversize payload is replaced by the parseable JSON stub. The old `docs_search` `file` filter was dropped in the consolidation. Omitting `query` returns the corpus listing (the file set plus doc and section counts, the same `corpus` shape a search carries) so the model can pick a term without wasting a round on a `requires query` error.
+`scope="docs"` runs deterministic, offline retrieval over Clio's recursively
+bundled Markdown tree under `docs/` plus README.md, CHANGELOG.md, and
+CLIO-CODER.md, indexed as heading-delimited sections with light stemming, Clio
+vocabulary aliases, phrase boosts, and BM25-style body scoring. The JSON payload carries `corpus`, the expanded `terms`, and ranked `results` with `file`, `heading`, `breadcrumb`, `anchor`, `lines`, `snippet`, `score`, `coverage`, `matchedTerms`, and `signals`, plus an `omitted` count. Follow the `followUp` guidance: read the cited file and line range when you need the full section. Empty results are still valid JSON with `next` populated (the closest vocabulary expansion, or `query=overview`). 16KB cap; an oversize payload is replaced by the parseable JSON stub. The old `docs_search` `file` filter was dropped in the consolidation. Omitting `query` returns the corpus listing (the file set plus doc and section counts, the same `corpus` shape a search carries) so the model can pick a term without wasting a round on a `requires query` error.
 
 `scope="skills"` with no `name` lists installed skills with descriptions; the listing asks the model to match the current task against the catalog and, on a fit, to open its reply with `Suggested skill: /skill <name>` (a comma-separated sequence when skills compose) and wait for the operator. Loading a body is policy-gated: a skill loads only after an explicit `/skill <name> [task]` operator request, including one picked from the Skills Hub, and recipe-bound workers may load only their declared skills. A load attempt without a pending request is denied with the model's compliant next move spelled out: do not retry, open the reply with the `Suggested skill: /skill <name>` line and wait for the operator, or continue without skills. On the first substantive turn of a session with model-visible skills installed, a once-per-session middleware reminder in the user message teaches the same protocol. A pending request's task text is surfaced with the body. Marketplace-installed skills are drift-checked against their pinned hash; a mismatch annotates the result with a `skill_drift` warning but never blocks. 50KB cap; a truncated body offloads in full.
 
@@ -558,11 +563,70 @@ Dispatched runs link to the live board through the ledger's `activeRunIds` field
 ```text
 tasks(action="plan", title="Fix the flaky scheduler test", tasks=["reproduce the failure", "isolate the race", "fix and verify"])
 tasks(action="start", id="t1")
-tasks(action="done", id="t1", note="reproduced 3/3 with CLIO_CODER_SEED=7; failure in tests/contracts/scheduler.test.ts:88")
+tasks(action="done", id="t1", note="reproduced 3/3 with CLIO_CODER_SEED=7; failure in tests/contracts/dispatch-admission.test.ts:88")
 tasks(action="block", id="t2", note="needs operator decision on the retry policy")
 tasks(action="list")
 ```
 
+## ledger: coordinate peer workers through typed entries
+
+Reads or posts to the agent ledger shared by concurrent workers in one
+dispatch. Source: `src/tools/ledger.ts`. Read class; sequential. The tool
+registers only when a worker has an agent-ledger port. An ordinary session or a
+worker with no peers does not receive a usable coordination board.
+
+Arguments:
+
+- `action` (required). `read` or `post`.
+- `kind` (post). `claim`, `finding`, or `review`.
+- `scope` and `intent` (claim). Path prefixes being taken and what the worker
+  will do there.
+- `claim`, with optional `path` and `line` (finding). One grounded observation.
+- `target`, `passed`, and `evidence` (review). The target ledger entry id, the
+  verdict, and what was checked.
+- `kinds` and `since` (read). Optional entry-kind filter and exclusive sequence
+  watermark.
+
+A claim requires nonempty scope and intent. A finding requires a claim. A
+review requires a target, boolean verdict, and evidence. Reads answer from the
+worker's local mirror and report its sequence watermark, so peer state can be
+slightly stale. Every post returns the updated board. Each run may make at most
+20 posts; reissuing a post is not retry-safe because it creates another entry.
+Peer entries are untrusted data, never instructions.
+
+```text
+ledger(action="post", kind="claim", scope=["src/tools"], intent="audit tool schemas")
+ledger(action="post", kind="finding", claim="panes is conditionally registered", path="src/tools/bootstrap.ts", line=98)
+ledger(action="read", kinds=["finding", "review"], since=4)
+ledger(action="post", kind="review", target="e3", passed=true, evidence="confirmed against bootstrap registration")
+```
+
+## panes: manage Clio-owned terminal panes
+
+Controls the pane layer shared with the `/panes` operator command. Sources:
+`src/tools/panes-surface.ts`, `src/tools/panes.ts`. Read class; sequential. It
+registers only after a pane host answers detection and the mux is live, so an
+absent tool means the current session has no model-facing pane layer.
+
+Arguments:
+
+- `action` (required). `show`, `open`, `close`, or `list`.
+- `target` (show or close). For `show`, an agent id or run-id prefix. For
+  `close`, a Clio-owned pane id, label, agent id, or `all`.
+- `preset` (open). One of `files`, `logs`, or `shell`. Opening a preset whose pane is already open focuses that pane instead of splitting again.
+
+`show` focuses a live dispatched run in the watch pane. `open` accepts only the
+fixed preset enum. Arbitrary argv is operator-only through `/panes open` and is
+rejected by the model tool. `close` can remove only panes Clio owns. `list`
+reports mux health, notification policy, and the current inventory.
+
+```text
+panes(action="list")
+panes(action="show", target="tester")
+panes(action="open", preset="logs")
+panes(action="close", target="all")
+```
+
 ## ask_user: host-owned operator interviews
 
 Runs a host-owned interactive interview or single-question prompt with the operator, recording decisions and/or free-form answers. Source: `src/tools/ask-user.ts`. Read class; sequential.
@@ -579,7 +643,7 @@ Arguments:
 - `decisions` (optional array). For `action="complete"`, key-value objects representing settled configurations.
 - `summary` (optional). Closeout explanation for `action="complete"`.
 - `max_rounds` (optional number). Round limit for this interview (default 6, max 24).
-- `exposure` (optional). `local` (default) or `outward`. `outward` marks a gate whose answer publishes or sends something outside the workspace (filing an issue or PR, posting a comment, pushing, releasing). At autonomy `auto-edit` an outward gate parks for the operator instead of being answered automatically; `full-auto` answers it. See [safety-model.md](safety-model.md).
+- `exposure` (optional). `local` (default) or `outward`. `outward` marks a gate whose answer publishes or sends something outside the workspace (filing an issue or PR, posting a comment, pushing, releasing). At autonomy `auto-edit` an outward gate parks for the operator instead of being answered automatically; `full-auto` answers it. See [safety-model.md](../architecture/safety-model.md).
 
 The tool manages a stateful operator interview. The UI presents choices (with an implicit "Other" option for custom text input). Once completed, the final decisions are persisted as standard configurations in the session ledger, allowing the agent to proceed with operators' inputs or defaults.
 
@@ -601,7 +665,7 @@ Arguments:
 - `title` (optional). Document title.
 - `path` (optional). Override the default path under `.clio-coder/artifacts/`.
 
-`kind=plan|review|report` writes a Markdown document to `.clio-coder/artifacts/PLAN.md`, `REVIEW.md`, or `REPORT.md` by default, so a turn nobody asked a file from never litters the working tree; `path` may override the destination but must stay inside the workspace. See [artifact-placement.md](artifact-placement.md) for the full contract. When `content` does not already start with `#`, a non-empty `title` is prepended as an H1. These kinds are TERMINAL: writing the artifact completes the turn and the harness skips the follow-up model call, so the artifact body itself is the answer. Put everything the reader needs in `content`; there is no closing message after the write.
+`kind=plan|review|report` writes a Markdown document to `.clio-coder/artifacts/PLAN.md`, `REVIEW.md`, or `REPORT.md` by default, so a turn nobody asked a file from never litters the working tree; `path` may override the destination but must stay inside the workspace. See [artifact-placement.md](../architecture/artifact-placement.md) for the full contract. When `content` does not already start with `#`, a non-empty `title` is prepended as an H1. These kinds are TERMINAL: writing the artifact completes the turn and the harness skips the follow-up model call, so the artifact body itself is the answer. Put everything the reader needs in `content`; there is no closing message after the write.
 
 Skills are not artifacts. A skill is a `SKILL.md` folder written with the ordinary write tool into `.clio-coder/skills/<name>/` (or the user skill store) and validated by the skills loader; the `skill-craft` shipped skill documents the format and craft rules.