@iowarp/clio-coder 0.3.0 → 0.3.1

package/docs/development-pipeline.md

@@ -0,0 +1,77 @@
+# Development Pipeline
+
+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
+harness that loads the skills (Clio, Claude Code, Codex) runs the same
+pipeline. One-shot reactive prompting is the anti-pattern this page retires:
+work that is not traceable to an issue does not merge.
+
+## The lifecycle
+
+Three stages. A skill earns a stage only when it encodes repo policy a
+model cannot guess or an irreversibility gate a small model will skip
+under pressure; git mechanics alone never justify a stage.
+
+| Stage | Skill | Output |
+| --- | --- | --- |
+| 1. File | [`file-ticket`](../skills/git/file-ticket/) | A labeled GitHub issue with evidence and acceptance criteria |
+| 2. Fix | [`fix-issue`](../skills/git/fix-issue/) | An uncommitted, verified change where failing tests preceded the fix, self-reviewed against the issue's acceptance criteria |
+| 3. Ship | [`ship`](../skills/git/ship/) | An atomic conventional commit referencing the issue (`fixes #N`), a gated push, and an open PR; merge is a human decision |
+
+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/)),
+[`resolve-merge-conflicts`](../skills/git/resolve-merge-conflicts/), and
+[`tdd`](../skills/coding/tdd/) are à-la-carte tools reached for when the
+situation calls for them, not stages every change passes through. An RCA
+written as the closing comment on the issue (`rca` label) is an artifact of
+hard bugs, not a mandatory toll booth. Batch ticket creation from a PRD
+bypasses stage 1 and uses [`backlog`](../skills/planning/backlog/)
+instead; everything downstream is identical.
+
+## Issue conventions
+
+- **Title**: conventional tag plus imperative summary (`fix: memory overlay
+  cannot scroll`), matching `.github/ISSUE_TEMPLATE/` prefixes.
+- **Body**: Problem, Reproduce, Evidence with `file:line` pointers,
+  Acceptance criteria as a verifiable checklist, Links.
+- **Labels**: exactly one type label (`bug`, `enhancement`,
+  `documentation`, `question`) plus applicable `area:*` labels.
+- **Milestone**: the open release milestone when the work is committed to
+  it; unassigned issues carry `needs-triage` until a human places them.
+
+### Label taxonomy
+
+| Kind | Labels | Meaning |
+| --- | --- | --- |
+| Type | `bug`, `enhancement`, `documentation`, `question` | What the issue is; exactly one |
+| Area | `area:tui`, `area:engine`, `area:memory`, `area:dispatch`, `area:skills`, `area:cli`, `area:api`, `area:docs` | Which subsystem; one or more |
+| Status | `needs-triage`, `rca`, `blocked` | Where in the lifecycle |
+| Community | `good first issue`, `help wanted`, `duplicate`, `invalid`, `wontfix` | GitHub defaults, unchanged |
+
+New `area:*` labels are proposed in an issue, not created ad hoc.
+
+## Milestones are releases
+
+Each open milestone is the next version (`v0.3.1`, `v0.4.0`). Triage means
+assigning an issue to a milestone or explicitly leaving it in the backlog.
+A release cut requires every issue in its milestone to be closed
+or bumped; the milestone closes when the tag is published.
+
+## Dogfooding setup
+
+The marketplace copy under `skills/git/` is the committed source of truth,
+pinned in `skills/registry.yaml` by `npm 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
+```
+
+The other pipeline skills are model-invoked from the marketplace catalog the
+same way. When a skill changes, re-run `npm run skills:pin` and re-copy;
+drift between an installed copy and the pinned hash surfaces a warning at
+activation.

package/docs/documentation-coverage.md

@@ -1,6 +1,6 @@
 # Clio Coder Documentation Coverage Matrix
 
-This matrix maps every top-level directory in `src/` and every domain directory under `src/domains/` to its authoritative documentation page. It records coverage status (`documented`, `partial`, `undocumented`), missing concepts, and key source contracts for `v0.3.0`.
+This matrix maps every top-level directory in `src/` and every domain directory under `src/domains/` to its authoritative documentation page. It records coverage status (`documented`, `partial`, `undocumented`), missing concepts, and key source contracts for `v0.3.1`.
 
 ## Coverage Matrix
 
@@ -12,7 +12,7 @@ This matrix maps every top-level directory in `src/` and every domain directory
 | `src/engine/acp/` | ACP protocol server, transport adapters, tool mediators, permission forwarding, error taxonomy | [acp.md](acp.md) | `documented` | Dedicated ACP specification covering server wiring, permission mediation, timeouts, error taxonomy, and security boundaries. |
 | `src/entry/` | Application bootstrapping, CLI router, interactive loop entry point | [architecture.md](architecture.md), [installation-and-lifecycle.md](installation-and-lifecycle.md) | `documented` | Documented in architecture compilation boundaries and lifecycle guides. |
 | `src/interactive/` | TUI architecture, screens, overlays, keybindings, panels, theme tokens, width matrices | [tui-design.md](tui-design.md), [commands-and-modes.md](commands-and-modes.md) | `documented` | Fully documented in TUI design specification and commands reference. |
