@iowarp/clio-coder 0.3.1 → 0.3.3

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.
@@ -38,11 +38,14 @@ Durable values live in the `guardrails:` section of settings.yaml (see [configur
 | `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`). |
 | `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
 
@@ -63,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
@@ -73,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:
@@ -88,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
 
@@ -101,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.1).
+> **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.3).
 
 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.
 

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.1).
+> **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.3).
 
 Private suites should live outside this repository. Keep datasets, prompts,
 live fleet coordinates, calibration outputs, and raw run artifacts in a private

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.1). 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.3). 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.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.
+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.3, 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`.
 
@@ -76,6 +76,10 @@ Session ledger entries are attributed to a run by the run id the producer stampe
 
 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.1).
+> **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.3).
 
 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.1`.
+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.3`.
 
 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.1).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/extensions_blueprint.html](html/extensions_blueprint.html) (Version: 0.3.3).
 
-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`.
 
@@ -50,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;
@@ -102,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.
 
@@ -116,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.
@@ -171,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.
 
 ---
 
@@ -193,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.
 
@@ -251,7 +251,7 @@ Share archives are single JSON files:
   "formatVersion": 1,
   "manifest": {
     "format": "clio.share.v1",
-    "clioVersion": "0.3.1",
+    "clioVersion": "0.3.3",
     "createdAt": "...",
     "files": []
   },

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.1).
+> **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.3).
 
 Clio Coder dispatches bounded worker agents. With a fleet configured, those
 workers run on remote machines over SSH while the orchestrator keeps every
@@ -37,8 +37,8 @@ attestation are strict protocol evidence, not proof against a malicious child
 that controls its own process; SSH also uses the attested remote process group
 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,
+Scout routing is advisory rather than forced: the session's Delegation
+passage steers explicit broad repository exploration to the read-only `scout` recipe,
 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
@@ -82,7 +82,9 @@ Recipes may declare `budget: {toolCalls, readReserve, synthesis}`. `toolCalls` i
 ## Node setup
 
 Fleet nodes are declared under `fleet.nodes` in `settings.yaml`. The implicit
-`local` node always exists and is never declared.
+`local` node always exists and is never declared. A run's node is the host its
+worker process ran on, never the host serving the model, so a run against a
+remote target from this machine still records `node: local`.
 
 ```yaml
 fleet:
@@ -537,7 +539,7 @@ closed while a winner remains unapplied.
 Receipts carry exactly one integrity version (`RUN_RECEIPT_INTEGRITY_VERSION = 15`), which authenticates the complete receipt and reconstructible ledger provenance surface. There is no historical verification path: any other version is invalid, and a receipt that fails verification is never read as evidence. The fleet provenance fields covered by the digest
 include:
 
-- `node`: the fleet node the worker ran on (`id`, `kind`, `host`).
+- `node`: the fleet node the worker ran on (`id`, `kind`, `host`). The `node.id` explicitly identifies the worker process host executing the task, not the model host (which is represented by the `target` id). This behavior tracks issue #120.
 - `reroutes`: dead-node failover hops, oldest first.
 - `gate`: review/compete provenance (role, group, cycle, subject run ids with
   their receipt digests, and the verdict that caused a revise builder).

package/docs/git-commit-provenance.md

