@iowarp/clio-coder 0.4.7 → 0.4.8

package/docs/guide/configuration-and-targets.md

@@ -1,8 +1,5 @@
 # Configuration, Targets, Runtimes, and Auth
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Configuration, Targets, Runtimes, and Auth visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/configuration_blueprint.html).
-
 Clio Coder is target-first: chat and fleet dispatch resolve through configured targets in `settings.yaml`, not through provider-specific ad hoc flags. Chat and print targets are HTTP and native engine-backed runtimes. Fleet dispatch can also target sanctioned subscription and external-worker runtimes described below.
 
 Clio's engine is built on the pi SDK (see [docs/architecture/pi-boundary.md](../architecture/pi-boundary.md)). Broad provider/model support comes from engine-backed descriptors and from the generic `openai-compat` and `anthropic-compat` targets. Clio adds orchestration, local/native runtime ergonomics, target configuration, dispatch, safety, and receipts rather than creating a first-class descriptor for every provider.
@@ -399,7 +396,7 @@ Three behaviors in this release are gated on a runtime's tier being `local-nativ
 
 The tier means "an inference server the operator runs, whose prefix cache and resident model Clio's own behavior can displace." That is what the three gates are actually asking:
 
-- **Pre-warm** runs only here, whatever `chat.prewarm` says, because a cloud provider bills the request and caches on its own schedule. The check is made twice, once from configuration before any runtime is resolved and once against the resolved runtime, so an unreachable target does not pay for a capability probe at boot just to be told no.
+- **Pre-warm** requires `chat.prewarm: true` and a verified, loaded and idle native deployment binding. The first supported path is the pinned llama.cpp deployment described below. Other native runtimes, unknown gateway routes and paid routes remain passive. Checks run before preparation and again before the request; a runtime tier alone grants no load or eviction authority.
 - **Endpoint capacity** defaults to one slot here when discovery reports nothing, and to unbounded elsewhere. vLLM and SGLang are the deliberate exceptions inside the tier: both serve genuinely concurrent requests, so an undiscovered limit is left unbounded rather than guessed at one.
 - **Five of the eight expected-cold reasons** are stamped only here, because a single-slot local cache is the only one an interleaved run actually displaces. The other three moved the prompt bytes themselves and are stamped on every tier. The full split is in [context-engine.md](../architecture/context-engine.md#cache-divergence-honesty).
 
@@ -1241,3 +1238,199 @@ When opening issues, include the Clio version, Node version, target id/runtime,
 ## Explicit Antigravity continuity
 
 Antigravity resumes a conversation only when a caller explicitly supplies its conversation ID through the worker runtime. The dispatch tool exposes no resume argument. A nonempty ID must be at most 4096 UTF-8 bytes and contain no Unicode control characters; it is passed as a literal `--conversation` argument. Clio requires the first init conversation ID to match the requested ID and fails the run if agy starts a different conversation. An absent or empty ID starts fresh. Antigravity runs are never retried automatically.
+
+## Exact prompt reuse and bounded warming
+
+Normal provider caching does not require Clio to manage inference state. Pi
+serializes native requests and normalizes provider usage; Clio preserves those
+values through the session ledger, worker receipts and trace records. A matching
+serialized prefix is a reuse candidate. Only backend usage/timing evidence can
+establish an actual hit. A compiler memoization hit or a forked transcript cannot.
+
+| Responsibility | Existing owner | Clio correction or limit |
+| --- | --- | --- |
+| Native request conversion, thinking history and cache controls | Pi 0.85.1 | Target retention reaches all instrumented native Pi APIs; explicit call options still win. |
+| Exclusive input/read/write buckets, cost tiers and one-hour write cost | Pi | Preserve the full catalog cost and per-call calculated total instead of flattening tiers or repricing an aggregate. |
+| Main, worker, failed/aborted and out-of-turn usage | Clio | Preserve optional `cacheWrite1h` as a subset of writes; retain billed failed calls. Missing provider usage remains unknown. |
+| Main and warm preparation | Pi public transforms and Clio payload hooks | Warm calls use the caller's transforms, ordered tools, thinking and payload replacement without executing tools or adding messages to history. |
+| Session transport identity | Pi/Clio session ownership | `sessionId` remains the real session id. No fleet-wide cache key replaces it. |
+| Distinct cross-session cache affinity, separately configured one-hour rate | SDK contract gap | No duplicate serializer or price calculator is introduced. Pi's supported provider pricing remains authoritative. |
+
+A native Pi target can request retention without enabling warming:
+
+```yaml
+targets:
+  - id: direct-openai
+    runtime: openai
+    cache:
+      retention: long
+```
+
+Precedence is explicit request option, then target, then
+`CLIO_CODER_ANTHROPIC_CACHE_RETENTION` for native Anthropic Messages, then Pi's
+own environment/default. Targets reload on the next turn, including when the
+id and model stay the same. The active conversation survives the runtime refresh.
+There are no duplicate model, recipe or fleet retention knobs.
+
+| API/deployment | Effective policy and current verification |
+| --- | --- |
+| Native OpenAI Responses, older supported models | Pi's model compatibility flags select `24h` for `long`. `none` omits controls; it does not universally disable automatic caching. Payload fixtures cover this path. |
+| Native OpenAI Responses, explicit-mode models | Pi selects `prompt_cache_options`; `none` requests explicit mode without breakpoints, and `long` selects `30m` TTL. Clio adds no extra breakpoints or weaker instruction roles. Payload fixtures cover this path. |
+| Native Anthropic Messages | Pi selects eligible short or one-hour cache-control blocks. `none` removes these controls. Real serializer/HTTP usage fixtures cover normalization and the one-hour subset. |
+| Direct llama.cpp | Normal calls retain `cache_prompt: true`; `retention: none` selects false. Optional warming requires the binding and evidence below. |
+| LiteLLM/generic OpenAI compatibility | Passive provider usage is retained. Generic synthesis does not advertise OpenAI `24h` retention. A declared route alone does not prove native controls or timings survive translation. Gateway warming stays disabled. |
+| vLLM | Normal inference and passive provider usage continue. A declared build can be checked, but version alone proves neither APC enablement nor idle scheduler/memory capacity. Warming stays disabled; no fixed-slot model is imposed. |
+| Claude Agent SDK, subscription/OAuth and other harnesses | Harness-specific transport and usage remain intact. Native Pi controls and direct API prices are not promises about another harness. |
+| Gemini explicit cache objects, Bedrock/platform cache administration | No new object lifecycle or administration is added. Existing Pi/provider support remains responsible for supported passive observations and requests. |
+
+For a direct llama.cpp **already loaded** worker at the audited commit, an
+operator can opt into a bounded pilot. Use the worker's actual `build_info`,
+exact model alias and endpoint; the values below are examples, not deployment
+measurements:
+
+```yaml
+chat:
+  prewarm: true
+targets:
+  - id: local-llama
+    runtime: llamacpp
+    url: http://127.0.0.1:8080
+    lifecycle: user-managed
+    cache:
+      retention: short
+      deployment:
+        backend: llamacpp
+        controlUrl: http://127.0.0.1:8080
+        model: your-exact-model-id
+        build: b1-c841aee
+      warm:
+        maxInputTokens: 8192
+        maxDurationMs: 30000
+        cooldownMs: 60000
+```
+
+Discovery uses GET requests with a two-second total deadline and refuses
+redirects. The control endpoint receives no inferred credentials. An authenticated
+control endpoint therefore remains unavailable to this initial reader. For a
+router, Clio inspects `/models` before any model-qualified request. Sleeping,
+loading or unloaded models are ineligible; a build change, unknown model or busy
+slot also refuses warming. The verified llama protocol is commit `c841aee`.
+Other builds stay passive until their no-autoload and inspection behavior is
+verified. A missing process epoch stays unknown; discovery is repeated rather
+than persisting a warm handle across restarts.
+
+A gateway declaration uses the same `deployment` map plus
+`gatewayDeploymentId`, with `model` set to the native model and `controlUrl` to
+its native endpoint. The reader compares a single matching LiteLLM route's id,
+model and API base before contacting that control endpoint. Failover or multiple
+replicas invalidate that binding. Even a matching route remains passive:
+end-to-end native control transport and reliable request affinity have not been
+validated on the configured gateway. No gateway credentials are forwarded to
+native discovery.
+
+The warm owns one request and at most one newer pending trigger. Pending work
+expires after 30 seconds. The default bound is 8192 estimated input tokens and
+a 30-second client deadline, with a 60-second cooldown; configured deadlines
+cannot exceed two minutes. Context transforms run before the input estimate.
+The one-token output and dummy suffix do not enter the conversation. The warm
+uses observe-only residency and `autoload=false` on native llama requests, so
+it cannot use the ordinary turn's implicit administrative authority.
+
+Admission retains the blanket active-dispatch refusal, checks shared Clio
+worker leases/reservations, and reads live native slots for foreign traffic.
+These are conservative admission observations, **not a global endpoint
+reservation**. Another process can begin work after the check. A foreground
+submit detaches a non-preemptible warm; its usage and local endpoint occupancy
+remain owned until the client round actually settles. Shutdown aborts detached
+rounds as well. Client cancellation never proves the server has stopped;
+subsequent admission must observe the backend again.
+
+`prewarm` custom ledger entries contain the actual usage, backend timings and
+deployment observation. `prewarmSkipped` records changed refusal reasons such
+as `deployment-unbound`, `model-not-loaded`, `deployment-build-mismatch`,
+`gateway-route-mismatch`, `gateway-cache-transport-unverified`,
+`vllm-scheduler-unverified`, `cooldown` and `expired`. These records contain no
+prompt payloads. Diagnostic payload capture remains a separate explicit opt-in.
+
+Turn off speculative work with `chat.prewarm: false`. Remove `cache.deployment`
+to return an individual target to passive operation. `cache.retention: none`
+selects the API's supported cache-off request policy and also refuses Clio
+warming; its exact effect on provider automatic caches is API-specific.
+Existing `chat.prewarm: true` configurations without deployment evidence now
+skip the speculative request. Ordinary inference remains available.
+
+No paid warming or automatic sibling-worker warming is enabled. Native workers
+retain isolated/fork/splice context selection and share Pi serialization and
+accounting, but the worker's context guard and payload hooks must be included
+in any future headless warm composition. There is no main-to-worker cache
+transfer based on ancestry.
+
+### Validation status for this change
+
+Live validation on 2026-09-11 exercised mini's `ornith1.5-35b-moe` on
+llama.cpp (`b1-c841aee`) and dynamo's `qwen3.8-27b` on LM Studio, first directly
+and then through blade's LiteLLM 1.98.0. The selected models were allowed to
+wake/load for inference; no serving configuration or administrative API was
+changed. The same native models and thinking-off intent were retained.
+
+Ten repetitions per route used about 2,850 tokens of public synthetic context
+and a bounded output. All useful requests in the corrected engine run returned
+exactly `OK`. Median client TTFT was:
+
+| Route | New prefix | Repeated prefix | After a separate warm |
+| --- | ---: | ---: | ---: |
+| Mini native | 1,691 ms | 183 ms | 163 ms |
+| Dynamo native | 1,255 ms | 156 ms | 155 ms |
+| Mini through LiteLLM | 1,706 ms | 196 ms | 173 ms |
+| Dynamo through LiteLLM | 1,259 ms | 163 ms | 162 ms |
+
+Mini reported roughly 2,834 cached tokens directly and 2,837 through the
+gateway after warming. Dynamo's OpenAI-compatible responses did not expose a
+cache-read breakdown; their normalized zero must not be presented as measured
+cache misses. Its timing improvement is an observation, not a per-request
+cache-token measurement. Gateway response metadata identified the expected
+models/deployments with no reported fallback or retry.
+
+Including the warm itself, warm plus useful request took **10.6–12.4% more
+median elapsed time** than one first request. That fails the preregistered 5%
+maximum total-time regression. Automatic warming therefore remains off by
+default. This workload favors reuse from useful requests; the after-warm TTFT
+reduction alone is not a total-work improvement. An idle-time or foreground
+contention benefit requires its own controlled measurement before rollout.
+
+Four full Clio main-agent CLI runs also completed with no tool calls and
+matching native/gateway outputs per model: mini returned `OK.`, dynamo `OK`.
+The punctuation means mini did not meet a literal exact-`OK` instruction in
+those full-prompt smoke runs; it is not hidden by the transport success. The
+engine workload above enforced the exact output separately.
+
+Four custom-worker CLI runs then returned exactly `OK`, with zero tool calls
+and succeeded outcomes. Each emitted receipt matched its persisted receipt and
+passed Clio's integrity verifier against its persisted run envelope. The mini
+worker through LiteLLM reported 719 cache-read tokens in that verified receipt.
+These checks establish transport and accounting continuity; the synthetic
+worker's task quality was not independently graded.
+
+The first exploratory driver omitted the public capability update that
+production applies after model synthesis. That made dynamo through LiteLLM
+spend its output budget on thinking. Those samples were preserved and marked
+invalid for semantic comparisons; the reported rerun includes the existing
+public update and checks visible output. This was a driver error, not a newly
+found production thinking regression.
+
+Fixtures additionally cover OpenAI/Anthropic serializers, normalized usage,
+SDK pricing tiers, failed calls, selected-target refresh, warm hooks and
+lifecycle, and deployment invalidation. Isolated/fork/splice worker context
+contracts pass. vLLM live verification is explicitly outside this local pass;
+its scheduler and APC controls remain unverified and passive.
+
+Raw local results are in `.clio-coder/artifacts/cache-live-2026-09-11T14-17-51.153Z/`,
+with full CLI events under `.clio-coder/artifacts/cache-cli-2026-09-11T14-20-44.264Z/`.
+Worker events and receipt verification are under
+`.clio-coder/artifacts/cache-worker-2026-09-11T14-26-13.738Z/`.
+The original preregistration is preserved separately from the schema-correct
+`.clio-coder/validation.yaml`. These artifacts are not distributed with a release.
+The run does not establish replica affinity guarantees, eviction/TTL behavior,
+foreign-traffic fairness, paid-provider savings, or a complete deployment pin
+for every model binary/tokenizer. Those limits prevent a general performance
+claim or enabling automatic gateway/worker warming.

package/docs/guide/configuration-reference.md

@@ -1,8 +1,5 @@
 # Configuration reference
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Configuration reference visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/configuration_reference_blueprint.html).
-
 Every switch that changes what Clio Coder does, in one place: settings keys, environment variables, CLI flags, project files under `.clio-coder/`, recipe and prompt-fragment frontmatter, tool arguments the model can send, and model knowledge-base tags. The source of truth is `src/`; this page is the audited inventory of what current source reads and is maintained alongside the code. The narrative guide is [configuration-and-targets.md](configuration-and-targets.md); operator prose for each environment variable is in [environment-variables.md](environment-variables.md).
 
 Precedence, where several surfaces set the same value: a one-run CLI flag beats a session override (`/settings`, `/model`, `/thinking`), which beats `.clio-coder/settings.local.yaml`, which beats `.clio-coder/settings.yaml`, which beats the user `settings.yaml`, which beats the compiled default. Entries whose order differs say so in their precedence column.
@@ -171,6 +168,15 @@ Precedence, where several surfaces set the same value: a one-run CLI flag beats
 | `targets[].litellm.request.tags` | `[clio-coder]` | Additional LiteLLM request tags (list of non-empty strings without commas); Clio always adds `clio-coder`. |  |
 | `targets[].litellm.request.timeoutSeconds` |  | Optional LiteLLM request/upstream timeout override sent as `x-litellm-timeout` (number from 0.001 through 86400); omit it to keep gateway policy. |  |
 | `targets[].maxConcurrentRequests` |  | Explicit request-slot limit for this inference endpoint (integer >= 1); overrides live slot discovery and is shared by every target on the same normalized URL; applies next turn. |  |
+| `targets[].cache.retention` | SDK default | Native Pi request cache policy: `none`, `short`, or `long`. Meaning depends on the selected API/model; this grants no management or paid-warming authority. | explicit call > target > Anthropic environment fallback > SDK default |
+| `targets[].cache.deployment.backend` | unset | Read-only binding to `llamacpp` or `vllm`; absence leaves warming ineligible. | target |
+| `targets[].cache.deployment.controlUrl` | unset | Explicit HTTP(S) discovery endpoint, without embedded credentials/query/fragment. No gateway credentials or administrative requests are sent here. | target |
+| `targets[].cache.deployment.model` | unset | Exact native model id, distinct from a gateway route alias. | target |
+| `targets[].cache.deployment.build` | unset | Expected worker build/version; a mismatch invalidates warm admission. Current llama warm protocol is verified against commit `c841aee`; other versions remain passive. | target |
+| `targets[].cache.deployment.gatewayDeploymentId` | unset | LiteLLM deployment id to compare against a single current `/v1/model/info` route. A match alone does not establish cache-control transport support. | target |
+| `targets[].cache.warm.maxInputTokens` | `8192` | Positive maximum estimated input tokens after engine context transforms; oversized warms are refused. This is an estimate, not a tokenizer or billing cap. | target |
+| `targets[].cache.warm.maxDurationMs` | `30000` | Positive client warm deadline, capped at 120000 ms. Client cancellation is not proof that backend computation stopped. | target |
+| `targets[].cache.warm.cooldownMs` | `60000` | Positive delay between completed warm requests; effective minimum 1000 ms. An identical prefix is suppressed for at least 60000 ms. | target |
 | `targets[].pricing.cacheRead` | `0` | USD rate for cache-read tokens (number >= 0); 0 when absent. |  |
 | `targets[].pricing.cacheWrite` | `0` | USD rate for cache-write tokens (number >= 0); 0 when absent. |  |
 | `targets[].pricing.input` |  | USD rate per input token unit used for cost accounting when set, taking precedence over catalog pricing (number >= 0); required together with `output`. |  |
