@iowarp/clio-coder 0.4.0 → 0.4.2

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

@@ -1,6 +1,11 @@
 # Troubleshooting & Error Remediation
 
-This guide provides concrete, actionable remediation procedures for operational errors, permission denials, target connection failures, and system diagnostics in Clio Coder `v0.4.0`.
+> **Visual blueprint:** The source checkout includes the complete
+> [Troubleshooting & Error Remediation visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/troubleshooting_blueprint.html).
+
+This guide provides concrete, actionable remediation procedures for
+operational errors, permission denials, target connection failures, and system
+diagnostics in the current source tree.
 
 ---
 
@@ -10,11 +15,11 @@ This guide provides concrete, actionable remediation procedures for operational
 | :--- | :--- | :--- |
 | `clio-coder run cannot confirm permission requests; rerun interactively to approve this action.` | A tool call required manual permission confirmation during a non-interactive headless `clio-coder run` execution. | Run the command interactively in the TUI (`clio`) to grant one-shot approval, adjust the workspace policy in `.clio-coder/safety.yaml`, or run with `--autonomy full-auto` if safe. |
 | `no trace database yet at <path>` | The trace mirror database has not been initialized because no interactive sessions or dispatches have executed yet. | Execute a turn or dispatch a task. In SQLite trace commands, this notice is informational (exit code `0`). |
-| `error: trace database not found: <path>` | An explicit `--db <path>` flag was provided pointing to a nonexistent database file. | Verify the database path or omit `--db` to use the default state directory database (`<stateDir>/trace.sqlite`). |
+| `trace database not found: <path>` | An explicit `--db <path>` flag was provided pointing to a nonexistent database file. | Verify the database path or omit `--db` to use the default state directory database (`<stateDir>/trace.sqlite`); the next line prints that default path. |
 | `no local skill marketplace catalog or index configured` | No catalog directory (`CLIO_CODER_SKILL_CATALOG_DIR`, a `skills/` folder in the working tree, or the installed package's own `skills/` catalog) and no JSON index (`CLIO_CODER_SKILL_MARKETPLACE_INDEX`, `<configDir>/skill-marketplace.json`, or the package's `skills/skill-marketplace.json`) was found. On an npm install this means the package is incomplete; check `clio-coder doctor`. | Point `CLIO_CODER_SKILL_CATALOG_DIR` at a `skills/` catalog or `CLIO_CODER_SKILL_MARKETPLACE_INDEX` at a valid `skill-marketplace.json`, or install a skill directly via `clio-coder skills install <path\|github-url>`. |
 | `<arg> is a global option and must come before the subcommand: clio-coder <usage> <command> ...` | A global CLI option (such as `--api-key`, `--no-context-files`, or `-nc`) was placed after the subcommand name. Directory roots are configured via `CLIO_CODER_*_DIR` environment variables. | Move the flag before the subcommand name (e.g. `clio-coder --api-key <key> run ...` instead of `clio-coder run --api-key <key> ...`). |
 | `target <id> is not registered` | The designated target ID does not exist in `settings.yaml`. | Run `clio-coder targets` to view available targets, or configure a new target using `clio-coder targets add`. |
-| `budget: ceiling must be >= 0 (got <val>)` | A negative session cost ceiling reached the scheduling budget (`src/domains/scheduling/budget.ts`). | Set a non-negative `budget.sessionCeilingUsd` in `settings.yaml`, or edit Session ceiling (USD) in Settings → Budget. |
+| `budget: ceiling must be >= 0 (got <val>)` | A negative session cost ceiling reached the scheduling budget (`src/domains/scheduling/budget.ts`). | Set a non-negative `safety.limits.sessionCostUsd` in `settings.yaml`, or edit Session ceiling (USD) in Settings → Budget. |
 | `worker_final_output_missing` | A worker process completed execution with exit code 0 but failed to emit a valid final answer before the stream closed. | Check the worker event log using `clio-coder trace tail <runId>` or inspect the receipt via `monitor(run_id="<id>", mode="receipt")`. |
 | `vram_capacity_fit_failure` | The model could not be scheduled or loaded due to insufficient GPU VRAM capacity on the target node. | Select a smaller quantized model variant, reduce context window size, or route to an alternative fleet node with greater memory capacity. |
 | `loop_guard_tools_disabled_exhausted` | The loop detector identified repeated unproductive tool calls with identical arguments and disabled tool execution. | Inspect model prompts and provide clearer intermediate steering instructions to prevent recursive tool loops. |
@@ -44,7 +49,7 @@ Those are the server's own numbers, not Clio's estimate. `server does not report
 last cold turn: working-set eviction (expected)
 ```
 
-The eight causes and what stamps each one are in [context-engine.md](context-engine.md#cache-divergence-honesty). `background_memory` renders in prose as `last cold turn: background memory step (expected)`.
+The eight causes and what stamps each one are in [context-engine.md](../architecture/context-engine.md#cache-divergence-honesty). `background_memory` renders in prose as `last cold turn: background memory step (expected)`.
 
 **3. Confirm it in the ledger.** The reasons are durable, so a finished session answers the same question without the TUI. Open `current.jsonl` under the session directory `clio-coder paths` reports and read the run's first assistant entry:
 
@@ -72,7 +77,7 @@ The eight causes and what stamps each one are in [context-engine.md](context-eng
 - **The model was swapped.** A router serving one model at a time reloads on a residency change, and everything the previous model had cached is gone. This normally does stamp `residency`, but only when the mutation went through Clio.
 - **The prompt moved for a reason Clio did not classify.** Compare the run's `promptHash` and `toolSignature` in `context-snapshots.jsonl` against the previous run's. Equal hashes with a cold backend point at the server; different hashes with no `prompt_recompiled` or `tool_surface_change` stamp is worth an issue.
 
-One case is expected on hybrid architectures and looks like a bug. Qwen3.8 keeps recurrent state that llama.cpp cannot roll back to an arbitrary token, so a change anywhere inside a cached prefix re-prefills from the last context checkpoint rather than from the changed byte. A small edit to old history can therefore cost thousands of tokens of prefill with the prompt hash otherwise stable. The server's checkpoint count and its `--checkpoint-min-step` are the levers; see the `qwen3.8-27b` family's `serving` and `measuredUnder` notes in `src/domains/providers/models/local-models/clio-local-coding-targets.yaml` for the measured figures and the exact argv they were taken under.
+One case is expected on hybrid architectures and looks like a bug. Qwen3.8 keeps recurrent state that llama.cpp cannot roll back to an arbitrary token, so a change anywhere inside a cached prefix re-prefills from the last context checkpoint rather than from the changed byte. A small edit to old history can therefore cost thousands of tokens of prefill with the prompt hash otherwise stable. The server's checkpoint count and its `--checkpoint-min-step` are the levers; see the `qwen3.8-27b` family's `serving` and `measuredUnder` notes in `src/domains/providers/models/local-models/clio-coder-local-coding-targets.yaml` for the measured figures and the exact argv they were taken under.
 
 ---
 

package/docs/{config-knobs-audit.md → history/config-knobs-audit.md}

@@ -1,18 +1,21 @@
 # Config Knobs Audit (Historical Appendix)
 
-> [!TIP]
-> **Interactive Spec Available:** An interactive historical knobs auditor and consolidation resolver is located at [docs/html/config_knobs_audit_blueprint.html](html/config_knobs_audit_blueprint.html) (Version: 0.2.9).
+> **Visual blueprint:** The source checkout includes the complete
+> [Config Knobs Audit (Historical Appendix) visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/config_knobs_audit_blueprint.html).
 
 > [!IMPORTANT]
 > This document is a historical record of the point-in-time configuration knob audit conducted on 2026-07-03.
 > It details the pre-consolidation state of the codebase before the `v0.2.9` release.
-> For the current, active, and authoritative reference of environment variables, please refer to [environment-variables.md](environment-variables.md).
+> For the current, active, and authoritative reference of environment variables, please refer to [environment-variables.md](../guide/environment-variables.md).
+
+> [!NOTE]
+> Pane settings were introduced after this audit and are intentionally absent from its tables. In the current schema, `panes.agents` and `panes.keepFailed` are retired and refused when newly authored; `clio-coder upgrade` removes them from an older settings file before strict validation. See [configuration-and-targets.md](../guide/configuration-and-targets.md) for the active pane keys and their migration behavior.
 
 ---
 
 Point-in-time inventory of every tunable knob outside `settings.yaml`: environment variables, the compiled-in defaults behind them, and the CLI flags that bridge into them. Gathered 2026-07-03 by sweeping `src/` for `process.env` reads and cross-checking `scripts/`, `benchmarks/`, and `docs/`. Purpose: reason about which knobs earn their keep, which belong in `settings.yaml`, and which are dead.
 
-> **Status: findings 1-5 fixed on 2026-07-03.** The tool-call budget vars were renamed (`CLIO_CODER_TURN_TOOL_CALL_BUDGET`, `CLIO_CODER_WORKER_TOOL_CALL_CAP`); guardrail policy moved into a `guardrails:` settings section with env as emergency override (`src/core/guardrails.ts`); the run.ts/print.ts env bridges collapsed into one typed transport (`src/core/run-overrides.ts`, `CLIO_CODER_RUN_OVERRIDES`), retiring `CLIO_CODER_MAX_CONTEXT_TOKENS`, `CLIO_CODER_KV_CACHE_MODE`, and `CLIO_CODER_SAMPLING_OVERRIDES`; the dead `CLIO_CODER_NO_UPDATE_NOTIFIER` setters were deleted; and [environment-variables.md](environment-variables.md) is now the maintained reference. The tables below describe the pre-fix state and are kept for the remaining findings (6-7).
+> **Status: findings 1-5 fixed on 2026-07-03.** Guardrail policy moved into settings, and the transitional guardrail environment overrides were removed on 2026-09-02. The run.ts/print.ts env bridges collapsed into one typed transport (`src/core/run-overrides.ts`, `CLIO_CODER_RUN_OVERRIDES`), retiring `CLIO_CODER_MAX_CONTEXT_TOKENS`, `CLIO_CODER_KV_CACHE_MODE`, and `CLIO_CODER_SAMPLING_OVERRIDES`; the dead `CLIO_CODER_NO_UPDATE_NOTIFIER` setters were deleted; and [environment-variables.md](../guide/environment-variables.md) is now the maintained reference. The tables below preserve the pre-fix state.
 
 ## The pattern, first
 
@@ -29,7 +32,7 @@ Every runtime-tunable value needs both halves; the pair is one knob, not two. Th
 |---|---|---|---|
 | `CLIO_CODER_ORCH_MAX_TOOL_CALLS` | 60 soft, hard = soft + 15 | `src/engine/loop-guard.ts` → `src/entry/orchestrator.ts` | Orchestrator per-turn tool-call budget. Soft crossing blocks further calls this turn; hard ceiling interrupts the turn. |
 | `CLIO_CODER_MAX_TOOL_CALLS` | 50 | `src/engine/loop-guard.ts` → `src/engine/worker-runtime.ts` | Worker lifetime tool-call cap for a dispatched run. Different axis than the orchestrator budget despite the near-identical name. |
-| `CLIO_CODER_MAX_RUNS` | 1000 | `src/domains/dispatch/state.ts` | Dispatch run-ledger retention cap. |
+| `CLIO_CODER_MAX_DISPATCH_RUNS` | 1000 | `src/domains/dispatch/state.ts` | Dispatch run-ledger retention cap. |
 | `CLIO_CODER_MAX_CONTEXT_TOKENS` | unset | `src/domains/providers/runtime-resolution.ts` | Context-window override for local runtimes. Also set internally by `clio-coder run --max-context-tokens` (see §6). |
 | `CLIO_CODER_KV_CACHE_MODE` | unset | retired | KV-cache quantization mode. Also set internally by the former `clio-coder run --kv-cache-mode` path. |
 | `CLIO_CODER_SAMPLING_OVERRIDES` | unset | `src/engine/apis/sampling-overrides.ts` | JSON sampling-parameter override. Set internally by print-mode sampling flags. |
@@ -45,7 +48,7 @@ Every runtime-tunable value needs both halves; the pair is one knob, not two. Th
 | `CLIO_CODER_STATUS_STUCK_MS` | 180000 | `src/interactive/status/watchdog.ts` | Stuck-turn watchdog threshold. |
 | `CLIO_CODER_SHUTDOWN_HOOK_MS` | 500 | `src/core/termination.ts` | Wall-clock budget per shutdown hook. |
 | `CLIO_CODER_FORCE_COMPACT` | off | `src/interactive/chat-loop.ts` | `1` forces compaction on the next turn regardless of threshold. |
-| `CLIO_CODER_TRUST_PROJECT_SKILLS` | off | `src/domains/resources/skills/loader.ts` | `1` trusts project-local skills for execution. |
+| `CLIO_CODER_TRUST_PROJECT_RESOURCES` | off | `src/domains/resources/skills/loader.ts` | `1` trusts project-local compatibility resources for execution. |
 | `CLIO_CODER_ALLOW_EXTERNAL_FULL_ACCESS` | off | `src/engine/claude/subprocess-runtime.ts`, `src/engine/antigravity/subprocess-runtime.ts` | `1` lets full-auto pass through to external CLI runtimes with their own full access. |
 | `CLIO_CODER_SKILL_CATALOG_DIR` | unset | `src/domains/resources/skills/marketplace.ts`, `provenance-pin.ts` | Local skill-catalog directory override. |
 | `CLIO_CODER_SKILL_MARKETPLACE_INDEX` | unset | `src/domains/resources/skills/marketplace.ts` | Marketplace index path override. |
@@ -103,10 +106,10 @@ All default off; all enabled with `1`.
 
 ## Findings and consolidation candidates
 
-1. **Naming: `CLIO_CODER_MAX_TOOL_CALLS` vs `CLIO_CODER_ORCH_MAX_TOOL_CALLS`.** These sound like the same knob but govern different axes (worker lifetime cap vs orchestrator per-turn budget). They were renamed to `CLIO_CODER_WORKER_TOOL_CALL_CAP` and `CLIO_CODER_TURN_TOOL_CALL_BUDGET`.
-2. **Operator policy living in env instead of settings.** The guard budgets, tool byte caps, and `CLIO_CODER_MAX_RUNS` are durable operator policy, the same species as `compaction.threshold` or `budget.sessionCeilingUsd`, which live in `settings.yaml`. These moved to a `guardrails:` settings section, keeping env as an emergency override.
+1. **Naming: `CLIO_CODER_MAX_TOOL_CALLS` vs `CLIO_CODER_ORCH_MAX_TOOL_CALLS`.** These sounded like the same knob but governed different axes. Both transitional names were later removed in favor of the canonical settings paths.
+2. **Operator policy living in env instead of settings.** Guard budgets, tool byte caps, and run retention are durable operator policy. Their canonical version 2 paths now live under `safety.limits` and `fleet`, with no environment precedence layer.
 3. **The env-bridge pattern (§6) is the real implementation bloat.** Set-env / run / restore-env in `run.ts` and `print.ts` was collapsed into `CLIO_CODER_RUN_OVERRIDES`.
-4. **Undocumented knobs.** Many operator knobs were undocumented in v0.2.7. Whatever survived the audit was consolidated into [environment-variables.md](environment-variables.md).
+4. **Undocumented knobs.** Many operator knobs were undocumented in v0.2.7. Whatever survived the audit was consolidated into [environment-variables.md](../guide/environment-variables.md).
 5. **Dead reference.** `CLIO_CODER_NO_UPDATE_NOTIFIER` (§7) was removed.
-6. **Overlap to check: skills trust.** `CLIO_CODER_TRUST_PROJECT_SKILLS` (env) and `skills.trustProjectCompatRoots` (settings) are adjacent trust decisions with different surfaces and different names. They govern different roots today, but one `skills.trust*` settings block with both switches would be easier to reason about.
+6. **Resolved overlap: project resource trust.** `integrations.projectResources.trustProjectImports` is now the only trust-policy surface; the transitional environment override was removed.
 7. **Healthy as-is.** Directory overrides (§2), debug toggles (§3), internal plumbing (§4), and test-only vars (§5) are all conventional env usage and cheap to keep. The hook-budget family is five vars but one subsystem with sane defaults; fold into settings only if hook tuning becomes routine.

package/docs/history/release-cut-checklist.md

@@ -0,0 +1,207 @@
+# v0.4.1 Release-Cut Checklist
+
+> **Visual blueprint:** The source checkout includes the complete
+> [v0.4.1 Release-Cut Checklist visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/release_cut_checklist_blueprint.html).
+
+> [!IMPORTANT]
+> Historical release record. v0.4.1 has been published, and this checklist is
+> retained to explain how that release was cut. It is not the procedure for
+> v0.4.2 or any later release; paths, gates, versions, dates, and authorization
+> state must be re-established from current source before a future cut.
+
+This is the ordered procedure for turning the prepared `v0.4.1` branch into a
+published release. Everything above the **AUTHORIZATION BOUNDARY** is local,
+repeatable, and reversible. Everything below it changes a remote ref, creates a
+release, or publishes an immutable package and therefore requires the
+operator's explicit approval of the exact candidate SHA and commands.
+
+## Part 1: verify the exact candidate
+
+1. Resolve and record the exact candidate SHA. Confirm `package.json` and both
+   version fields in `package-lock.json` are `0.4.1`, and confirm the first
+   version heading in `CHANGELOG.md` is exactly
+   `## 0.4.1 - 2026-09-01`. Work from the branch ref explicitly when a branch
+   and tag share the name: `refs/heads/v0.4.1` is the branch and
+   `refs/tags/v0.4.1` is the tag.
+2. Confirm the tracked worktree is clean. Do not fold unrelated local or
+   ignored release evidence into the candidate.
+3. Install exactly from the lockfile:
+
+   ```sh
+   npm ci --prefer-offline --no-audit --no-fund
+   ```
+
+4. Run the one local release gate:
+
+   ```sh
+   npm run ci:release
+   ```
+
+   `ci:release` runs `ci` and then `scripts/check-release.mjs`. The `ci` script
+   performs typecheck; Biome and repository hygiene; the shipped-skill pin
+   check; the build; the 35-file `node --test` suite; and the trace-viewer
+   tests. The release audit then checks the built launcher and dist contents,
+   version/changelog coherence, required package resources, dependency audit,
+   and tarball size and contents. Run individual subcommands only to diagnose a
+   failure; rerunning each one before `ci:release` does not add coverage.
+5. Confirm the hosted push/PR configuration still has one CI workflow, one
+   Node 22 job, and one release-gate step in `.github/workflows/ci.yml`. There
+   is no repeat/shuffle job, shard matrix, or Node 24 lane.
+   `.github/workflows/release.yml` is a separate tag-only publication workflow;
+   it reruns the same `ci:release` gate on the tagged tree rather than inheriting
+   another workflow's result.
+6. Keep evals outside the gate. The engine under `src/domains/eval/` and the
+   reference suites under `evals/` ship for explicit operator measurements,
+   but neither CI nor `ci:release` runs an eval. When a release-specific model
+   measurement is requested, run it and retain its artifacts separately:
+
+   ```sh
+   node dist/cli/index.js eval run --suite evals/behavioral-model.yaml --target <id> --clio-coder-entry dist/cli/index.js
+   node dist/cli/index.js eval run --suite evals/behavioral-model-negative-control.yaml --target <id> --clio-coder-entry dist/cli/index.js
+   ```
+
+   These runs can inform an operator decision, but they are not CI or release
+   gates. The model-free `evals/behavioral-machinery.yaml` suite is likewise a
+   maintained reference suite, not a checked release baseline.
+7. When a configured target is available, run one real built-binary turn:
+
+   ```sh
+   node dist/cli/index.js run --target <id> --autonomy read-only \
+     "Report the active target and confirm this is a release smoke turn."
+   ```
+
+   Run it with an isolated `CLIO_CODER_HOME` containing only the test target.
+   Record a missing or unauthorized target as a deferred live check; never
+   substitute a model-dependent result for the deterministic gate.
+
+   Then run the same two checks against a copy of your real settings:
+
+   ```sh
+   npm run smoke:real-home -- --target <id>
+   ```
+
+   The script copies `~/.config/clio-coder/settings.yaml` (and
+   `credentials.yaml` when present) into a scratch `CLIO_CODER_HOME`, runs
+   `doctor` and one headless turn there, fails on a doctor crash or
+   deprecation warning, a turn that exits non-zero, a tool policy drift
+   refusal, or a turn with no `agent_end` event, prints doctor's own failing
+   rows for you to read, and deletes the scratch home. The 0.4.2 smoke ran only
+   with isolated homes and missed two bugs a real settings file exposed on
+   first launch: a raised `safety.limits.readBytesPerCall` refusing to boot,
+   and a `clio:` skill metadata key warning.
+8. Inspect the package twice: first with `npm pack --dry-run`, then with a real
+   `npm pack` directed to a temporary directory. Record the filename, integrity,
+   shasum, packed size, and unpacked size. Confirm `dist/`, `src/`, `skills/`,
+   `evals/`, the Markdown guides, package metadata, and required runtime assets
+   are present. Confirm `docs/html/`, `apps/workbench/`, `.superpowers/`,
+   `tests/`, `scripts/`, scratch files, and source maps are absent.
+9. Install that tarball into a clean temporary prefix with an empty
+   `CLIO_CODER_HOME`. Verify `clio-coder --version`, `--help`, an empty-state
+   non-TTY launch, `doctor`, and `uninstall --dry-run` without using
+   developer-local state. The in-suite installed-package smoke already proves
+   a packed install can launch from a foreign working directory; this step
+   inspects the exact final tarball.
+10. Run the interactive release matrix against the clean install. Cover fresh
+    onboarding, v1 settings migration, all seven `/settings` deep links,
+    retired-command tombstones, slash autocomplete, `@` references, public and
+    private bang operators, paste inertness, marketplace promotion, and the
+    opt-in workers dock. Record PASS / FAIL / BLOCKED with concrete evidence.
+    A deterministic behavior failure blocks the cut; a model-choice outcome is
+    reported as model-dependent rather than rewritten into a deterministic
+    claim.
+
+## Part 2: notes and package coherence
+
+11. Confirm the `## 0.4.1 - 2026-09-01` changelog section tells the complete
+    release story in release-body order and contains no `Unreleased` section
+    above it. The tag workflow extracts this section verbatim for the GitHub
+    Release.
+12. Confirm README quickstart and source-install commands name real commands,
+    current paths, and `v0.4.1`. Confirm current eval documentation points to
+    `src/domains/eval/` and `evals/`, not to a retired parallel tree.
+13. Confirm `docs/architecture/artifact-versions.md` includes every persisted artifact added
+    or re-versioned by the candidate, including any canonical naming schema
+    identifiers. A compatibility reader does not make a newly emitted schema
+    optional to document.
+14. After any version, changelog, package-list, or release-note edit, rerun
+    `npm run ci:release` and commit the coherent result on `v0.4.1`.
+
+## Part 3: present the gate
+
+15. Before touching a remote ref, report the exact final candidate SHA and
+    tracked status; commits added since the prior handoff; the local
+    `ci:release` result; the GitHub Actions URL for the candidate when one
+    exists; package and changelog versions; tarball audit; clean-install and
+    interactive results; any deferred live or eval measurement; and the
+    proposed commands for the remaining parts.
+16. Reconfirm whether `refs/tags/v0.4.1`, a v0.4.1 GitHub Release, or
+    `@iowarp/clio-coder@0.4.1` already exists. Obtain the operator's npm
+    dist-tag decision explicitly; do not infer `latest` or `next` from a prior
+    release.
+
+---
+
+## AUTHORIZATION BOUNDARY
+
+Every step below is externally visible or cannot be undone by an ordinary
+local Git command. Do not execute any of it until the operator approves the
+exact SHA and commands.
+
+## Part 4: fast-forward `main`
+
+17. `git fetch origin` immediately before integrating. Require `origin/main`
+    to be an ancestor of the reviewed candidate and confirm no other worktree
+    has `main` checked out.
+18. Fast-forward local `main` to `refs/heads/v0.4.1`; do not create a merge
+    commit, rebase the candidate, or reset a published branch. Verify `main`
+    equals the reviewed SHA and is clean.
+19. Fetch once more and stop on unexpected remote movement. Push `main` without
+    force.
+
+## Part 5: exact-SHA CI, tag, and GitHub Release
+
+20. The `main` push triggers the single `ci` workflow. Require its one Node 22
+    job for the exact reviewed SHA to finish green before tagging. A red run
+    blocks the cut and is investigated on its own evidence.
+21. Reconfirm the tag and GitHub Release do not exist. Create annotated tag
+    `v0.4.1` on the green SHA and push only `refs/tags/v0.4.1`.
+22. The tag triggers `.github/workflows/release.yml`. It verifies the tag
+    matches `package.json`, independently runs `npm run ci:release` on the
+    tagged tree, packs the tarball, extracts the v0.4.1 changelog section, and
+    creates the GitHub Release. It does not publish to npm. Verify the run SHA,
+    release notes, attached tarball, and URL.
+
+## Part 6: npm publication
+
+23. Run `npm whoami`; confirm the registry, account, package scope, and that
+    `@iowarp/clio-coder@0.4.1` is still absent.
+24. Reconfirm the operator's dist-tag decision, then run `npm publish` once
+    with that decision. `prepublishOnly` reruns `ci:release`; it is a final
+    safety net, not a substitute for Parts 1 and 5.
+25. Treat publication as irreversible. A published version cannot be replaced;
+    correct a mistake with a higher version rather than attempting to reuse
+    `0.4.1`.
+
+## Part 7: post-publish verification
+
+26. Verify `npm view @iowarp/clio-coder@0.4.1` and the selected dist-tag.
+27. On a clean machine, install from the registry rather than the local
+    tarball. Repeat the version/help/doctor lifecycle checks, then configure a
+    real target and run one real turn when authorized.
+28. From a supported pre-v0.4.1 installation, run `clio-coder upgrade` and
+    verify settings v2 plus the recorded Clio Coder naming migration. Confirm
+    canonical writers use the new machine identifiers and a released legacy
+    identifier remains read-compatible within the documented v0.5/v0.6 window.
+29. Record the final SHA, CI and tag-workflow URLs, tag, GitHub Release URL,
+    npm version and dist-tag, tarball evidence, and post-publish verification in
+    the release report.
+
+---
+
+## Rollback
+
+There is no rollback after npm publication. Before publication, delete only
+newly created release artifacts that the operator explicitly authorizes for
+removal. Correct a pushed `main` branch with a new forward commit, never by
+rewriting it. Local verification and note edits remain ordinary reversible Git
+work until they cross the authorization boundary.

package/docs/{development-pipeline.md → process/development-pipeline.md}

@@ -1,5 +1,8 @@
 # Development Pipeline
 
+> **Visual blueprint:** The source checkout includes the complete
+> [Development Pipeline visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/development_pipeline_blueprint.html).
+
 How a change to Clio Coder moves from "we noticed something" to a published
 release. This is the process the maintainers follow and the process Clio
 herself follows when dogfooding: every stage is a marketplace skill, so any
@@ -15,20 +18,20 @@ under pressure; git mechanics alone never justify a stage.
 
 | Stage | Skill | Output |
 | --- | --- | --- |
-| 1. File | [`file-ticket`](../skills/git/file-ticket/) | A labeled GitHub issue with evidence and acceptance criteria |
-| 2. Fix | [`fix-issue`](../skills/git/fix-issue/) | An uncommitted, verified change where failing tests preceded the fix, self-reviewed against the issue's acceptance criteria |
-| 3. Ship | [`ship`](../skills/git/ship/) | An atomic conventional commit referencing the issue (`fixes #N`), a gated push, and an open PR; merge is a human decision |
+| 1. File | [`file-ticket`](../../skills/git/file-ticket/) | A labeled GitHub issue with evidence and acceptance criteria |
+| 2. Fix | [`fix-issue`](../../skills/git/fix-issue/) | An uncommitted, verified change where failing tests preceded the fix, self-reviewed against the issue's acceptance criteria |
+| 3. Ship | [`ship`](../../skills/git/ship/) | An atomic conventional commit referencing the issue (`fixes #N`), a gated push, and an open PR; merge is a human decision |
 
-Releases follow [release-cut-checklist.md](release-cut-checklist.md) as a
+Releases follow [release-cut-checklist.md](../history/release-cut-checklist.md) as a
 human-gated checklist, not a skill. Worktrees
-([`worktree-create`](../skills/git/worktree-create/),
-[`worktree-merge`](../skills/git/worktree-merge/)),
-[`resolve-merge-conflicts`](../skills/git/resolve-merge-conflicts/), and
-[`tdd`](../skills/coding/tdd/) are à-la-carte tools reached for when the
+([`worktree-create`](../../skills/git/worktree-create/),
+[`worktree-merge`](../../skills/git/worktree-merge/)),
+[`resolve-merge-conflicts`](../../skills/git/resolve-merge-conflicts/), and
+[`tdd`](../../skills/coding/tdd/) are à-la-carte tools reached for when the
 situation calls for them, not stages every change passes through. An RCA
 written as the closing comment on the issue (`rca` label) is an artifact of
 hard bugs, not a mandatory toll booth. Batch ticket creation from a PRD
-bypasses stage 1 and uses [`backlog`](../skills/planning/backlog/)
+bypasses stage 1 and uses [`backlog`](../../skills/planning/backlog/)
 instead; everything downstream is identical.
 
 ## Inheriting a Pi release
@@ -40,11 +43,10 @@ replace Clio copies without crossing the product boundary:
    and `pi-tui`.
 2. Run `npm run pi:surface-diff`. A changed or removed symbol that Clio imports
    is an error; a new export is review input.
-3. Run `npm run ci`, then explicitly run the wire-capture fixtures and
-   `tests/smoke/tui-width-matrix.test.ts` from the
-   [Pi regression net](pi-boundary.md#pi-regression-net).
+3. Run the focused contracts in the
+   [Pi regression net](../architecture/pi-boundary.md#pi-regression-net), then run `npm run ci`.
 4. Walk Pi's fixed-issue list against the
-   [Pi SDK boundary table](pi-boundary.md). For every fix in a surface Clio
+   [Pi SDK boundary table](../architecture/pi-boundary.md). For every fix in a surface Clio
    still owns, either delete Clio's copy in favor of Pi or add a dated reason
    for keeping the delta.
 5. Review the matching pi-coding-agent release diff for application features
@@ -58,22 +60,18 @@ installed Pi versions differ from the checked-in snapshot.
 
 ## Test lanes
 
-`npm test` runs `scripts/shard-tests.mjs`. Contract and smoke files are assigned
-deterministically to weighted parallel lanes, with timings from
-`scripts/shard-weights.json`; `--list` shows the assignment and `--shard <n>`
-reproduces one numbered lane. Tests whose assertion is itself sensitive to
-wall-clock scheduling live in the explicit serial set. The runner waits for all
-parallel lanes to drain, then runs that set alone with
-`CLIO_TEST_CONCURRENCY=1`. Reproduce it with:
+`npm test` uses Node's test runner over every `tests/contracts/*.test.ts` and
+`tests/smoke/*.test.ts` file, with `tests/harness/tmp-root.ts` preloaded to
+isolate test state. Its `pretest` hook builds `dist/` when the CLI bundle is
+absent. Run one focused file while iterating with:
 
 ```bash
-node scripts/shard-tests.mjs --shard serial
+npm run test:file -- tests/contracts/<name>.test.ts
 ```
 
-Do not repair a timing-measurement failure by widening its product bound or by
-moving ordinary watchdog tests into the serial set. `tests/harness/load.ts`
-scales watchdogs by the parallel lane count; the serial lane is reserved for
-claims that cease to mean the same thing under contention.
+There is no committed weighted-shard or special serial-lane runner. Keep timing
+claims within the focused contract that owns them, and use the full `npm run ci`
+gate before handoff.
 
 ## Issue conventions
 
@@ -99,7 +97,7 @@ New `area:*` labels are proposed in an issue, not created ad hoc.
 
 ## Milestones are releases
 
-Each open milestone is the next version (`v0.3.7`, `v0.4.0`). Triage means
+Each open milestone names an upcoming version. Triage means
 assigning an issue to a milestone or explicitly leaving it in the backlog.
 A release cut requires every issue in its milestone to be closed
 or bumped; the milestone closes when the tag is published.

package/docs/process/documentation-coverage.md

@@ -0,0 +1,100 @@
+# Documentation coverage and source-alignment audit
+
+> **Visual blueprint:** The source checkout includes the complete
+> [Documentation coverage and source-alignment audit visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/documentation_coverage_blueprint.html).
+
+This is the page-level audit for Clio Coder 0.4.2. The source comparison is
+pinned to commit `ff56ea3e`. A disagreement means that a current factual claim,
+default, identifier, path, schema, or command differs from the implementation at
+that commit. Historical records are evaluated as dated evidence and are not
+treated as current operator guidance.
+
+## Headline
+
+- Markdown pages audited: **51**.
+- Dedicated HTML blueprints now present: **51**.
+- Pages without a blueprint: **0**. Every Markdown page has one visual
+  counterpart, so there are no exception reasons to record.
+- Pages with one or more source disagreements at `ff56ea3e`: **42**.
+- Pages with no source disagreement found at `ff56ea3e`: **9**.
+- Source disagreements corrected in Markdown: **42 of 42 affected pages**.
+- HTML blueprints synchronized from the corrected Markdown: **51 of 51**.
+
+At audit time, 40 blueprint files covered 40 pages because
+`prompt-envelope-and-tools.md` had two HTML implementations while
+`proactive-memory.md` shared the evidence and memory blueprint. The table below
+preserves that audit-time state.
+
+## Page audit
+
+| Markdown page | Primary source references | HTML blueprint at audit time | Disagreements with `ff56ea3e` |
+| --- | --- | --- | --- |
+| `README.md` | `package.json`; `src/cli/index.ts`; `src/cli/docs.ts`; `src/cli/doctor.ts`; CLI smoke tests | No dedicated blueprint. `html/index.html` is the landing page. | None found. |
+| `architecture/acp.md` | `src/engine/acp/**`; `src/cli/acp.ts`; `src/entry/orchestrator.ts` | `html/acp_blueprint.html` | Source line pointers and the log prefix are stale. The event and metadata allowlists omit dispatch events and agent attribution fields. Dispatch events can carry a bounded task preview despite the claimed prose embargo. Git is classified as `other`, while dispatch, steer, and monitor also have mappings; five current canonical tools also fall back to `other` and are absent from the table. Tool aliases and the policy source use the `clio-coder-*` namespace, not `clio-*`. The tool mediator governs outbound ACP delegation, not the hosted ACP server's resumable permission bridge. |
+| `architecture/alcf-provider.md` | `src/domains/providers/runtimes/cloud/alcf.ts`; `src/engine/alcf-oauth.ts`; `src/engine/apis/openai-completions.ts` | `html/alcf_blueprint.html` | The runtime stores `model.clioCoder.chatTemplateKwargsUnsupported`, but the request adapter reads the legacy `model.clio` location. The documented omission therefore is not current runtime behavior. |
+| `architecture/architecture.md` | `tests/boundaries/check-boundaries.ts`; `src/core/domain-loader.ts`; `src/entry/orchestrator.ts`; `src/engine/**`; `src/tools/bootstrap.ts`; `src/worker/**` | `html/architecture_blueprint.html` | The boundary checker has six rules, not five. The instant-shell import-graph test no longer exists. Dispatch is eagerly created by tool bootstrap and imports its runner directly, not through `lazy-tool`. The loaded-domain table omits toolchain and optional mux, the feature inventory omits the CLI-owned `user-tasks` domain, and several non-`DomainModule` areas are mislabeled as loaded modules. |
+| `architecture/artifact-placement.md` | `src/core/artifact-paths.ts`; `src/core/xdg.ts`; artifact stores under `src/domains/**`; `src/tools/artifact.ts` | `html/artifact_placement_blueprint.html` | `.clio-coder/test-scratch` has no source owner; scratch output lives below the state directory. `.clio-coder/` becomes ignored only when bootstrap writes the rule. Re-including children below an ignored parent does not implement the documented Git policy; deliberate assets require an explicit force-add. |
+| `architecture/artifact-versions.md` | `src/engine/session.ts`; `src/domains/session/migrations/**`; `src/domains/dispatch/receipt-integrity.ts`; dispatch state stores; `src/domains/eval/schema/**`; `src/domains/observability/trace-store.ts`; `src/domains/user-tasks/store.ts` | `html/artifact_versions_blueprint.html` | Sessions are format 4 and only format 3 migrates to 4. Eval artifacts live below the data directory and use `clio-coder.eval.*` schema identifiers; `EVAL_ARTIFACT_VERSION` no longer exists. Fleet contracts are Markdown in tiered roots, not YAML. A malformed checkout lease fails closed. Trace logs use `[clio-coder:trace]`, while direct readers reject schema drift. Receipt pseudocode names obsolete APIs and types and understates v20 verification. Out-of-turn usage also records prewarm and background memory. The versioned user-tasks file is omitted, while not every other persisted row is versioned. The page incorrectly claims an exhaustive registry; several internal stores are absent. Runtime-descriptor, execution-plan, eval-verdict, capacity-state, and library-pin handling are misstated, and several numeric source pointers are stale. |
+| `guide/built-in-agents.md` | `src/domains/agents/**`; `src/domains/dispatch/**`; `src/worker/**` | `html/agents_blueprint.html` | Discovery omits enabled extension roots and the reserved `auto` identifier. The compact prompt catalog excludes internal recipes and handles oracle separately. Name, description, budget, and other recipe fields are required, so the example recipe is invalid. Audience also permits `custom`. Adaptive routing uses `fleet.adaptiveRouting.agentRoles`. Event names use `clio_coder_*`. Fleet contract v5 is current. The `context-bootstrap` row grants a `ledger` tool its shipped recipe does not carry. |
+| `architecture/capacity-and-scheduling.md` | `src/domains/scheduling/**`; `src/domains/dispatch/capacity-lease.ts`; `src/domains/dispatch/admission.ts`; `src/domains/dispatch/reservation-store.ts`; provider capacity probes | `html/capacity_scheduling_blueprint.html` | The lease schema omits the optional host field. Worker protocol heartbeats run each second, while durable capacity leases renew every ten seconds. Endpoint saturation can queue through the lease controller rather than always refusing immediately. The reference mini endpoint has four llama.cpp slots, not the stated one-slot common case. Numeric source pointers are stale, and lease expiry is described without the live-process identity exception. |
+| `guide/commands-and-modes.md` | `src/cli/**`; `src/interactive/slash-commands.ts`; `src/domains/dispatch/**`; `src/tools/**` | `html/commands_blueprint.html` | Policy and event identifiers use `clio-coder-policy` and `clio_coder_*`. The interop boot prompt is not quoted accurately. The built-in-agent list omits the operator-only oracle. Memory settings use `context.memory.enabled`, not `memory.intervention.enabled`. |
+| `history/config-knobs-audit.md` | Historical snapshot of `src/core/config.ts`, runtime settings, and worker budgets | `html/config_knobs_audit_blueprint.html` | None found in its dated scope. Retired variables such as `CLIO_CODER_RESIDENCY` are historical evidence, not live guidance. |
+| `guide/configuration-and-targets.md` | `src/core/defaults.ts`; `src/core/config.ts`; `src/domains/providers/**`; `src/cli/configure.ts`; `src/cli/targets.ts`; `src/cli/models.ts`; `src/cli/auth.ts` | `html/configuration_blueprint.html` | The six safety limit leaves no longer have environment overrides. Policy and managed-file identifiers use the `clio-coder-*` namespace. The external-agent example uses retired `delegation.agents` rather than `integrations.externalAgents.entries`. |
+| `guide/configuration-reference.md` | `src/core/defaults.ts`; `src/core/config.ts`; all CLI parsers; tool schemas; agent recipe schema; local model catalogs | No; parity gap. | Several YAML string values named `off` were rendered as Boolean `False`, and environment defaults were rendered as booleans instead of presence semantics. `fleet.concurrency` defaults to the constant 4, not derived host capacity. Recipe precedence omits extensions and incorrectly permits project overrides of built-ins. `workers.rosters` is retired; the current key is `fleet.rosters`. |
+| `architecture/context-engine.md` | `src/domains/context/**`; `src/domains/session/**`; `src/domains/providers/**`; `src/domains/prompts/preload.ts`; interactive context and prewarm modules | `html/context_blueprint.html` | Context-window precedence and the unknown fallback are incomplete. The warning boundary is 128,000 while the desired floor is 131,072. Compaction and prewarm examples use v1 keys; `excludeLastTurns` is retired. A replay evidence path was deleted. The reference endpoint describes an obsolete one-slot Qwen route instead of mini with Ornith, four slots, and 262,144 context per slot. Codewiki frontmatter omits empty optional fields rather than always serializing seven. |
+| `architecture/context-working-set.md` | `src/domains/context/working-set/**`; `src/domains/session/**`; `src/interactive/turn-context.ts`; context CLI and tool modules | No; parity gap. | Settings use `context.compaction.threshold`, and `excludeLastTurns` is retired. `age-horizon` does not reproduce legacy selection because a minimum token floor was added. Recall never guesses the nearest reference; invalid-reference errors do not list candidates, while other errors list at most eight. Deleted replay evidence is cited as if shipped. |
+| `process/development-pipeline.md` | `package.json`; `scripts/check-hygiene.ts`; `.github/**`; `tests/**` | No; parity gap. | The width-matrix test, shard scripts, shard weights, and load harness do not exist. The test command now invokes contract and smoke tests directly and has no documented list, shard, serial lane, or `CLIO_TEST_CONCURRENCY` behavior. A named wire-capture fixture suite is no longer present. |
+| `architecture/dispatch-architecture-rationale.md` | `src/domains/dispatch/**`; `tests/boundaries/check-boundaries.ts` | `html/dispatch_rationale_blueprint.html` | File, barrel-line, and cross-domain import counts are stale. Receipt integrity is v20, not v16. The boundary checker has six rules, not five. |
+| `architecture/dispatch-typed-intent.md` | `src/domains/dispatch/intent*.ts`; `src/domains/dispatch/path-scope.ts`; `src/tools/dispatch-*.ts`; dispatch admission tests | No; parity gap. | Exact `.` and `./` roots normalize to repository root. Expected outputs use a looser normalizer than the three scope fields. `{check:"none"}` resolves a verifier actually named `none`. Absent or partial intent warnings are classified but deliberately not published in production. No-intent judge and reviewer requests can only hit legacy inference errors. Two legacy reason codes have no current producer. Prose-path reporting is extension-filtered and capped. Output-versus-write-root and legacy contradiction checks run only when both relevant lists are nonempty. A cited compatibility test was deleted. |
+| `process/documentation-coverage.md` | `src/**`; `tests/**`; `docs/html/**` | No; parity gap. | None found in the former ownership claims, but the former page did not provide the required page-level source, blueprint, and drift audit. |
+| `process/documentation-guide.md` | `src/**`; `tests/**`; documentation and HTML inventories | `html/documentation_blueprint.html` | The map says 20 tools, receipt v16, 45 glossary terms, six trace commands, and nine artifact schemas; current values are 21 canonical tools, receipt v20, 50 glossary terms, eight trace commands, and 25 registry rows. Several pages with standalone HTML are described as lacking it. Nine existing Markdown pages are absent from the map. |
+| `guide/environment-variables.md` | `src/core/guardrails.ts`; `src/core/xdg.ts`; all `process.env` reads; hygiene inventory | `html/environment_blueprint.html` | The page is complete for product `CLIO_CODER_*` variables plus `NO_COLOR`, not for every environment variable read by source. It omits standard directory, editor, terminal, remote-session, multiplexer, text-width, timezone, CI, Ollama capacity, and dynamic credential variable families. |
+| `process/eval-runner.md` | `src/domains/eval/**`; `src/cli/eval.ts`; eval boundary and schema tests | `html/eval_blueprint.html` | Canonical runner kind is `clio-coder-run`, schema IDs use `clio-coder.eval.*`, and the artifact field is `clioCoder`; the old forms are compatibility inputs only. The command list omits `eval inventory --json`, and the schema reference omits current agent, autonomy, cost, workspace setup, and observation fields. Some threshold-file failures exit 1 rather than 2. The mini baseline has Ornith, four slots, 262,144 context per slot, and `thinking: off`. |
+| `process/evals-internal.md` | `src/domains/eval/**`; `evals/**` | `html/evals_internal_blueprint.html` | Examples use legacy `clio.eval.behavior.v1` and `clio-run`; canonical identifiers are `clio-coder.eval.behavior.v1` and `clio-coder-run`. |
+| `architecture/evidence-and-memory.md` | `src/domains/evidence/**`; `src/domains/memory/**`; `src/cli/evidence.ts`; `src/cli/memory.ts`; receipt integrity | `html/memory_blueprint.html` | The evidence vocabulary has 29 tags, not 25. Current receipt integrity is v20; older seals are retired rather than all being invalid. The exact not-found output and CLI inventory are incomplete. Forensic classification explicitly forbids task prose as causal evidence. |
+| `process/evolution.md` | `src/domains/evolution/**`; `src/cli/evolve.ts` | `html/evolution_blueprint.html` | None found. |
+| `guide/exit-codes-and-output.md` | `src/cli/**`; `src/entry/**`; CLI smoke tests | `html/exit_codes_blueprint.html` | The JSON event table is described too broadly; full mode can pass additional `clio_coder_*` tool, permission, and plan frames. Core process exit codes are correct. |
+| `guide/extensions-and-sharing.md` | `src/domains/extensions/**`; `src/domains/resources/**`; `src/domains/share/**`; extension and share CLIs | `html/extensions_blueprint.html` | Extensions discover skills, prompts, agents, fleets, and reserved themes, not only prompts and skills. Judge eval arms are not full-auto. Share archives use `clio-coder-share-archive`, `clio-coder.share.v1`, and `clioCoderVersion`; old names are compatibility inputs. The exported settings fragment contains current v2 leaves rather than the documented old scope. |
+| `process/fleet-demo-runbook.md` | `src/domains/dispatch/**`; `src/domains/scheduling/**`; `src/cli/doctor.ts` | No; parity gap. | Current receipts use integrity v20, not v16, and older versions are retired rather than universally failing verification. |
+| `guide/fleet-dispatch.md` | `src/domains/dispatch/**`; `src/domains/scheduling/**`; dispatch tools | `html/fleet_dispatch_blueprint.html` | Current receipts use v20, not v19. Older receipts are retired and never read as evidence. Tool expansion provenance uses `clio-coder.tool.expand`, not `clio.tool.expand`. Agent-ledger citations point into the former dispatch monolith rather than `dispatch-runner.ts`. |
+| `process/git-commit-provenance.md` | `src/core/commit-attribution.ts`; `src/core/git-commit-attribution.ts`; `src/core/defaults.ts`; dispatch attribution tests | No; parity gap. | Canonical configuration is `integrations.git.commitAttribution`; `attribution.gitCommits` is migration-only. Commit trailers recognize and emit `receipt-v20`, not v19. |
+| `guide/glossary.md` | Owning types in `src/domains/dispatch/**`, `src/domains/session/**`, `src/domains/context/**`, and `src/tools/**` | `html/glossary_blueprint.html` | Receipt integrity is v20. Dispatch run and session IDs are 12-character random base36 identifiers, while session turn and entry IDs use UUIDv7. Route candidates contain more identity and policy fields than the four-field definition. Council is a current topology. `internal` is a dispatch request origin, not a worker run origin. Context ledger buckets are incomplete. |
+| `guide/installation-and-lifecycle.md` | `src/cli/upgrade.ts`; `src/cli/doctor.ts`; `src/cli/reset.ts`; `src/cli/uninstall.ts`; `src/domains/lifecycle/**`; `src/core/xdg.ts` | `html/lifecycle_blueprint.html` | Install metadata omits `repairedAt` and overgeneralizes preexisting-home detection beyond config, data, and state. The upgrade section presents a stale 0.3.x sequence as current and claims one migration, while the current registry has five migrations and 0.4.2 emits a generic notice. |
+| `architecture/middleware-and-components.md` | `src/domains/components/**`; `src/domains/middleware/**`; `src/cli/components.ts`; orchestrator registration | `html/middleware_blueprint.html` | Memory middleware uses the v2 `context.memory.*` settings, not `memory.intervention.*`. Its row omits four hooks and incorrectly places background model work directly at every tool cadence. The built-in registration table omits `observer.marketplace-offer`. |
+| `architecture/model-catalog.md` | `src/domains/providers/catalog.ts`; `src/domains/providers/models/**`; provider probes and capability resolution; model CLI | `html/models_blueprint.html` | The Qwen3.8 sample disagrees with the bundled entry on maximum output tokens, vision, thinking mechanism, and sampler temperature. The page omits the default chat thinking level of `low`. Reference topology should identify mini as the four-slot Ornith llama.cpp route and dynamo as the Qwen3.8 LM Studio chat route. |
+| `architecture/observability.md` | `src/domains/observability/**`; `src/domains/evidence/**`; `src/core/bus-events.ts`; `src/interactive/view/**` | `html/observability_blueprint.html` | Receipt integrity references use v19 instead of v20. The completion-event sample has a nonexistent `status` field and omits current outcome fields. The named dynamo sample identifies the wrong served model; the reference chat model is `qwen3.8-27b-dynamo`, while the dispatched-worker example belongs on mini with Ornith. |
+| `process/performance-methodology.md` | `src/interactive/render-trace.ts`; `src/interactive/interactive-shell.ts`; terminal lease and pacing modules; current smoke tests | No; parity gap. | Two cited render tests were deleted, `CLIO_CODER_PERF_REPORT` no longer exists, and the boot trace prefix changed to `[clio-coder:boot]`. The documented commands, graph and V8 proofs, and numeric reports belong to retired harnesses and cannot be reproduced by the current suite; installed-package coverage is now narrower. |
+| `architecture/pi-boundary.md` | `src/engine/ai.ts`; `src/engine/api-registry.ts`; `src/engine/provider-payload.ts`; `src/interactive/chat-loop.ts`; engine lifecycle tests | `html/pi_boundary_blueprint.html` | The current boundary row still names deleted `src/tools/string-enum.ts` as a live adapter instead of locating the Pi re-export only in `src/engine/ai.ts`. |
+| `guide/proactive-memory.md` | `src/domains/memory/**`; `src/domains/middleware/memory-intervention.ts`; `src/core/defaults.ts`; `src/interactive/memory-overlay.ts` | Shared `html/memory_blueprint.html` | Canonical v2 settings are `context.memory.enabled`, `cadenceToolCalls`, `trajectorySteps`, `maxOutputTokens`, `timeoutMs`, `target`, and `model`. Defaults are true, 10, 8, 2,000, 60,000, null, and null. Retired `memory.intervention.*` and background keys, 400-token and 30-second defaults, and related cost claims are stale. The reference topology names a fictitious node and one-slot route instead of mini and dynamo. A cited proactive-memory eval test was deleted, while the active exported harness now lacks maintained direct test coverage. Measurement tables conflict with one another and are not identified as dated external evidence. `qwopus` is cataloged, not selected as a shipped default. |
+| `architecture/prompt-envelope-and-tools.md` | `src/domains/prompts/compiler.ts`; `src/interactive/chat-loop.ts`; `src/core/tool-names.ts`; `src/tools/registry.ts`; `src/tools/agent-tools.ts` | `html/tools_blueprint.html`; a second prompt-envelope implementation was a duplicate and was deleted in the parity pass | The compile cache key omits several current identity fields and tool-schema bytes. There are 21 canonical tools, not 20, and the minimal and science profiles include ledger. Pane exposure is also conditional. Default compaction first performs non-destructive working-set eviction; destructive masking is legacy-only behind `CLIO_CODER_LEGACY_MASK=1`. The exhaustive size-policy description omits ledger and panes. A steering event still uses the retired `clio_*` namespace. |
+| `architecture/provider-adapter-cookbook.md` | `src/domains/providers/registry.ts`; `src/domains/providers/types/runtime-descriptor.ts`; engine provider adapters | `html/provider_adapter_blueprint.html` | `TargetDescriptor` carries auth metadata rather than an API key. The reasoning cache belongs to the providers domain, not a session ledger. Credential resolution and infill binding do not occur in `synthesizeModel`. The thinking mechanism table lists wire/runtime formats rather than the actual mechanism enum. The cited `thinking-runtime.test.ts` was deleted; current off-wire coverage is narrower. |
+| `history/release-cut-checklist.md` | `scripts/check-release.mjs`; package smoke tests; workflows; `package.json` | No; parity gap. | None found in its explicitly historical v0.4.1 scope. |
+| `guide/resource-library.md` | `src/domains/resources/library.ts`; `src/cli/library.ts`; Skills Hub integration | No; parity gap. | None found. |
+| `architecture/safety-model.md` | `src/domains/safety/**`; `src/tools/registry.ts`; `src/tools/policy.ts`; `src/entry/orchestrator.ts`; dispatch write boundaries | `html/safety_blueprint.html` | Saved autonomy is `safety.autonomy`, not a top-level `autonomy` leaf. The canonical tool surface has 21 entries and the table omits ledger and panes, whose registration is conditional. Permission events and ACP governance use retired `clio_*` and `clio-policy` names. |
+| `process/scientific-validation.md` | `src/domains/safety/rigor.ts`; `src/domains/safety/finish-contract.ts`; verification authoring code | `html/validation_blueprint.html` | None found. |
+| `architecture/session-lifecycle.md` | `src/engine/session.ts`; `src/domains/session/**` | `html/session_lifecycle_blueprint.html` | Current session format is 4. Format 3 migrates additively to 4, while versions below 3 and above 4 are rejected. The example metadata header still uses version 3 and the legacy `clioVersion` field; compatibility prose says every older session is refused. |
+| `guide/skills-marketplace.md` | `src/interactive/overlays/skills-hub.ts`; `src/domains/resources/skills/marketplace.ts` | `html/skills_blueprint.html` | None found. |
+| `architecture/time-conventions.md` | `src/interactive/format-time.ts`; dispatch capacity and scheduling modules; `src/core/state-file-lock.ts`; receipt and session stores | `html/time_conventions_blueprint.html` | In-process spans use either `performance.now()` or `hrtime.bigint()`, while persisted and cross-process deadlines use wall time. Not every clock has an injection seam or a global harness clock. Three cited source or test paths do not exist, and the agent-ledger path is wrong. |
+| `guide/tool-usage.md` | `src/tools/agent-tools.ts`; `src/tools/registry.ts`; `src/tools/dispatch-arguments.ts`; per-tool implementations | `html/tool_usage_blueprint.html` | Dispatch rejects per-item `agent_id`, top-level `failover`, and top-level `allowed_candidates`; routing policy belongs below `routing`. Receipt examples use v19 rather than v20. Ledger and panes are missing from the reference. The canonical OBSERVE plane has seven tools, although only six use the shared observation envelope. Docs corpus wording assumes a flat `docs/*.md` directory. Several cited dispatch, safety, and scheduler test paths were deleted. |
+| `architecture/trace-store.md` | `src/cli/trace.ts`; `src/domains/observability/trace-store.ts` | `html/trace_blueprint.html` | None found. |
+| `guide/troubleshooting.md` | `src/core/**`; `src/cli/**`; `src/domains/**`; exact error strings | `html/troubleshooting_blueprint.html` | The local model catalog path is `src/domains/providers/models/local-models/clio-coder-local-coding-targets.yaml`, not the former `clio-local-coding-targets.yaml`. |
+| `architecture/tui-design.md` | `src/interactive/theme/tokens.ts`; `src/interactive/theme/glyphs.ts`; interactive renderer and view modules | `html/tui_design_blueprint.html` | The cited `tests/contracts/usage-vocabulary.test.ts` no longer exists. |
+| `architecture/worker-dispatch-mechanics.md` | `src/worker/**`; dispatch receipt, worker spec, heartbeat, and failure classification modules | `html/worker_dispatch_blueprint.html` | Receipt integrity is v20, not v19. A pre-v20 seal is retired and excluded from evidence rather than treated as a current invalid seal. Steering and permission events use the `clio_coder_*` namespace. The detailed retry-acceptance table cites contract files that no longer exist. |
+
+## Blueprint disposition
+
+The eleven audit-time gaps now have dedicated blueprints: the documentation
+hub, configuration reference, context working set, development pipeline, typed
+dispatch intent, this coverage audit, fleet demo runbook, Git commit provenance,
+performance methodology, release checklist, and resource library. Proactive
+memory also has its own page instead of sharing the evidence blueprint, and the
+duplicate prompt-envelope implementation was removed. The historical
+configuration-knob audit remains available under the History section of the
+HTML index.
+
+## Audit disposition
+
+The source-alignment pass corrected all findings across the 42 affected
+Markdown pages. The table preserves what the audit found at `ff56ea3e`; it does
+not describe outstanding Markdown debt. Every HTML blueprint now renders the
+complete corrected counterpart and identifies its Markdown source explicitly.