@iowarp/clio-coder 0.3.0 → 0.3.2

package/docs/development-pipeline.md

@@ -0,0 +1,102 @@
+# 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.
+
+## Inheriting a Pi release
+
+Pi dependency upgrades use a fixed five-step review so that upstream fixes
+replace Clio copies without crossing the product boundary:
+
+1. Read the release notes or package changelogs for `pi-ai`, `pi-agent-core`,
+   and `pi-tui`.
+2. Run `npm run pi:surface-diff`. A changed or removed symbol that Clio imports
+   is an error; a new export is review input.
+3. Run `npm run ci`, then explicitly run the wire-capture fixtures and
+   `tests/smoke/tui-width-matrix.test.ts` from the
+   [Pi regression net](pi-boundary.md#pi-regression-net).
+4. Walk Pi's fixed-issue list against the
+   [Pi SDK boundary table](pi-boundary.md). For every fix in a surface Clio
+   still owns, either delete Clio's copy in favor of Pi or add a dated reason
+   for keeping the delta.
+5. Review the matching pi-coding-agent release diff for application features
+   worth a Clio ticket.
+
+After review, regenerate `docs/pi-surface.json` with
+`npm run pi:surface-snapshot`, inspect the symbol and signature changes, and
+commit the dependency pins, snapshot, boundary notes, and proving contracts
+together. `npm run lint` invokes the surface check automatically when the
+installed Pi versions differ from the checked-in snapshot.
+
+## 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.2`, `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/dispatch-architecture-rationale.md

@@ -123,4 +123,4 @@ affected import site for no behavioral gain. A boundary rule should protect an
 invariant. "Always import through the barrel" protects a preference.
 
 What is *not* permitted is anything the five direction rules forbid, and those
-stay enforced by `npm run check:boundaries`.
+stay enforced by the boundary checker that `npm run lint` runs.

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.2`.
 
 ## 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.2. |
 
 ## 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.2).
 
 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

@@ -2,7 +2,7 @@
 
 Every environment variable the shipped `src/` tree reads, grouped by role. Settings.yaml is the durable home for operator policy; env vars exist for per-process overrides (CI, one-off experiments), directory layout, debugging, and internal plumbing. When prose and source disagree, prefer the source; the table cites the read site.
 
-This page is the complete inventory, and `tests/contracts/environment-variable-inventory.test.ts` fails if `src/` reads a variable that has no row here.
+This page is the complete inventory, and the `environment-variable-inventory` check in `scripts/check-hygiene.ts` (run by `npm run lint`) fails if `src/` reads a variable that has no row here.
 
 > [!TIP]
 > [docs/html/environment_blueprint.html](html/environment_blueprint.html) is a browsable walkthrough of the most commonly set variables with an effective-path resolver. It covers a curated subset, so use the tables below when you need the full list.
@@ -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,11 +37,15 @@ 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_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_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_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`). |
 | `CLIO_CODER_MODEL_CATALOG_DIRS` | unset | Extra model-catalog directories (`src/domains/providers/knowledge-base-path.ts`). |
 | `CLIO_CODER_NO_NETWORK_TOOLS` | off | `1` strips network tools from every registry in the process; the skills-eval harness sets it for hermetic arms; `--allow-network` clears it (`src/tools/network-policy.ts`). |
+| `CLIO_CODER_SMOOTH_STREAM` | settings value | Per-process override for `terminal.smoothStreaming`: `0`/`off`/`false`, `auto`, or `1`/`on`/`true`. A valid value wins over settings; an invalid value fails safely to `off`. |
+| `CLIO_CODER_REDUCE_MOTION` | off | `1` makes smooth-streaming `auto` use the immediate coalescer. Explicit `on` remains an operator request, while stdout backpressure still pauses frame production. |
+| `CLIO_CODER_SCREEN_READER` | off | `1` makes smooth-streaming `auto` use the immediate coalescer so a screen reader receives the existing low-motion update behavior. |
+| `CLIO_CODER_INSTANT_SHELL` | on | `0` disables the single-owner Stage 0 interactive shell for immediate rollback. Unset or `1` mounts one terminal/editor owner before service hydration; ACP, headless, ordinary non-TTY, and subcommand paths never mount it. An explicit `CLIO_CODER_INTERACTIVE=1` keeps its force-interactive non-TTY behavior. |
 
 ## Directory and install layout
 