@@ -0,0 +1,120 @@
+# Git Commit Provenance
+
+Clio Coder adds evidence-aware role trailers to commits created through Clio.
+The feature is enabled by default:
+
+```yaml
+attribution:
+  gitCommits: true
+```
+
+Settings -> Advanced exposes the same switch as **Clio commit provenance**, with
+`enabled` and `disabled` values. A change applies immediately to subsequent
+commits in the session. When disabled, Clio leaves commit messages entirely
+unchanged.
+
+## Canonical identity
+
+The identity is compiled into Clio and is not user-editable:
+
+```text
+Clio Coder <clio-coder@iowarp.ai>
+```
+
+Clio never replaces the human author or committer. The person and Git identity
+that made the commit remain in the commit's author and committer fields.
+
+## Evidence-dependent roles
+
+Each trailer states what trusted execution evidence proves. A role is not an
+advertisement and is never inferred from an agent saying in prose that it ran a
+check or performed a review.
+
+```text
+Assisted-by: Clio Coder <clio-coder@iowarp.ai>
+Tested-by: Clio Coder <clio-coder@iowarp.ai>
+Reviewed-by: Clio Coder <clio-coder@iowarp.ai>
+Co-authored-by: Clio Coder <clio-coder@iowarp.ai>
+```
+
+- `Assisted-by` means Clio materially created or edited work in the commit.
+- `Tested-by` means an actual validation command completed successfully against
+  the work. Prose that claims tests passed is not evidence.
+- `Reviewed-by` means an independent verifier or reviewer produced a passing
+  result. A self-review or an unsealed assertion is not enough.
+- `Co-authored-by` is added only when Clio materially authored part of the
+  change. GitHub and GitLab recognize this compatibility trailer for
+  contributor and avatar display. Testing or review alone never adds it.
+
+Existing human trailers stay in place. A Clio trailer already present in any
+letter case is respected rather than repeated, line endings are normalized only
+while attribution is enabled, and repeated processing is idempotent. When a directly relevant
+receipt-v15 digest passes integrity verification, Clio may additionally add the
+full digest:
+
+```text
+Clio-Evidence: receipt-v15/sha256:<64-character digest>
+```
+
+Clio does not invent, shorten, or add an unrelated digest. The role trailers do
+not depend on this optional line.
+
+## Commit paths and hooks
+
+The deterministic SDLC fleet attributes its plan, code, and documentation
+commits at the controlled commit seam. Material agent work supplies assistance
+and authorship, successful deterministic code steps supply testing, and a
+passing independent gate supplies review. Any later workspace mutation makes
+prior testing and review stale; only validation or review that is fresh for the
+commit can be claimed.
+
+For Clio-controlled child processes, Clio supplies a process-local managed
+hooks directory through command-scope Git configuration. The directory holds a
+chaining wrapper for every hook name Git knows, so the repository's own
+`pre-commit`, `commit-msg`, `pre-push`, and remaining default hooks still run
+exactly as before with their original exit status. Only the `prepare-commit-msg`
+wrapper adds anything, and only after the repository's own hook has run and
+succeeded. It runs only when both `AI_AGENT=clio-coder` and the effective
+attribution setting are present. It uses `git interpret-trailers`. Normal
+commits from an external terminal do not receive Clio's managed hooks.
+
+The child-process seams attribute by spawn provenance, not by sealed evidence.
+A commit the agent itself runs through the Bash tool, a worker, or a registered
+code step claims assistance and authorship, because it records the agent's own
+session work. A commit made by a delegated external harness over ACP claims
+assistance only, since that harness authored the change. A commit made by an
+operator hook command claims nothing. Testing and review are never claimed at
+these seams; only the fleet's coordinator-owned results can supply them.
+
+The managed hook attributes only a message supplied up front with `-m`, `-F`,
+or a merge. It skips amend, commit-message reuse, squash, cherry-pick, revert,
+rebase, sequencer operations, and editor sessions, so historical messages are
+not falsely attributed and an abandoned editor still aborts the commit.
+`--no-verify` does not bypass `prepare-commit-msg`, matching Git's normal hook
+semantics. The message is finalized at this stage before Git signs the commit,
+so signed commits retain their existing behavior.
+
+Clio never overwrites repository hooks or changes `core.hooksPath`. If a custom
+hooks path or another setup cannot be composed safely, Clio fails open, emits a
+bounded diagnostic, and relies on controlled commit seams such as the fleet
+runner. Attribution failure does not destroy a commit; only a pre-existing hook
+that already failed continues to block it.
+
+The repository probe behind the managed environment (whether the command's
+working directory is inside a work tree, and what `core.hooksPath` resolves to)
+is reused for ten seconds per working directory and Git environment, and the
+managed hooks directory is installed once per process. A `git init` or a
+`core.hooksPath` change takes effect for spawns that begin after that window.
+
+## Platform identity and avatar
+
+Git commit data contains names and email addresses, not logos. GitHub and
+GitLab obtain the displayed avatar from the platform account that has verified
+the commit email. Until maintainers verify `clio-coder@iowarp.ai` on
+IOWarp-controlled GitHub and GitLab identities, for example `clio-coder-bot` or
+`iowarp-clio`, those platforms render the trailers as plain text with a default
+avatar; the trailers themselves are complete and correct either way. That
+verification is a maintainer follow-up rather than a release gate, and
+`assets/clio-coder-avatar-512.png` is an exact PNG conversion of the existing
+512 px Clio logo for platforms that require PNG. No account creation or remote
+operation is performed by Clio Coder.

