@iowarp/clio-coder 0.4.6 → 0.4.8

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
@@ -18,27 +15,27 @@ under pressure; git mechanics alone never justify a stage.
 
 | Stage | Skill | Output |
 | --- | --- | --- |
-| 1. File | [`file-ticket`](../../skills/git/file-ticket/) | A labeled GitHub issue with evidence and acceptance criteria |
-| 2. Fix | [`fix-issue`](../../skills/git/fix-issue/) | An uncommitted, verified change where failing tests preceded the fix, self-reviewed against the issue's acceptance criteria |
-| 3. Ship | [`ship`](../../skills/git/ship/) | An atomic conventional commit referencing the issue (`fixes #N`); contributors push it to their fork and open a PR, while maintainer work stays local for gated integration; merge is a human decision |
+| 1. File | [`file-ticket`](../../library/skills/git/file-ticket/) | A labeled GitHub issue with evidence and acceptance criteria |
+| 2. Fix | [`fix-issue`](../../library/skills/git/fix-issue/) | An uncommitted, verified change where failing tests preceded the fix, self-reviewed against the issue's acceptance criteria |
+| 3. Ship | [`ship`](../../library/skills/git/ship/) | An atomic conventional commit referencing the issue (`fixes #N`); contributors push it to their fork and open a PR, while maintainer work stays local for gated integration; merge is a human decision |
 
 Releases follow [release-cut-checklist.md](release-cut-checklist.md) as a
 human-gated checklist, not a skill. Worktrees
-([`worktree-create`](../../skills/git/worktree-create/),
-[`worktree-merge`](../../skills/git/worktree-merge/)),
-[`branch-closeout`](../../skills/git/branch-closeout/),
-[`resolve-merge-conflicts`](../../skills/git/resolve-merge-conflicts/), and
-[`tdd`](../../skills/coding/tdd/) are à-la-carte tools reached for when the
+([`worktree-create`](../../library/skills/git/worktree-create/),
+[`worktree-merge`](../../library/skills/git/worktree-merge/)),
+[`branch-closeout`](../../library/skills/git/branch-closeout/),
+[`resolve-merge-conflicts`](../../library/skills/git/resolve-merge-conflicts/), and
+[`tdd`](../../library/skills/coding/tdd/) are à-la-carte tools reached for when the
 situation calls for them, not stages every change passes through. An RCA
 written as the closing comment on the issue (`rca` label) is an artifact of
 hard bugs, not a mandatory toll booth. Batch ticket creation from a PRD
-bypasses stage 1 and uses [`backlog`](../../skills/planning/backlog/)
+bypasses stage 1 and uses [`backlog`](../../library/skills/planning/backlog/)
 instead; everything downstream is identical.
 
 ## Closeout
 
 A merged PR is not operationally finished until its local scaffolding is
-closed. The reusable [`branch-closeout`](../../skills/git/branch-closeout/) skill automates this verification and teardown safely. After the human merge decision:
+closed. The reusable [`branch-closeout`](../../library/skills/git/branch-closeout/) skill automates this verification and teardown safely. After the human merge decision:
 
 1. Fetch and prune, confirm the PR's merged state, and identify the resulting
    commit on `origin/main`. Direct ancestry proves an ordinary merge; a squash
@@ -142,13 +139,13 @@ or bumped; the milestone closes when the tag is published.
 
 ## Dogfooding setup
 
-The marketplace copy under `skills/git/` is the committed source of truth,
-pinned in `skills/registry.yaml` by `pnpm run skills:pin`. Runtime roots are
+The marketplace copy under `library/skills/git/` is the committed source of truth,
+pinned in `library/skills/registry.yaml` by `pnpm run skills:pin`. Runtime roots are
 gitignored, so each developer installs locally:
 
 ```bash
-cp -r skills/git/file-ticket .clio-coder/skills/   # Clio Coder
-cp -r skills/git/file-ticket .claude/skills/       # Claude Code
+cp -r library/skills/git/file-ticket .clio-coder/skills/   # Clio Coder
+cp -r library/skills/git/file-ticket .claude/skills/       # Claude Code
 ```
 
 The other pipeline skills are model-invoked from the marketplace catalog the

package/docs/process/documentation-coverage.md

@@ -1,18 +1,18 @@
 # 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**.