@@ -62,8 +66,6 @@ All default off; enable with `1`.
 | `CLIO_CODER_TRACE_BOOT` | Boot-phase timing trace (`src/core/boot-trace.ts`). |
 | `CLIO_CODER_TIMING` | Startup timing report (`src/entry/orchestrator.ts`). |
 | `CLIO_CODER_DEBUG_SHUTDOWN` | Shutdown-path diagnostics (`src/core/termination.ts`). |
-| `CLIO_CODER_DEBUG_LMSTUDIO` | LM Studio wire logging (`src/domains/providers/runtimes/common/lmstudio-logger.ts`). |
-| `CLIO_CODER_RUNTIME_VERBOSE` | Verbose runtime logging (`src/engine/apis/lmstudio-native.ts`). |
 | `CLIO_CODER_HOOK_BUDGET_DEBUG` | Per-overrun hook-budget diagnostics (`src/domains/middleware/runtime.ts`). |
 
 ### File-writing traces
@@ -72,7 +74,7 @@ These two take a path, not `1`. Setting either to `1` writes a file named `1` in
 
 | Variable | Contents | Controls |
 | --- | --- | --- |
-| `CLIO_CODER_RENDER_TRACE` | timing only | Per-frame render timing for the interactive TUI, truncated on open so one file is one session. Records frame durations and counts and no conversation text, which makes it the instrument for reproducing a frame-cost claim at a given terminal size (`src/interactive/render-trace.ts`). |
+| `CLIO_CODER_RENDER_TRACE` | timing only | Versioned JSONL for the full interactive render pipeline, truncated on open so one file is one session. Records event/input sequence ranges, queue and panel high-water marks, explicit frames, grouped stdout commits, write return values, backpressure, and drain—but no conversation text. Output is bounded and asynchronous after the initial pre-TUI file open; trace failure is nonfatal. See [performance-methodology.md](performance-methodology.md) for endpoint definitions (`src/interactive/render-trace.ts`). |
 | `CLIO_CODER_MEMORY_TRACE` | conversation text | Proactive task-memory step envelopes, including up to 8000 characters of the text each step saw. This is content-bearing by construction, so the file carries whatever the session carried. Do not enable it on work you would not paste, and do not attach the file to a bug report without reading it first (`src/domains/memory/task-memory-trace.ts`). |
 
 Example:
@@ -87,12 +89,18 @@ Set by Clio for its own processes; not operator knobs.
 
 | Variable | Purpose |
 | --- | --- |