package/docs/glossary.md

@@ -127,7 +127,7 @@ This document defines core architectural concepts and terminology used throughou
 - **Owning Type**: `DispatchRequest` in `src/domains/dispatch/contract.ts`.
 
 ### 31. Run Ledger
-- **Definition**: The durable dispatch run list at `runs.json` in the state directory, retention-capped by `guardrails.maxDispatchRuns`. It is what the fleet board, `clio-coder runs`, and eval linking read.
+- **Definition**: The durable dispatch run list at `runs.json` in the state directory, retention-capped by `guardrails.maxDispatchRuns`. It is what the fleet board, `clio-coder fleet status`, and eval linking read.
 - **Owning Type**: `RunEnvelope` in `src/domains/dispatch/types.ts`, persisted by `src/domains/dispatch/state.ts`.
 
 ### 32. Agent Ledger

package/docs/installation-and-lifecycle.md

@@ -3,7 +3,7 @@
 Clio Coder is designed to be self-contained and platform-compliant. This document outlines the default directory paths, file purposes, permission levels, and lifecycle commands (`install`, `reset`, `upgrade`, and `uninstall`). Clio Coder installs from npm as `@iowarp/clio-coder` (`npm install -g @iowarp/clio-coder`, published since v0.3.0) or from a source checkout with a deterministic local symlink; the CLI classifies both install kinds and `clio-coder upgrade` handles each.
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard with a path simulator and visual flowcharts is located at [docs/html/lifecycle_blueprint.html](html/lifecycle_blueprint.html) (Version: 0.3.1). You can open it directly in any web browser to view details dynamically.
+> **Interactive Spec Available:** An interactive dashboard with a path simulator and visual flowcharts is located at [docs/html/lifecycle_blueprint.html](html/lifecycle_blueprint.html) (Version: 0.3.3). You can open it directly in any web browser to view details dynamically.
 
 ---
 
@@ -49,7 +49,7 @@ The tables above cover the per-user roots. A repository Clio works in also grows
 | `.clio-coder/profile.yaml` | Operator input | Operator profile; closed enums and bounded path lists. | Yes. | Kept |
 | `.clio-coder/fleets/*.md`, `.clio-coder/fleets/commands.yaml` | Overlay | Fleet contracts and their command registry. Adds to the fleets shipped under `src/domains/agents/fleets/`. | Yes; shipped fleets remain. | Kept |
 | `.clio-coder/agents/*.md` | Overlay | Project agent recipes. Composes with shipped builtins and the user's `~/.config/clio-coder/agents`; a project recipe reusing a builtin id is **ignored**, not applied, with a note on stderr. | Yes; shipped agents remain. | Kept, and named |