-- Dedicated HTML blueprints now present: **51**.
+- Dedicated HTML blueprints present after that audit: **51**.
 - Pages without a blueprint: **0**. Every Markdown page has one visual
   counterpart, so there are no exception reasons to record.
 - Pages with one or more source disagreements at `ff56ea3e`: **42**.
@@ -98,3 +98,30 @@ The source-alignment pass corrected all findings across the 42 affected
 Markdown pages. The table preserves what the audit found at `ff56ea3e`; it does
 not describe outstanding Markdown debt. Every HTML blueprint now renders the
 complete corrected counterpart and identifies its Markdown source explicitly.
+
+## Clio Coder 0.4.7 documentation refresh
+
+The 0.4.7 pass was a source-alignment pass, not a re-measurement of the 0.4.2
+audit above, whose table stands as the historical record.
+
+Pages carrying new or rewritten sections in this pass: `README.md`,
+`architecture/context-engine.md`, `architecture/library.md`,
+`architecture/model-catalog.md`, `architecture/pi-boundary.md`,
+`architecture/safety-model.md`, `architecture/session-lifecycle.md`,
+`architecture/tui-design.md`, `architecture/worker-context.md`,
+`guide/commands-and-modes.md`, `guide/configuration-reference.md`,
+`guide/extensions-and-sharing.md`, `guide/harness-extensions.md`,
+`guide/interop.md`, `guide/plugins.md`, `guide/resource-library.md`,
+`guide/skills-marketplace.md`, and `process/scientific-validation.md`, each with
+its paired blueprint.
+
+Two standing rules this pass reaffirmed. Every asserted behavior is anchored to
+the function or contract that implements it, named inline, rather than inferred
+from a UI label or a neighbouring paragraph. And a value that appears only in a
+test fixture is not a product default: the compiled defaults in
+`src/core/defaults.ts` are the authority for what ships unset.
+
+Per-run verification evidence for the refresh lives with the maintenance records
+for that sprint, not in this page. This page tracks documentation coverage, and
+run logs age out of usefulness faster than the docs they checked.
+

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. |
@@ -46,7 +43,8 @@ Classify claims clearly:
 | [configuration-reference.md](../guide/configuration-reference.md) | `src/core/defaults.ts`, `src/cli/**`, `src/tools/**`, `src/domains/agents/recipe-schema.ts`, `src/domains/providers/models/local-models/**` | Audited inventory of every settings key, environment variable, CLI flag, project-file key, frontmatter key, tool argument, and model tag with defaults and precedence. |
 | [safety-model.md](../architecture/safety-model.md) | `src/domains/safety/**`, `src/tools/registry.ts`, `src/tools/policy.ts`, `src/tools/verify/**`, `src/entry/orchestrator.ts`, `src/domains/dispatch/write-boundary.ts` | Operating posture, `resolveEffectiveAutonomy` / `resolveBaselineAutonomy`, detect-and-rollback write boundaries, approval axes, damage control, typed validation. |
 | [prompt-envelope-and-tools.md](../architecture/prompt-envelope-and-tools.md) | `src/domains/prompts/compiler.ts`, `src/interactive/chat-loop.ts`, `src/core/tool-names.ts`, `src/tools/registry.ts`, `src/tools/observation.ts`, `src/tools/agent-tools.ts` | Prompt envelope reuse, canonical tool delivery via single `agent-tools.ts` adapter, seven-plane tool surface, observation envelope, strict `ToolName` keying. |
-| [tool-usage.md](../guide/tool-usage.md) | `src/tools/agent-tools.ts`, `src/tools/registry.ts`, `src/tools/observation.ts` | In-depth reference for all 21 canonical tools, including conditional registration, parameters, typical payloads, normalizers, and error examples. |
+| [tool-usage.md](../guide/tool-usage.md) | `src/tools/agent-tools.ts`, `src/tools/registry.ts`, `src/tools/observation.ts` | In-depth reference for all 24 canonical tools, including conditional registration, parameters, typical payloads, normalizers, and error examples. |
+| [panes-and-files.md](../guide/panes-and-files.md) | `src/interactive/panes-runtime.ts`, `src/interactive/yazi-bridge.ts`, `src/domains/mux/operations.ts`, `src/domains/mux/yazi/theme.ts`, `src/cli/panes.ts` | Operator path to panes and the files pane: install, settings, doctor rows, `/files` and `Alt+E`, presets, what `/quit` closes, theme boundary, troubleshooting. |
 | [provider-adapter-cookbook.md](../architecture/provider-adapter-cookbook.md) | `src/domains/providers/registry.ts`, `src/domains/providers/types/runtime-descriptor.ts` | RuntimeDescriptor, probe(), probeReasoning(), synthesizeModel(), thinking mechanisms. |
 | [pi-boundary.md](../architecture/pi-boundary.md) | `src/engine/**`, `src/tools/truncate.ts`, `tests/boundaries/check-boundaries.ts` | Which Pi SDK capabilities Clio delegates to, which Clio-specific adapters remain, and the boundary tests that keep the split explicit. |
 | [alcf-provider.md](../architecture/alcf-provider.md) | `src/domains/providers/runtimes/cloud/alcf.ts`, `src/engine/alcf-oauth.ts` | Globus PKCE OAuth, openAuthStorage(), Sophia vLLM, Metis API, chatTemplateKwargsUnsupported. |
