@iowarp/clio-coder 0.4.1 → 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.
 
 ---
 
@@ -14,7 +19,7 @@ This guide provides concrete, actionable remediation procedures for operational
 | `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,21 +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](configuration-and-targets.md) for the active pane keys and their migration behavior.
+> 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
 
@@ -32,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. |
@@ -48,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. |
@@ -106,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/{release-cut-checklist.md → history/release-cut-checklist.md}

@@ -1,5 +1,14 @@
 # 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
@@ -57,11 +66,29 @@ operator's explicit approval of the exact candidate SHA and commands.
 7. When a configured target is available, run one real built-binary turn:
 
    ```sh
-   npm run live:smoke -- --target <id>
+   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/`,
@@ -92,7 +119,7 @@ operator's explicit approval of the exact candidate SHA and commands.
 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/artifact-versions.md` includes every persisted artifact added
+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.

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.

package/docs/process/documentation-guide.md

@@ -0,0 +1,187 @@
+# Documentation Standards and Codebase Alignment
+
+> **Visual blueprint:** The source checkout includes the complete
+> [Documentation Standards and Codebase Alignment visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/documentation_blueprint.html).
+
+Clio Coder is an experimental community alpha. Documentation should help contributors and early users work from the source of truth without overstating maturity. When docs drift, prefer the current source and tests over older prose or aspirational roadmap notes.
+
+---
+
+## Source-first documentation rule
+
+Before changing public docs, inspect the relevant implementation:
+
+1. `git log --oneline -- <area>` for recent intent and release context.
+2. `src/**` for current behavior.
+3. `tests/**` for executable contracts and edge cases.
+4. `README.md`, `CHANGELOG.md`, and `docs/**/*.md` for existing public wording.
+
+Classify claims clearly:
+
+| Claim class | How to word it |
+| --- | --- |
+| Shipped and tested | State directly and link to source/tests. |
+| Implemented but experimental | Say alpha/experimental and name sharp edges. |
+| Typed contract exists, default runtime is inert | Say the schema exists but no public loader/rules are active. |
+| Planned/future | Put in roadmap language; do not present as available behavior. |
+
+---
+
+## Documentation map
+
+| Guide | Primary source references | What it should cover |
+| --- | --- | --- |
+| [README.md](../../README.md) | `CHANGELOG.md`, package metadata, release receipts | Product overview, install, first run, alpha framing, and release status. |
+| [docs/README.md](../README.md) | This docs directory | Documentation hub. |
+| [documentation-guide.md](documentation-guide.md) | `docs/**`, `src/**`, `tests/**` | Documentation structure, source ownership, writing rules, and blueprint policy. |
+| [commands-and-modes.md](../guide/commands-and-modes.md) | `src/cli/index.ts`, `src/cli/args.ts`, `src/interactive/slash-commands.ts`, `src/domains/dispatch/**` | CLI commands, headless run flags (`--session`, `--continue`, `--json-events`), session continuity, `--json` wire projection promise, slash commands, keybindings, live steering. |
+| [context-engine.md](../architecture/context-engine.md) | `src/domains/context/**`, `src/domains/session/context-accounting.ts`, `src/domains/session/context-ledger.ts`, `src/domains/session/compaction/` | Context window resolution, per-model probe capabilities, token accounting, snapshots, the three compaction mechanisms, model-driven `clio-coder context init`, format v4 session enforcement. |
+| [context-working-set.md](../architecture/context-working-set.md) | `src/domains/context/working-set/**`, `src/domains/session/entries.ts`, `src/interactive/turn-context.ts` | Working-set vocabulary, eviction as a projection, the `contextEviction` / `contextRecall` records, the marker contract, the `age-horizon` and `structural-v1` policies, recall semantics, and the operator surfaces. |
+| [architecture.md](../architecture/architecture.md) | `tests/boundaries/check-boundaries.ts`, `src/core/domain-loader.ts`, `src/engine/**`, `src/worker/**` | Source layout, six enforced boundary rules, runtime flow mermaid diagram, event and audit model, and detect-and-rollback write boundaries. |
+| [time-conventions.md](../architecture/time-conventions.md) | `src/domains/dispatch/code-step.ts`, `src/domains/dispatch/extension.ts`, `src/domains/session/**`, `src/domains/observability/**` | Monotonic durations, wall-clock instants, anchored spans, injected clocks, timeout accounting, and timestamp serialization. |
+| [dispatch-architecture-rationale.md](../architecture/dispatch-architecture-rationale.md) | `src/domains/dispatch/**`, `tests/boundaries/check-boundaries.ts` | Design rationale, not behavior: invariants that cross the seams a dispatch split would use, what any future split must preserve, the one dispatch→eval import, and the closed barrel-import decision. |
+| [dispatch-typed-intent.md](../architecture/dispatch-typed-intent.md) | `src/domains/dispatch/intent.ts`, `src/domains/dispatch/intent-compatibility.ts`, `src/domains/dispatch/path-scope.ts`, `src/tools/dispatch-plan.ts` | Dispatch intent v2, path provenance, legacy inference, retirement telemetry, and fail-closed version handling. |
+| [configuration-and-targets.md](../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` | TargetDescriptor, contextWindowProvenance (`configured`, `discovered`, `catalog`, `runtime-default`), settings.yaml, strict validation, saved defaults vs live routing. |
+| [artifact-placement.md](../architecture/artifact-placement.md) | `src/core/artifact-paths.ts`, `src/core/config.ts`, `src/domains/agents/result-contract-filesystem.ts` | Audience-based artifact placement, configured output roots, containment, and migration from legacy paths. |
+| [configuration-reference.md](../guide/configuration-reference.md) | `src/core/defaults.ts`, `src/cli/**`, `src/tools/**`, `src/domains/agents/recipe-schema.ts`, `src/domains/providers/models/local-models/**` | Audited inventory of every settings key, environment variable, CLI flag, project-file key, frontmatter key, tool argument, and model tag with defaults and precedence. |
+| [safety-model.md](../architecture/safety-model.md) | `src/domains/safety/**`, `src/tools/registry.ts`, `src/tools/policy.ts`, `src/tools/verify/**`, `src/entry/orchestrator.ts`, `src/domains/dispatch/write-boundary.ts` | Operating posture, `resolveEffectiveAutonomy` / `resolveBaselineAutonomy`, detect-and-rollback write boundaries, approval axes, damage control, typed validation. |
+| [prompt-envelope-and-tools.md](../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/observation.ts`, `src/tools/agent-tools.ts` | Prompt envelope reuse, canonical tool delivery via single `agent-tools.ts` adapter, seven-plane tool surface, observation envelope, strict `ToolName` keying. |
+| [tool-usage.md](../guide/tool-usage.md) | `src/tools/agent-tools.ts`, `src/tools/registry.ts`, `src/tools/observation.ts` | In-depth reference for all 21 canonical tools, including conditional registration, parameters, typical payloads, normalizers, and error examples. |
+| [provider-adapter-cookbook.md](../architecture/provider-adapter-cookbook.md) | `src/domains/providers/registry.ts`, `src/domains/providers/types/runtime-descriptor.ts` | RuntimeDescriptor, probe(), probeReasoning(), synthesizeModel(), thinking mechanisms. |
+| [pi-boundary.md](../architecture/pi-boundary.md) | `src/engine/**`, `src/tools/truncate.ts`, `tests/boundaries/check-boundaries.ts` | Which Pi SDK capabilities Clio delegates to, which Clio-specific adapters remain, and the boundary tests that keep the split explicit. |
+| [alcf-provider.md](../architecture/alcf-provider.md) | `src/domains/providers/runtimes/cloud/alcf.ts`, `src/engine/alcf-oauth.ts` | Globus PKCE OAuth, openAuthStorage(), Sophia vLLM, Metis API, chatTemplateKwargsUnsupported. |
+| [environment-variables.md](../guide/environment-variables.md) | `src/core/guardrails.ts`, `src/core/xdg.ts`, `src/domains/providers/knowledge-base-path.ts` | Comprehensive env var matrix: guardrail overrides, directory layout (CLIO_CODER_HOME), debug toggles, and internal plumbing. |
+| [built-in-agents.md](../guide/built-in-agents.md) | `src/domains/agents/**`, `src/domains/agents/builtins/*.md`, `src/domains/dispatch/**` | Builtin agent recipes, discovery roots, frontmatter schema, fleet contract shadowing (`.clio-coder/fleets/<name>.md`), active route automation. |
+| [fleet-dispatch.md](../guide/fleet-dispatch.md) | `src/domains/dispatch/**` | Multi-node SSH dispatch: process-safe admission, capacity leases, fleet contracts v1 through v5, v4 write boundaries, v5 plan and gate steps, bounded check/repair loops (`loop_bound_exhausted`), deterministic code steps, attestation, and receipts v20. |
+| [capacity-and-scheduling.md](../architecture/capacity-and-scheduling.md) | `src/domains/scheduling/**`, `src/domains/dispatch/capacity-lease.ts`, `src/domains/dispatch/reservation-store.ts` | Multi-process capacity leases (`dispatch-admission.json`), heartbeat TTLs, cross-process transaction locks (`dispatch-admission.json.lock`), and cluster drain controls. |
+| [worker-dispatch-mechanics.md](../architecture/worker-dispatch-mechanics.md) | `src/worker/**` | NDJSON parent-child socket protocols, control/bulk lane demuxing, watchdog timers, worker attestation (13 protocol fields), permission parking, exit codes. |
+| [fleet-demo-runbook.md](fleet-demo-runbook.md) | `src/domains/dispatch/**` | Multi-node fleet demo: SSH setup, C++ build/repair workflow, reviewer gates, and receipt verification v20. |
+| [session-lifecycle.md](../architecture/session-lifecycle.md) | `src/engine/session.ts`, `src/domains/session/**` | Session lifecycle, on-disk ledger format v4 (`current.jsonl`), tree branching (`tree.json`), active-path lineage selection, `/fork`, `/resume`, checkpoints, and write-ahead protected-artifact journal. |
+| [acp.md](../architecture/acp.md) | `src/engine/acp/**`, `src/cli/acp.ts` | Agent Client Protocol (ACP) server over stdio, tool mediation, non-stall permission handling, timeout bounds, and error taxonomy. |
+| [artifact-versions.md](../architecture/artifact-versions.md) | `src/domains/dispatch/receipt-integrity.ts`, `src/engine/session.ts`, `src/worker/spec-contract.ts`, `src/domains/agents/fleet-contract.ts`, `src/domains/eval/schema/`, `src/domains/observability/trace-store.ts` | Operator-facing registry and migration policies for selected compatibility-sensitive serialized artifacts. |
+| [exit-codes-and-output.md](../guide/exit-codes-and-output.md) | `src/cli/**`, `src/entry/**` | Global process exit codes (0, 1, 2, 3), `--help` standard on stdout, machine-readable JSON streaming (`--json`, `--json-events`), and headless stdout deliverable contracts. |
+| [troubleshooting.md](../guide/troubleshooting.md) | `src/core/**`, `src/cli/**`, `src/domains/**` | Actionable error remediation and diagnostics keyed by exact user-facing messages. |
+| [glossary.md](../guide/glossary.md) | `src/domains/dispatch/types.ts`, `src/tools/**`, `src/domains/agents/**`, `src/core/**` | Canonical definitions of 50 core architectural concepts mapped to `src/` types. |
+| [documentation-coverage.md](documentation-coverage.md) | `src/**` | Complete source-to-documentation mapping matrix and subsystem coverage status. |
+| [tui-design.md](../architecture/tui-design.md) | `src/interactive/theme/tokens.ts`, `src/interactive/theme/glyphs.ts` | TUI color system, glyph vocabulary (`contextReserve`), structural layouts, state choreography, code ink. |
+| [installation-and-lifecycle.md](../guide/installation-and-lifecycle.md) | `src/cli/paths.ts`, `src/cli/doctor.ts`, `src/cli/uninstall.ts`, `src/cli/removal.ts` | Installation, upgrade, reset, uninstallation, launcher ownership and what `--remove-binary` will and will not remove, partial-failure behavior, configuration folders (`credentials.yaml` `0o600`), and permissions. |
+| [release-cut-checklist.md](../history/release-cut-checklist.md) | `scripts/check-release.mjs`, `tests/smoke/installed-package.test.ts`, `.github/workflows/`, `package.json` | Historical v0.4.1 release procedure retained as evidence; future releases must draft and verify their own checklist. |
+| [development-pipeline.md](development-pipeline.md) | `skills/git/**`, `.github/**`, `scripts/check-release.mjs`, `package.json` | Issue-to-PR development lifecycle, validation, release inheritance, and the human merge boundary. |
+| [git-commit-provenance.md](git-commit-provenance.md) | `src/core/commit-attribution.ts`, `src/core/git-commit-attribution.ts`, `src/domains/dispatch/fleet-commit-attribution.ts` | Evidence-aware commit roles, trailers, managed hook chaining, and receipt v20 attribution. |
+| [observability.md](../architecture/observability.md) | `src/domains/observability/**`, `src/interactive/view/**`, `src/domains/dispatch/**`, `src/core/bus-events.ts` | `/view` artifact browsing, receipt verification, worker diagnostics, event routing, and cost snapshots. |
+| [performance-methodology.md](performance-methodology.md) | `src/interactive/render-trace.ts`, `src/interactive/**`, `tests/contracts/rendering-invariants.test.ts`, `tests/smoke/real-binary-boot.test.ts` | Reproducible terminal and model-path performance endpoints, trace interpretation, measurement controls, and reporting rules. |
+| [evidence-and-memory.md](../architecture/evidence-and-memory.md) | `src/domains/evidence/**`, `src/domains/memory/**`, `src/cli/evidence.ts`, `src/cli/memory.ts` | Evidence corpus layout, findings, memory lifecycle and prompt injection. |
+| [proactive-memory.md](../guide/proactive-memory.md) | `src/domains/memory/**` | Proactive task memory architecture, session task bank, intervention rules, and handoff carrying. |
+| [trace-store.md](../architecture/trace-store.md) | `src/cli/trace.ts`, `src/domains/observability/trace-store.ts` | WAL SQLite trace mirror database schema, rowid cursor queries, rebuildability, and eight `clio-coder trace` subcommands: `runs`, `phases`, `tail`, `procs`, `inspect`, `prune`, read-only `sql`, and `ui`. |
+| [eval-runner.md](eval-runner.md) | `src/domains/eval/**`, `src/cli/eval.ts` | Local YAML eval tasks, dual token accountings (`tokens.*` wire vs `receiptUsage.*` journal), fail-closed null totals, EvalArtifactV4 format, `verify.measure` task outcome recording. |
+| [evals-internal.md](evals-internal.md) | `src/domains/eval/**`, `evals/**` | Private suite handling, measurement design, and the boundary between shipped reference inputs and external campaigns. |
+| [extensions-and-sharing.md](../guide/extensions-and-sharing.md) | `src/domains/extensions/**`, `src/domains/resources/**`, `src/domains/share/**`, `src/cli/extensions.ts`, `src/cli/share.ts` | Prompt, skill, agent, fleet, and reserved theme resources; extension manifests; portable share archives. |
+| [resource-library.md](../guide/resource-library.md) | `src/domains/resources/library.ts`, `src/cli/library.ts` | Catalog schemas, private and remote source policy, checksum pins, resource installation, and update checks. |
+| [skills-marketplace.md](../guide/skills-marketplace.md) | `src/interactive/overlays/skills-hub.ts`, `src/domains/resources/skills/marketplace.ts` | Skills Hub marketplace discovery through the install resolver, empty state, install actions, publishing flow. |
+| [model-catalog.md](../architecture/model-catalog.md) | `src/domains/providers/catalog.ts`, `src/domains/providers/models/**`, `src/domains/providers/probe/**`, `src/domains/providers/model-capabilities.ts` | Model catalog, live probes (`--offline` toggle), exact-id selector `probeCapabilitiesForModel`, field-note promotion. |
+| [middleware-and-components.md](../architecture/middleware-and-components.md) | `src/domains/components/**`, `src/domains/middleware/**`, `src/cli/components.ts` | Active component snapshots, phase-aware middleware hook budgets (`DEFAULT_MIDDLEWARE_HOOK_BUDGETS_MS`). |
+| [scientific-validation.md](scientific-validation.md) | `src/domains/safety/rigor.ts`, `src/domains/safety/finish-contract.ts` | Advisory validation-contract patterns for scientific artifacts and HPC assumptions. |
+| [evolution.md](evolution.md) | `src/domains/evolution/**`, `src/cli/evolve.ts` | Falsifiable Change Manifest JSON templates, evidence-linked validation, and `clio-coder evolve`. |
+| [config-knobs-audit.md](../history/config-knobs-audit.md) | `src/cli/config.ts` | Point-in-time inventory of legacy environment variables (Historical Appendix). |
+
+---
+
+## Style conventions
+
+### Alpha framing
+
+Use direct, honest language:
+
+- "experimental community alpha"
+- "source-build path"
+- "current runtime is conservative/inert"
+- "advisory contract"
+- "planned/future milestone"
+
+Avoid phrases that imply managed production stability, full plugin maturity, or automatic scientific validation when the current code does not provide it.
+
+### Markdown structure
+
+- Prefer short sections with tables for command and schema references.
+- Use fenced examples that can be copied.
+- Keep links relative and repository-portable; do not use absolute `file:///home/...` links.
+- Mention source file paths in backticks instead of editor-specific absolute URLs.
+
+### GitHub alerts
+
+Use alerts sparingly:
+
+> [!NOTE]
+> Context or caveats that prevent misinterpretation.
+
+> [!WARNING]
+> Sharp edges, alpha limitations, or behavior that can surprise contributors.
+
+> [!CAUTION]
+> Safety, data loss, or security-sensitive constraints.
+
+---
+
+## Blueprint coverage and format strategy
+
+Clio Coder maintains two complementary documentation formats:
+
+1. **Markdown documents (`docs/guide/**/*.md`, `docs/architecture/**/*.md`, `docs/process/**/*.md`, and `docs/history/**/*.md`)**: The canonical reference for coding agents, developers, and maintainers, with `docs/README.md` as the hub. They optimize for retrievability, exact enumerations, schema tables, typed TypeScript contracts, and source citations (`src/...:line`).
+2. **HTML blueprints (`docs/html/*_blueprint.html`)**: One visual counterpart per Markdown page for human readers. Each blueprint carries the complete canonical prose plus navigation and copy affordances, and declares its source in `meta[name="clio-markdown-source"]`.
+
+### Blueprint Creation Policy
+
+Blueprint coverage is explicit rather than inferred from document style. The
+page-level audit lives in
+[`documentation-coverage.md`](documentation-coverage.md). All 51 Markdown pages
+have a dedicated blueprint. `docs/html/index.html` groups those counterparts by
+the same Guide, Architecture, Process, and History tree, while a source meta tag
+provides the one-to-one machine-readable mapping. Every mapping must remain
+unique, complete, and free of orphaned Markdown or HTML pages.
+`npm run lint` rejects any absent named blueprint, enforces that mapping, and
+compares every extractable `clio-coder <command>` string and `CLIO_CODER_*`
+name in each counterpart.
+
+---
+
+## Update checklist
+
+When a feature changes:
+
+1. Identify the source owner (`src/cli`, `src/interactive`, `src/tools`, or a domain).
+2. Check whether public CLI help changed.
+3. Update the mapped guide in the same PR.
+4. If behavior affects safety, sessions, receipts, prompts, targets, or dispatch, update both README-level user docs and the deeper guide.
+5. Run a lightweight link check for changed Markdown.
+6. For release docs, verify version badges/sections match `package.json` and `CHANGELOG.md`.
+7. Run `npm run lint` to verify Markdown and HTML blueprint parity.
+
+Suggested local link check:
+
+```bash
+python3 - <<'PY'
+import pathlib, re
+for md in list(pathlib.Path('docs').rglob('*.md')) + [pathlib.Path('README.md')]:
+    text = md.read_text()
+    for m in re.finditer(r'\[[^\]]+\]\(([^)]+)\)', text):
+        link = m.group(1)
+        if link.startswith(('http://', 'https://', 'mailto:', '#')):
+            continue
+        target = link.split('#')[0]
+        if target and not (md.parent / target).exists():
+            line = text.count('\n', 0, m.start()) + 1
+            print(f'{md}:{line}: missing {link}')
+PY
+```
+
+---
+
+## Community documentation priorities
+
+Clio users tend to be early adopters running real repositories, local models, and scientific/HPC code. Good docs should therefore prioritize:
+
+- reproducible first-run and target configuration;
+- local model/runtime field notes with exact versions and serving settings;
+- safety receipts and redaction guidance for issue reports;
+- small examples for project-local `CLIO-CODER.md`, `.clio-coder/safety.yaml`, prompts, skills, and agents;
+- clear labels for experimental surfaces such as middleware and scientific validation contracts.