-| `.clio-coder/skills/**` | Overlay | Project skills, trusted as repository-local. Composes with skills Clio ships. | Yes; shipped skills remain. | Kept, and named |
+| `.clio-coder/skills/**` | Overlay | Project skills, trusted as repository-local. This is where `clio-coder skills install <name>` lands a catalog skill; the shipped catalog under the package's `skills/` is a marketplace to install from, not a discovery root, so nothing appears here until the operator installs it. | Yes; the shipped catalog remains installable. | Kept, and named |
 | `CLIO-CODER.md` (repository root) | Runtime state | The generated project handbook. Human-reviewable, but written by `context init`. | Yes; regenerate with `clio-coder context init`. | Kept unless `--all` |
 | `.clio-coder/codewiki.json` | Runtime state | Structural index, schema v5. | Yes; rebuilt by `clio-coder context index`. | **Removed** |
 | `.clio-coder/state.json` | Runtime state | Index fingerprint and freshness stamps. | Yes; forces a rebuild. | **Removed** |
@@ -63,10 +63,12 @@ The tables above cover the per-user roots. A repository Clio works in also grows
 user configuration directory, not in any repository.
 
 None of `.clio-coder/` is published by Clio's own package. The directories Clio ships
-(`src/domains/agents/builtins/`, `src/domains/agents/fleets/`, `skills/workflow/cut-it/`, `skills/git/`,
-`src/domains/prompts/fragments/`, `src/domains/providers/models/`) are read from
-the installed package root; the `.clio-coder/` entries above compose with them and never
-replace them on disk.
+(`src/domains/agents/builtins/`, `src/domains/agents/fleets/`, the whole `skills/` catalog
+with its `registry.yaml` and `skill-marketplace.json`, `src/domains/prompts/fragments/`,
+`src/domains/providers/models/`) are read from the installed package root; the `.clio-coder/`
+entries above compose with them and never replace them on disk. Builtin agent recipes bind
+skills straight out of the package catalog; the operator's own session reaches the same
+catalog only as a marketplace, through `clio-coder skills install <name>` or `/skill <name>`.
 
 ---
 