+| `AI_AGENT` | Clio sets this generic child-process attribution marker to `clio-coder` at both shipped entry points and reinforces it for bash tools, fleet workers, registered code steps, and command hooks. Child tooling may read it to identify the agent that launched it (`src/cli/index.ts`, `src/worker/entry.ts`, `src/core/bash-exec.ts`). |
+| `CLIO_CODER_GIT_COMMITS_ENABLED` | Carries the effective `attribution.gitCommits` setting to Clio-controlled child-process seams. It is set from validated settings and is not an operator override (`src/core/git-commit-attribution.ts`). |
+| `CLIO_CODER_COMMIT_ASSISTED`, `CLIO_CODER_COMMIT_AUTHORED` | Per-spawn inputs to the managed `prepare-commit-msg` hook, which also requires `AI_AGENT=clio-coder` and `CLIO_CODER_GIT_COMMITS_ENABLED=1`; normal external shells never receive this set. Only assistance and authorship cross the environment. Testing, review, and receipt trailers are composed in process by the fleet seam, so a child shell cannot forge them by exporting a variable (`src/core/git-commit-attribution.ts`). |
+| `CLIO_CODER_GIT_CONFIG_BASE_COUNT`, `CLIO_CODER_GIT_DEFAULT_HOOKS_EQUIVALENT` | Bookkeeping that lets each managed hook wrapper remove only Clio's command-scope `core.hooksPath` pair before chaining the repository's own hook of the same name. Existing `GIT_CONFIG_COUNT` entries remain in force; an explicit `core.hooksPath` is treated as composable only when it resolves exactly to the repository's default hooks directory (`src/core/git-commit-attribution.ts`). |
 | `CLIO_CODER_INTERACTIVE` | Marks the interactive TUI process; scrubbed from bash-tool children so nested invocations do not inherit it (`src/cli/clio.ts`, `src/core/bash-exec.ts`). |
 | `CLIO_CODER_RUN_OVERRIDES` | JSON envelope for run-scoped CLI options (`--max-context-tokens`, `--kv-cache-mode`, sampling flags). One typed variable instead of one env var per option; worker subprocesses inherit it (`src/core/run-overrides.ts`). |
 | `CLIO_CODER_RESUME_SESSION_ID` | Session id handed across a self-restart; consumed and deleted at boot (`src/entry/orchestrator.ts`). |
 | `CLIO_CODER_BOOTSTRAP_GENERATE_CHILD` | Marks the CLIO-CODER.md-generation child so it skips recursion (`src/domains/context/extension.ts`). |
 | `CLIO_CODER_WORKER_LABELS` | Comma-separated labels a dispatched worker reports as its own (`src/domains/dispatch/transport.ts`, `src/worker/entry.ts`). |
 | `CLIO_CODER_WORKER_PGID` | Process-group id the transport assigns a worker so its whole tree can be signalled (`src/domains/dispatch/transport.ts`, `src/worker/entry.ts`). |
+| `CLIO_CODER_WORKER_RUN` | Marks a dispatched worker process; a skill install run inside it is stamped `installed-by: worker` (`src/worker/entry.ts`, `src/domains/resources/skills/install.ts`). |
+| `CLIO_CODER_INJECTED_COMPILE_CACHE` | Marks a `NODE_COMPILE_CACHE` value Clio injected into a native worker's environment so its module graph compiles from Clio's V8 compile cache. The worker entry consumes the pair from its own environment immediately after Node reads it, so no worker child of any kind inherits it, and the spawn path never lets the marker travel beside an operator-supplied `NODE_COMPILE_CACHE` (`src/core/compile-cache.ts`, `src/domains/dispatch/worker-spawn.ts`, `src/worker/entry.ts`). |
 
 ## Test-only
 
@@ -100,6 +108,7 @@ Set by Clio for its own processes; not operator knobs.
 | --- | --- |
 | `CLIO_CODER_WORKER_FAUX` (+ `_MODEL`, `_TEXT`, `_STOP_REASON`, `_ERROR_MESSAGE`) | Fake worker model for tests (`src/engine/ai.ts`). |
 | `CLIO_CODER_TEST_UPGRADE_NO_NETWORK` | Skips npm install during upgrade tests (`src/cli/upgrade.ts`). |
+| `CLIO_CODER_TEST_STAGE1_DELAY_MS`, `CLIO_CODER_TEST_STAGE1_FAIL` | `NODE_ENV=test`-only, bounded instant-shell interleaving and injected hydration failure seams for the built PTY acceptance suite (`src/cli/clio.ts`). |
 | `CLIO_CODER_REQUIRE_HOME_PREFIX` | Test guardrail: abort if resolved directories escape `CLIO_CODER_HOME` (`src/core/init.ts`). |
 
 Variables used only by `scripts/` and `benchmarks/` harnesses (the `CLIO_CODER_LIVE_*` smoke-test family, benchmark fleet configuration, install-script inputs) are not part of the shipped runtime and are documented inline where they are consumed.

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.2).
 
 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.2).
 
 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.2). 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.2, 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,8 +70,16 @@ 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).
 
