@iowarp/clio-coder 0.4.7 → 0.4.8

package/docs/README.md

@@ -4,9 +4,6 @@
 
 # Clio Coder documentation
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Clio Coder documentation visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/readme_blueprint.html).
-
 This is the documentation map for Clio Coder. Start with the path closest to
 what you are trying to do; the deeper references are here when you need exact
 schemas, wire contracts, or architectural invariants.
@@ -23,8 +20,7 @@ docs/
 ├── guide/          Operator and user workflows
 ├── architecture/   Runtime contracts and design
 ├── process/        Development, validation, and release practice
-├── history/        Dated records that are not current guidance
-└── html/           Source-checkout visual blueprints
+└── history/        Dated records that are not current guidance
 ```
 
 ## Start here
@@ -36,7 +32,10 @@ docs/
 | Understand what Clio may read, change, or execute | [Safety Model](architecture/safety-model.md) |
 | Diagnose a problem by its exact message | [Troubleshooting](guide/troubleshooting.md) |
 
-A minimal first run is:
+A minimal first run needs Node.js 22.19 or newer and a model to talk to: a
+local inference server such as Ollama or LM Studio, a lab gateway, or a cloud
+API. Quick Connect asks for the endpoint, a key when the server needs one, and
+a model.
 
 ```bash
 npm install -g @iowarp/clio-coder
@@ -184,12 +183,10 @@ Clio's documentation ships with Clio, not with your workspace. Everything below
 resolves from the installed package root (`resolvePackageRoot()`,
 `src/core/package-root.ts`), never from the directory you launched in.
 
-**What is indexed.** Every `.md` file under `<package-root>/docs/`, excluding
-`docs/html/`, plus root `README.md`, `CHANGELOG.md` and `CLIO-CODER.md` when each
-of those exists. The npm package ships `docs/**/*.md`, `README.md` and
-`CHANGELOG.md`; it does not ship `docs/html/` or a root `CLIO-CODER.md`, so in an
-npm install the blueprints are absent and the handbook is indexed only when you
-are running from a source checkout. The index is deterministic and needs no
+**What is indexed.** Every `.md` file under `<package-root>/docs/`, plus root
+`README.md`, `CHANGELOG.md` and `CLIO-CODER.md` when each exists. The npm package
+ships the Markdown reference used by both the application and agents. A root `CLIO-CODER.md` is indexed
+only when present, such as in a source checkout. The index is deterministic and needs no
 network or embedding service (`src/tools/context/docs-engine.ts`).
 
 **Searching and then reading.** `context(scope="docs", query="…")` returns
@@ -208,27 +205,31 @@ root**, which is that directory's parent. So when the prompt names `/pkg/docs`:
 Do not duplicate the `docs/` segment, and do not resolve a citation against the
 workspace. Omitting `query` lists the corpus instead of searching it.
 
-**The blueprint viewer.** `clio-coder docs` serves `docs/html/` from the package
-root on `127.0.0.1:<port>`. It does not look at your current directory and does
-not check whether you are in a Git checkout: the only question is whether the
-installed package has those files. When it does not, the command prints the
-packaged Markdown path and a link to the blueprints on GitHub instead of starting
-a server.
+**The web documentation.** `clio-coder docs` opens the documentation map in the
+Clio Coder web app. `clio-coder docs safety` opens the safety guide. It resolves
+content from the installed package, independent of your current project, and
+reuses this installation's background app when configured. Otherwise it starts
+a foreground loopback server; press Ctrl+C to stop. `--no-open` prints the private
+launch link without opening a browser. The command never installs a service.
+
+## Reading in the application
 
-## Interactive blueprints
+The GUI renders these Markdown sources directly with the application's theme,
+syntax highlighting, copy controls, tables and diagrams. Navigation groups come
+from this map, search indexes the same pages, and each page's outline is generated
+from its headings. Internal references stay in the application.
 
-Every Markdown page has a dedicated visual blueprint under `docs/html/`, and
-the separate `docs/html/index.html` landing page mirrors this documentation
-tree. Blueprint links use the public repository so they still work when a guide
-is read from the npm package. From a source checkout, serve the same files
-locally with:
+Edit the Markdown once to update both human and agent documentation. There is
+no separate HTML source tree, document server, or alternate reading view.
 
 ```bash
 clio-coder docs
+clio-coder docs safety
+clio-coder docs guide/configuration-reference.md --no-open
 ```
 
-The Markdown pages are the portable reference and ship with the npm package.
-The HTML blueprints are development aids and are not required for the runtime.
+The Markdown files remain the portable reference for the CLI, agents, editors,
+and repository readers. Opening documentation does not require a model connection.
 
 ## Writing documentation
 

package/docs/architecture/acp.md

@@ -1,8 +1,5 @@
 # Agent Client Protocol (ACP) Server
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Agent Client Protocol (ACP) Server visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/acp_blueprint.html).
-
 This document defines the architecture, transport protocols, tool mediation layers, permission handling, and error taxonomy for Clio Coder's Agent Client Protocol (ACP) server implementation in the current source tree.
 
 Source implementations: `src/engine/acp/` and `src/cli/acp.ts`.
