@iowarp/clio-coder 0.4.0 → 0.4.2

package/docs/process/documentation-guide.md

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

package/docs/{eval-runner.md → process/eval-runner.md}

@@ -1,11 +1,11 @@
 # Clio Coder Local Evaluation Runner
 
-> [!TIP]
-> **Interactive Spec Available:** An interactive task suite validator, subprocess execution simulator, and compare calculator is located at [docs/html/eval_blueprint.html](html/eval_blueprint.html) (Version: 0.4.0).
+> **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).
+Source of truth: [src/domains/eval/](../../src/domains/eval/) and [src/cli/eval.ts](../../src/cli/eval.ts).
 
 ---
 
@@ -20,6 +20,7 @@ clio-coder eval run --task-file <tasks.yaml> [--repeat <n>] [--out <path>] [--cl
 clio-coder eval report <evalId> --format text|json|md|swe-jsonl|junit
 clio-coder eval compare <baselineEvalId> <candidateEvalId> [--metric <name>] [--format text|json|md|junit] [--allow-config-drift]
 clio-coder eval gate <candidateEvalId> --baseline <baselineEvalId> [--thresholds <file>]
+clio-coder eval inventory --json
 ```
 
 ### Command Roles
@@ -33,6 +34,7 @@ clio-coder eval gate <candidateEvalId> --baseline <baselineEvalId> [--thresholds
   * `junit`: XML report for CI/CD integration.
 * **`compare`**: Compares two evaluation artifacts (baseline and candidate) by matching tasks.
 * **`gate`**: Compares candidate metrics against baseline and absolute thresholds. Correctness and safety regressions fail independently of informational budgets.
+* **`inventory`**: Prints the fixed machine-readable inventory used by GUI hosts. It includes stored report identity, provenance, serving facts, accounting, and per-scenario outcomes without report attachments.
 
 Exit codes:
 
@@ -42,7 +44,7 @@ Exit codes:
 | `eval run` | `0` when all task repetitions pass | `1` when any task fails, `2` for invalid configs |
 | `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 any hard failure, `2` for config/invalid ID errors |
+| `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 |
 
 ---
 
@@ -75,7 +77,7 @@ tasks:
       excludes:
         - "**/node_modules/**"
     runner:
-      kind: "clio-run" # clio-run | context-index | context-init | external-command
+      kind: "clio-coder-run" # clio-coder-run | context-index | context-init | external-command
       prompt: "Optimize the FFT tolerance bounds in solver.ts"
       timeoutMs: 60000
     verify:
@@ -103,12 +105,12 @@ tasks:
 | --- | --- | --- |
 | `version` | - | Must equal `2`. |
 | `suite` | `id`, `title`, `visibility`, `description` | Metadata identifying the evaluation suite. |
-| `matrix` | `targets[]`, `repeats`, `dimensions[]` | Matrix of execution targets, repetition count, and the execution-envelope fields intentionally varied by the suite. |
-| `workspace` | `kind`, `path`, `url`, `commit`, `checkout`, `excludes` | Workspace strategy: `local` (run in-place), `git` (clone from URL), or `temp-copy` (isolated copy of a directory). |
-| `runner` | `kind`, `prompt`, `command`, `commands`, `args`, `timeoutMs` | Runner type: `clio-run` (starts Clio agent loop), `context-index` (runs indexer), `context-init` (initializes context), `external-command` (spawns subprocess). |
-| `behavioral` | `schema`, `corpus`, `execution`, `expectedBehavior`, `forbiddenBehavior`, `judge` | Optional `clio.eval.scenario.v1` behavioral contract. Rules name a closed category and a typed predicate over transcript, tool, receipt, or grader facts. |
+| `matrix` | `targets[]`, `repeats`, `dimensions[]`, `maxCostUsd` | Matrix of execution targets, repetition count, execution-envelope fields intentionally varied by the suite, and an optional cumulative known-cost ceiling. |
+| `workspace` | `kind`, `path`, `url`, `commit`, `checkout`, `excludes`, `setup` | Workspace strategy: `local` (run in-place), `git` (clone from URL), or `temp-copy` (isolated copy of a directory). Optional `setup` commands prepare the workspace before the runner starts. |
+| `runner` | `kind`, `prompt`, `autonomy`, `agent`, `command`, `commands`, `args`, `timeoutMs` | Runner type: `clio-coder-run` (starts Clio's agent loop), `context-index` (runs the indexer), `context-init` (initializes context), or `external-command` (spawns a subprocess). `agent` selects a worker recipe and `autonomy` sets one-run headless authority. |
+| `behavioral` | `schema`, `corpus`, `execution`, `expectedBehavior`, `forbiddenBehavior`, `judge` | Optional `clio-coder.eval.scenario.v1` behavioral contract. Rules name a closed category and a typed predicate over transcript, tool, receipt, or grader facts. |
 | `verify` | `commands`, `measure`, `assertions`, `forbidPaths` | Validation steps: shell commands, a task-outcome grader, metric assertions (e.g. `op: lt` for max token counts), and files/directories that must not be created or modified (`forbidPaths`). |
-| `metrics` | `collect` | List of metric names to compile for the evaluation runs. |
+| `metrics` | `collect`, `readObservation` | Metric names to compile plus optional public allowlisted and decoy paths reduced to bounded read counters. Raw path strings do not enter behavioral facts. |
 
 ---
 
@@ -120,7 +122,7 @@ tasks:
 ---
 
 ## Runner Kinds
-* **`clio-run`**: Invokes the main Clio Coder agent loop with the task's prompt, tracing all tools.
+* **`clio-coder-run`**: Invokes the main Clio Coder agent loop with the task's prompt, tracing all tools. The released `clio-run` spelling is accepted only as a legacy input alias and is normalized before validation; writers and new suites use `clio-coder-run`.
 * **`context-index`**: Triggers the context engine to build index structures (`codewiki`).
 * **`context-init`**: Initializes workspace files (such as generating `CLIO-CODER.md`).
 * **`external-command`**: Spawns an external command or sequence of commands in the task workspace.
@@ -190,7 +192,7 @@ export interface EvalArtifactV4 {
   version: 4;
   evalId: string;
   suite: { id: string; hash: string };
-  clio: EvalClioProvenance;
+  clioCoder: EvalClioProvenance;
   environment: EvalEnvironmentProvenance;
   matrix: { target: string; model: string | null; thinking: string | null };
   summary: EvalArtifactSummaryV4;
@@ -206,11 +208,11 @@ export interface EvalArtifactV4 {
 
 ## The verdict envelope
 
-Every result carries a strictly parsed `clio.eval.verdict.v1` envelope (`src/domains/eval/schema/verdict.ts`). Suite v2 results are adapted into it at one explicit boundary (`src/domains/eval/schema/adapter.ts`) rather than by widening the artifact version, because the envelope carries no information a v4 artifact cannot hold.
+Every result carries a strictly parsed `clio-coder.eval.verdict.v1` envelope (`src/domains/eval/schema/verdict.ts`). Suite v2 results are adapted into it at one explicit boundary (`src/domains/eval/schema/adapter.ts`) rather than by widening the artifact version, because the envelope carries no information a v4 artifact cannot hold.
 
 ```json
 {
-  "schema": "clio.eval.verdict.v1",
+  "schema": "clio-coder.eval.verdict.v1",
   "scenarioId": "latency-nonnegative",
   "trialIndex": 0,
   "outcome": "pass",
@@ -230,7 +232,7 @@ The envelope is fail-closed by construction. `outcome` is one of `pass`, `fail`,
 
 ### Behavioral scenario and verdict documents
 
-Behavioral evaluation is additive and does not change the persisted `clio.eval.verdict.v1` reader. A Suite v2 task may declare a `clio.eval.scenario.v1` block, and its Artifact v4 result then carries a sibling `clio.eval.behavior.v1` document whose `verdictRef` names the verdict schema, scenario id, and trial index. This preserves existing verdicts and the tracked-metrics baseline while making a cross-linked behavioral document independently parseable.
+Behavioral evaluation is additive and does not change the persisted `clio-coder.eval.verdict.v1` reader. A Suite v2 task may declare a `clio-coder.eval.scenario.v1` block, and its Artifact v4 result then carries a sibling `clio-coder.eval.behavior.v1` document whose `verdictRef` names the verdict schema, scenario id, and trial index. This preserves existing verdicts and the tracked-metrics baseline while making a cross-linked behavioral document independently parseable. Readers normalize the released `clio.eval.*` identifiers for compatibility, but current writers emit only `clio-coder.eval.*` identifiers.
 
 The closed categories are `tool_choice`, `exploration`, `delegation`, `safety_comprehension`, `claim_grounding`, `denied_tool_recovery`, `completion_behavior`, and `task_correctness`. Each category result is exactly one of `satisfied`, `violated`, `unknown`, or `unmeasured`. The document outcome is `pass`, `behavioral_failure`, `unknown`, `unmeasured`, or `infrastructure_failure`; missing facts are never invented as successes, and an infrastructure failure cannot become a behavioral pass.
 
@@ -240,8 +242,8 @@ Suite execution adapts scalar run metrics into these observable facts at the Sui
 
 ### Public built-in behavioral corpus
 
-The repository ships corpus `public-built-in-behavior` version `1.0.0` under
-`benchmarks/eval/`. It contains no private prompts, endpoints, credentials, or
+The source repository carries corpus `public-built-in-behavior` version `1.0.0`
+under `evals/`. It contains no private prompts, endpoints, credentials, or
 mutable external dataset:
 
 - `behavioral-machinery.yaml` provides one positive and one adversarial
@@ -262,12 +264,15 @@ mutable external dataset:
   that the rules can reject observed model behavior rather than merely restate
   aggregate success counters.
 
-Build once, then run either focused suite from the repository root:
+These are source-checkout workflows: the npm archive keeps the inputs for
+inspection and reproducibility, but the deterministic TypeScript driver uses
+the repository development toolchain. Build once, then run either focused
+suite from the repository root:
 
 ```sh
-node dist/cli/index.js eval run --suite benchmarks/eval/behavioral-machinery.yaml --clio-coder-entry dist/cli/index.js
-node dist/cli/index.js eval run --suite benchmarks/eval/behavioral-model.yaml --target mini --clio-coder-entry dist/cli/index.js
-node dist/cli/index.js eval run --suite benchmarks/eval/behavioral-model-negative-control.yaml --target mini --clio-coder-entry dist/cli/index.js
+node dist/cli/index.js eval run --suite evals/behavioral-machinery.yaml --clio-coder-entry dist/cli/index.js
+node dist/cli/index.js eval run --suite evals/behavioral-model.yaml --target mini --clio-coder-entry dist/cli/index.js
+node dist/cli/index.js eval run --suite evals/behavioral-model-negative-control.yaml --target mini --clio-coder-entry dist/cli/index.js
 ```
 
 The machinery tasks use the repository read-only and create only private
@@ -306,8 +311,8 @@ A dispatched worker's receipt reports `sessionId: null` and writes no session ar
 
 ### Behavioral multi-metric results
 
-A result with a `clio.eval.behavior.v1` verdict also carries the additive
-`clio.eval.behavior.metrics.v1` projection. The projection binds the scenario
+A result with a `clio-coder.eval.behavior.v1` verdict also carries the additive
+`clio-coder.eval.behavior.metrics.v1` projection. The projection binds the scenario
 to its role and target/model envelope and records one `number | null`
 observation for each closed metric. The source travels beside every value:
 
@@ -356,8 +361,8 @@ is emitted as testcase output rather than a failed testcase.
 ### Execution-envelope provenance and comparability
 
 Every newly written behavioral result carries an additive
-`clio.eval.execution-envelope.v1` sibling. Artifact v4,
-`clio.eval.verdict.v1`, and `clio.eval.behavior.metrics.v1` retain their
+`clio-coder.eval.execution-envelope.v1` sibling. Artifact v4,
+`clio-coder.eval.verdict.v1`, and `clio-coder.eval.behavior.metrics.v1` retain their
 existing identities. The envelope records the selected prompt fragment ids,
 authored versions or `unversioned` marker, fragment content hashes, prompt
 composition hash, recipe id/version/fingerprint when a worker recipe applies,
@@ -382,31 +387,15 @@ metric means and variances. When the prompt or recipe identity changes, the
 generated evidence names each affected corpus scenario and role instead of
 hiding it behind an aggregate score.
 
-### Checked behavioral release baseline
+### Reference behavioral baseline
 
-The checked deterministic baseline is
-`benchmarks/eval/behavioral-machinery-baseline.json`. The release gate runs all
-26 machinery-only scenarios through the built CLI and compares a stable
-projection of their labels, metrics, and execution envelopes with that file.
-It requires no model, private endpoint, credential, or mutable dataset.
-
-When an intentional prompt, recipe, policy, or expected-behavior change moves
-the evidence, run the same machinery suite first, inspect the failing diff and
-the named affected corpus results, then update explicitly:
-
-```sh
-npm run build
-node benchmarks/eval/check-behavioral-release.mjs --update
-git diff -- benchmarks/eval/behavioral-machinery-baseline.json
-```
-
-The baseline update belongs in the reviewed change that caused it. Do not use
-the update command merely to make a red gate green. The model-required and
-negative-control suites remain manual release evidence because their outputs
-depend on a live target; they are never folded into the deterministic baseline.
-The projection excludes `latency.wallMs` because scheduler timing is not stable
-evidence. Behavioral labels, deterministic metrics, and the execution envelope
-remain checked byte for byte.
+`evals/behavioral-machinery-baseline.json` is retained as reviewable reference
+evidence for the machinery corpus. It is not a CI or release gate. Run the
+current `evals/behavioral-machinery.yaml` through the built CLI when a prompt,
+recipe, policy, or expected-behavior change needs a fresh measurement, inspect
+the named scenario evidence, and update any retained baseline deliberately in
+the reviewed change. Model-required and negative-control suites remain manual
+measurements tied to their exact target and serving configuration.
 
 ### Hard thresholds and informational budgets
 
@@ -443,10 +432,12 @@ cannot offset a task or safety regression.
 
 ```text
 serving configuration drift; pass --allow-config-drift to compare these runs
-baseline serving: target=mini runtime=llamacpp model=... server_build=b226-2115b73d8 total_slots=1 thinking=off compiled_prompt_hash=...
+baseline serving: target=mini runtime=llamacpp model=ornith1.5-35b-moe server_build=... total_slots=4 thinking=off compiled_prompt_hash=...
 candidate serving: ...
 ```
 
+The current reference `mini` endpoint is the llama.cpp router at `192.168.86.141:8080`. It serves `ornith1.5-35b-moe` with four parallel slots and 262144 context tokens per slot. These deployment facts are reference topology, not defaults imposed on another target; retain the artifact's observed serving configuration with every comparison.
+
 `--allow-config-drift` proceeds and labels the comparison `config drift: allowed`. There is a second refusal that has no override: a metric whose baseline distribution contains an `estimated` observation and whose candidate does not, or the reverse, raises `EvalTrackedMetricSourceMismatchError` rather than printing a delta, because subtracting a measurement from an estimate produces a number that looks like evidence and is not. `--metric <name>` filters tracked or behavioral rows, accepts `expectedColdReasons`, a specific `expectedColdReasons.<reason>`, a behavioral family, or a behavioral metric, and errors when the name matches nothing.
 
 ---

package/docs/{evals-internal.md → process/evals-internal.md}

@@ -1,7 +1,7 @@
 # Internal Eval Suites
 
-> [!TIP]
-> **Interactive Spec Available:** An interactive blueprint is available at [docs/html/evals_internal_blueprint.html](html/evals_internal_blueprint.html) (Version: 0.4.0).
+> **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
@@ -15,13 +15,13 @@ clio-coder eval run --suite <external-path> --clio-coder-entry dist/cli/index.js
 ```
 
 Use `--out <dir>` when the artifact should be written outside the default Clio
-data directory. Product eval artifacts and external benchmark campaigns are
-separate: public benchmark adapters live under `benchmarks/community/` and do
-not use the eval runner.
+data directory. External benchmark campaigns should adapt their cases and
+grader observations into the same eval engine while keeping private datasets,
+credentials, endpoints, and raw artifacts outside this repository.
 
 The public behavioral corpus is the deliberate exception to the otherwise
 private Suite v2 data policy. Its reviewable, synthetic suites live under
-`benchmarks/eval/`: a model-free positive/adversarial authority pair for every
+`evals/`: a model-free positive/adversarial authority pair for every
 built-in worker recipe, four tiny main-agent model scenarios covering all eight
 behavioral categories with event- and grader-derived facts, and an intentional
 decoy negative control. The model-free driver uses the shipped recipe catalog,
@@ -83,7 +83,7 @@ thinking level is measuring the server, not the change under test.
 
 The verdict envelope keeps its original `behavioral: null` field for compatibility.
 A suite that declares a versioned behavioral scenario records the result as a
-separate `clio.eval.behavior.v1` document on the Artifact v4 result, cross-linked
+separate `clio-coder.eval.behavior.v1` document on the Artifact v4 result, cross-linked
 to the unchanged verdict identity. Its labels come only from bounded transcript,
 tool, receipt, or grader facts, never from an ungrounded judge paragraph. A run whose harness broke records
 `machinery: "infrastructure_failure"`, which the parser refuses to pair with a
@@ -210,7 +210,7 @@ tasks:
         - node_modules
         - dist
     runner:
-      kind: clio-run
+      kind: clio-coder-run
       prompt: Fix the intentionally broken function so the local verifier passes.
     verify:
       commands:
@@ -271,7 +271,7 @@ tasks:
         - dist
         - .clio-coder
     runner:
-      kind: clio-run
+      kind: clio-coder-run
       prompt: Summarize the repository purpose and make no file changes.
     verify:
       forbidPaths:
@@ -305,7 +305,7 @@ tasks:
         - dist
         - .clio-coder
     runner:
-      kind: clio-run
+      kind: clio-coder-run
       prompt: Fix the failing unit test with the smallest source change.
     verify:
       commands:

package/docs/{evolution.md → process/evolution.md}

@@ -1,7 +1,7 @@
 # Evolution and Change Manifests
 
-> [!TIP]
-> **Interactive Spec Available:** An interactive change manifest editor, authority risk assessor, and checklist workspace is located at [docs/html/evolution_blueprint.html](html/evolution_blueprint.html) (Version: 0.4.0).
+> **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.
 

package/docs/{fleet-demo-runbook.md → process/fleet-demo-runbook.md}

@@ -1,10 +1,13 @@
 # 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
 are executable in order; this document doubles as the recording script.
-Background and reference: [fleet-dispatch.md](fleet-dispatch.md).
+Background and reference: [fleet-dispatch.md](../guide/fleet-dispatch.md).
 
 ## Reference fabric
 
@@ -51,9 +54,12 @@ clio-coder doctor
 
 Doctor probes each node over its real SSH channel: reachability, a
 version-matched `clio-coder` on the remote path, path parity for the project root,
-and a writable remote state dir. Passing nodes become dispatch-eligible;
-failures are warnings that name the fix. Re-run doctor after any host,
-project, or version change; admission fails closed on a stale preflight.
+and a writable remote state dir. Those rows are read-only diagnostics: the
+current command does not create or refresh `fleet-preflight.json`, so it does
+not make a passing node dispatch-eligible. Placement can still consume an
+existing preflight record, but admission fails closed when that record is
+missing or stale after a host, project, or version change. There is currently
+no mutating doctor command that refreshes it.
 
 Confirm the durable view:
 
@@ -136,9 +142,9 @@ clio-coder evidence inspect <evidenceId>
 run ledger; a tampered or mismatched receipt fails the build with the field
 that diverged. The receipts of the remote runs verify on the orchestrator host because the
 ledger and receipts live on the shared filesystem. Current receipts use strict
-v16 and authenticate every current receipt and reconstructed-ledger field.
-Every other receipt version is rejected rather than reported as partial; the
-current binary has no historical receipt reader.
+v20 and authenticate every current receipt and reconstructed-ledger field.
+Lower versions are reported as retired and are never read as evidence or
+migrated; malformed and future shapes fail verification.
 
 ## Provenance walkthrough: what a PI can verify from receipts alone
 
@@ -168,9 +174,10 @@ reconstruct:
    complete receipt schema and its stable ledger row. `clio-coder evidence build
    --run <id>` recomputes and cross-checks it; `verifyReceiptIntegrity` in
    `src/domains/dispatch/receipt-integrity.ts` is the reference
-	implementation. Current receipts use v16 and every other version fails
-	verification. Incompatible state must be archived or removed; it is never
-	read as evidence through a compatibility verifier.
+	implementation. Current receipts use v20. Lower versions are reported as
+	retired, while malformed and future shapes fail verification. Incompatible
+	state may be archived for inspection, but it is never read as evidence through
+	a compatibility verifier.
 
 The walkthrough for an audience is three commands: `clio-coder evidence build
 --run <id>` (it verifies), open the receipt JSON (read `node`, `gate`,

package/docs/{git-commit-provenance.md → process/git-commit-provenance.md}

@@ -1,13 +1,20 @@
 # 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:
 
 ```yaml
-attribution:
-  gitCommits: true
+integrations:
+  git:
+    commitAttribution: true
 ```
 
+The released `attribution.gitCommits` path is a migration alias. Current
+settings files and writers use `integrations.git.commitAttribution`.
+
 Settings -> Advanced exposes the same switch as **Clio commit provenance**, with
 `enabled` and `disabled` values. A change applies immediately to subsequent
 commits in the session. When disabled, Clio leaves commit messages entirely
@@ -49,11 +56,11 @@ Co-authored-by: Clio Coder <clio-coder@iowarp.ai>
 Existing human trailers stay in place. A Clio trailer already present in any
 letter case is respected rather than repeated, line endings are normalized only
 while attribution is enabled, and repeated processing is idempotent. When a directly relevant
-receipt-v19 digest passes integrity verification, Clio may additionally add the
+receipt-v20 digest passes integrity verification, Clio may additionally add the
 full digest:
 
 ```text
-Clio-Evidence: receipt-v19/sha256:<64-character digest>
+Clio-Evidence: receipt-v20/sha256:<64-character digest>
 ```
 
 Clio does not invent, shorten, or add an unrelated digest. The role trailers do