+### Task and decision provenance
+
+Session evidence retains the two operator-facing bookkeeping ledgers instead of flattening them into prose. A `taskLedger` projection names the stable board id, goal counts, active runs, required evidence, and bounded task rows with status, origin, `userTaskId`, reason, and evidence. This keeps an operator task traceable from the project inbox correlation through agent pickup and completion. A `decisionLedger` projection names the active-path anchor, interview identity and status, timing, round count, summary, and every settled or superseded decision. Operator revisions are explicit through `revisedAt`, `revisionSource=operator`, and the recorded correction text. Both kinds remain session facts in `trace.raw.jsonl`, `trace.cleaned.jsonl`, and the readable transcript; evidence does not reinterpret them as validation results.
+
 ---
 
 ## Evidence Tag Taxonomy and Failure Causes

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.2).
 
 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.
 
@@ -57,7 +57,7 @@ Only the first exploratory iteration (`iterationId: "exploratory-1"`) is permitt
 During `clio-coder evolve manifest validate` and `summarize` commands, Clio Coder validates the referenced evidence bundles:
 - **Format Verification**: Every reference in the `evidenceRefs` array must follow the format `run-<id>` or `session-<id>`.
 - **Durable Store Resolution**: Each reference must correspond to a folder that actually exists under `<dataDir>/evidence/`. If any referenced bundle is missing, validation fails and reports a dangling reference issue.
-- **Engine Boundaries**: To maintain domain boundaries (`check:boundaries`), the validation function `validateChangeManifest` is completely decoupled. It accepts a `resolveEvidenceRef` predicate option. The CLI passes a resolver connected to the evidence store, keeping the evolution domain from directly importing the evidence domain.
+- **Engine Boundaries**: To maintain the domain boundaries the lint-time boundary checker enforces, the validation function `validateChangeManifest` is completely decoupled. It accepts a `resolveEvidenceRef` predicate option. The CLI passes a resolver connected to the evidence store, keeping the evolution domain from directly importing the evidence domain.
 
 ### Self-Edit Gate Deferral (Slice 5b)
 

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.2`.
 
 Source implementations: `src/cli/` and `src/entry/`.
 
@@ -29,10 +29,10 @@ Every subcommand in Clio Coder adheres to the strict `--help` convention:
 
 ### Global vs Subcommand Flag Positioning
 
-Global options (such as `--cwd`, `--config-dir`, `--state-dir`, `--profile`, and `--debug`) must precede the subcommand. If a global flag is placed after the subcommand name, Clio prints a remediation guide to `stderr` and exits with code `2`:
+Global options (such as `--api-key`, `--no-context-files`, and `-nc`) must precede the subcommand. Directory redirection is configured via the `CLIO_CODER_*_DIR` environment variables (see [docs/environment-variables.md](environment-variables.md)). If a global flag is placed after the subcommand name, Clio prints a remediation guide to `stderr` and exits with code `2`:
 
 ```text