@@ -721,7 +727,6 @@ Grouped by command. Global flags appear under `global`.
 | `--limit` | For `trace runs`, integer 1 to 500 number of runs to list (also `--limit=N`). |
 | `--max-age-days` | For `trace prune`, integer 1 to 36500 retention age in days for this prune only (also `--max-age-days=N`). |
 | `--max-bytes` | For `trace prune`, integer size ceiling in bytes, at least 1048576, for this prune only (also `--max-bytes=N`). |
-| `--port` | For `trace ui`, TCP port for the localhost viewer, 0 to 65535 (also `--port=N`); 0 picks an ephemeral port. |
 | `-h` | Short form of --help. |
 
 ### `uninstall`

package/docs/guide/environment-variables.md

@@ -1,8 +1,5 @@
 # Environment Variables
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Environment Variables visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/environment_blueprint.html).
-
 This page inventories Clio-specific runtime variables and the ambient variables that materially change documented operator behavior. `settings.yaml` is the durable home for operator policy; environment variables support per-process overrides, directory layout, debugging, credentials, terminal integration, and internal plumbing. When prose and source disagree, prefer the cited read site.
 
 The `environment-variable-inventory` check in `scripts/check-hygiene.ts`, run by `pnpm run lint`, enforces coverage for Clio's `CLIO_*` variables and `NO_COLOR`. It intentionally does not treat every operating-system or provider convention as a Clio knob. Examples outside that enforced family include `PATH`, `HOME`, terminal capability variables, and provider API-key names selected dynamically by `src/engine/env-api-keys.ts`.