@@ -55,6 +53,7 @@ Classify claims clearly:
 | [fleet-dispatch.md](../guide/fleet-dispatch.md) | `src/domains/dispatch/**` | Multi-node SSH dispatch: process-safe admission, capacity leases, fleet contracts v1 through v5, v4 write boundaries, v5 plan and gate steps, bounded check/repair loops (`loop_bound_exhausted`), deterministic code steps, attestation, and receipts v20. |
 | [capacity-and-scheduling.md](../architecture/capacity-and-scheduling.md) | `src/domains/scheduling/**`, `src/domains/dispatch/capacity-lease.ts`, `src/domains/dispatch/reservation-store.ts` | Multi-process capacity leases (`dispatch-admission.json`), heartbeat TTLs, cross-process transaction locks (`dispatch-admission.json.lock`), and cluster drain controls. |
 | [worker-dispatch-mechanics.md](../architecture/worker-dispatch-mechanics.md) | `src/worker/**` | NDJSON parent-child socket protocols, control/bulk lane demuxing, watchdog timers, worker attestation (13 protocol fields), permission parking, exit codes. |
+| [worker-context.md](../architecture/worker-context.md) | `src/worker/spec-contract.ts`, `src/domains/dispatch/**`, `src/worker/**` | Worker context inheritance: isolated, fork, and splice context modes for native workers, historical message selection, and token limits. |
 | [fleet-demo-runbook.md](fleet-demo-runbook.md) | `src/domains/dispatch/**` | Multi-node fleet demo: SSH setup, C++ build/repair workflow, reviewer gates, and receipt verification v20. |
 | [session-lifecycle.md](../architecture/session-lifecycle.md) | `src/engine/session.ts`, `src/domains/session/**` | Session lifecycle, on-disk ledger format v4 (`current.jsonl`), tree branching (`tree.json`), active-path lineage selection, `/fork`, `/resume`, checkpoints, and write-ahead protected-artifact journal. |
 | [acp.md](../architecture/acp.md) | `src/engine/acp/**`, `src/cli/acp.ts` | Agent Client Protocol (ACP) server over stdio, tool mediation, non-stall permission handling, timeout bounds, and error taxonomy. |
@@ -65,19 +64,25 @@ Classify claims clearly:
 | [documentation-coverage.md](documentation-coverage.md) | `src/**` | Complete source-to-documentation mapping matrix and subsystem coverage status. |
 | [tui-design.md](../architecture/tui-design.md) | `src/interactive/theme/tokens.ts`, `src/interactive/theme/glyphs.ts` | TUI color system, glyph vocabulary (`contextReserve`), structural layouts, state choreography, code ink. |
 | [installation-and-lifecycle.md](../guide/installation-and-lifecycle.md) | `src/cli/paths.ts`, `src/cli/doctor.ts`, `src/cli/uninstall.ts`, `src/cli/removal.ts` | Installation, upgrade, reset, uninstallation, launcher ownership and what `--remove-binary` will and will not remove, partial-failure behavior, configuration folders (`credentials.yaml` `0o600`), and permissions. |