---config-dir is a global option and must come before the subcommand: clio-coder --config-dir <path> <command> ...
+--api-key is a global option and must come before the subcommand: clio-coder --api-key <key> <command> ...
 ```
 
 ---
@@ -59,16 +59,22 @@ Many Clio CLI subcommands provide structured JSON output for integration with sc
 
 | Subcommand | Flag | Output Structure |
 | :--- | :--- | :--- |
-| `clio-coder run` | `--json` | Stream of incremental NDJSON event frames (`message`, `tool_call`, `tool_result`, `terminal`). |
-| `clio-coder run` | `--json-events terminal` | Filters event stream to emit only the final terminal run receipt. |
+| `clio-coder run` | `--json` | Stream of incremental NDJSON event frames (`session`, `agent_start`, `turn_start`, `message_start`, `message_end`, `thinking_delta`, `text_delta`, `tool_execution_start`, `tool_execution_end`, `turn_end`, `agent_end`). |
+| `clio-coder run` | `--json-events terminal` | Emits the `session` header, a synthesized `turn_start` (`startedAt`), the `agent_end` and `notice` events that pass the filter, and a synthesized `turn_end` carrying `startedAt`, `endedAt`, `exitCode`, and `error` when the turn failed. Per-segment token usage rides `agent_end`. Excludes multi-kilobyte intermediate message bodies (#122). |
+| `clio-coder run` | `--json-events full` | Emits complete event stream with projected assistant messages (`streamed: true`, `textLength`, `thinkingLength`) to eliminate duplicate wire tokens (#122). |
 | `clio-coder agents` | `--json` | JSON array of registered agent recipe metadata objects. |
 | `clio-coder targets` | `--json` | JSON object containing the configured `targets` array. |
 | `clio-coder models` | `--json` | JSON array of catalog models with capability flags. |
-| `clio-coder fleet status` | `--json` | JSON snapshot of cluster nodes, active leases, and drain status. |
+| `clio-coder fleet status` | `--json` | JSON snapshot object with `generatedAt`, `admission` (`open` or `draining`), `running`, `retrying`, and `totals`. Each run row carries its `node`, defaulting to `local`. |
 | `clio-coder trace runs` | `--json` | JSON array of trace run records. |
-| `clio-coder trace sql` | Positional query | JSON array of rows returned by the read-only SQLite `SELECT` query. |
+| `clio-coder trace sql` | Positional query | JSON array of rows returned by the read-only SQLite query. A single `SELECT` or read-only `WITH` statement is accepted; multiple statements and mutating keywords are refused with exit code 2. |
 | `clio-coder paths` | `--json` | JSON object mapping platform directory names to absolute paths. |
 
-### Incremental Streaming Invariant
+### Incremental Streaming & Deduplication Invariant (#122, #123)
 
-The `--json` stream from `clio-coder run` emits **deltas and increments**, never repeated whole-message snapshots. This guarantees that consumers receive stream tokens linearly without duplicating memory or bandwidth.
+The `--json` stream from `clio-coder run` emits **deltas and increments**, never repeated whole-message snapshots:
+1. `text_delta` and `thinking_delta` stream incremental content tokens.
+2. `message_end` and `turn_end` frames project assistant content blocks to metadata descriptors (`{ streamed: true, textLength }` and `{ streamed: true, thinkingLength, thinkingSignature }`), stripping raw text/thinking bodies so content is never transmitted across the wire twice.
+3. Tool calls and results are preserved intact since they carry execution payloads not present in text deltas.
+4. Terminal accounting and token usage remain fully populated for auditability.
+5. Exit code validation strictly precedes database inspection: unknown flags, missing required positionals, or mutating SQL queries consistently exit `2` with usage syntax printed to `stderr` (#123).

package/docs/extensions-and-sharing.md

@@ -1,9 +1,9 @@
 # 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.2).
 
-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.
+Clio Coder has lightweight community-oriented resource packaging. Extensions are filesystem bundles that contribute prompts and skills. Share archives are portable JSON files for moving project/user Clio resources between machines or collaborators. Themes are built into the engine and are no longer loaded from extensions.
 
 Source of truth: `src/domains/extensions/**`, `src/domains/resources/**`, `src/domains/share/**`, `src/cli/extensions.ts`, and `src/cli/share.ts`.
 
@@ -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.
 
 ---
 
@@ -49,7 +50,7 @@ description: Focused bug-fix prompt
 argument-hint: "<file> <symptom>"
 ---
 
-Investigate {{1}} for this symptom: {{2}}
+Investigate $1 for this symptom: $2
 
 Return:
 1. likely root cause;
@@ -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
@@ -95,10 +102,10 @@ Use in the TUI:
 
 ```text
 /skill
-/skill:hdf5-review review the output validation path
+/skill hdf5-review review the output validation path
 ```
 
-`/skill` opens the Skills Hub with discovered project skills, user skills, and marketplace entries. `/skill:name args` submits `args` with a pending skill request; the model must call `context` (scope="skills") for that skill before following the workflow. The same pending-request path runs in headless mode, so `clio-coder run "/skill:name args"` matches the interactive behavior.
+`/skill` opens the Skills Hub with discovered project skills, user skills, and marketplace entries. `/skill <name> [args]` submits `args` with a pending skill request; the model must call `context` (scope="skills") for that skill before following the workflow. The same pending-request path runs in headless mode, so `clio-coder run "/skill hdf5-review inspect the writer"` matches the interactive behavior.
 
 Every activation records a session ledger entry with the skill name, file path, hash, source, trigger (`slash-command` or `tool`), and turn id when one is available. The same ledger is mirrored into session metadata, prompt diagnostics, and run receipts. Compaction keeps the newest active skill turn in the retained suffix so a loaded skill is not silently summarized away.
 
@@ -109,7 +116,7 @@ The canonical invocation name is the frontmatter `name` when present, otherwise
 Recognized frontmatter fields:
 
 - `name`, `description`: core identity.
-- `disable-model-invocation: true`: hides the skill from the model-visible catalog while keeping it loadable by `/skill:name`.
+- `disable-model-invocation: true`: hides the skill from the model-visible catalog while keeping it loadable by `/skill <name>`.
 - `allowed-tools`, `disallowed-tools`: parsed as tool policy fields for the loaded skill workflow.
 - `license`, `version`, `compatibility`, and other non-core keys: captured as skill metadata and surfaced when the skill loads through `context`.
 - `source-url`, `registry-id`, `installed-at`, `updated-at`, `audit`: captured as install provenance when present.
@@ -164,7 +171,7 @@ Clio does not call Skills.sh during startup or prompt assembly, and does not emi
 
 ### Prompt envelope and safety
 
-Skill bodies never enter the prompt uninvited. The model discovers skills only through `context(scope="skills")`: a call with no `name` returns a one-line listing (name, scope, description) of model-visible skills, and a body loads only when the pending-skill policy authorizes that name for the turn, which requires an explicit operator invocation such as `/skill:<name>`. Skills are prompt resources, not execution grants: any script a skill references still runs through normal Clio tools and safety gates, and a loaded skill's `allowed-tools` declaration narrows the tool surface at admission (reason code `skill_surface`) without ever granting anything the host would refuse.
+Skill bodies never enter the prompt uninvited. The model discovers skills only through `context(scope="skills")`: a call with no `name` returns a one-line listing (name, scope, description) of model-visible skills, and a body loads only when the pending-skill policy authorizes that name for the turn, which requires an explicit operator invocation such as `/skill <name>`. Skills are prompt resources, not execution grants: any script a skill references still runs through normal Clio tools and safety gates, and a loaded skill's `allowed-tools` declaration narrows the tool surface at admission (reason code `skill_surface`) without ever granting anything the host would refuse.
 
 ---
 
@@ -186,7 +193,7 @@ compatibility:
   clio: ">=0.2.0"
 ```
 
-Required fields are `manifestVersion: 1`, `id`, `version`, and `description`. `name` defaults to `id` when absent. The current resource kinds are `prompts`, `skills`, and `themes`; theme loading is reserved and currently returns an empty list in the resource loader.
+Required fields are `manifestVersion: 1`, `id`, `version`, and `description`. `name` defaults to `id` when absent. Clio loads `prompts` and `skills`. A manifest may reserve a `themes` path for forward compatibility, but Clio does not load theme resources.
 
 IDs must be lowercase and may include numbers, dots, underscores, and hyphens; they must start/end alphanumeric.
 
@@ -244,7 +251,7 @@ Share archives are single JSON files:
   "formatVersion": 1,
   "manifest": {
     "format": "clio.share.v1",
-    "clioVersion": "0.3.0",
+    "clioVersion": "0.3.2",
     "createdAt": "...",
     "files": []
   },