-| `src/tools/` | 19 built-in tools across 7 planes, registry, policy engine bindings, observation envelope bounds | [tool-usage.md](tool-usage.md), [prompt-envelope-and-tools.md](prompt-envelope-and-tools.md) | `documented` | Comprehensive 19-tool reference with schemas, examples, and envelope size constraints. |
+| `src/tools/` | 20 built-in tools across 7 planes, registry, policy engine bindings, observation envelope bounds | [tool-usage.md](tool-usage.md), [prompt-envelope-and-tools.md](prompt-envelope-and-tools.md) | `documented` | Comprehensive 20-tool reference with schemas, examples, and envelope size constraints. |
 | `src/utils/` | Image manipulation, photon operations, git execution utilities | [architecture.md](architecture.md), [tool-usage.md](tool-usage.md) | `documented` | Utility helpers documented within tool usage and architectural boundaries. |
 | `src/worker/` | Worker subprocess lifecycle, NDJSON transport, heartbeat timers, control lane demuxing, spec contracts | [worker-dispatch-mechanics.md](worker-dispatch-mechanics.md) | `documented` | Complete reference for NDJSON socket protocols, watchdog timers, and exit status mapping. |
 | `src/domains/agents/` | 12 built-in recipes, agent catalog, recipe schema, fleet commands, fleet contract v4 | [built-in-agents.md](built-in-agents.md), [fleet-dispatch.md](fleet-dispatch.md) | `documented` | Documented in built-in agent recipes guide and fleet dispatch architecture. |
@@ -35,12 +35,12 @@ This matrix maps every top-level directory in `src/` and every domain directory
 | `src/domains/scheduling/` | Capacity lease acquisition, heartbeats, expiry, cross-process locks, cluster scheduling | [capacity-and-scheduling.md](capacity-and-scheduling.md), [fleet-dispatch.md](fleet-dispatch.md) | `documented` | Dedicated capacity leasing, heartbeat TTL, and cross-process lock reference. |
 | `src/domains/session/` | Context ledger v3, tree branching (`/tree`), `/fork`, `/resume`, checkpoints, protected-artifact journal | [session-lifecycle.md](session-lifecycle.md) | `documented` | Dedicated session lifecycle guide covering ledger format v3, branching, journal, and recovery. |
 | `src/domains/share/` | Portable share archive bundles, manifest verification, import/export flows | [extensions-and-sharing.md](extensions-and-sharing.md) | `documented` | Share archives and portable bundle formats documented in extensions guide. |
-| `src/domains/webhook/` | Empty directory | None (Inert) | `inert` | Directory contains no active modules or exports in v0.3.0. |
+| `src/domains/webhook/` | Empty directory | None (Inert) | `inert` | Directory contains no active modules or exports in v0.3.1. |
 
 ## Cross-Cutting Reference Guides
 
 In addition to source subsystem mappings, the documentation set includes cross-cutting contracts:
 
 1. [artifact-versions.md](artifact-versions.md): Canonical version registry and migration contract for all 9 serialized artifact schemas across Clio Coder.
-2. [glossary.md](glossary.md): Formal definitions of 17 core architectural concepts mapped to their TypeScript types in `src/`.
+2. [glossary.md](glossary.md): Formal definitions of 40 core architectural concepts mapped to their TypeScript types in `src/`.
 3. [troubleshooting.md](troubleshooting.md): Comprehensive diagnostic and remediation guide keyed by exact user-facing error strings.

package/docs/documentation-guide.md

@@ -1,7 +1,7 @@
 # Documentation Standards and Codebase Alignment
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive documentation link linter, phrasing/claim evaluator, and alignment portal is located at [docs/html/documentation_blueprint.html](html/documentation_blueprint.html) (Version: 0.3.0).
+> **Interactive Spec Available:** An interactive documentation link linter, phrasing/claim evaluator, and alignment portal is located at [docs/html/documentation_blueprint.html](html/documentation_blueprint.html) (Version: 0.3.1).
 
 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.
 