-| [release-cut-checklist.md](../history/release-cut-checklist.md) | `scripts/check-release.mjs`, `tests/smoke/installed-package.test.ts`, `.github/workflows/`, `package.json` | Historical v0.4.1 release procedure retained as evidence; future releases must draft and verify their own checklist. |
-| [development-pipeline.md](development-pipeline.md) | `skills/git/**`, `.github/**`, `scripts/check-release.mjs`, `package.json` | Issue-to-PR development lifecycle, validation, release inheritance, and the human merge boundary. |
+| [release-cut-checklist.md](release-cut-checklist.md) | `scripts/check-release.mjs`, `tests/smoke/installed-package.test.ts`, `.github/workflows/`, `package.json` | Standard release procedure: local candidate preparation, release gate verification, fast-forward landing on main, annotated tag publication, and npm publish. |
+| [release-cut-checklist.md (v0.4.1)](../history/release-cut-checklist.md) | `scripts/check-release.mjs`, `tests/smoke/installed-package.test.ts`, `.github/workflows/`, `package.json` | Historical v0.4.1 release procedure retained as evidence; future releases must draft and verify their own checklist. |
+| [development-pipeline.md](development-pipeline.md) | `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 eight `clio-coder trace` subcommands: `runs`, `phases`, `tail`, `procs`, `inspect`, `prune`, read-only `sql`, and `ui`. |
+| [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`. |
 | [eval-runner.md](eval-runner.md) | `src/domains/eval/**`, `src/cli/eval.ts` | Local YAML eval tasks, dual token accountings (`tokens.*` wire vs `receiptUsage.*` journal), fail-closed null totals, EvalArtifactV4 format, `verify.measure` task outcome recording. |
 | [evals-internal.md](evals-internal.md) | `src/domains/eval/**`, `evals/**` | Private suite handling, measurement design, and the boundary between shipped reference inputs and external campaigns. |
 | [extensions-and-sharing.md](../guide/extensions-and-sharing.md) | `src/domains/extensions/**`, `src/domains/resources/**`, `src/domains/share/**`, `src/cli/extensions.ts`, `src/cli/share.ts` | Prompt, skill, agent, fleet, and reserved theme resources; extension manifests; portable share archives. |
+| [library.md](../architecture/library.md) | `src/domains/plugins/**`, `src/domains/resources/library.ts`, `src/cli/library.ts` | Package kinds, catalog resolution, integrity, scope selection, and trust. |
 | [resource-library.md](../guide/resource-library.md) | `src/domains/resources/library.ts`, `src/cli/library.ts` | Catalog schemas, private and remote source policy, checksum pins, resource installation, and update checks. |
-| [skills-marketplace.md](../guide/skills-marketplace.md) | `src/interactive/overlays/skills-hub.ts`, `src/domains/resources/skills/marketplace.ts` | Skills Hub marketplace discovery through the install resolver, empty state, install actions, publishing flow. |
+| [skills-marketplace.md](../guide/skills-marketplace.md) | `src/interactive/overlays/library.ts`, `src/interactive/overlays/library-tabs.ts`, `src/domains/resources/skills/marketplace.ts` | Skills marketplace discovery through library overlays, catalog inspection, install actions, publishing flow. |
+| [plugins.md](../guide/plugins.md) | `src/domains/plugins/**`, `src/domains/resources/library.ts`, `src/cli/library.ts` | Portable domain bundles, library installation, enable/disable states, drift detection, pins, and package lifecycle. |
+| [authoring-plugins.md](../guide/authoring-plugins.md) | `library/**`, `src/domains/plugins/**`, `src/domains/resources/library-validation.ts` | Plugin and package structure, root plugin.json manifests, resource mapping, validation, and authoring guidelines. |
+| [harness-extensions.md](../guide/harness-extensions.md) | `src/domains/extensions/**`, `src/domains/plugins/**`, `src/interactive/**` | Harness extension lifecycle, command handlers, dynamic reload, and interaction with the Clio execution environment. |
+| [interop.md](../guide/interop.md) | `src/cli/interop.ts`, `src/domains/interop/**`, `src/interactive/overlays/interop.ts` | External coding agent interoperability: host discovery, resource inspection, safe adoption of prompts and skills into the library. |
 | [model-catalog.md](../architecture/model-catalog.md) | `src/domains/providers/catalog.ts`, `src/domains/providers/models/**`, `src/domains/providers/probe/**`, `src/domains/providers/model-capabilities.ts` | Model catalog, live probes (`--offline` toggle), exact-id selector `probeCapabilitiesForModel`, field-note promotion. |
 | [middleware-and-components.md](../architecture/middleware-and-components.md) | `src/domains/components/**`, `src/domains/middleware/**`, `src/cli/components.ts` | Active component snapshots, phase-aware middleware hook budgets (`DEFAULT_MIDDLEWARE_HOOK_BUDGETS_MS`). |
 | [scientific-validation.md](scientific-validation.md) | `src/domains/safety/rigor.ts`, `src/domains/safety/finish-contract.ts` | Advisory validation-contract patterns for scientific artifacts and HPC assumptions. |