package/docs/guide/exit-codes-and-output.md

@@ -1,8 +1,5 @@
 # Exit Codes & Machine-Readable Output Contracts
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Exit Codes & Machine-Readable Output Contracts visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/exit_codes_blueprint.html).
-
 This document specifies the process exit codes, machine-readable JSON streaming formats, standard I/O separation rules, and `--help` conventions across all Clio Coder CLI commands in the current source tree.
 
 Source implementations: `src/cli/` and `src/entry/`.

package/docs/guide/extensions-and-sharing.md

@@ -1,8 +1,5 @@
 # Extensions, Resources, and Share Archives
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Extensions, Resources, and Share Archives visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/extensions_blueprint.html).
-
 Clio Coder has two package kinds. A plugin is a domain bundle: prompts, skills, agent recipes, fleet contracts, scripts, and reference files, installed with `clio-coder library install <path>`. A harness extension is executable runtime capability: command tools and hook declarations, installed with `clio-coder extensions install <path>`. Only plugins contribute resources; see [plugins.md](plugins.md) and [harness-extensions.md](harness-extensions.md) for each contract.
 
 Share archives are portable JSON files for moving project and user Clio resources between machines or collaborators.

package/docs/guide/fleet-dispatch.md

@@ -1,8 +1,5 @@
 # Fleet Dispatch
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Fleet Dispatch visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/fleet_dispatch_blueprint.html).
-
 Clio Coder dispatches bounded worker agents. With a fleet configured, those
 workers run on remote machines over SSH while the orchestrator keeps every
 guarantee it makes locally: one admission path, one autonomy matrix, one

package/docs/guide/glossary.md

@@ -1,8 +1,5 @@
 # Clio Coder Glossary
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Clio Coder Glossary visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/glossary_blueprint.html).
-
 This document defines the 50 core architectural concepts and terminology used throughout Clio Coder, mapped to their authoritative TypeScript type definitions in `src/`.
 
 ---

package/docs/guide/harness-extensions.md

@@ -1,7 +1,5 @@
 # Harness extensions
 
-> **Visual blueprint:** See the [visual reference](../html/harness_extensions_blueprint.html) in the source checkout.
-
 Harness extensions add executable capabilities to Clio. Library recipes may also carry explicitly invoked workflow or evaluation scripts. Installing or browsing a recipe never registers harness tools, hooks, operator commands, or UI. A domain workflow that combines prompts, agents, skills, fleets, and reference files is a plugin, installed with `clio-coder library install <path>`.
 
 An extension declares command tools in `clio-coder-extension.yaml`, `.yml`, or `.json`. Clio discovers and validates declarations without importing or executing package code. Tools become available in a new session after installation. Native workers can use a tool when their admitted recipe includes its qualified name; narrower profiles such as `minimal-local` exclude extension commands.

package/docs/guide/installation-and-lifecycle.md

@@ -1,8 +1,5 @@
 # Installation and Lifecycle Operations
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Installation and Lifecycle Operations visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/lifecycle_blueprint.html).
-
 Clio Coder installs from the npm registry as `@iowarp/clio-coder` using npm,
 pnpm, or Bun, or from a source checkout using the pinned pnpm workflow. The
 [README installation guide](../../README.md#install) covers global installs,
@@ -48,7 +45,7 @@ npm install -g @iowarp/clio-coder --omit=optional
 # Or: bun add -g @iowarp/clio-coder --omit=optional
 ```
 
-Measured on Linux x64 with a production install (`--omit=dev`): 387MB across 118 packages with the SDK, 143MB across 109 packages without it. That is 244MB and nine packages saved, a 63% smaller tree, and what remains is fully open-licensed.
+Historical Linux x64 measurement before the web package integration (`--omit=dev`): 387 MB across 118 packages with the SDK, 143 MB across 109 packages without it. Treat those numbers as a comparison, not the current install size: the platform, dependency versions and optional packages change the total. The release tarball size excludes separately installed npm dependencies.
 
 Everything except the `claude-sdk` runtime works on the smaller install: boot, `clio-coder doctor`, every other target and worker runtime. Dispatching a `claude-sdk` target on an install that omitted the package fails that run with a diagnostic naming the package and the command that fixes it (`npm install @anthropic-ai/claude-agent-sdk@0.3.186`); nothing else degrades, and nothing fails at startup.
 

package/docs/guide/interop.md

@@ -1,7 +1,5 @@
 # Coding agent interoperability
 
-> **Visual blueprint:** See the [visual reference](../html/interop_blueprint.html) in the source checkout.
-
 Interoperability runs both ways. Inbound, Clio can discover resources held by
 Claude Code, Codex, Antigravity CLI, GitHub Copilot CLI, and OpenCode, then adopt
 safe text resources into the library after approval. Outbound, the same canonical

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

@@ -1,8 +1,5 @@
 # Panes and the Files Pane
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Panes and the Files Pane visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/panes_files_blueprint.html).
-
 This page is the operator's path from a clean machine to a working files pane
 beside a Clio Coder session: what to install, how a session joins its pane
 host, the commands and keys, the settings that govern them, what `doctor`

package/docs/guide/plugins.md

@@ -1,8 +1,5 @@
 # Portable plugins and the library
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Plugins visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/plugins_blueprint.html).
-
 A plugin is a complete, versioned bundle of skills and supporting files. The portable root `plugin.json` follows [Agent Plugins 1.0.0](https://agent-plugins.org/). Clio reads native prompts, agent recipes, and fleets from its namespaced manifest extension. Installing a bundle keeps those resources and their references together.
 
 Browse the bundled catalog, preview a complete installation, then install it:

package/docs/guide/proactive-memory.md

@@ -1,8 +1,5 @@
 # Proactive task memory
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Proactive task memory visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/proactive_memory_blueprint.html).
-
 Clio's proactive task memory protects long-running work from behavioral state
 decay: a requirement, environment fact, failed attempt, or diagnosis can still
 exist in the transcript while no longer influencing the next action. The design

package/docs/guide/resource-library.md

@@ -1,7 +1,5 @@
 # Library packages
 
-> **Visual blueprint:** See the [Library visual reference](../html/resource_library_blueprint.html) in the source checkout.
-
 The **library** is Clio's collection of installable **packages**. Each package has one kind: `plugin`, `skill`, `agent`, `prompt`, or `fleet`. Every kind uses a root `plugin.json`, an explicit Semantic Version, a full-tree SHA-256 pin, and the same installation state. A plugin bundles several resources; each other kind exposes one public resource and may include supporting files.
 
 ## Browse and install

package/docs/guide/skills-marketplace.md

@@ -1,7 +1,5 @@
 # Skills in the library
 
-> **Visual blueprint:** See the [Skills visual reference](../html/skills_blueprint.html) in the source checkout.
-
 Skills are one kind of [library package](resource-library.md). `/skills` opens the Library overlay's skill tab directly, while `/library` opens the full overlay (covering skills, plugins, agents, prompts, and fleets). `/skill <name>` invokes a skill, and `/skill off` clears the session's active tool surface; bare `/skill` returns usage guidance pointing to `/skills`. Skill packages use the same manifest, version, full-tree digest, origins, scope and lifecycle as every other package.
 
 ```bash

package/docs/guide/tool-usage.md

@@ -1,8 +1,5 @@
 # Tool Usage Reference
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Tool Usage Reference visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/tool_usage_blueprint.html).
-
 This is the deep usage reference behind the deliberately terse tool descriptions in the prompt envelope. Toolkit v2 keeps rich guidance out of tool descriptions and puts it here, where `context(scope="docs", query=...)` retrieves it section by section. Each tool below has its own self-contained `##` section covering the argument surface, defaults, truncation and continuation behavior, and concrete calls. Source of truth is `src/tools/`.
 
 In the current source tree, `src/tools/agent-tools.ts` serves as the single agent-tool adapter across both orchestrator and worker runtimes. Both surfaces resolve their executable tools through the exact same `effectiveToolNames` narrowing, ensuring that attested tool schemas never drift from the tools available at runtime. Tools are keyed strictly by the `ToolName` union with no alias table. Argument leniency for weak-model callers is provided exclusively by per-tool `prepareArguments` normalizers declared on `ToolSpec`.

package/docs/guide/troubleshooting.md

@@ -1,8 +1,5 @@
 # Troubleshooting & Error Remediation
 
-> **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.

package/docs/history/config-knobs-audit.md

@@ -1,8 +1,5 @@
 # Config Knobs Audit (Historical Appendix)
 
-> **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.

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

@@ -1,8 +1,5 @@
 # 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

package/docs/process/development-pipeline.md

@@ -1,8 +1,5 @@
 # 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

package/docs/process/documentation-coverage.md

@@ -1,14 +1,14 @@
 # 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.
 
+The HTML coverage below is historical. The current application renders the
+Markdown source directly; the parallel HTML tree has been retired.
+
 ## Headline
 
 - Markdown pages audited: **51**.

package/docs/process/documentation-guide.md

@@ -1,8 +1,5 @@
 # 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.
 
 ---
@@ -33,7 +30,7 @@ Classify claims clearly:
 | --- | --- | --- |
 | [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. |
+| [documentation-guide.md](documentation-guide.md) | `docs/**`, `src/**`, `tests/**` | Documentation structure, source ownership, writing rules, and rendering 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. |
@@ -72,7 +69,7 @@ Classify claims clearly:
 | [development-pipeline.md](development-pipeline.md) | `library/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. |
+| [performance-methodology.md](performance-methodology.md) | `src/interactive/render-trace.ts`, `src/interactive/**`, `tests/extended/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 nine `clio-coder trace` subcommands: `runs`, `phases`, `tail`, `procs`, `code-steps`, `inspect`, `prune`, read-only `sql`, and `ui`. |
@@ -130,25 +127,21 @@ Use alerts sparingly:
 
 ---
 
-## Blueprint coverage and format strategy
-
-Clio Coder maintains two complementary documentation formats:
+## One source, generated presentation
 
-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"]`.
+The Markdown tree is the canonical reference for people and agents. The web
+application generates the reading view, navigation, search index and heading
+outline from those same files. It supplies the theme, code-copy controls and
+safe diagram rendering. Do not author or regenerate parallel HTML documents.
 
-### Blueprint Creation Policy
+Keep `docs/README.md` organized around reader goals. Its linked tables define
+the navigation groups; all discovered Markdown pages also appear in the full
+inventory. Use descriptive headings and relative links so the renderer can
+create stable anchors and keep navigation inside the application.
 
-Blueprint coverage is explicit rather than inferred from document style. The
-page-level audit lives in
-[`documentation-coverage.md`](documentation-coverage.md). Every canonical Markdown page
-has a dedicated blueprint. Recheck the complete inventory during each release cut. `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.
-`pnpm 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.
+`pnpm run lint` checks source-corpus coverage and rejects links to retired HTML.
+The web documentation tests walk every page, verify its rendered heading targets
+and internal links, and check that unsafe content cannot become executable HTML.
 
 ---
 
@@ -162,7 +155,7 @@ When a feature changes:
 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 `pnpm run lint` to verify Markdown and HTML blueprint parity.
+7. Run `pnpm run lint` and the web documentation tests to verify corpus coverage, links and rendering.
 
 Suggested local link check:
 

package/docs/process/eval-runner.md

@@ -1,8 +1,5 @@
 # Clio Coder Local Evaluation Runner
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Clio Coder Local Evaluation Runner visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/eval_blueprint.html).
-
 The local evaluation runner executes repository-local YAML task suites as deterministic subprocess checks. It is useful for comparing harness changes, prompts, tools, or local workflows.
 
 Source of truth: [src/domains/eval/](../../src/domains/eval/) and [src/cli/eval.ts](../../src/cli/eval.ts).

package/docs/process/evals-internal.md

@@ -1,8 +1,5 @@
 # Internal Eval Suites
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Internal Eval Suites visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/evals_internal_blueprint.html).
-
 Private suites should live outside this repository. Keep datasets, prompts,
 live fleet coordinates, calibration outputs, and raw run artifacts in a private
 checkout or object store.

package/docs/process/evolution.md

@@ -1,8 +1,5 @@
 # Evolution and Change Manifests
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Evolution and Change Manifests visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/evolution_blueprint.html).
-
 Clio Coder uses change manifests to make harness changes reviewable, falsifiable, and rollback-friendly. CLIO stands for Context Layer for Input/Output, named for the Greek muse of history. A manifest is JSON, generated or checked with `clio-coder evolve manifest`, and should describe what changed, why, what evidence supports it, what could regress, how to validate it, and how to roll it back.
 
 Source of truth: `src/domains/evolution/manifest.ts`, `src/domains/evolution/validate.ts`, and `src/cli/evolve.ts`.

package/docs/process/fleet-demo-runbook.md

@@ -1,8 +1,5 @@
 # Fleet Demo Runbook
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Fleet Demo Runbook visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/fleet_demo_blueprint.html).
-
 A repeatable multi-node demonstration: one orchestrator drives a real
 CMake/C++ fix through a reviewer-gated dispatch across SSH nodes, and every
 worker's receipt (including the remote ones) verifies afterward. The steps

package/docs/process/git-commit-provenance.md

@@ -1,8 +1,5 @@
 # Git Commit Provenance
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Git Commit Provenance visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/git_commit_provenance_blueprint.html).
-
 Clio Coder adds evidence-aware role trailers to commits created through Clio.
 The feature is enabled by default:
 

package/docs/process/performance-methodology.md

@@ -1,8 +1,5 @@
 # Performance Measurement Methodology
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Performance Measurement Methodology visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/performance_methodology_blueprint.html).
-
 Clio Coder treats performance observations as diagnostic evidence, not as a
 reason to weaken behavior. Event ordering, persistence, permissions, terminal
 restoration, accessibility, output contracts, and installed-package behavior
@@ -75,7 +72,7 @@ The measurement snapshot below was originally backed by
 suite. Their names remain in the dated command transcripts below only to make
 the recorded method auditable; the commands are not current invocations.
 Current correctness coverage lives in
-`tests/contracts/rendering-invariants.test.ts`, and
+`tests/extended/rendering-invariants.test.ts`, and
 `tests/smoke/real-binary-boot.test.ts` exercises the built binary. Neither is a
 replacement glass-latency benchmark. `CLIO_CODER_RENDER_TRACE` remains the
 supported way to capture a live render trace for a fresh measurement campaign.