@@ -40,7 +40,7 @@ Classify claims clearly:
 | [configuration-and-targets.md](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. |
 | [safety-model.md](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](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](tool-usage.md) | `src/tools/agent-tools.ts`, `src/tools/registry.ts`, `src/tools/observation.ts` | In-depth reference for all 19 worker tools: parameters, typical payloads, `prepareArguments` normalizers, and error examples. |
+| [tool-usage.md](tool-usage.md) | `src/tools/agent-tools.ts`, `src/tools/registry.ts`, `src/tools/observation.ts` | In-depth reference for all 20 worker tools: parameters, typical payloads, `prepareArguments` normalizers, and error examples. |
 | [provider-adapter-cookbook.md](provider-adapter-cookbook.md) | `src/domains/providers/registry.ts`, `src/domains/providers/types/runtime-descriptor.ts` | RuntimeDescriptor, probe(), probeReasoning(), synthesizeModel(), thinking mechanisms. |
 | [alcf-provider.md](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](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. |
@@ -54,7 +54,7 @@ Classify claims clearly:
 | [artifact-versions.md](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` | Version registry and migration policies for all 9 serialized artifact schemas across Clio Coder. |
 | [exit-codes-and-output.md](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](troubleshooting.md) | `src/core/**`, `src/cli/**`, `src/domains/**` | Actionable error remediation and diagnostics keyed by exact user-facing messages. |
-| [glossary.md](glossary.md) | `src/domains/dispatch/types.ts`, `src/tools/**`, `src/domains/agents/**`, `src/core/**` | Canonical definitions of 17 core architectural concepts mapped to `src/` types. |
+| [glossary.md](glossary.md) | `src/domains/dispatch/types.ts`, `src/tools/**`, `src/domains/agents/**`, `src/core/**` | Canonical definitions of 40 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](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](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. |

package/docs/environment-variables.md

@@ -15,7 +15,7 @@ Durable values live in the `guardrails:` section of settings.yaml (see [configur
 | --- | --- | --- | --- |
 | `CLIO_CODER_TURN_TOOL_CALL_BUDGET` | `guardrails.turnToolCallBudget` | 60 | Orchestrator per-turn soft tool-call budget; the hard interrupt ceiling sits 15 above it (`src/engine/loop-guard.ts`). |
 | `CLIO_CODER_WORKER_TOOL_CALL_CAP` | `guardrails.workerToolCallCap` | 150 | Lifetime ceiling on tool calls one dispatched worker may execute. Calls the harness refused (reserve steering, synthesis-lockout denials) never spend it. Agent recipe budgets may narrow but never widen it (`src/engine/loop-guard.ts`). |
-| `CLIO_CODER_MAX_RUNS` | `guardrails.maxDispatchRuns` | 1000 | Dispatch run-ledger retention cap (`src/domains/dispatch/state.ts`). |
+| `CLIO_CODER_MAX_DISPATCH_RUNS` | `guardrails.maxDispatchRuns` | 1000 | Dispatch run-ledger retention cap (`src/domains/dispatch/state.ts`). The older `CLIO_CODER_MAX_RUNS` spelling still reads when the canonical name is unset. |
 | `CLIO_CODER_READ_MAX_BYTES` | `guardrails.readMaxBytes` | 51200 | Per-call byte cap for the read tool, floored at 1024 (`src/tools/read.ts`). |
 | `CLIO_CODER_OBSERVATION_TURN_BUDGET_BYTES` | `guardrails.observationTurnBudgetBytes` | 196608 | Shared per-turn byte pool across observation tools (`src/tools/observation.ts`). |
 | `CLIO_CODER_INTERNAL_DISPATCH_TIMEOUT_MS` | `guardrails.internalDispatchTimeoutMs` | 900000 | Wall-clock cap for one internal generator dispatch: the wiki documenter and the bootstrap scout (`src/cli/internal-dispatch.ts`). |
@@ -37,6 +37,7 @@ Durable values live in the `guardrails:` section of settings.yaml (see [configur
 | `CLIO_CODER_HOOK_BUDGET_WARMUP_CALLS` | 1 | Hook calls exempted from budget accounting at startup. |
 | `CLIO_CODER_HOOK_BUDGET_WINDOW` | 5 | Sliding-window size for steady-state hook-budget warnings. |
 | `CLIO_CODER_HOOK_BUDGET_THRESHOLD` | 3 | Overruns within the window before a steady-state warning. |
+| `CLIO_CODER_LMSTUDIO_CORESIDENT_CONTEXT` | 131072 | Largest context length Clio requests when it loads an LM Studio model while another model is resident on the same server. LM Studio reports no VRAM and caps GPU offload instead of refusing an oversized load, so a KV cache that does not fit is served from CPU at a crawl; the ceiling bounds that by evidence. `off` or `0` disables clamping (`src/engine/apis/lmstudio-residency.ts`). |
 | `CLIO_CODER_LMSTUDIO_SDK_PREDICT` | off | `1` sends LM Studio predictions over the SDK again instead of its OpenAI-compatible port. Predictions moved to HTTP because the SDK surface ignores the thinking control, so this is an escape hatch back to the older transport and not a debug toggle. Listing, loading, and unloading always use the SDK (`src/engine/apis/lmstudio-native.ts`). |
 | `CLIO_CODER_SKILL_CATALOG_DIR` | unset | Local skill-catalog directory override (`src/domains/resources/skills/marketplace.ts`). |
 | `CLIO_CODER_SKILL_MARKETPLACE_INDEX` | unset | Skill-marketplace index path override (`src/domains/resources/skills/marketplace.ts`). |

package/docs/eval-runner.md

@@ -1,7 +1,7 @@
 # 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.3.0).
+> **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.3.1).
 
 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.
 
@@ -15,8 +15,8 @@ The CLI commands under `clio-coder eval` support running, validating, reporting,
 
 ```bash
 clio-coder eval validate --suite <suite.yaml>
-clio-coder eval run --suite <suite.yaml> [--target <id>] [--model <id>] [--out <path>] [--clio-entry <path>]
-clio-coder eval run --task-file <tasks.yaml> [--repeat <n>] [--out <path>] [--clio-entry <path>]
+clio-coder eval run --suite <suite.yaml> [--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>]
 clio-coder eval report <evalId> --format text|json|md|swe-jsonl|junit
 clio-coder eval compare <baselineEvalId> <candidateEvalId>
 clio-coder eval gate <candidateEvalId> --baseline <baselineEvalId> [--thresholds <file>]

package/docs/evals-internal.md

@@ -1,7 +1,7 @@
 # Internal Eval Suites
 
 > [!TIP]
-> **Interactive Spec Available:** Interactive blueprints are available for internal evaluation suites at [docs/html/evals_internal_blueprint.html](html/evals_internal_blueprint.html) and soak benchmark suites at [docs/html/soak_blueprint.html](html/soak_blueprint.html) (Version: 0.3.0).
+> **Interactive Spec Available:** Interactive blueprints are available for internal evaluation suites at [docs/html/evals_internal_blueprint.html](html/evals_internal_blueprint.html) and soak benchmark suites at [docs/html/soak_blueprint.html](html/soak_blueprint.html) (Version: 0.3.1).
 
 Private suites should live outside this repository. Keep datasets, prompts,
 live fleet coordinates, calibration outputs, and raw run artifacts in a private
@@ -11,7 +11,7 @@ Run a private suite from this source checkout with:
 
 ```sh
 npm run build
-clio-coder eval run --suite <external-path> --clio-entry dist/cli/index.js
+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

package/docs/evidence-and-memory.md

@@ -1,9 +1,9 @@
 # Evidence Corpus and Long-Term Memory
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive memory lifecycle dashboard and simulator is located at [docs/html/memory_blueprint.html](html/memory_blueprint.html) (Version: 0.3.0). Use it to design, validate, and simulate memory proposals, approval loops, pruning rules, and token budgets.
+> **Interactive Spec Available:** An interactive memory lifecycle dashboard and simulator is located at [docs/html/memory_blueprint.html](html/memory_blueprint.html) (Version: 0.3.1). Use it to design, validate, and simulate memory proposals, approval loops, pruning rules, and token budgets.
 
-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. In v0.3.0, 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.
+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. In v0.3.1, 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`.
 
@@ -70,6 +70,10 @@ Eval evidence adds `eval-result.json` and uses empty receipt/protected-artifact
 | `protected-artifacts.json` | Protected artifact state/events. |
 | `findings.json` / `findings.md` | Structured and readable findings. |
 
+### Run attribution under concurrency
+
+Session ledger entries are attributed to a run by the run id the producer stamped on the entry at write time. Rows built from those entries carry that provenance in a `runLink` field (`{ kind, confidence, candidateRunIds? }`) in `tool-events.jsonl` and `protected-artifacts.json`; a write-time stamp is `kind: "entry-run-id"`, `confidence: "exact"`. Entries written without run context fall back to timestamp windowing, labeled `kind: "timestamp-window"`, `confidence: "best-effort"`, and printed as `link=timestamp-window` in the transcript. Concurrent dispatch runs share one clock and their windows overlap, so an entry inside more than one window has no owner the bundle can name. Such an entry is reported in the bundle of every run it may belong to, with `runId: null`, `kind: "ambiguous-timestamp-window"`, and a `candidateRunIds` list, plus a `best-effort-link` finding counting them. It is never dropped and never claimed as exact.
+
 When a run was chained (pipeline), composed with a persona override, or escalated for a permission, `transcript.md` and `trace.cleaned.jsonl` surface the receipt's provenance field sets, and `clio-coder evidence inspect` prints them as a `provenance <runId>:` block. The field paths, types, and stability labels are documented in the [receipt provenance schema](./observability.md#receipt-fields-for-dispatch-provenance).
 
 ---

package/docs/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.3.0).
+> **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.3.1).
 
 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/exit-codes-and-output.md

@@ -1,6 +1,6 @@
 # Exit Codes & Machine-Readable Output Contracts
 
-This document specifies the process exit codes, machine-readable JSON streaming formats, standard I/O separation rules, and `--help` conventions across all Clio Coder CLI commands in `v0.3.0`.
+This document specifies the process exit codes, machine-readable JSON streaming formats, standard I/O separation rules, and `--help` conventions across all Clio Coder CLI commands in `v0.3.1`.
 
 Source implementations: `src/cli/` and `src/entry/`.
 

package/docs/extensions-and-sharing.md

@@ -1,7 +1,7 @@
 # Extensions, Prompt Templates, Skills, and Share Archives
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/extensions_blueprint.html](html/extensions_blueprint.html) (Version: 0.3.0).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/extensions_blueprint.html](html/extensions_blueprint.html) (Version: 0.3.1).
 
 Clio Coder has lightweight community-oriented resource packaging. Extensions are filesystem bundles that contribute prompts, skills, and future theme resources. Share archives are portable JSON files for moving project/user Clio resources between machines or collaborators.
 
@@ -13,16 +13,17 @@ Source of truth: `src/domains/extensions/**`, `src/domains/resources/**`, `src/d
 
 Prompts and skills are loaded from package, user, and project roots. Higher-ranked roots override lower-ranked resources with the same name.
 
-Prompts use the three-tier precedence:
+Prompts and skills both add compatibility roots so that the command and skill files other agents already have on the machine are usable without copying. Both root lists come from the interop agent registry (`src/domains/interop/registry.ts`), so the two kinds cannot drift apart. The prompt precedence, lowest to highest, is:
 
-| Rank | Scope | Root |
-| --- | --- | --- |
-| 0 | package | enabled extension resource roots |
-| 1 | user | `<configDir>/prompts` |
-| 2 | project | `.clio-coder/prompts` |
-| 3 | cli | reserved for call-site injected resources |
+| Precedence | Scope | Source | Root |
+| --- | --- | --- | --- |
+| 10 | package | extension | enabled extension resource roots |
+| 20 | user | claude / codex / opencode | `~/.claude/commands`, `~/.codex/prompts`, `~/.config/opencode/command` |
+| 30 | user | clio | `<configDir>/prompts` |
+| 40 | project | claude / codex / opencode | `.claude/commands`, `.codex/prompts`, `.opencode/command` (untrusted by default) |
+| 50 | project | clio | `.clio-coder/prompts` |
 
-Skills add Agent Skills compatibility roots so that skills installed by other agents are usable without copying. The skill precedence, lowest to highest, is:
+The skill precedence, lowest to highest, is:
 
 | Precedence | Scope | Source | Root |
 | --- | --- | --- | --- |
@@ -33,7 +34,7 @@ Skills add Agent Skills compatibility roots so that skills installed by other ag
 | 50 | project | clio | `.clio-coder/skills` |
 | 60 | cli | path | reserved for call-site injected resources |
 
-Clio-native roots intentionally outrank shared compatibility roots at the same scope, so `.clio-coder/skills` overrides a project `.codex/skills` skill of the same name, and `<configDir>/skills` overrides `~/.agents/skills`. If multiple compatibility roots contain the same skill name at the same precedence, Clio resolves the collision deterministically by file path and records a diagnostic. If two roots resolve to the same canonical `SKILL.md` through a symlink, Clio keeps the higher-precedence entry and records a diagnostic.
+Clio-native roots intentionally outrank shared compatibility roots at the same scope, so `.clio-coder/skills` overrides a project `.codex/skills` skill of the same name, and `<configDir>/skills` overrides `~/.agents/skills`. If multiple compatibility roots contain the same name at the same precedence, the tie breaks by the registry's agent order rather than by path spelling, so a skill symlinked into two foreign roots resolves to the same winner on every machine. If two roots resolve to the same canonical `SKILL.md` through a symlink, Clio keeps the higher-precedence entry and records a diagnostic naming the path that is in use.
 
 ---
 
@@ -66,6 +67,12 @@ Use in the TUI:
 
 Templates without frontmatter are accepted; Clio derives a fallback description from the first non-empty line. Invalid frontmatter degrades to a warning for prompt templates rather than failing the whole load.
 
+### Foreign prompt roots
+
+A Claude Code slash command in `.claude/commands`, a Codex prompt in `.codex/prompts`, and an OpenCode command in `.opencode/command` are prompt templates Clio reads directly, at both user and project scope. A foreign prompt is text substituted into a message the operator typed, so it keeps the untrusted-by-project default that skills have and never gains an execution grant of its own.
+
+User-scope foreign prompts are trusted the way user-scope foreign skills are: they came from the operator's own machine. A project-scope one lists in `/prompts` with an `untrusted` marker and refuses to substitute into a message until the trust flag is set, because an unreviewed checkout would otherwise get to write part of the operator's next message. Setting `skills.trustProjectCompatRoots: true` (or exporting `CLIO_CODER_TRUST_PROJECT_SKILLS=1`) is the opt-in for both kinds. Typing `/name` for an untrusted prompt template prints `prompt template <name> comes from an untrusted project root; set skills.trustProjectCompatRoots to use it` and sends nothing to the model. Headless `clio-coder run /name` prints the same refusal and exits 1. A token that names neither a command nor a template reports `is not a command`.
+
 ---
 
 ## Skills
@@ -244,7 +251,7 @@ Share archives are single JSON files:
   "formatVersion": 1,
   "manifest": {
     "format": "clio.share.v1",
-    "clioVersion": "0.3.0",
+    "clioVersion": "0.3.1",
     "createdAt": "...",
     "files": []
   },

package/docs/fleet-demo-runbook.md

@@ -10,38 +10,38 @@ Background and reference: [fleet-dispatch.md](fleet-dispatch.md).
 
 | Role | Machine | Notes |
 | --- | --- | --- |
-| Orchestrator | `zbook` | Runs the interactive Clio session. |
-| SSH node | `blade` | General worker capacity. |
-| SSH node | `mini` | Serves the operator's resident models on its GPU; residency stays observe. |
-| SSH node | `dragon` | General worker capacity. |
+| Orchestrator | `local` | Runs the interactive Clio session. |
+| SSH node | `node-a` | General worker capacity. |
+| SSH node | `node-b` | Serves the operator's resident models on its GPU; residency stays observe. |
+| SSH node | `node-c` | General worker capacity. |
 
 All four machines share the filesystem, so the project root resolves to the
 same absolute path everywhere. The demo project is any CMake/C++ repository
 with a known failing build or test; a one-line compile error in a `.cpp` file
 works well on camera.
 
-## 1. Declare the fleet (zbook)
+## 1. Declare the fleet (local)
 
 Add the nodes to `settings.yaml` (see `clio-coder paths` for its location):
 
 ```yaml
 fleet:
   nodes:
-    - id: blade
-      host: blade
+    - id: node-a
+      host: node-a.example.net
       maxWorkers: 2
-    - id: mini
-      host: mini
+    - id: node-b
+      host: node-b.example.net
       maxWorkers: 1
       residency: observe
-    - id: dragon
-      host: dragon
+    - id: node-c
+      host: node-c.example.net
       maxWorkers: 2
 ```
 
-The implicit `local` node (zbook itself) is never declared. `residency:
+The implicit `local` node (the orchestrator host itself) is never declared. `residency:
 observe` is the default and is written here only to make the demo point
-explicit: workers on mini must never evict its resident models.
+explicit: workers on node-b must never evict its resident models.
 
 ## 2. Preflight the nodes
 
@@ -69,9 +69,8 @@ clio-coder
 
 In the session:
 
-- `/fleet` opens the fleet overlay; Tab cycles status, nodes, profiles, and
-  bindings. The nodes tab shows blade, mini, and dragon online with their
-  capacity.
+- `/fleet` opens Settings → Fleet; its node rows show node-a, node-b, and node-c
+  online with their capacity.
 - Alt+W toggles the dispatch board, which will fill with per-run cards once
   work starts.
 
@@ -82,13 +81,13 @@ placement. Example prompt for the chat input:
 
 ```
 Dispatch the fix for the failing CMake build as a reviewed task: builder on
-node blade, reviewer on node dragon, at most 2 review cycles. The task is:
+node node-a, reviewer on node node-c, at most 2 review cycles. The task is:
 "Fix the compile error in src/mesh/loader.cpp so `cmake --build build` and
 `ctest --test-dir build` both pass. Keep the change minimal."
 ```
 
 The model calls the dispatch tool with `review: {max_cycles: 2, node:
-"dragon"}` and `node: "blade"` on the task. Because a remote placement is
+"node-c"}` and `node: "node-a"` on the task. Because a remote placement is
 plan-scale, supervised autonomy parks the call and shows the plan artifact
 (topology, per-task agent, model, node); one approval launches the whole
 plan. Full-auto skips the stop and seals the plan hash into the receipts
@@ -96,15 +95,15 @@ instead.
 
 What to watch:
 
-- The board card for the builder shows `node blade`, live tool activity, and
+- The board card for the builder shows `node node-a`, live tool activity, and
   the per-worker context meter.
-- The reviewer card shows `node dragon` and `gate reviewer c1`; the reviewer
+- The reviewer card shows `node node-c` and `gate reviewer c1`; the reviewer
   runs read-only and ends with a `VERDICT:` line.
 - On a revise verdict, a second builder card appears with `gate builder c2`;
   the reviewer's findings were threaded to it as input data.
-- `/fleet` status rows carry the node column for both runs.
+- The `Alt+W` Fleet Runs board carries the node column for both runs.
 
-If a node dies mid-run (for the demo: stop sshd on blade), the run finalizes
+If a node dies mid-run (for the demo: stop sshd on node-a), the run finalizes
 as stalled, the node is classified dead after consecutive channel failures,
 and the bounded retry reroutes to a survivor with the hop recorded on the new
 receipt.
@@ -135,7 +134,7 @@ clio-coder evidence inspect <evidenceId>
 
 `clio-coder evidence build` recomputes the receipt's integrity digest against the
 run ledger; a tampered or mismatched receipt fails the build with the field
-that diverged. The receipts of the remote runs verify on zbook because the
+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
 v15 and authenticate every current receipt and reconstructed-ledger field.
 Every other receipt version is rejected rather than reported as partial; the

package/docs/fleet-dispatch.md

@@ -1,6 +1,6 @@
 # Fleet Dispatch
 
-> **Interactive Spec Available:** An interactive fleet node topology planner, scout router, receipt verifier, and failure taxonomy simulator is located at [docs/html/fleet_dispatch_blueprint.html](html/fleet_dispatch_blueprint.html) (Version: 0.3.0).
+> **Interactive Spec Available:** An interactive fleet node topology planner, scout router, receipt verifier, and failure taxonomy simulator is located at [docs/html/fleet_dispatch_blueprint.html](html/fleet_dispatch_blueprint.html) (Version: 0.3.1).
 
 Clio Coder dispatches bounded worker agents. With a fleet configured, those
 workers run on remote machines over SSH while the orchestrator keeps every
@@ -39,10 +39,10 @@ for bounded abort escalation.
 
 Scout routing is advisory rather than forced: the worker operating contract
 steers explicit broad repository exploration to the read-only `scout` recipe,
-and middleware emits a continuation nudge after nine or more manual
-read-only exploration calls without a successful Scout dispatch. Direct reads
-remain allowed; Clio does not automatically rewrite a broad request into a
-Scout run.
+and middleware emits one advisory notice after nine or more manual
+read-only exploration calls without a successful Scout dispatch. The advisory
+costs no extra model round. Direct reads remain allowed; Clio does not
+automatically rewrite a broad request into a Scout run.
 
 Design decisions that shape everything else:
 
@@ -100,13 +100,13 @@ fleet:
       maxWorkers: 1
 ```
 
-`clioEntry` may override the remote invocation (default `clio-coder worker`).
+`clioCoderEntry` may override the remote invocation (default `clio-coder worker`).
 Node ids must be unique and `local` is reserved.
 
 Worker profiles can pin work to a node: `workers.profiles.<name>.node` routes
-every dispatch bound to that profile. The `/fleet` overlay's profiles tab
-edits the pin (`o` key), and the dispatch tool accepts an explicit `node`
-argument per task.
+every dispatch bound to that profile. Settings → Fleet (`/fleet`) edits the
+pin on the profile's `node` row, and the dispatch tool accepts an explicit
+`node` argument per task.
 
 ## Doctor preflight
 
@@ -173,6 +173,12 @@ accepted by the current reader.
   failures change the process-local registry health to `offline`. Doctor
   preflight is a separate durable eligibility gate: a failed or stale record
   blocks placement without pretending it changed channel health.
+- A result-contract repair round is a synthetic tool exchange, and its assistant
+  half carries explicit zero usage. Request sizing reads usage from every
+  assistant message that is not aborted or errored, and a repair message with no
+  usage crashed the worker one round after its terminal message. Zero usage is
+  skipped by the estimator, so the model's last real usage still anchors the
+  estimate and the worker survives the repair round (#70).
 
 ## Topologies
 
@@ -192,6 +198,56 @@ request-level `autonomy` can only narrow the level (reviewers and judges run
 | Compete | `mode: "compete", candidates: 2..4` | N candidates in scratch worktrees, read-only judge, winner applied or preserved. |
 | Agent automation | `agent: "auto"` | Baselines candidate agent from task shape via shared classifier (`coder`, `tester`, `documenter`, `verifier`, `researcher`, `scout`); advisory unless activated. |
 
+### Agent ledger
+
+Every topology that runs more than one worker at once opens an agent ledger, the
+bounded coordination board those workers share while they run: the parallel
+fan-out (`src/tools/dispatch.ts:3247`), a detached batch of two or more
+(`:538`), and compete (`:1549`). A worker reaches it through the `ledger` tool
+and posts one of three typed entries. A `claim` stakes path prefixes so peers
+stop colliding, a `finding` reports one observation with the path and line that
+ground it, and a `review` judges another entry by its id. Nothing untyped is
+postable, and a run gets 20 posts.
+
+The orchestrator is the sole writer. A post travels up the control lane as a
+body and nothing else, and every attribution field is stamped from the
+orchestrator's own admission record, so no worker-supplied value can reach a
+field a peer or a receipt reads as identity. Admitted entries are pushed back
+down as `ledger_delta` stdin frames into a per-worker mirror, so a read answers
+locally with a watermark instead of blocking on a round trip. A worker that
+spawns late is handed the whole board twice over: the hub replays it on
+subscription, and it is rendered into that worker's dynamic prompt messages at
+spawn as untrusted peer data.
+
+The reducers never merge. Citations are compared in workspace-relative form, so
+`./src/a.ts` and the absolute path of that file are one path. A path cited by
+two or more runs is corroborated, a path cited by one is uncorroborated and still rendered standing on its own, a
+finding with no citation is an ungrounded lead, and an entry a review failed is
+marked disputed where it stands. Overlapping claims from different runs carry
+the ids they overlap, which is advisory; the per-wave write boundary is what
+actually stops two writers.
+
+When the board closes depends on where the batch settles. An attached parallel
+fan-out closes it when the tool call returns, and compete closes it once every
+candidate and the judge have settled. A detached batch, and a parallel batch the
+operator moved to the background, carry the ledger id on the durable batch
+record and close it on the first `monitor(mode="collect")`, because their peers
+stay concurrent past the call that started them. After the close, appends are
+refused and counted.
+
+The main model reads the board too, once its workers have all settled. The
+parallel dispatch result, the compete result, and `monitor(mode="collect")` for
+a detached batch each carry one `agent ledger (<n> entries, sequence <w>)`
+section after the per-run lines, holding the same bounded render a worker sees,
+with the same attribution and the same corroboration and dispute marks and
+still no count, score, or consensus line. The same text is on the result's
+`details.agentLedgerBoard`. A board nobody posted to is omitted, so a
+single-run dispatch and an unused board read exactly as they did before.
+
+What survives into a receipt is that run's `ledgerContribution`, which is the
+ledger id, its posted and refused counts, and a sha256 over its own attributed entries, sealed orchestrator-side
+and covered by receipt integrity.
+
 ### Detached fan-out, backgrounding, and collect
 
 `detach: true` validates, admits, and spawns every task, then returns. The
@@ -545,6 +601,44 @@ hard block.
 
 ## Operator visibility
 
+- Every run carries the origin that asked for it, and every surface shows it
+  with the same pair of glyphs: `◇` for a run the operator started with `/run`
+  or `/delegate`, `◆` for one the model started by calling a dispatch tool, and
+  a dim `·` for the runs Clio starts for itself. A running `◇` on the board is
+  therefore the operator's own work. The footer chip in the status line splits
+  into `◇1 ◆3` when more than one kind is live and stays `fleet N` otherwise.
+  Board rows carry an origin glyph too.
+- User-origin and agent-origin runs stream into the chat transcript as an
+  attributed worker block. The typed command is echoed dim above the block.
+  Header units display `<agentId>` then `<targetId>/<wireModelId>` then `run <runId>`
+  for fleet workers (such as `◇ coder · node-a/example-coder-model · run 2mkas6s`),
+  or `<id> (acp) · run <runId>` with no route for ACP delegation peers. The block
+  body renders the worker prose down a rail, one coalesced line of tool names,
+  and a one-line receipt footer showing the outcome glyph, token count, duration,
+  and contract status (such as `└ ✓ ok · 8.4k tok · 18s · contract unmeasured`),
+  with the failure reason printed on the rail above the footer when a run fails.
+- Runs the model itself asked for through the dispatch tool (identified by
+  parentToolCallId) render as folded `◆` cards under the spawning tool segment;
+  operator-typed runs are `◇` and open. The fold chord uses the `clio.tool.expand`
+  keybinding (`Alt+O`), which toggles the newest foldable item of either kind
+  (tool call or worker block). `Ctrl+Alt+O` or `Alt+Shift+O` toggles every tool
+  call and worker block at once.
+- Sharing: nothing a worker produced enters the main model's context unless
+  `--share` was passed or the operator runs `/share [runId]`. What enters is a
+  bounded note of the shape `[worker result] <agent> · run <id> · <outcome> · shared by the operator`
+  followed by the bounded answer text, traveling the ordinary user-turn path.
+  The operating contract tells the main agent that this note is operator
+  steering backed by a readable receipt, not a tool result to verify against
+  its own dispatch history.
+  Bare `/share` picks the newest finished run the operator started themselves
+  (never a model-asked `◆` run); `/share <runId>` may name a model-asked run
+  explicitly. `/new` resets the transcript and the pool bare `/share` draws
+  from, so a run from the previous session cannot be shared into the new one.
+- Replay: `/resume` replays worker blocks from receipts; the session file's
+  `workerRun` entries carry ids, origin, and runtime only, without prose; the
+  replayed answer is bounded from the receipt exactly like the live one. A
+  missing receipt renders `receipt unavailable`.
+- Memory workers on the background target never appear as transcript blocks.
 - The dispatch board shows per-run cards with the node id (absent placement
   renders `local`), gate badges (`gate reviewer c2`), reroute badges, live
   tool activity (names only; arguments never cross the worker stdout seam),
@@ -552,9 +646,9 @@ hard block.
 - The context meter renders the worker's last-message context occupancy
   against the model's context window: healthy below 80 percent, warn from 80,
   critical from 95.
-- `/fleet` cycles status (running and retrying runs with a node column),
-  nodes (the registry view with state, capacity, and last-seen), profiles
-  (with the node pin), and bindings.
+- `/fleet` opens Settings → Fleet: profiles (with the node pin), bindings,
+  and read-only node rows (state, capacity, and last-seen). Running and
+  retrying runs, with their node, live in the `Alt+W` Fleet Runs board.
 - The monitor tool reports the node and reroute lineage on `status`, `list`,
   and `collect`.
 - `clio-coder fleet status [--json]` shows the durable ledger view cross-process.
@@ -575,6 +669,11 @@ Remote workers default to residency observe: the SSH transport exports
 them. A node opts into management explicitly with `residency: manage` in its
 fleet entry.
 
+A model the router tags as pinned (`pinned:true` or `role:scout`) is never
+evicted once resident, so Clio refuses to load it by evicting a resident that
+settings still reference by role; on a one-slot router such an override
+declines with a `will-not-fit` notice instead of stranding the configured model.
+
 ## Opt-in live regression
 
 After `npm run build`, an operator with a configured model target can run the