@@ -122,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). All 51 Markdown pages
-have a dedicated blueprint. `docs/html/index.html` groups those counterparts by
-the same Guide, Architecture, Process, and History tree, while a source meta tag
-provides the one-to-one machine-readable mapping. Every mapping must remain
-unique, complete, and free of orphaned Markdown or HTML pages.
-`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.
 
 ---
 
@@ -154,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).
@@ -14,6 +11,9 @@ Source of truth: [src/domains/eval/](../../src/domains/eval/) and [src/cli/eval.
 The CLI commands under `clio-coder eval` support running, validating, reporting, comparing, and gating evaluation suites.
 
 ```bash
+clio-coder eval validate --package <path|kind:name> [--eval <name>] [--user|--project]
+clio-coder eval run --package <path|kind:name> [--eval <name>] [--user|--project] [--out <path>]
+clio-coder eval skill <name|path> [--scenario <id>] [--json]
 clio-coder eval validate --suite <suite.yaml>
 clio-coder eval run --suite <suite.yaml> [--trials <n>] [--target <id>] [--model <id>] [--out <path>] [--clio-coder-entry <path>]
 clio-coder eval run --task-file <tasks.yaml> [--repeat <n>] [--out <path>] [--clio-coder-entry <path>]
@@ -24,8 +24,9 @@ clio-coder eval inventory --json
 ```
 
 ### Command Roles
-* **`validate`**: Validates the structure and constraints of a Suite v2 YAML file without executing it.
-* **`run`**: Runs a Suite v2 (via `--suite`) or a compatibility v1 task file (via `--task-file`). Outputs a text summary and writes an eval artifact under `<dataDir>/evals/` and evidence under `<dataDir>/evidence/eval-<evalId>/`.
+* **`validate`**: Validates the structure and constraints of a Suite v2 YAML file (via `--suite`) or package evaluations (via `--package <path|kind:name> [--eval <name>]`) without executing them.
+* **`run`**: Runs a Suite v2 (via `--suite`), a compatibility v1 task file (via `--task-file`), or a packaged evaluation (via `--package <path|kind:name> [--eval <name>]`). Outputs a text summary and writes an eval artifact under `<dataDir>/evals/` and evidence under `<dataDir>/evidence/eval-<evalId>/`.
+* **`skill`**: Evaluates an individual skill directory or catalog entry against its baseline scenarios declared in `evals.md`.
 * **`report`**: Formats and prints a report from a saved `evalId`. Supports multiple `--format` outputs:
   * `text` (default): Human-readable stdout summary.
   * `json`: Raw JSON structure of the artifact.
@@ -41,7 +42,8 @@ Exit codes:
 | Command | Success | Failure |
 | --- | --- | --- |
 | `eval validate` | `0` when validation passes | `2` for validation issues |
-| `eval run` | `0` when all task repetitions pass | `1` when any task fails, `2` for invalid configs |
+| `eval run` | `0` when all task repetitions pass | `1` when any task/gate fails (including package evals), `2` for invalid configs or load errors |
+| `eval skill` | `0` when all scenarios pass | `1` for failures/regressions, `3` for unmeasured harness state or evidence errors, `2` for invalid arguments |
 | `eval report` | `0` when artifact loads | `1` if artifact cannot be read, `2` for invalid ID |
 | `eval compare` | `0` when both artifacts compare and the behavioral hard gate passes | `1` for a hard regression or unreadable artifact, `2` for invalid ID |
 | `eval gate` | `0` when correctness, safety, and hard threshold assertions pass | `1` for hard failures, unreadable inputs, and malformed threshold files; `2` for an invalid eval ID or usage error |

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
@@ -62,7 +59,7 @@ exit. This keeps diagnostic output from corrupting the temporary shell without
 changing the measured endpoints.
 
 ```bash
-CLIO_CODER_RENDER_TRACE=/tmp/clio-render.jsonl \
+CLIO_CODER_RENDER_TRACE=/tmp/clio-coder-render.jsonl \
 CLIO_CODER_TRACE_BOOT=1 \
 CLIO_CODER_INTERACTIVE=1 \
 node dist/cli/index.js
@@ -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.