@@ -14,11 +11,10 @@ Source implementations: `src/engine/acp/` and `src/cli/acp.ts`.
 Clio Coder provides a native ACP server via the `clio-coder acp` command. The server implements the open Agent Client Protocol specification (ACP v1 / schema 0.4.5) over standard I/O JSON-RPC 2.0 transport (`src/engine/acp/transport.ts`).
 
 The ACP server allows external IDEs, editors (such as Zed), and automated orchestration engines to drive Clio Coder sessions over a structured protocol.
-The source tree includes the `apps/workbench` localhost desktop client. Its ACP
-adapter supports session browsing and deletion, safe settings, target probes,
-usage, recovery, evaluation inventory, routing and dispatch inspection, toolchain
-status, agent attribution, and the live fleet event strip. The workbench is a
-source application and is not included in the published CLI package.
+The source tree includes the `apps/clio-coder-web` application, which supervises
+ACP children and exposes session operations through authenticated local REST and
+SSE. The earlier `apps/workbench` client is retained as reference source and is
+excluded from workspace builds, publication, and product gates.
 
 ```mermaid
 graph LR
@@ -186,7 +182,7 @@ Every frame the server writes is bounded (`src/engine/acp/types.ts`). Every cap
 
 ### Admission failure
 
-A prompt Clio cannot start fails with `prompt_not_admitted` and zero preceding `session/update` notifications. `data.reason` is one of `orchestrator-not-configured`, `target-unknown`, `target-not-configured`, `target-not-found`, `runtime-not-registered`, `model-not-configured`, `chat-unsupported`, `streaming-unsupported`, or the catch-all `admission-failed`. That list is closed and the server enforces it: the engine's runtime-resolution diagnostics are a larger and faster-moving vocabulary (`runtime-target-unsupported`, `runtime-use-unsupported`, `required-capability-missing`, and others), and any reason outside the list is reported as `admission-failed` rather than teaching clients a code the profile never promised. The two halves of an unconfigured orchestrator are distinguished: no `chat.target` reports `orchestrator-not-configured`, and a configured target with no `chat.model` reports `model-not-configured`, so a client is pointed at the half of the settings that is actually missing. The message is a sanitized one-line sentence and never contains the settings path. A failure after admission fails with `turn_failed` instead. Readiness before the first prompt is unchanged and lives in the CLI: `paths --json` for home identity, `doctor --json` for installation sanity, and `targets --json [--probe]` for target, auth, and health. `--probe` performs a request to the configured endpoint, so the client decides when that is allowed.
+A prompt Clio cannot start fails with `prompt_not_admitted` and zero preceding `session/update` notifications. `data.reason` is one of `orchestrator-not-configured`, `target-unknown`, `target-not-configured`, `target-not-found`, `runtime-not-registered`, `model-not-configured`, `chat-unsupported`, `streaming-unsupported`, `authentication-required`, or the catch-all `admission-failed`. That list is closed and the server enforces it: the engine's runtime-resolution diagnostics are a larger and faster-moving vocabulary (`runtime-target-unsupported`, `runtime-use-unsupported`, `required-capability-missing`, and others), and any reason outside the list is reported as `admission-failed` rather than teaching clients a code the profile never promised. The two halves of an unconfigured orchestrator are distinguished: no `chat.target` reports `orchestrator-not-configured`, and a configured target with no `chat.model` reports `model-not-configured`, so a client is pointed at the half of the settings that is actually missing. The message is a sanitized one-line sentence and never contains the settings path. A failure after admission fails with `turn_failed` instead. The server checks credential availability through the provider auth contract before admitting a prompt; `authentication-required` carries no environment-variable name, credential, or provider prose. A background service does not inherit terminal-only API keys: save the key with `clio-coder auth login <target>`, then close and reopen the session. Other readiness checks before the first prompt live in the CLI: `paths --json` for home identity, `doctor --json` for installation sanity, and `targets --json [--probe]` for target, auth, and health. `--probe` performs a request to the configured endpoint, so the client decides when that is allowed.
 
 ### Permission requests
 

package/docs/architecture/alcf-provider.md

@@ -1,8 +1,5 @@
 # ALCF Inference Provider
 
-> **Visual blueprint:** The source checkout includes the complete
-> [ALCF Inference Provider visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/alcf_blueprint.html).
-
 Clio can use Argonne's ALCF inference gateway as an OpenAI-compatible target
 backed by Globus OAuth. The runtime id is `alcf`; each configured target points
 at one gateway cluster URL, such as Sophia or Metis.

package/docs/architecture/architecture.md

@@ -1,8 +1,5 @@
 # Clio Coder Architecture and Boundaries
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Clio Coder Architecture and Boundaries visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/architecture_blueprint.html).
-
 Clio Coder is an experimental, terminal-first coding harness for the CLIO ecosystem. CLIO stands for Context Layer for Input/Output; the project is named for the Greek muse of history and developed by the Gnosis Research Center at Illinois Tech. Its architecture favors small, auditable subsystems over a single monolithic agent loop: CLI entry points, the interactive TUI, provider/runtime code, worker subprocesses, tools, and feature domains are kept separate so local-model support and scientific-software workflows can evolve without collapsing safety boundaries.
 
 This page is source-code aligned for the current source tree.

package/docs/architecture/artifact-placement.md

@@ -1,8 +1,5 @@
 # Artifact Placement
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Artifact Placement visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/artifact_placement_blueprint.html).
-
 Every file Clio generates has one home, decided by who reads it. The rule that
 follows from that: **the repo working tree holds files a human asked for.**
 Anything Clio produced on its own initiative lands in the project-local

package/docs/architecture/artifact-versions.md

@@ -1,8 +1,5 @@
 # Artifact Versions & Serialization Contracts
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Artifact Versions & Serialization Contracts visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/artifact_versions_blueprint.html).
-
 This document is an operator-facing registry of compatibility-sensitive file
 formats, serialized structures, integrity digests, and migration rules in the
 current source tree. It is not an exhaustive inventory of every internal store

package/docs/architecture/capacity-and-scheduling.md

@@ -1,8 +1,5 @@
 # Capacity Leases & Fleet Scheduling
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Capacity Leases & Fleet Scheduling visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/capacity_scheduling_blueprint.html).
-
 This document specifies the multi-process capacity leasing protocols, node
 scheduling models, cross-process transaction locks, and failure recovery
 mechanics in the current source tree.

package/docs/architecture/context-engine.md

@@ -1,8 +1,5 @@
 # Context Engine
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Context Engine visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/context_blueprint.html).
-
 Clio Coder tracks context pressure, records per-turn snapshots, and protects the provider context with bounded tool results plus single-threshold compaction.
 
 Source of truth lives in `src/domains/session/context-accounting.ts`, `src/domains/session/context-ledger.ts`, `src/domains/session/compaction/`, `src/domains/context/working-set/`, `src/domains/session/migrations/index.ts`, and the chat-loop integration in `src/interactive/chat-loop.ts`.

package/docs/architecture/context-working-set.md

@@ -1,8 +1,5 @@
 # Working Set
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Working Set visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/context_working_set_blueprint.html).
-
 The working set is the part of the session ledger the model actually receives on the next request. When context pressure crosses `context.compaction.threshold`, Clio narrows that view before it considers summarizing anything: selected tool-result bodies and closed-turn thinking blocks stop being replayed, and a one-line marker takes each body's place. Nothing is deleted. The ledger keeps every byte the tools produced, the transcript keeps showing them, and the model can ask for any evicted body back by ref.
 
 Source of truth is `src/domains/context/working-set/` (`contract.ts`, `fold.ts`, `project.ts`, `marker.ts`, `protect.ts`, `engine.ts`, `recall.ts`, `policies/`), the ledger records in `src/domains/session/entries.ts`, and the compaction stage in `src/interactive/turn-context.ts` (`runAutoCompact`).

package/docs/architecture/dispatch-architecture-rationale.md

@@ -1,8 +1,5 @@
 # Dispatch Architecture Rationale
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Dispatch Architecture Rationale visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/dispatch_rationale_blueprint.html).
-
 Why `src/domains/dispatch/` is one domain, why one import out of it looks
 irregular and is allowed to, and why the repository has no barrel-only import
 convention. No code moved as a result of this document. It exists so that a

package/docs/architecture/dispatch-typed-intent.md

@@ -1,8 +1,5 @@
 # Typed Dispatch Intent: Migration and Refusal Policy
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Typed Dispatch Intent: Migration and Refusal Policy visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/dispatch_typed_intent_blueprint.html).
-
 Typed dispatch intent is the structured declaration of what a dispatched worker
 may read, may write, is expected to produce, and must verify. It replaces the
 practice of reconstructing that answer from optional `writeRoots` plus path-like

package/docs/architecture/evidence-and-memory.md

@@ -1,8 +1,5 @@
 # Evidence Corpus and Long-Term Memory
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Evidence Corpus and Long-Term Memory visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/memory_blueprint.html).
-
 Clio Coder treats run claims and agent lessons as structured artifacts to support reproducibility and scientific provenance. In evaluations such as [SWE-bench](https://www.swebench.com), capturing granular execution evidence is essential for validating agent claims. Evidence corpora are deterministic directories built from run ledgers, receipts, sessions, audits, and eval artifacts. Currently, forensic evidence auto-builds on dispatch run completion: when a run finalizes, the observability domain automatically compiles the evidence bundle under `<dataDir>/evidence/run-<id>/` and updates a compact sidecar index row in `<stateDir>/evidence-index.json`. Long-term memory records are local, evidence-linked, and only injected after explicit approval. Use the TUI [`/view`](observability.md) command for interactive inspection of receipts, dispatch output, durable tool output, compaction summaries, and session accountability before building or citing evidence.
 
 Source of truth: `src/domains/evidence/**`, `src/domains/memory/**`, `src/cli/evidence.ts`, and `src/cli/memory.ts`.

package/docs/architecture/library.md

@@ -1,7 +1,5 @@
 # Library architecture
 
-> **Visual blueprint:** See the [Library architecture visual reference](../html/library_blueprint.html) in the source checkout.
-
 Clio uses **library** for the collection and **package** for a distributable item. This name covers both local authoring and indexed distribution without suggesting a remote store or a purchase. CLI `library`, slash `/library`, the Library overlay and the bundled `library/registry.yaml` describe the same collection. The Pi API snapshot does not contain the retired command names, so top-level `plugins`, top-level `skills`, and `/resources` are removed rather than retained as aliases. Retired slash commands `/plugins` and `/resources` return an explicit usage error pointing to `/library` (for recipe packages) and `/extensions` (for harness extensions). Bare `/skill` returns usage guidance pointing to `/skills`, while `/skill <name>` activates a skill and `/skill off` clears the active skill's armed tool surface (without erasing instructions already loaded in transcript or context).
 
 ## Invariants

package/docs/architecture/middleware-and-components.md

@@ -1,8 +1,5 @@
 # Middleware and Component Registry
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Middleware and Component Registry visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/middleware_blueprint.html).
-
 Clio Coder has two related but separate surfaces:
 
 1. **Components**: deterministic inventory of files that can affect harness behavior.

package/docs/architecture/model-catalog.md

@@ -1,8 +1,5 @@
 # Model Catalog, Runtime Refresh, and Field Notes
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Model Catalog, Runtime Refresh, and Field Notes visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/models_blueprint.html).
-
 Clio Coder treats a selectable model as the intersection of three sources:
 
 1. **Configured targets** in `settings.yaml` (`targets[]`, `defaultModel`, and optional `wireModels`).
@@ -225,7 +222,7 @@ When an LLM response is interrupted because it hits an output token limit during
    - Replay repair does not mutate saved session transcripts, original stop reasons, usage metrics, or thinking signatures.
    - If target model, provider, or API switches, or reasoning is turned off, this narrow request repair is skipped and existing conversion policy applies; opaque signatures and cross-model conversions retain their original provider semantics.
    - A per-response output-token cap does not cap total task tokens or guarantee completed task execution; existing repair and deadline limits continue to apply.
-   - Verified by contract suite `tests/contracts/reasoning-length-replay.test.ts`.
+   - Verified by contract suite `tests/extended/reasoning-length-replay.test.ts`.
 
 ---
 

package/docs/architecture/observability.md

@@ -1,8 +1,5 @@
 # Observability Viewer
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Observability Viewer visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/observability_blueprint.html).
-
 `/view` is the interactive artifact viewer for a Clio session. It keeps the live transcript compact while preserving a full inspection path for durable artifacts, task ledgers, and successful workspace outputs.
 
 ```text

package/docs/architecture/pi-boundary.md

@@ -1,8 +1,5 @@
 # Pi SDK Boundary
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Pi SDK Boundary visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/pi_boundary_blueprint.html).
-
 Clio Coder pins Pi 0.85.1 as its provider, agent-loop, and terminal SDK. This
 page records where Pi owns a reusable primitive and where Clio deliberately
 keeps product behavior. Review this table on every Pi upgrade. An action marked
@@ -111,7 +108,7 @@ else, `src/interactive/**` included, reaches Pi through engine re-exports such a
 graph, alongside five other isolation rules including the Stage 0 instant-shell
 closure (`STAGE_0_OWNER`, `STAGE0_SEAMS`). `tests/contracts/engine-lifecycle.test.ts`
 covers agent-loop ordering, reset, tool-argument normalization, the keybinding
-table and alt-screen render seams; `tests/contracts/tool-boundaries.test.ts`
+table and alt-screen render seams; `tests/extended/tool-boundaries.test.ts`
 covers tool schema admission and execution isolation across runtimes.
 
 ## Pi regression net
@@ -121,11 +118,11 @@ Run these contracts first on a Pi bump, before the full gate:
 - `tests/boundaries/check-boundaries.ts` (static architecture boundaries and Stage 0 seams)
 - `tests/contracts/engine-lifecycle.test.ts` (agent-loop ordering, reset, tool-argument normalization, keybinding table, alt-screen render seams)
 - `tests/contracts/provider-transport.test.ts`
-- `tests/contracts/openrouter-transport.test.ts`
-- `tests/contracts/provider-context-boundary.test.ts`
-- `tests/contracts/rendering-invariants.test.ts`
-- `tests/contracts/gemma-channel-filter.test.ts`
-- `tests/contracts/tool-boundaries.test.ts`
+- `tests/extended/openrouter-transport.test.ts`
+- `tests/extended/provider-context-boundary.test.ts`
+- `tests/extended/rendering-invariants.test.ts`
+- `tests/extended/gemma-channel-filter.test.ts`
+- `tests/extended/tool-boundaries.test.ts`
 - `tests/contracts/session-durability.test.ts`
 - `tests/smoke/process-lifecycle.test.ts`
 

package/docs/architecture/prompt-envelope-and-tools.md

@@ -1,8 +1,5 @@
 # Prompt Envelope and Tools
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Prompt Envelope and Tools visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/tools_blueprint.html).
-
 Clio Coder keeps the model-facing envelope stable and moves enforcement into the runtime registry and safety policy.
 
 Source of truth: `src/core/tool-names.ts`, `src/tools/agent-tools.ts`, `src/tools/bootstrap.ts`, `src/tools/policy.ts`, `src/tools/observation.ts`, `src/tools/ignore-policy.ts`, and the per-tool modules under `src/tools/**`.
@@ -217,7 +214,7 @@ For aggregate cost and token facts across sessions, use `clio-coder usage report
 
 ## Self-documentation retrieval
 
-`context(scope="docs")` is the model-facing companion to the human `clio-coder docs` server. From a source checkout, the server serves `docs/html/**` blueprints for people; in every installation, the docs scope indexes the bundled Markdown corpus for agents. It is deterministic and offline: no embeddings service, network call, or filesystem write is needed.
+`context(scope="docs")` is the model-facing companion to `clio-coder docs`, which opens the human documentation in the unified web app. The app renders the bundled Markdown corpus directly, with generated navigation and heading outlines. The docs scope indexes that same corpus for agents. It is deterministic and offline: no embeddings service, network call, or filesystem write is needed.
 
 The search index splits markdown into heading-delimited sections, records heading breadcrumbs and line ranges, and ranks results with light stemming, controlled Clio vocabulary aliases, phrase boosts, and BM25-style body scoring. The tool returns compact JSON containing corpus metadata, normalized and expanded query terms, and ranked hits with `file`, `heading`, `breadcrumb`, `anchor`, section `lines`, `snippetLines`, a bounded `snippet`, `matchedTerms`, `signals`, `coverage`, and `score`. `limit` defaults to 5 sections and caps at 12. The per-file filter the pre-consolidation docs tool accepted was dropped; narrow with more specific query terms instead. Even an empty result is valid JSON with empty arrays and a populated `next` continuation.
 

package/docs/architecture/provider-adapter-cookbook.md

@@ -1,8 +1,5 @@
 # Provider Adapter Cookbook
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Provider Adapter Cookbook visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/provider_adapter_blueprint.html).
-
 This cookbook guides developers through implementing custom model runtimes and inference server integrations within Clio Coder. It explains the runtime descriptor interfaces, probing protocols, model synthesis, and how to configure reasoning and thinking behaviors.
 
 Source of truth:
@@ -164,7 +161,7 @@ level onto `thinking.type: "adaptive"` plus `output_config.effort` (read from th
 `thinkingLevelMap` and `compat.forceAdaptiveThinking`) or onto a bounded `budget_tokens` for
 budget-based models. Clio's `onPayload` hook no longer rewrites those fields; it only sets the
 OpenAI Responses `reasoning.summary` verbosity, which the agent loop cannot express as an option.
-`tests/contracts/thinking-off-wire.test.ts` locks the local LM Studio and
+`tests/extended/thinking-off-wire.test.ts` locks the local LM Studio and
 llama.cpp controls used when thinking is off. Anthropic request assembly is
 inherited from the pinned Pi dependency; Clio no longer carries a separate
 contract test that reconstructs Pi's whole adaptive or budget payload.

package/docs/architecture/safety-model.md

@@ -1,8 +1,5 @@
 # Clio Coder Safety Model
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Clio Coder Safety Model visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/safety_blueprint.html).
-
 Clio Coder's safety posture is code-enforced, not prompt-only. As the orchestrator coding agent in the [IOWarp](https://iowarp.ai) ecosystem developed by the [Gnosis Research Center](https://grc.iit.edu) at Illinois Tech under NSF Award [#2411318](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2411318), Clio gates execution by target capabilities, the tool registry, the safety policy engine, project policies, protected-artifact checks, and audit receipts.
 
 Source of truth: `src/domains/safety/**`, `src/tools/registry.ts`, `src/tools/bootstrap.ts`, `src/tools/policy.ts`, `src/entry/orchestrator.ts`, `src/domains/dispatch/write-boundary.ts`, `src/interactive/view/artifacts.ts`, and `damage-control-rules.yaml`.

package/docs/architecture/session-lifecycle.md

@@ -1,8 +1,5 @@
 # Session Lifecycle
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Session Lifecycle visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/session_lifecycle_blueprint.html).
-
 This document is the authoritative specification for Clio Coder interactive and headless session lifecycles, on-disk ledger structures, tree-based conversation branching, checkpoints, and recovery protocols in the current source tree.
 
 Source implementations: `src/engine/session.ts` and `src/domains/session/`.

package/docs/architecture/time-conventions.md

@@ -1,8 +1,5 @@
 # Time and Clock Conventions
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Time and Clock Conventions visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/time_conventions_blueprint.html).
-
 This document describes the time practices implemented in the current Clio
 Coder source tree. The code distinguishes process-local elapsed spans from
 durable instants, but it does not impose one clock primitive on every module.

package/docs/architecture/trace-store.md

@@ -1,8 +1,5 @@
 # Trace store contract
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Trace store contract visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/trace_blueprint.html).
-
 Clio's trace database is a rebuildable, queryable mirror. Receipts, session
 ledgers, gate artifacts, and evidence remain the source of truth. Removing
 `<state-dir>/trace.sqlite` loses no authoritative run data.
@@ -99,7 +96,6 @@ clio-coder trace procs <runId> [--db PATH]
 clio-coder trace code-steps <rootId> [--json]
 clio-coder trace prune [--max-age-days N] [--max-bytes N] [--db PATH] [--json]
 clio-coder trace sql <SELECT query> [--db PATH]
-clio-coder trace ui [--db PATH] [--port N]
 ```
 
 `clio-coder trace --help` and every subcommand `--help` print usage and exit with code 0.
@@ -122,24 +118,36 @@ When resolving the SQLite database path:
 5. **`procs`**: Lists orchestrator and worker process executions associated with a `runId`. Displays state (`live` or `ended`), PID, process kind, name, and command string.
 6. **`prune`**: Applies the resolved age and byte retention policy while protecting queued and running runs. Text and JSON results report the policy, removed runs and rows, physical bytes reclaimed, protected runs, and whether `VACUUM` ran.
 7. **`sql`**: Executes a single read-only `SELECT` or `WITH` SQL statement against the SQLite trace database. The subcommand enforces read-only access before opening storage: queries containing semicolons or data mutation keywords (`INSERT`, `UPDATE`, `DELETE`, `CREATE`, etc.) are rejected with exit code 2. BigInt numbers in result objects format as JSON strings.
-8. **`ui`**: Launches the web-based interactive trace viewer server on the specified `--port` (default 0). This subcommand requires a source checkout containing `apps/trace-viewer/server.mjs`.
 
-### Trace Viewer Surface
+### Unified Web Trace API
 
-The viewer binds to `127.0.0.1` only and serves a read-only JSON API beside the static page:
+The source application in `apps/clio-coder-web/` replaces the separate trace
+viewer. It binds to `127.0.0.1` and requires the per-launch bearer token. The CLI
+trace commands above continue to work independently of the web process.
 
 | Endpoint | Source |
 | --- | --- |
-| `GET /api/health` | Schema version handshake. |
-| `GET /api/runs[?limit=N]` | `runs`, newest first. |
-| `GET /api/runs/:runId` | One `runs` row. |
-| `GET /api/runs/:runId/phases` | `phases`, ordered by `seq`. |
-| `GET /api/runs/:runId/events[?after=cursor&limit=N]` | `events` by rowid cursor, capped at 500 per page. |
-| `GET /api/runs/:runId/gates` | `gate_results`. |
-| `GET /api/runs/:runId/envelopes` | `envelopes`. |
-| `GET /api/runs/:runId/processes` | `processes`. |
-| `GET /api/runs/:runId/receipt` | Sidecars beside the database: `<stateDir>/receipts/<runId>.json` and the matching `<stateDir>/evidence-index.json` row. |
-
-The receipt endpoint derives `<stateDir>` from the directory holding the trace database, since `clio-coder trace ui` reads `<stateDir>/trace.sqlite`. A mirror copied away from its state directory has no sidecars, so a missing, unreadable, or malformed file yields a `null` half with HTTP 200 rather than an error. The response drops `output`, `upstreamResponses`, `routeDecision`, `briefing`, and `steering`: the panel renders provenance, not transcripts.
-
-The run page renders the task request, wall-clock duration, phase description, failure reason and retry count, a chronological log of every event type with its payload, gate verdicts and violations, the run's processes, and a receipt panel covering outcome, verification state and basis, spend, per-tool call statistics, safety counters, findings, and build provenance. Fields the harness never sealed read as absent rather than as zero.
+| `GET /api/traces/status` | Schema and availability status. |
+| `GET /api/traces/runs` | Keyset-paginated runs, with source and text filters. |
+| `GET /api/traces/runs/:runId` | One run. |
+| `GET /api/traces/runs/:runId/phases` | Phases ordered by sequence. |
+| `GET /api/traces/runs/:runId/events` | Rowid-cursor event history. |
+| `GET /api/traces/runs/:runId/live` | SSE event tail. |
+| `GET /api/traces/runs/:runId/gates` | Gate results. |
+| `GET /api/traces/runs/:runId/envelopes` | Trace envelopes. |
+| `GET /api/traces/runs/:runId/processes` | Process records. |
+| `GET /api/traces/runs/:runId/receipt` | Receipt and evidence-index sidecars. |
+
+The receipt endpoint reads sidecars beside the database. Missing or malformed
+sidecars yield a null half without failing the run page. The default projection
+omits `output`, `upstreamResponses`, `routeDecision`, `briefing`, and `steering`;
+`?include=full` explicitly requests the full receipt. The authenticated operator can
+inspect trace payloads. The browser renders all model content through its safe
+rich-content renderer.
+
+The run page shows the request, phase waterfall, duration, costs, events with
+payloads, gate decisions, processes, and receipt provenance. Unrecorded fields
+remain absent rather than becoming zero. The typed route table and OpenAPI in
+`apps/clio-coder-web/contracts/` define query parameters and response schemas.
+
+The shared `TraceReader.runsPage({before, limit, filter})` seam owns run-list pagination for the web API. It orders by `started_at DESC, run_id DESC`, returns a bounded page and `nextBefore`, and combines source, status, and search filters with bound SQL parameters. A read-only legacy database derives `source` without a migration. The app validates and encodes the cursor; it does not duplicate pagination SQL.

package/docs/architecture/tui-design.md

@@ -1,8 +1,5 @@
 # Clio TUI Design System
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Clio TUI Design System visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/tui_design_blueprint.html).
-
 This document is the reference specification for the Clio Coder TUI visual layout, styling, and behavior. It describes color semantics, the glyph vocabulary, structural recipes, and state choreography for all surfaces under [src/interactive/](../../src/interactive/).
 
 The governing principle: **the user reads state from color, structure from frames, and identity from brand marks.** Everything that is not state or structure remains visually quiet.
@@ -202,7 +199,7 @@ Interactive startup uses one terminal lease across both boot stages. Stage 0 own
 ### 5.1 Welcome Launchpad & Session Header
 
 The header has two shapes and no box. Source: `src/interactive/welcome-dashboard.ts`;
-contracts: `tests/contracts/welcome-boot-header.test.ts`.
+contracts: `tests/extended/welcome-boot-header.test.ts`.
 
 - **Launchpad (before the first prompt): exactly three rows.** A masthead with
   identity flush left and workspace flush right separated by a `frame`-token

package/docs/architecture/worker-context.md

@@ -1,7 +1,5 @@
 # Worker context inheritance
 
-> **Visual blueprint:** [Worker context visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/worker_context_blueprint.html).
-
 Clio dispatch separates **what a worker inherits** from **how workers are scheduled**. This implements the isolation, fork, and splice patterns discussed in [Organizing context in a multi-agent harness](https://www.langchain.com/blog/organizing-context-in-a-multi-agent-harness), using Clio's existing Pi agent loop and dispatch admission boundary.
 
 The default remains an isolated conversation. A native worker gets its own Pi Agent, worker system prompt, admitted tools, dynamic project context, task, and run-local accounting. Context inheritance does not grant additional tools, write roots, or autonomy. Conversation isolation is not a filesystem sandbox; use dispatch worktrees when filesystem isolation is required.
@@ -96,7 +94,7 @@ compatibility allowance and not a universal provider contract. A per-response ca
 also caps one response, not a task: it does not bound total task tokens or
 guarantee the task finishes.
 
-`tests/contracts/worker-output-settings.test.ts` covers the eight combinations of
+`tests/extended/worker-output-settings.test.ts` covers the eight combinations of
 trust state and layer (trusted project at low/medium/xhigh effort, trusted local
 override, untrusted, changed-after-trust, malformed, and user settings only).
 

package/docs/architecture/worker-dispatch-mechanics.md

@@ -1,8 +1,5 @@
 # Worker Dispatch Mechanics
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Worker Dispatch Mechanics visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/worker_dispatch_blueprint.html).
-
 This document describes the design and lifecycle of Clio Coder dispatched workers, focusing on the spawning sequence, execution isolation, the standard input/output NDJSON communication loop, and permission escalation routing.
 
 Source of truth:
@@ -231,7 +228,7 @@ The current reduced contract suite divides dispatch coverage by ownership:
 | --- | --- |
 | `tests/contracts/dispatch-lifecycle.test.ts` | Attached and detached lifecycle deduplication, durable transitions, terminal finalization, and orphan recovery from durable attempts. |
 | `tests/contracts/dispatch-admission.test.ts` | Typed-scope authority, capability pairing, deterministic capacity admission, conservative slot defaults, and ACP authority boundaries. |
-| `tests/contracts/dispatch-schema.test.ts` | Capability-shaped model schema, referenced `$defs`, and hidden-field compatibility. |
+| `tests/extended/dispatch-schema.test.ts` | Capability-shaped model schema, referenced `$defs`, and hidden-field compatibility. |
 
 Earlier releases carried separate envelope, assignment, detached-assignment,
 and failure-class test files for the detailed retry scenarios. Those files are

package/docs/guide/authoring-plugins.md

@@ -1,7 +1,5 @@
 # Authoring a portable agent plugin
 
-> **Visual blueprint:** See the [visual reference](../html/authoring_plugins_blueprint.html) in the source checkout.
-
 An agent plugin packages a workflow and its supporting resources as one versioned installation. Its canonical identity is the [Agent Plugins 1.0.0 manifest](https://agent-plugins.org/schemas/1.0.0/plugin.schema.json). Clio keeps the complete package together, verifies its full-tree digest, and discovers the resources supported by the current runtime.
 
 The minimal package has a root `plugin.json` and an immediate child skill directory:
@@ -120,7 +118,7 @@ What a peer host does *not* load matters just as much. Claude Code scans a plugi
 
 That leaves a real choice when a package should serve both audiences. Ordinary top-level `agents/` and `prompts/` directories are the recommended Clio layout and stay a valid first-class library package; the repository marketplace simply does not publish such a package, and `pnpm run library:pin` prints the reason. To publish it as well, declare its Clio resource roots at paths no peer host scans, for example `"agents": "native/agents"` in the manifest's `resources` map, and put the recipes there. The bundled `materio` package does this with its own historical directory name.
 
-Keep the skill surface intact when you edit a package: adding a `skills/` directory to a standalone skill silently stops its root `SKILL.md` from loading. `tests/contracts/library-portability.test.ts` asserts all of this for every curated package, and `scripts/verify-portable-hosts.sh` re-measures it against the real host CLIs. See [coding agent interoperability](interop.md) for the exact install commands.
+Keep the skill surface intact when you edit a package: adding a `skills/` directory to a standalone skill silently stops its root `SKILL.md` from loading. `tests/extended/library-portability.test.ts` asserts all of this for every curated package, and `scripts/verify-portable-hosts.sh` re-measures it against the real host CLIs. See [coding agent interoperability](interop.md) for the exact install commands.
 
 Harness extensions register runtime tools through the [harness extension contract](harness-extensions.md). They use a separate extension manifest and installation state, and they cannot declare domain resources: prompts, agents, skills, fleets and reference files ship in a plugin. See [plugin library usage](plugins.md) for catalogs, updates, pins and terminal UI operations.
 

package/docs/guide/built-in-agents.md

@@ -1,8 +1,5 @@
 # Clio Coder Agent Fleet
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Clio Coder Agent Fleet visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/agents_blueprint.html).
-
 Clio Coder dispatches focused fleet agents from Markdown recipes. Recipes are data files, not hidden code plugins: YAML frontmatter declares identity, tool requirements, skill bindings, audience, capability and latency classes, budget, and result contract; the Markdown body is the agent instruction text.
 
 The source of truth is `src/domains/agents/**`. Clio's agent dispatch engine and execution boundaries are built upon the [@earendil-works/pi-agent-core](https://www.npmjs.com/package/@earendil-works/pi-agent-core) library.

package/docs/guide/commands-and-modes.md

@@ -1,8 +1,5 @@
 # Commands and Modes
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Commands and Modes visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/commands_blueprint.html).
-
 Clio Coder is a terminal-first coding agent. This page is the detailed command
 reference for interactive sessions, headless runs, dispatch, verification, and
 common operator workflows; the README remains an approachable product and
@@ -73,11 +70,10 @@ For process exit codes, stdout deliverable guarantees, and machine-readable JSON
 | `clio-coder trace code-steps <rootId> [--json]` | Show the deterministic code-step records one fleet root wrote (argv, cwd, env names, exit code, duration, output digest, artifact paths). They are files beside the ledger, not rows in the mirror, so `--db` does not apply. |
 | `clio-coder trace prune [--max-age-days N] [--max-bytes N] [--db PATH] [--json]` | Apply the trace-retention policy while protecting queued and running runs; JSON reports the resolved policy, rows, runs and bytes removed, protected runs, and whether vacuum ran. |
 | `clio-coder trace sql <SELECT query> [--db PATH]` | Run one read-only query against the mirror. Only a single `SELECT` or read-only `WITH` statement is accepted; anything else exits 2. |
-| `clio-coder trace ui [--db PATH] [--port N]` | Serve the localhost-only waterfall viewer. The viewer is not part of the published package. |
 | `clio-coder dev evolve manifest init\|validate\|summarize` | Create and check typed harness change manifests. |
 | `clio-coder extensions list\|discover\|install\|enable\|disable\|remove` | Manage installed extension packages and resource roots. `clio-coder ext` is an accepted alias. |
 | `clio-coder library list\|search\|register\|inspect\|validate\|install\|update\|enable\|disable\|drift\|pin\|remove` | Manage packages of kind plugin, skill, agent, prompt or fleet at user/project scope; `install/update --dry-run` preview. `library skills` lists runtime skills; `library inventory --json` is the fixed GUI read. |
-| `clio-coder docs [topic] [--no-open]` | Serve the interactive HTML docs of a source checkout on 127.0.0.1; the npm package ships the Markdown guides only. |
+| `clio-coder docs [topic] [--no-open]` | Open the documentation in the web app, rendered directly from the canonical Markdown. Reuse the configured background app or start a foreground loopback server; `--no-open` prints its launch link. |
 | `clio-coder usage report [--repo <path>] [--days <n>] [--json]` | Cross-session usage facts from session/run ledgers and retained out-of-turn calls, including known failed-compaction spending and missing coverage. The window defaults to 30 days and the JSON schema is marked experimental. |
 | `clio-coder dev share export --out <path> [--project\|--user\|--both] [--context] [--prompts] [--skills] [--settings] [--extensions]` | Export project context, prompts, skills, settings fragments, and extension bundles. |
 | `clio-coder dev share import <path> [--dry-run] [--force] [--project\|--user] [--json]` | Import a share archive with conflict reporting. |
@@ -685,7 +681,7 @@ to execute through the existing engine worker path, the sanctioned Claude Code w
 
 | Command | Purpose |
 | --- | --- |
-| `pnpm run ci` | Local and GitHub PR gate: typecheck, lint, library package pin and skill audit checks, build, the deterministic test suite, and the trace-viewer suite. |
+| `pnpm run ci` | Local and GitHub PR gate: typecheck, lint, library package pin and skill audit checks, build, the deterministic test suite, and the web application suite. |
 | `pnpm run ci:release` | Maintainer release gate: `pnpm run ci`, then the `check-release` dist and packaging audit. |
 | `pnpm run typecheck` | Strict TypeScript pass. |
 | `pnpm run lint` | Biome checks plus `scripts/check-hygiene.ts`, which runs the boundary invariants, the library package pin and skill audit checks, and the README and docs drift rules. |