@@ -134,7 +136,7 @@ First-run target setup after install:
 **Option A: Local Model / API Key Target**
 ```bash
 clio-coder configure --list
-clio-coder configure --id local-lmstudio --runtime lmstudio-native --url http://localhost:1234 --model your-model --set-orchestrator --set-fleet-default
+clio-coder configure --id local-lmstudio --runtime lmstudio --url http://localhost:1234 --model your-model --set-orchestrator --set-fleet-default
 clio-coder targets use local-lmstudio
 clio-coder targets --probe
 clio-coder
@@ -198,15 +200,16 @@ The 0.3.0 binary prints its header (`install npm`, `channel latest`,
 `current 0.3.0`), runs `npm install -g @iowarp/clio-coder@latest`, and then
 hands over to the binary that install just put on `PATH` with
 `clio-coder upgrade --post-install`. That newer binary runs the migration
-check (the registry is empty for 0.3.1, so `state/migrations.json` is written
-as `{"applied": []}` and nothing else moves), runs `clio-coder doctor --fix`,
+check, records `2026-08-18-lmstudio-runtime-id` in `state/migrations.json`, and
+normalizes any legacy LM Studio target id, websocket URL, and stored credential
+name. It then runs `clio-coder doctor --fix`,
 which refreshes `install.json`, and reports the transition as
-`ok: 0.3.0 -> 0.3.1 (migrations: 0)`. The outer 0.3.0 process closes with
+`ok: 0.3.0 -> 0.3.1 (migrations: 1)`. The outer 0.3.0 process closes with
 `ok: 0.3.0 -> post-install checks complete`. Under nvm or a custom npm prefix
 this works because `npm install -g` and the bare `clio-coder` resolve through
 the same prefix; the doctor rows the child prints are the proof of which binary
 answered. `clio-coder upgrade --dry-run` first names the exact command it would
-run, says that no migrations are registered, and prints
+run, names the pending LM Studio migration, and prints
 `would refresh state metadata 0.3.0 -> 0.3.1` without touching the record.
 
 If you instead ran `npm install -g @iowarp/clio-coder` yourself, or launched
@@ -218,22 +221,26 @@ next `clio-coder` launch refreshes it. `install.json` then reads
 `upgradedFrom: "0.3.0"`; doctor's row becomes
 `0.3.1 (installed ..., upgraded ... from 0.3.0)`.
 
-The first interactive launch after the version changed shows one notice,
-`clio: upgraded 0.3.0 → 0.3.1. What changed at the keyboard: ...`, naming the
-commands that moved into `/settings` (`/targets`, `/fleet`, `/scoped-models`),
-the retired git skills (`commit-crafting`, `create-pr`, `investigate-issue`,
-`review-changes`, replaced by `file-ticket`, `fix-issue`, `ship`), the artifact
-tool's new default location under `.clio-coder/artifacts/`, and the CHANGELOG
-section for the rest. It is shown once per version, recorded as
-`noticedVersion` in `install.json`, and never to a headless `run` or an ACP
-server.
-
-Settings written by 0.3.0 keep working unchanged. `identity:` is accepted and
-ignored, since nothing ever read it; the next settings write drops the line. A
-fleet node's `clioEntry` is read as `clioCoderEntry` and left spelled as it
-was. `CLIO_CODER_MAX_RUNS` still reads as the older spelling of
-`CLIO_CODER_MAX_DISPATCH_RUNS`. No credentials, sessions, receipts, or memory
-records are touched.
+#### Upgrading to 0.3.3
+
+Upgrading from 0.3.1 to 0.3.3 is automated:
+
+```bash
+clio-coder upgrade
+```
+
+Key lifecycle and operational updates in v0.3.3:
+- Upgraded the underlying engine SDK libraries to 0.84.0 with signal-aware OAuth cancellation.
+- Hardened migration resilience: damaged `credentials.yaml` files no longer block upgrades when no renames are needed (#121); `--skip-migrations` is available as a recovery override.
+- Fullscreen TUI mode (`terminal.tuiMode`, `terminal.fullscreenScrollbar`) is available via Settings → Terminal (restart required). Adaptive presentation pacing is the live `terminal.smoothStreaming` setting; 0.3.3 defaults it to `off`, with conservative `auto` and explicit `on` available from the same section.
+- Interactive launch paints a measured Stage 0 shell on the same terminal and editor that Stage 1 hydrates. Typing, queued submits, resize, and Ctrl+C remain live during hydration; set `CLIO_CODER_INSTANT_SHELL=0` for the legacy fully hydrated first-frame path.
+- Turn settlement is enforced on `/new`, `/resume`, `/tree`, and `/fork` to cleanly commit in-flight streams before session writer replacement (#114).
+- Resumed and forked session entry replays standardize message prefixes through `src/engine/messages.ts`.
+- `AI_AGENT=clio-coder` is set on all child processes for system attribution.
+
+The first interactive launch after upgrading shows the version notice:
+`clio: upgraded 0.3.1 → 0.3.3. What changed at the keyboard: ...`
+Recorded once per version in `install.json` as `noticedVersion`.
 
 ### C. System Resets (`clio-coder reset`)
 Selective recovery wipes:

package/docs/middleware-and-components.md

@@ -1,7 +1,7 @@
 # Middleware and Component Registry
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard with an interactive component scanner and a dynamic hook-and-effect pipeline is located at [docs/html/middleware_blueprint.html](html/middleware_blueprint.html) (Version: 0.3.1).
+> **Interactive Spec Available:** An interactive dashboard with an interactive component scanner and a dynamic hook-and-effect pipeline is located at [docs/html/middleware_blueprint.html](html/middleware_blueprint.html) (Version: 0.3.3).
 
 Clio Coder has two related but separate surfaces: