@iowarp/clio-coder 0.4.1 → 0.4.3

package/docs/{context-engine.md → architecture/context-engine.md}

@@ -1,7 +1,7 @@
 # Context Engine
 
-> [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/context_blueprint.html](html/context_blueprint.html) (Version: 0.4.0).
+> **Visual blueprint:** The source checkout includes the complete
+> [Context Engine visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/context_blueprint.html).
 
 Clio Coder tracks context pressure, records per-turn snapshots, and protects the provider context with bounded tool results plus single-threshold compaction.
 
@@ -11,13 +11,13 @@ The non-destructive eviction layer has its own guide: [context-working-set.md](c
 
 ## Context window resolution
 
-Each target has a declared, desired, and effective context window. The effective window is the operating ceiling used by budget checks and compaction. Sources rank most-live first: the window discovery reports the model is loaded at, then a probed window, then a target override, then a model hint, catalog knowledge, a local-native default, and finally a descriptor default.
+Each target has a declared, desired, and effective context window. The effective window is the operating ceiling used by budget checks and compaction. A one-run `--max-context-tokens` override wins when present. Otherwise sources rank most-live first: the window discovery reports the model is loaded at, then a probed window, a target capability override, a model hint, knowledge-base data, the built-in model catalog, a runtime descriptor default, and finally Clio's assumed fallback.
 
 The loaded window outranks the declared one because it is the only figure describing what the backend will serve. LM Studio routinely opens a model well below its `max_context_length`, and a run planned against the larger number overruns the server before compaction ever fires. Discovery carries that number per model in `discoveredModelStates[<model>].contextLength`, and the residency notice reads the same entry, so a model Clio is budgeting a loaded window for is never announced as absent.
 
 A resumed session carries the loaded window it already recorded. A resume re-resolves its target before discovery has reported what the backend has open, so the first turn used to budget against the probed figure, which on a multi-slot or multi-copy backend can be several times the real headroom, and corrected a turn later. `lastLoadedContextWindow` reads the last `loaded` window the session's own `context-snapshots.jsonl` recorded for the same target and model and hands it to resolution as `knownLoadedContextWindow`. It is used only when live discovery reports nothing, and it is scoped to that target and model, so a different selection re-probes and a model reloaded at a new size corrects as soon as discovery names the live window.
 
-Local-native runtimes use a recommended minimum desired window of 128,000 tokens. If the live model reports a smaller loaded context window, Clio re-resolves the target so accounting uses the actual ceiling.
+Clio uses 131,072 tokens as the minimum desired window and as the fallback when no source reports one, on every runtime tier. A reported effective window below 128,000 tokens triggers the undersized-window warning. If a live model reports a smaller loaded context window, Clio re-resolves the target so accounting uses the actual ceiling.
 
 The `/context` overlay states which layer answered, next to the token total: `loaded`, `probed`, `configured`, `declared`, or `assumed`.
 
@@ -39,13 +39,13 @@ The `/context` overlay and footer meter read the same ledger categories in displ
 
 ## Single-threshold compaction
 
-Auto-compaction is controlled by one pressure threshold. Pressure is `budgeted_tokens / context_window`, where the budgeted figure is the reconciled total when the provider has attested one and the chars/4 estimate otherwise. The default threshold is `0.8`.
+Auto-compaction is controlled by `context.compaction.threshold`. Pressure is `budgeted_tokens / context_window`, where the budgeted figure is the reconciled total when the provider has attested one and the chars/4 estimate otherwise. The default threshold is `0.8`.
 
 Crossing that threshold engages three mechanisms in a fixed order. The first two are cheap, reversible, and call no model. Only the third rewrites what the session says about itself.
 
 ### 1. Working-set eviction
 
-When `compaction.auto` is enabled and pressure crosses the threshold before a request, Clio applies the configured working-set policy first. The policy selects tool-result bodies and closed-turn thinking blocks, `runAutoCompact` appends one `contextEviction` ledger entry, and `refreshAgentMessagesFromSession` projects those units out of model replay behind a one-line marker. Nothing is deleted: the ledger keeps the original bodies, the transcript keeps showing them, and `/resume`, `/tree`, `/fork`, and the HTML export are unaffected.
+When `context.compaction.auto` is enabled and pressure crosses the threshold before a request, Clio applies the configured working-set policy first. The policy selects tool-result bodies and closed-turn thinking blocks, `runAutoCompact` appends one `contextEviction` ledger entry, and `refreshAgentMessagesFromSession` projects those units out of model replay behind a one-line marker. Nothing is deleted: the ledger keeps the original bodies, the transcript keeps showing them, and `/resume`, `/tree`, `/fork`, and the HTML export are unaffected.
 
 Already-evicted units are never selected again. Recent turns keep their full observations and thinking, governed by `context.workingSet.protectLastTurns`. Results whose estimated body is below `context.workingSet.minEvictableTokens` (200 tokens by default) are kept whatever their age as a low-yield churn guard. The engine separately refuses any candidate whose marker would save no tokens. The `age-horizon` policy is therefore the selection the old destructive mask made minus those small results, not a byte-identical reproduction of it; the default `structural-v1` policy applies its structural rules before any age rule.
 
@@ -85,7 +85,7 @@ When the ledger is replayed to the model, compaction summaries, branch summaries
 
 Every provider Clio targets caches by exact prefix. Anthropic hashes the cumulative prefix up to a `cache_control` breakpoint and looks back at most 20 blocks for an earlier write; the minimum cacheable prefix is 512 to 4,096 tokens by model, reads cost 0.1x input and writes 1.25x. OpenAI caches automatically from 1,024 tokens in 128-token increments on exact prefix matches at 0.1x. vLLM hashes each KV block from its parent block's hash, so a change in one block invalidates every later block. llama.cpp (and LM Studio on top of it) picks the slot with the longest common prefix and re-evaluates only the suffix, and `--cache-reuse` can shift later KV chunks back into place after a mid-prompt removal. The consequence is the same everywhere except on llama.cpp with cache reuse: whatever bytes change, everything after the earliest changed position is re-prefilled. That is why a marker is byte-stable, why a recall rides the tail instead of restoring the body in place, why `structural-v1` batches evictions down to `target` instead of trimming on every turn, and why the replay tables report cold prefix tokens per event next to tokens evicted: at a 32k budget one event re-prefills most of the window whichever policy chose the items, so the lever that protects a cloud cache is the number of events, not their contents. A local backend with cache reuse pays less for the same removal, which is where finer-grained eviction and recall earn their keep.
 
-The procedural replay target sweep measured 0.4, 0.5, 0.6, and an exhaustive rung-6 stop over 24 traces. Target 0.4 and exhaustive selection converged because un-evictable residue exhausted the candidate pool. Against 0.6, target 0.4 cut cold-prefix tokens by 2.8% at 64k and 7.3% at 128k, with no summary reduction and a 0.00072 reduction in retention covered at 128k. That is below the 10% cache-saving threshold set for changing a cross-tier default, so the default remains 0.6. The complete sweep and reopening rule are in the replay README.
+A historical local replay target sweep measured 0.4, 0.5, 0.6, and an exhaustive rung-6 stop over 24 traces. Target 0.4 and exhaustive selection converged because un-evictable residue exhausted the candidate pool. Against 0.6, target 0.4 cut cold-prefix tokens by 2.8% at 64k and 7.3% at 128k, with no summary reduction and a 0.00072 reduction in retention covered at 128k. That was below the 10% cache-saving threshold used for the experiment, so the default remained 0.6. The generated tables and reopening calculation were local artifacts and are not versioned in this repository; use the replay commands in [Commands and Modes](../guide/commands-and-modes.md#working-set-replay) to measure the current tree.
 
 The same arithmetic governs the compiled system prompt, which sits ahead of every message. Its sections are ordered stable prefix first, so a section that can change between two turns never sits ahead of one that cannot; the order and the rule behind it are in [prompt-envelope-and-tools.md](prompt-envelope-and-tools.md#section-order-stable-prefix-first).
 
@@ -139,9 +139,9 @@ Clio sends it at three moments: after the session prompt compiles at session sta
 
 The payload is the request the next turn would send minus the operator's text: the same system prompt, the same tool schemas, the same replayed messages, the same thinking level, and the same `cache_prompt`, with one single-character user message appended so the chat template renders the prefix up to the user turn, and `max_tokens: 1`. It is built through the same `streamSimple` dispatcher `createEngineAgent` hands the engine as its `streamFn`, not a hand-assembled payload, because any byte that differs ahead of the user turn defeats the purpose.
 
-The pre-warm is refused rather than queued whenever it would compete with real work. It runs only on `local-native` targets, whatever `prewarm.enabled` says, because a cloud provider bills the request and caches on its own schedule. It never runs while a turn is in flight, while any dispatch is outstanding, on a worker, or in headless `run`. The dispatch guard is a stand-in: without per-endpoint capacity accounting the pre-warm cannot tell whether a worker already occupies the server it would warm, so it stands down for all worker traffic. The round already claims one endpoint slot for as long as its request is out and releases it in a `finally`, through the `registerEndpointSlot` seam the chat loop wires from the endpoint-capacity registry, so capacity counts a pre-warm the same way it counts the orchestrator's streaming turn.
+The pre-warm is refused rather than queued whenever it would compete with real work. It runs only on `local-native` targets, whatever `chat.prewarm` says, because a cloud provider bills the request and caches on its own schedule. It never runs while a turn is in flight, while any dispatch is outstanding, on a worker, or in headless `run`. The dispatch guard is a stand-in: without per-endpoint capacity accounting the pre-warm cannot tell whether a worker already occupies the server it would warm, so it stands down for all worker traffic. The round already claims one endpoint slot for as long as its request is out and releases it in a `finally`, through the `registerEndpointSlot` seam the chat loop wires from the endpoint-capacity registry, so capacity counts a pre-warm the same way it counts the orchestrator's streaming turn.
 
-Pressing Enter lets go of an in-flight pre-warm at the keystroke, before the admission gate. Whether it also aborts the HTTP request is gated on what the backend does with a cancelled one, and the measured backend does nothing. On the operator's llama.cpp router (build `b226-2115b73d8`, Qwen3.8-27B, `--parallel 1`), aborting 1.5 s into a 47,620-token prefill did not cancel the server's work: the server finished prefilling, so the prefix did survive the abort and the next request read 47,596 of 47,620 tokens from cache with `prompt_ms 927`, but that request also waited 89.5 s of wall clock for the abandoned one to leave the single slot. Letting the pre-warm complete instead cost 89.3 s plus a 1.3 s turn, the same wall clock. The abort therefore frees no slot and saves no time on this backend; all it does is discard the usage and timings of prefill the server performed. So a submit detaches the round instead: Clio stops calling it the current pre-warm, never waits on it, withholds its `/context` line because it no longer describes the prefix the next turn will send, and still records what it cost. `ABORT_ROUND_ON_SUBMIT` in `src/interactive/turn-prewarm.ts` carries the measurement and flips the behavior for a backend that honors cancellation.
+Pressing Enter lets go of an in-flight pre-warm at the keystroke, before the admission gate. Whether it also aborts the HTTP request is gated on what the backend does with a cancelled one, and the backend used for the original experiment did nothing. On an earlier single-slot llama.cpp deployment (build `b226-2115b73d8`, Qwen3.8-27B, `--parallel 1`), aborting 1.5 s into a 47,620-token prefill did not cancel the server's work: the server finished prefilling, so the prefix did survive the abort and the next request read 47,596 of 47,620 tokens from cache with `prompt_ms 927`, but that request also waited 89.5 s of wall clock for the abandoned one to leave the single slot. Letting the pre-warm complete instead cost 89.3 s plus a 1.3 s turn, the same wall clock. The abort therefore freed no slot and saved no time on that backend; all it did was discard the usage and timings of prefill the server performed. The current operator topology is different: `mini` is a llama.cpp router at `192.168.86.141:8080` serving `ornith1.5-35b-moe` with four parallel slots and 262,144 context tokens per slot, while `dynamo` is LM Studio at `192.168.86.143:1234` serving `qwen3.8-27b-dynamo` for chat. The cancellation result must be remeasured before it is generalized to either deployment. A submit currently detaches the round: Clio stops calling it the current pre-warm, never waits on it, withholds its `/context` line because it no longer describes the prefix the next turn will send, and still records what it cost. `ABORT_ROUND_ON_SUBMIT` in `src/interactive/turn-prewarm.ts` carries the historical measurement and flips the behavior for a backend that honors cancellation.
 
 Each round appends one `prewarm` custom ledger entry carrying its trigger, the backend prompt tokens, `timing`, and `promptCache`. The entry is never rendered and never becomes a model message, so it contributes zero tokens to the context estimate. `/context` shows `prewarmed: N tokens in X ms` until the next settled run answers the question it asked. `prewarm` is never an expected-cold reason: a pre-warm is the opposite of a disturbance. Its provider usage is real spend and is reported to `/cost` and `clio-coder usage report` under its own row, the way a `/btw` side question is.
 
@@ -150,12 +150,8 @@ Each round appends one `prewarm` custom ledger entry carrying its trigger, the b
 The public settings use one compaction threshold plus a non-destructive working-set stage:
 
 ```yaml
-compaction:
-  auto: true
-  threshold: 0.8
-  excludeLastTurns: 6
-  # model: provider/summary-model-id
-  # systemPrompt: ~/.config/clio-coder/prompts/compaction.md
+chat:
+  prewarm: true
 
 context:
   workingSet:
@@ -164,12 +160,14 @@ context:
     target: 0.6
     protectLastTurns: 6
     minEvictableTokens: 200
-
-prewarm:
-  enabled: true
+  compaction:
+    auto: true
+    threshold: 0.8
+    # model: provider/summary-model-id
+    # systemPrompt: ~/.config/clio-coder/prompts/compaction.md
 ```
 
-`compaction.auto` controls the pre-request trigger. Manual `/context compact` still runs when `auto` is false. `compaction.model` optionally selects a dedicated summarization model, and `compaction.systemPrompt` optionally points at a prompt override file. `compaction.excludeLastTurns` only governs the temporary legacy mask path; working-set protection uses `context.workingSet.protectLastTurns`.
+`context.compaction.auto` controls the pre-request trigger. Manual `/context compact` still runs when `auto` is false. `context.compaction.model` optionally selects a dedicated summarization model, and `context.compaction.systemPrompt` optionally points at a prompt override file. The retired `compaction.excludeLastTurns` key is not part of settings v2. The temporary legacy mask uses its compiled six-turn fallback, while working-set protection uses `context.workingSet.protectLastTurns`.
 
 | Key | Default | Accepted | Meaning |
 | --- | --- | --- | --- |
@@ -276,6 +274,10 @@ reads only the changed indexable files for path-based updates, replaces their fi
 deleted records, and rebuilds edges from the merged import set. Non-indexable
 paths are no-ops.
 
+### Architecture seed
+
+`clio-coder context map` derives an archify architecture specification from the structural index with no model call and writes it to `.clio-coder/artifacts/maps/<repo>.architecture.json` (or `--out <path>`). The seed guarantees that every component is a real directory area of the index under the wiki plan's area-depth rule, capped at twelve by file count plus at most three external packages; that every connection is an import edge the index recorded, collapsed area to area and labeled with its count; and that `meta.repository` appears only when the origin remote is a GitHub URL and `HEAD` is a full revision. Only in that case do components carry `sources`, each naming an indexed file and its first declared symbol's line, because archify accepts source citations only against a pinned revision. Component IDs remain unique across internal and external names, connection IDs are unique, and matching directory/package names retain separate import destinations and counts. Placement is layered by import direction with explicit routes for archify's standard profile; composition warnings may still require operator edits. It refuses, naming `clio-coder context index`, when no index exists. Clio never renders the seed: the archify skill validates and delivers it. When the seed carries pinned repository evidence, pass `--repo-root .` to re-verify every cited path against the working tree; omit that option for an unpinned seed.
+
 ### Markdown Wiki & `code_nav` Resolution
 
 The wiki lives under `.clio-coder/wiki/` as a nested tree and is written by the
@@ -300,11 +302,13 @@ owns each entry's status and rewrites the file after every page, so a run that
 ends early records exactly which pages are still owed. Staging survives such a
 run and the next one resumes from it.
 
-Every page opens with front matter carrying `title`, `summary`, `sources`,
-`symbols`, `tests`, `invariants`, and `validate`. That is the retrieval layer:
-`quickstart.md`, every directory `index.md`, and the task-routing table are
-generated from it after each run, so navigation cannot drift or miss a page and
-no writer has to remember to update it.
+Every page opens with repaired front matter. Its metadata model has `title`,
+`summary`, `sources`, `symbols`, `tests`, `invariants`, and `validate`, but the
+serializer always writes only `title`, adds `summary` when non-empty, and omits
+empty list fields. That metadata is the retrieval layer: `quickstart.md`, every
+directory `index.md`, and the task-routing table are generated from the repaired
+values after each run, so navigation cannot drift or miss a page and no writer
+has to remember to update it.
 
 Assembly repairs rather than rejects. A missing H1, absent or malformed front
 matter, a dangling `sources` entry, a link to a page that was never written, and
@@ -372,5 +376,5 @@ version, project language, file/config/symbol/edge counts, language and role
 counts, top areas, entry points, key symbols, and dependency samples. The
 welcome dashboard shows module count, wiki page count and freshness, and a
 small entry-point excerpt from the same digest. Agents query the structural
-layer through the read-only `code_nav` tool. See [tool-usage.md](tool-usage.md)
+layer through the read-only `code_nav` tool. See [tool-usage.md](../guide/tool-usage.md)
 for the full mode reference.

package/docs/{context-working-set.md → architecture/context-working-set.md}

@@ -1,11 +1,14 @@
 # Working Set
 
-The working set is the part of the session ledger the model actually receives on the next request. When context pressure crosses `compaction.threshold`, Clio narrows that view before it considers summarizing anything: selected tool-result bodies and closed-turn thinking blocks stop being replayed, and a one-line marker takes each body's place. Nothing is deleted. The ledger keeps every byte the tools produced, the transcript keeps showing them, and the model can ask for any evicted body back by ref.
+> **Visual blueprint:** The source checkout includes the complete
+> [Working Set visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/context_working_set_blueprint.html).
+
+The working set is the part of the session ledger the model actually receives on the next request. When context pressure crosses `context.compaction.threshold`, Clio narrows that view before it considers summarizing anything: selected tool-result bodies and closed-turn thinking blocks stop being replayed, and a one-line marker takes each body's place. Nothing is deleted. The ledger keeps every byte the tools produced, the transcript keeps showing them, and the model can ask for any evicted body back by ref.
 
 Source of truth is `src/domains/context/working-set/` (`contract.ts`, `fold.ts`, `project.ts`, `marker.ts`, `protect.ts`, `engine.ts`, `recall.ts`, `policies/`), the ledger records in `src/domains/session/entries.ts`, and the compaction stage in `src/interactive/turn-context.ts` (`runAutoCompact`).
 
 > [!WARNING]
-> This is an experimental community alpha surface. The default policy is `structural-v1`; `age-horizon` reproduces the selection Clio made before this layer existed and stays available.
+> This is an experimental community alpha surface. The default policy is `structural-v1`; `age-horizon` preserves the old age-based selection except for the current low-yield token floor and stays available.
 
 ## Vocabulary
 
@@ -109,7 +112,7 @@ Rule order is the policy. Each rung emits candidates newest-first, every candida
 
 Rungs 1 through 5 are unconditional: redundant content is free to drop, whatever the pressure. Rung 6 is the only one that looks at token counts, and it stops the moment the projected size reaches `context.workingSet.target × contextWindow`. Newest-first within a rung is a cost decision: evicting the youngest safe unit keeps the cold region after the eviction point small, so the turn that pays for the event pays least.
 
-The long-trace sweep found that targets 0.4 and an exhaustive rung 6 produced identical results because the usable candidate pool ran out first. Relative to the 0.6 default, 0.4 reduced cold-prefix tokens by 2.8% at 64k and 7.3% at 128k, did not reduce summaries, and lowered retention covered by 0.00072 at 128k. The default therefore remains 0.6. The replay README records the full grid and the numeric reopening rule.
+A historical local long-trace sweep found that targets 0.4 and an exhaustive rung 6 produced identical results because the usable candidate pool ran out first. Relative to the 0.6 default, 0.4 reduced cold-prefix tokens by 2.8% at 64k and 7.3% at 128k, did not reduce summaries, and lowered retention covered by 0.00072 at 128k. The default therefore remained 0.6. The generated grid and reopening calculation were local artifacts and are not versioned in this repository; use the replay commands in [Commands and Modes](../guide/commands-and-modes.md#working-set-replay) to measure the current tree.
 
 The facts the rungs read come from `path-index.ts`, one deterministic pass over the active-path entries producing one observation per tool result that names a path: which file, which line range, which paths a listing surfaced, whether the call failed, and where in the turn sequence it sits. Tools that observe no path (dispatch, web fetch, tasks, ask user, context) produce no observation. There are no content fingerprints.
 
@@ -117,13 +120,13 @@ The facts the rungs read come from `path-index.ts`, one deterministic pass over
 
 Recall is explicit and by ref. There is no auto-readmission: the marker tells the model exactly which call brings the body back, and the model decides.
 
-`resolveRecall(entries, view, ref, activeLeafTurnId)` resolves a ref against the fold at the live leaf and returns the original body byte-exact, read with the same field precedence the projection would have used. It fails in three typed ways, and each message names the nearest valid ref when one exists:
+`resolveRecall(entries, view, ref, activeLeafTurnId)` resolves a ref against the fold at the live leaf and returns the original body byte-exact, read with the same field precedence the projection would have used. It fails in three typed ways:
 
 - `invalid_ref` when the ref is empty or carries whitespace.
 - `not_on_active_path` when the session has no such turn on this branch, which includes a ref from a branch `/tree` abandoned.
 - `not_evicted` when the unit is still in context. An assistant turn reports separately that thinking is not recallable.
 
-Both messages end with the refs that can be recalled on the active path (tool results only, up to eight, then a count), because a failed recall is usually a mistyped ref and the listing is what the next call needs.
+The `not_on_active_path` and `not_evicted` messages end with the refs that can be recalled on the active path (tool results only, up to eight, then a count). `invalid_ref` reports only the malformed value. Clio deliberately lists valid refs instead of guessing a nearest ref, because similar time-ordered identifiers can name unrelated results.
 
 An LLM summary also preserves recall discovery across its cut. When an evicted tool result falls before `firstKeptTurnId`, the generated checkpoint carries a `<recallable-refs>` block with the same `ref (tool path)` rows used by recall failures, bounded to eight rows plus a remaining count. Results that stay after the cut keep their ordinary markers and are not repeated in the block.
 
@@ -131,7 +134,7 @@ An LLM summary also preserves recall discovery across its cut. When an evicted t
 
 That also makes recall the churn signal. `churn = recalls / itemsEvicted` over the active path. A high churn number means the policy keeps evicting content the session still needs, which is a reason to change the policy rather than to raise the threshold.
 
-The procedural replay does not synthesize churn from path reuse. Its reference graph maps each earlier observation to every later reread or discovery of the same path, while a real `contextRecall` is an explicit model choice of one ref. A later reread already returns current content at the tail, so also injecting the old body would duplicate data and misread stale or superseded observations as recall demand. Replay reports `recallTokens` as a one-time demand bound per evicted item and waits for explicit `contextRecall` records before reporting recall count, churn, or tail growth. The graph-density measurements and reopening condition are in the replay README.
+The procedural replay does not synthesize churn from path reuse. Its reference graph maps each earlier observation to every later reread or discovery of the same path, while a real `contextRecall` is an explicit model choice of one ref. A later reread already returns current content at the tail, so also injecting the old body would duplicate data and misread stale or superseded observations as recall demand. Replay reports `recallTokens` as a one-time demand bound per evicted item and waits for explicit `contextRecall` records before reporting recall count, churn, or tail growth. Graph-density measurements and reopening calculations are generated local artifacts rather than a versioned replay README.
 
 An offloaded result returns its pointer, never the file. The model gets the same `full: <path>` promise the original tool result ended with and reads it with `read` when it wants it.
 
@@ -164,7 +167,7 @@ context:
 | `context.workingSet.protectLastTurns` | `6` | integer ≥ 1 | Recent turns whose observations and thinking are never evicted. |
 | `context.workingSet.minEvictableTokens` | `200` | integer ≥ 0 | Results below this body estimate are never evicted. The default protects low-yield bodies; marker break-even is enforced separately. |
 
-`compaction.excludeLastTurns` governs only the temporary legacy mask path; working-set protection uses `protectLastTurns`. Settings validation is strict, so an unknown key under this block fails startup with its exact path.
+The retired `compaction.excludeLastTurns` key is not accepted by settings v2. The temporary legacy mask uses a compiled six-turn fallback; working-set protection uses `context.workingSet.protectLastTurns`. Settings validation is strict, so an unknown key under this block fails startup with its exact path.
 
 `CLIO_CODER_LEGACY_MASK=1` restores the destructive stale-observation stage for one release as a compatibility escape hatch. It rewrites the ledger, and it is removed in the next release.
 
@@ -181,14 +184,14 @@ context:
 These are tracked follow-ups, not available behavior:
 
 - **Auto-readmission.** Nothing brings an evicted body back on its own. There are no path fingerprints and no registry of what the model is likely to need next.
-- **Cost model and deferred scheduling.** Pressure is the only trigger, and it is `compaction.threshold`, not `target`. The replay tables price every applied event by the cold prefix it re-prefills (about 29k tokens per event at a 64k budget), and batching from the threshold down to the target is what keeps one event per cycle; a trigger at the target would make every turn above 60% with one newly redundant read an event of its own, and no row in the sweep shows fewer summaries in return. There is no break-even horizon, no deferred eviction plan, and no piggybacking beyond the fact that the working-set stage already runs first inside `runAutoCompact`.
+- **Cost model and deferred scheduling.** Pressure is the only trigger, and it is `context.compaction.threshold`, not `target`. Historical local replay tables priced every applied event by the cold prefix it re-prefilled (about 29k tokens per event at a 64k budget), and batching from the threshold down to the target kept one event per cycle; a trigger at the target would make every turn above 60% with one newly redundant read an event of its own. Those tables are not versioned benchmark results. There is no break-even horizon, no deferred eviction plan, and no piggybacking beyond the fact that the working-set stage already runs first inside `runAutoCompact`.
 - **Intra-turn eviction.** Eviction runs before a request is sent. A single turn whose tool results overflow the window is handled by the observation envelope's caps and by summary compaction, not by this layer.
 - **Worker runtimes.** Dispatched workers replay their own ledgers without the working-set stage.
 - **Digests.** A marker carries tool, size, and a first-line preview. The generated summaries from #165 are not embedded in it.
 
 ## See also
 
-- `clio-coder context replay --sessions <path>...` replays Clio ledgers, and `--synthetic <ids>` replays the seeded procedural corpora, through the same fold, projection, and policy code with `none`, `random`, and `oracle` controls; `clio-coder context working-set --session <id|path>` prints one session's fold and path index. Both are described under [Working-set replay](commands-and-modes.md#working-set-replay). Generated replay tables are local artifacts rather than versioned benchmark results.
+- `clio-coder context replay --sessions <path>...` replays Clio ledgers, and `--synthetic <ids>` replays the seeded procedural corpora, through the same fold, projection, and policy code with `none`, `random`, and `oracle` controls; `clio-coder context working-set --session <id|path>` prints one session's fold and path index. Both are described under [Working-set replay](../guide/commands-and-modes.md#working-set-replay). Generated replay tables are local artifacts rather than versioned benchmark results.
 - [context-engine.md](context-engine.md) for context window resolution, token accounting, and how this stage sits ahead of summary compaction.
 - [session-lifecycle.md](session-lifecycle.md) for the ledger format, active-path lineage, and branching.
-- [glossary.md](glossary.md) for the one-line definitions of these terms.
+- [glossary.md](../guide/glossary.md) for the one-line definitions of these terms.

package/docs/{dispatch-architecture-rationale.md → architecture/dispatch-architecture-rationale.md}

@@ -1,12 +1,15 @@
 # Dispatch Architecture Rationale
 
+> **Visual blueprint:** The source checkout includes the complete
+> [Dispatch Architecture Rationale visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/dispatch_rationale_blueprint.html).
+
 Why `src/domains/dispatch/` is one domain, why one import out of it looks
 irregular and is allowed to, and why the repository has no barrel-only import
 convention. No code moved as a result of this document. It exists so that a
 later split is argued from invariants rather than from file counts.
 
-Counts verified against the current tree: 65 TypeScript files in
-`src/domains/dispatch/`, a 137-line barrel at `src/domains/dispatch/index.ts`,
+Counts verified against the current tree: 85 TypeScript files in
+`src/domains/dispatch/`, a 199-line barrel at `src/domains/dispatch/index.ts`,
 and one dispatch → eval import.
 
 ---
@@ -28,7 +31,7 @@ split would use. They cross them.
 | Write-boundary attribution is per scheduling *window*, so the compiler refuses a wave with two writers | scheduling, write boundaries, plan compilation | `execution-plan.ts`, `write-boundary.ts` |
 | A loop's later nodes are `unneeded`, decided by the scheduler, not the plan | plan compilation, scheduling, receipts | `fleet-plan.ts`, `execution-scheduler.ts` |
 | Staleness revalidation re-runs a verification a later workspace step invalidated | scheduling, plan compilation, code steps | `execution-scheduler.ts` |
-| Receipt integrity v16 seals normalized routing intent | routing, receipts | `receipt-integrity.ts`, `routing-intent.ts` |
+| Receipt integrity v20 seals normalized routing intent | routing, receipts | `receipt-integrity.ts`, `routing-intent.ts` |
 
 The write-boundary and loop rows are the sharpest. Both are properties of a
 *wave*, which is a scheduling concept computed by the plan compiler and enforced
@@ -80,7 +83,7 @@ outward, because that is the one seam the invariants above actually respect.
 `../eval/artifacts/store.js`. The eval barrel does not export it. This is the
 only dispatch → eval import in the domain.
 
-This is coupling worth recording, not a violation. It breaks none of the five
+This is coupling worth recording, not a violation. It breaks none of the six
 enforced boundary rules, and the direction is defensible: the routing quality
 reducer treats an eval artifact as evidence, so it must parse one, and
 `parseEvalArtifactV4` is the strict fail-closed parser rather than a convenience
@@ -104,10 +107,10 @@ The evidence that decides it:
 
 - Measured across `src/domains/**`, counting an import as cross-domain when the
   importing file and the resolved target sit in different `src/domains/<name>`
-  directories: **110** cross-domain subpath imports against **29** cross-domain
-  barrel imports. Direct subpath import is the majority pattern by roughly four
+  directories: **228** cross-domain subpath imports against **41** cross-domain
+  barrel imports. Direct subpath import is the majority pattern by roughly six
   to one, not an exception to a rule.
-- All five enforced boundary rules
+- All six enforced boundary rules
   (`tests/boundaries/check-boundaries.ts`) constrain dependency **direction**:
   who may depend on whom. Not one constrains import **form**. There is no rule
   to be half-consistent with.
@@ -116,11 +119,11 @@ The evidence that decides it:
   it. A barrel-only rule would have to widen the agents barrel for no reason but
   import style.
 
-A barrel-only sixth rule would require widening many barrels to re-export
+A barrel-only seventh rule would require widening many barrels to re-export
 symbols currently reached directly. Every one of those is a public-surface
 addition justified by nothing but import style, and it would rewrite every
 affected import site for no behavioral gain. A boundary rule should protect an
 invariant. "Always import through the barrel" protects a preference.
 
-What is *not* permitted is anything the five direction rules forbid, and those
+What is *not* permitted is anything the six direction rules forbid, and those
 stay enforced by the boundary checker that `npm run lint` runs.

package/docs/{dispatch-typed-intent.md → architecture/dispatch-typed-intent.md}

@@ -1,5 +1,8 @@
 # Typed Dispatch Intent: Migration and Refusal Policy
 
+> **Visual blueprint:** The source checkout includes the complete
+> [Typed Dispatch Intent: Migration and Refusal Policy visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/dispatch_typed_intent_blueprint.html).
+
 Typed dispatch intent is the structured declaration of what a dispatched worker
 may read, may write, is expected to produce, and must verify. It replaces the
 practice of reconstructing that answer from optional `writeRoots` plus path-like
@@ -11,8 +14,8 @@ omitted, partial, versioned differently, or contradictory, lists the stable
 reason codes an operator or integrator can branch on, and states the measurable
 condition under which the legacy inference fallback may be proposed for removal.
 
-Related pages: [tool-usage.md](tool-usage.md) for the `dispatch` tool arguments,
-[fleet-dispatch.md](fleet-dispatch.md) for fleet contracts,
+Related pages: [tool-usage.md](../guide/tool-usage.md) for the `dispatch` tool arguments,
+[fleet-dispatch.md](../guide/fleet-dispatch.md) for fleet contracts,
 [artifact-versions.md](artifact-versions.md) for the serialization registry, and
 [safety-model.md](safety-model.md) for how a resolved write boundary is enforced.
 
@@ -25,21 +28,30 @@ Related pages: [tool-usage.md](tool-usage.md) for the `dispatch` tool arguments,
   "intent": {
     "read_roots":     ["src/domains/dispatch/"],
     "write_roots":    ["src/domains/dispatch/", "tests/contracts/"],
-    "relevant_paths": ["docs/dispatch-typed-intent.md"],
+    "relevant_paths": ["docs/architecture/dispatch-typed-intent.md"],
     "expected_outputs": ["src/domains/dispatch/intent-compatibility.ts"],
     "verification":   [{ "check": "typecheck" }, { "check": "lint", "timeout_ms": 60000 }]
   }
 }
 ```
 
-Every path is a repository-relative POSIX path under the boundary grammar in
-`src/core/path-boundary.ts`. A trailing `/` means the subtree; no trailing `/`
-means that exact file. Absolute paths, `..`, `.` segments, backslashes, and
-globs are refused rather than interpreted. Each list is normalized,
-deduplicated, and sorted by code point, holds at most 32 entries, and each entry
-is at most 512 UTF-8 bytes. `verification` holds at most 8 entries and every
+The three scope fields, `read_roots`, `write_roots`, and `relevant_paths`, use
+the repository-relative POSIX boundary grammar in `src/core/path-boundary.ts`.
+A trailing `/` means the subtree; no trailing `/` means that exact file.
+Absolute paths, `..` segments, interior `.` segments, backslashes, and globs
+are refused in those fields. An entry that is exactly `.` or `./` is accepted
+as the repository root and normalizes out of the list. Expected outputs use a
+separate normalizer: it rejects absolute paths, backslashes, root escapes, and
+an empty normalized path, but it normalizes interior `.` and repeated `/`
+segments and does not interpret or reject glob characters. Each list is
+normalized, deduplicated, and sorted by
+code point, holds at most 32 entries, and each entry is at most 512 UTF-8 bytes.
+`verification` holds at most 8 entries and every
 `check` is a declared id resolved from package scripts or
-`.clio-coder/verifiers.yaml`, never a shell command.
+`.clio-coder/verifiers.yaml`, never a shell command. The one exception is
+`{ "check": "none" }`, which models write to mean "no verification"; it
+normalizes to an empty list instead of costing a refused round unless the
+workspace actually declares a verifier whose id is `none`.
 
 Normalization is in `src/domains/dispatch/intent.ts`. The normalized object
 carries `version: 2` and a `pathProvenance` array binding every policy-bearing
@@ -56,7 +68,7 @@ Each rule resolves to exactly one of three decisions.
 | Decision | Meaning | Where it surfaces |
 | :--- | :--- | :--- |
 | **accept** | The request is unambiguous. | Nothing is reported. |
-| **warn** | The request is compatible, but its policy-bearing scope rests on something weaker than a declaration. The dispatch runs with the authority it would have had anyway. | The approval artifact renders the full resolved scope before a supervised dispatch runs; `pathScope` is sealed on the receipt. |
+| **warn** | The request is compatible, but the classifier identified a weaker declaration or a scope-replacement tradeoff. The dispatch runs with the authority it would have had anyway. | Current admission publishes the typed-scope replacement warning. Legacy provenance still appears in the approval artifact and sealed `pathScope`; the absent-intent and missing-verification classifier findings are not emitted as standalone warnings. |
 | **refuse** | The request states two incompatible things about authority, or states one this build cannot interpret. | Terminal admission error carrying the reason code. The dispatch never runs. |
 
 The invariant that separates `warn` from `refuse`: **a warning is never the
@@ -67,7 +79,7 @@ touch, the answer is a refusal, never the union of the two.
 
 ### 2.1 Omitted intent
 
-Accepted, with a warning. Policy-bearing scope is resolved by
+Accepted without a standalone runtime warning. Policy-bearing scope is resolved by
 `legacyPathScope()`: legacy `writeRoots` become the write boundary with
 provenance `derived`, and path-like tokens in the task (confidence `medium`) and
 briefing (confidence `low`) become working-context paths with provenance
@@ -77,7 +89,10 @@ Inferred paths select project rules and compile worker context. They never
 become write boundaries and never add a verification requirement. The only path
 into a write boundary without a declaration is the explicit legacy `writeRoots`
 field, which the caller had to set on purpose. This is what makes omission a
-warning rather than a refusal: nothing about it can widen authority.
+compatible rather than a refusal: nothing about it can widen authority. The pure
+compatibility classifier can return `intent_absent_legacy_inference`, but the
+production dispatch path deliberately treats omitted intent as ordinary. The
+approval artifact and receipt provenance remain the operator-visible record.
 
 An absolute or malformed path token in prose is not silently dropped. It throws
 `DispatchPathScopeInferenceError` with code `legacy_scope_path_absolute` or
@@ -90,13 +105,15 @@ Accepted. Every field is independently optional and an omitted list normalizes
 to empty. A declaration is not required to be complete to be authoritative:
 declaring only `write_roots` is a complete statement about write scope.
 
-One partial shape gets a warning. Intent that declares `write_roots` or
+The pure classifier identifies one partial shape as a warning. Intent that declares `write_roots` or
 `expected_outputs` but no `verification` describes work that changes the tree
 with nothing the orchestrator itself runs to prove the change is sound
-(`intent_partial_verification_absent`).
+(`intent_partial_verification_absent`). Current production admission keeps only
+terminal refusals from this classifier, so it does not emit that finding as an
+operator diagnostic.
 
-One partial shape is refused. An `expected_outputs` entry outside every declared
-`write_root` (`intent_outputs_outside_write_roots`) means the write boundary
+One partial shape is refused when both lists are non-empty. An `expected_outputs`
+entry outside every declared `write_root` (`intent_outputs_outside_write_roots`) means the write boundary
 would block exactly the artifact the task is required to produce. Refusing that
 at admission costs a rejected call; accepting it costs a full worker run that
 cannot succeed.
@@ -119,8 +136,9 @@ is the same: restate the fields on a fresh dispatch call.
 
 Refused. Three contradictions are enumerated.
 
-- **Legacy against declared write scope.** `writeRoots` and `intent.write_roots`
-  resolving to different trees is `intent_write_roots_contradiction`. Neither the
+- **Legacy against declared write scope.** When both lists are non-empty,
+  `writeRoots` and `intent.write_roots` resolving to different trees is
+  `intent_write_roots_contradiction`. Neither the
   union nor the legacy field wins; the caller drops `writeRoots` and declares
   once.
 - **Narrowed against enclosing scope.** A per-task intent in a batch, or any
@@ -135,19 +153,20 @@ Refused. Three contradictions are enumerated.
 
 The declared-versus-inferred case is not a contradiction and is not refused.
 When a request declares intent, prose inference stops resolving scope entirely;
-paths mentioned only in prose are reported as omitted through
-`typed_scope_replaced_inferred_paths` and take no part in rule selection or
-authority. Declared always outranks inferred.
+paths mentioned only in prose take no part in rule selection or authority.
+`typed_scope_replaced_inferred_paths` reports the useful subset that looks like
+a source or documentation path, or ends in a directory separator, capped at 12
+entries for the transcript. Declared always outranks inferred.
 
 ---
 
 ## 3. Producer Compatibility Table
 
 Every producer that can reach a worker passes through `validateJobSpec()` in
-`src/domains/dispatch/validation.ts`, which is where the classifier runs. The
-rules above therefore hold for every row below, including the rows that cannot
-declare intent yet: those rows resolve scope by inference and are refused only
-when they state a contradiction.
+`src/domains/dispatch/validation.ts`. When an `intent` property is present, that
+validator runs the classifier and retains its terminal refusals. Requests with
+no intent skip compatibility classification and resolve scope through the legacy
+inference path, whose malformed-path errors remain terminal.
 
 | Dispatch producer | Source | Typed intent | Behavior without declaration | Refuses on |
 | :--- | :--- | :--- | :--- | :--- |
@@ -155,13 +174,13 @@ when they state a contradiction.
 | **`dispatch` tool, batch `tasks[]`** | `src/tools/dispatch-arguments.ts` | Declared per task, shallow-merged over the top-level default | Same as singular, per task | All codes, plus `intent_scope_widening` against the top-level ceiling |
 | **`dispatch` modes parallel / sequential / pipeline / detached** | `src/tools/dispatch-admission.ts` | Inherited unchanged from the task that declared it | Legacy inference | All codes |
 | **`dispatch` mode compete, candidates** | `src/tools/dispatch-admission.ts` | Inherited unchanged from the single base task | Legacy inference | All codes. `verification` is refused for the mode (`verification_unsupported_for_mode`) |
-| **`dispatch` mode compete, judge** | `src/tools/dispatch-admission.ts` | None. The judge is a fresh read-only request | Legacy inference over the judge's own task | All codes |
+| **`dispatch` mode compete, judge** | `src/tools/dispatch-admission.ts` | None. The judge is a fresh read-only request | Legacy inference over the judge's own task | Legacy inference errors only |
 | **`dispatch` mode council, members** | `src/tools/dispatch-admission.ts` | Inherited, narrowed to read-only: declared write roots arrive as read roots | Legacy inference | All codes. `verification` is refused for the mode (`council_verification_unsupported`) |
-| **`dispatch` mode council, synthesis judge** | `src/tools/dispatch-admission.ts` | None. Fresh read-only request | Legacy inference over the judge's own task | All codes |
+| **`dispatch` mode council, synthesis judge** | `src/tools/dispatch-admission.ts` | None. Fresh read-only request | Legacy inference over the judge's own task | Legacy inference errors only |
 | **`dispatch` review gate, builder** | `src/tools/dispatch-admission.ts` | Inherited unchanged | Legacy inference | All codes |
-| **`dispatch` review gate, reviewer** | `src/tools/dispatch-admission.ts` | None on the request. `expected_outputs` and `verification` reach the reviewer as rendered *requirements*, never as evidence | Legacy inference over the reviewer's own task | All codes |
+| **`dispatch` review gate, reviewer** | `src/tools/dispatch-admission.ts` | None on the request. `expected_outputs` and `verification` reach the reviewer as rendered *requirements*, never as evidence | Legacy inference over the reviewer's own task | Legacy inference errors only |
 | **`dispatch` `apply_winner`** | `src/tools/dispatch-admission.ts` | Not applicable. Branch application runs no worker | Not applicable | Branch-shape refusals only |
-| **`from_scout` continuation** | `src/tools/dispatch-scout-admission.ts` | **None today.** The compiled continuation plan carries no intent | Legacy inference per step | Contradiction codes only |
+| **`from_scout` continuation** | `src/tools/dispatch-scout-admission.ts` | **None today.** The compiled continuation plan carries no intent | Legacy inference per step | Legacy inference errors only |
 | **Fleet contract agent step (v4+ `writes:`)** | `src/domains/dispatch/fleet-run.ts` | Declared. The contract's `writes:` compiles to `relevant_paths` | Legacy inference for pre-v4 contracts and readonly steps | All codes |
 | **Fleet contract gate / plan step** | `src/domains/dispatch/fleet-run.ts` | Declared, same path (`writes` is the gate path or the plan step's boundary) | Legacy inference when undeclared | All codes |
 | **Fleet delegation-plan spliced step** | `src/domains/dispatch/fleet-run.ts` | Declared from the validated plan task's `writes` | Legacy inference when the task declares none | All codes |
@@ -169,14 +188,14 @@ when they state a contradiction.
 | **ACP delegation target** | `src/domains/dispatch/extension.ts` | Accepted and carried into the plan, but the external agent runs its own tool surface | Legacy inference | All codes, plus a hard refusal of any resolved `writeRoots` on this transport |
 | **Custom agent recipe** | `src/domains/agents/` | Not a producer. A recipe narrows the tool surface and capability class; it never declares dispatch scope | Not applicable | Not applicable |
 | **Extension-authored `DispatchRequest`** | Any `DispatchContract` consumer | Declared, if the extension builds one through `declaredScopeIntent()` or the normalizer | Legacy inference | All codes |
-| **`clio-coder run --agent`** | `src/cli/run.ts` | **None today** | Legacy inference | Contradiction codes only |
-| **`clio-coder wiki generate`** | `src/cli/wiki-generate.ts` | **None today.** Sets legacy `writeRoots` | Legacy inference plus a derived write boundary | Contradiction codes only |
-| **`clio-coder bootstrap generate`** | `src/cli/bootstrap-generate.ts` | **None today** | Legacy inference | Contradiction codes only |
-| **Interactive slash commands, overlays, watchdog** | `src/interactive/` | **None today** | Legacy inference | Contradiction codes only |
+| **`clio-coder run --agent`** | `src/cli/run.ts` | **None today** | Legacy inference | Legacy inference errors only |
+| **`clio-coder wiki generate`** | `src/cli/wiki-generate.ts` | **None today.** Sets legacy `writeRoots` | Legacy inference plus a derived write boundary | Legacy inference errors only |
+| **`clio-coder bootstrap generate`** | `src/cli/bootstrap-generate.ts` | **None today** | Legacy inference | Legacy inference errors only |
+| **Interactive slash commands, overlays, watchdog** | `src/interactive/` | **None today** | Legacy inference | Legacy inference errors only |
 
-"All codes" means every code in section 5 that can apply to the row's shape.
-"Contradiction codes only" means the row cannot declare intent, so only the
-`intent_absent_legacy_inference` warning and the legacy inference errors apply.
+"All codes" means every terminal code in section 5 that can apply to the row's
+shape. "Legacy inference errors only" means the row cannot declare intent, so
+only malformed or absolute prose-path inference can refuse it.
 
 ---
 
@@ -208,8 +227,8 @@ filesystem, no clock, no environment, and no package layout. The supported
 version set is a compiled-in constant, not a lookup. A source checkout, a global
 npm install, and a bundled `dist/` therefore classify identical input
 identically, which is what makes the version policy verifiable rather than
-environmental. `tests/contracts/dispatch-intent-compatibility.test.ts` asserts it
-by classifying the same input from two different working directories.
+environmental. `tests/contracts/dispatch-admission.test.ts` covers the current
+normalization and compatibility boundary.
 
 The one input that is legitimately environmental is the *verification catalog*:
 `check` ids resolve from the project's `package.json` scripts and
@@ -221,16 +240,18 @@ Clio installation. An undeclared id fails closed with
 
 ## 5. Reason Codes
 
-Every code is stable and appears as the prefix of its diagnostic, in the form
-`<code>: <what is wrong and what to do about it>`.
+Active refusal codes are stable and appear as the prefix of their diagnostic, in
+the form `<code>: <what is wrong and what to do about it>`. The table also marks
+classifier-only findings and compatibility identifiers that have no current
+producer.
 
 | Code | Decision | Meaning |
 | :--- | :--- | :--- |
-| `intent_absent_legacy_inference` | warn | No typed intent; scope came from legacy inference. |
-| `intent_partial_verification_absent` | warn | Declares tree-changing work with no verification requirement. |
+| `intent_absent_legacy_inference` | classifier-only warn | No typed intent; scope came from legacy inference. Production admission does not emit it. |
+| `intent_partial_verification_absent` | classifier-only warn | Declares tree-changing work with no verification requirement. Production admission does not emit it. |
 | `typed_scope_replaced_inferred_paths` | warn | Typed intent was declared, so prose-only paths took no part in scope. |
-| `legacy_scope_inferred` | warn | Legacy dispatch resolved policy-bearing scope with no declaration. |
-| `legacy_scope_empty` | warn | Legacy dispatch inferred no policy-bearing path at all. |
+| `legacy_scope_inferred` | retained compatibility id | Accepted by the event projection for older producers; no current source emits it. |
+| `legacy_scope_empty` | retained compatibility id | Accepted by the event projection for older producers; no current source emits it. |
 | `intent_version_unsupported` | refuse | `intent.version` names a version this build does not speak. |
 | `intent_malformed` | refuse | Not a normalized intent for a reason other than its version. |
 | `intent_write_roots_contradiction` | refuse | Legacy `writeRoots` and `intent.write_roots` name different trees. |
@@ -253,7 +274,8 @@ Every code is stable and appears as the prefix of its diagnostic, in the form
 ## 6. Examples
 
 Typed intent is the default for every example below. A call that omits it still
-works; it just resolves its scope from weaker evidence.
+works without a dedicated warning; it resolves its scope from weaker evidence
+recorded in the approval artifact and receipt.
 
 ### 6.1 Main-agent call, single writer