@iowarp/clio-coder 0.3.9 → 0.4.1

package/docs/installation-and-lifecycle.md

@@ -3,7 +3,19 @@
 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.9). 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.4.0). You can open it directly in any web browser to view details dynamically.
+
+### Optional dependency: the Claude Agent SDK
+
+`@anthropic-ai/claude-agent-sdk` is an `optionalDependencies` entry, not a hard dependency. Its platform package carries a proprietary binary of roughly 224MB per platform, and only the `claude-sdk` runtime uses it. Skip it with:
+
+```bash
+npm install -g @iowarp/clio-coder --omit=optional
+```
+
+Measured on Linux x64 with a production install (`--omit=dev`): 387MB across 118 packages with the SDK, 143MB across 109 packages without it. That is 244MB and nine packages saved, a 63% smaller tree, and what remains is fully open-licensed.
+
+Everything except the `claude-sdk` runtime works on the smaller install: boot, `clio-coder doctor`, every other target and worker runtime. Dispatching a `claude-sdk` target on an install that omitted the package fails that run with a diagnostic naming the package and the command that fixes it (`npm install @anthropic-ai/claude-agent-sdk@0.3.186`); nothing else degrades, and nothing fails at startup.
 
 ---
 
@@ -84,6 +96,7 @@ The core files are created automatically during the first run. `credentials.yaml
 | **State** | `install.json` | Install metadata: Clio version, node, platform, `installedAt` (written once at first install), `upgradedAt` and `upgradedFrom` (stamped on a version change), and `noticedVersion` (the version whose one-time upgrade notice the interactive launch has shown). | Writer/umask default | Removed by uninstall / `reset --state`. |
 | **State** | `migrations.json` | Log of successfully applied schema/state migrations. | Writer/umask default | Removed by uninstall / `reset --state`. |
 | **Data** | `memory/records.json` | Long-term learning memories (up to 500 records) proposed/approved from runs. | Writer/umask default | Removed by uninstall / `reset --data`. |
+| **Data** | `tools/<id>/<version>/` | One pinned external program Clio downloaded on request (`clio-coder tools install <id>`), with its upstream license text and a `clio-install.json` recording url, sha256, platform and install time. Binaries `0o755`, documents `0o644`. Only the pinned version is kept: a successful install prunes the versions it supersedes. | `0o755` dir | `clio-coder tools remove <id>` deletes every version of one tool; removed by uninstall / `reset --data`. |
 | **State** | `audit/YYYY-MM-DD.jsonl` | Daily safety audit logs showing allowed/blocked tool actions. | Writer/umask default | Removed by uninstall / `reset --state`. |
 | **State** | `sessions/<cwdHash>/<id>/` | Session details: `meta.json`, `current.jsonl`, and fork hierarchies `tree.json`. | Writer/umask default | Removed by uninstall / `reset --state`. |
 
@@ -175,7 +188,7 @@ Runs a series of health sweeps across the environment:
 *   Asserts owner-only permissions on credentials (`0o600`).
 *   Reports the installed Clio, Node, platform, and engine package readiness.
 *   Checks config, data, state, cache, and state metadata freshness. It also warns when an OpenAI-compatible or Anthropic-compatible target appears to be a native LM Studio or Ollama server that should be converted.
-*   *Recovery:* Run `clio-coder doctor --fix` to create missing directories and templates, repair credential permissions, and refresh install metadata. Settings are always validated against the current schema; `--fix` does not rewrite removed keys or migrate an older settings file, so the operator must correct every reported path deliberately.
+*   *Recovery:* Run `clio-coder doctor --fix` to create missing directories and templates, repair credential permissions, and refresh install metadata. Settings are always validated against the current schema; `--fix` does not rewrite removed keys or migrate an older settings file. Run `clio-coder upgrade` for registered lifecycle migrations, including removal of the retired `panes.agents` and `panes.keepFailed` keys; paths with no registered migration still require deliberate editing.
 
 ### B. Upgrades (`clio-coder upgrade`)
 Refreshes state metadata and applies pending data-dir migrations.
@@ -256,7 +269,7 @@ inventory of what a level covers, because a remembered list drifts as soon as a
 new artifact is written into a root.
 
 *   `--state` *(Default)*: Deletes the state root only. It holds every session transcript and the audit trail beside it, so a reset is the end of `resume`, `/view`, and their history. This is the level a bare `clio-coder reset` selects, and it carries that note in its preview.
-*   `--data`: Deletes the data root only: memory, evidence, evals (durable products).
+*   `--data`: Deletes the data root only: memory, evidence, evals, and any vendored external tools (durable products). The vendored tools are the one entry a reset cannot regenerate locally; `clio-coder tools install <id>` downloads them again.
 *   `--cache`: Deletes the cache root only.
 *   `--auth`: Deletes `credentials.yaml`. Removes all saved keys.
 *   `--config`: Deletes `settings.yaml` to revert preferences to default.

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.9).
+> **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.4.0).
 
 Clio Coder has two related but separate surfaces:
 

package/docs/model-catalog.md

@@ -1,7 +1,7 @@
 # Model Catalog, Runtime Refresh, and Field Notes
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard mapping capabilities, probe discovery, and target resolution is located at [docs/html/models_blueprint.html](html/models_blueprint.html) (Version: 0.3.9).
+> **Interactive Spec Available:** An interactive dashboard mapping capabilities, probe discovery, and target resolution is located at [docs/html/models_blueprint.html](html/models_blueprint.html) (Version: 0.4.0).
 
 Clio Coder treats a selectable model as the intersection of three sources:
 
@@ -161,6 +161,15 @@ The Context Engine evaluates thinking mechanisms per model target and manages li
 
 - **Ollama Native (`ollama-native`):** Ollama utilizes the native `thinking` field in the request and response payloads. The engine handles Ollama-specific effort levels and streams reasoning increments cleanly through the native thinking channel.
 - **LM Studio (`lmstudio`):** Chat uses the OpenAI-compatible `/v1/chat/completions` surface, including its `reasoning` stream field. Clio controls thinking only with `reasoning_effort` and never sends `chat_template_kwargs` to LM Studio. See <https://lmstudio.ai/docs/developer/openai-compat/chat-completions>.
+- **LiteLLM (`litellm`):** This is a gateway runtime, not an `openai-compat`
+  alias. Discovery checks `/health/liveliness`, reads aliases and capability
+  metadata from `/v1/model/info`, and records the physical deployment reported
+  by `x-litellm-*` response headers. Defaults stay conservative when metadata is
+  absent: tools, vision, and reasoning are not inferred. The runtime advertises
+  standard `json_schema` structured output and treats schema-plus-tools as a
+  conflict because the gateway alias does not identify one stable upstream.
+  Residency is observe-only because LiteLLM owns loading and eviction behind the
+  alias.
 - **OpenAI Completions (`openai-completions`):** The OpenAI-compatible completions provider preserves reasoning blocks within assistant messages. It replays thinking blocks via the `reasoning_content` parameter in the message history, ensuring that the model maintains its chain-of-thought across conversational turns without stripping the data.
 - **Anthropic OAuth / API (`anthropic-max`):** Uses the `anthropic-extended` thinking format. The engine supports Anthropic's native extended thinking block protocol, streaming thinking increments and outputting them wrapped appropriately or natively depending on target capabilities.
 - **Reasoning-Never Models (`thinking.mechanism: none`):** When a model is configured or cataloged with `thinking.mechanism: none`, it is treated as a reasoning-never model. For these models, Clio must not send any thinking fields or parameters in requests, must not replay thinking blocks, must not surface thinking events to the TUI, and must not preserve or log reasoning token usage in metrics.

package/docs/observability.md

@@ -1,7 +1,7 @@
 # Observability Viewer
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/observability_blueprint.html](html/observability_blueprint.html) (Version: 0.3.9).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/observability_blueprint.html](html/observability_blueprint.html) (Version: 0.4.0).
 
 `/view` is the interactive artifact viewer for a Clio session. It keeps the live transcript compact while preserving a full inspection path for durable artifacts, task ledgers, and successful workspace outputs.
 
@@ -257,8 +257,8 @@ The base provenance sets, steering, routing, quality, worker identity, result-co
 | `safety.toolTelemetry.ingestionErrors` | `number` | Current dispatch receipts | Malformed or lost frames, event-fold/source errors, and drain timeouts that make otherwise mediated telemetry incomplete | experimental |
 | `safety.toolTelemetry.unfinished` | `{ tool, count }[]` | Current dispatch receipts | Tool starts that had no matching finish when the receipt sealed | experimental |
 | `safety.toolTelemetry.workspaceMutationPossible` | `boolean` | Current dispatch receipts | Whether incomplete or unavailable telemetry could conceal a shared-workspace mutation; retry admission fails closed when true | experimental |
-| `autonomyEnforcement.grade` | `string` | Always in v0.3.7 | The autonomy grade level enforced for the run | experimental |
-| `autonomyEnforcement.autonomy` | `string` | Always in v0.3.7 | The effective autonomy level name (e.g. auto-edit, suggest, read-only, full-auto) | experimental |
+| `autonomyEnforcement.grade` | `string` | Always in v0.4.0 | The autonomy grade level enforced for the run | experimental |
+| `autonomyEnforcement.autonomy` | `string` | Always in v0.4.0 | The effective autonomy level name (e.g. auto-edit, suggest, read-only, full-auto) | experimental |
 | `autonomyEnforcement.externalMode` | `string` | When running external worker | The execution mode of the external worker runtime | experimental |
 | `autonomyEnforcement.dangerousBypass` | `boolean` | When running external worker | Whether a safety bypass was explicitly activated | experimental |
 | `validationGrounding.claimed` | `number` | Validation grounding evaluated | Count of validations claimed by worker | experimental |

package/docs/proactive-memory.md

@@ -1,6 +1,6 @@
 # Proactive task memory
 
-> **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.9).
+> **Interactive Spec Available:** An interactive memory lifecycle dashboard and simulator is located at [docs/html/memory_blueprint.html](html/memory_blueprint.html) (Version: 0.4.0).
 
 Clio's proactive task memory protects long-running work from behavioral state
 decay: a requirement, environment fact, failed attempt, or diagnosis can still

package/docs/prompt-envelope-and-tools.md

@@ -1,7 +1,7 @@
 # Prompt Envelope and Tools
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/tools_blueprint.html](html/tools_blueprint.html) (Version: 0.3.9).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/tools_blueprint.html](html/tools_blueprint.html) (Version: 0.4.0).
 
 Clio Coder keeps the model-facing envelope stable and moves enforcement into the runtime registry and safety policy.
 

package/docs/provider-adapter-cookbook.md

@@ -1,7 +1,7 @@
 # Provider Adapter Cookbook
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive runtime adapter descriptor builder and probe sequence capability checklist is located at [docs/html/provider_adapter_blueprint.html](html/provider_adapter_blueprint.html) (Version: 0.3.9).
+> **Interactive Spec Available:** An interactive runtime adapter descriptor builder and probe sequence capability checklist is located at [docs/html/provider_adapter_blueprint.html](html/provider_adapter_blueprint.html) (Version: 0.4.0).
 
 This cookbook guides developers through implementing custom model runtimes and inference server integrations within Clio Coder. It explains the runtime descriptor interfaces, probing protocols, model synthesis, and how to configure reasoning and thinking behaviors.
 

package/docs/release-cut-checklist.md

@@ -1,193 +1,180 @@
-# v0.3.8 Release-Cut Checklist
-
-The ordered steps that turn the prepared `v0.3.8` branch into a published
-release. Everything above the line marked **AUTHORIZATION BOUNDARY** is
-repeatable and reversible and is run locally before the cut. Everything below
-it is external or irreversible and needs an explicit decision from the
-operator. This page is the procedure and the release report carries the live
-state of every step.
-
-## Status of the prepared tree
-
-| Item | State |
-| --- | --- |
-| Branch | After the release-cut evidence commit, `v0.3.8` is 30 commits ahead of `main`: the 29-commit candidate through `9b7b80cc` plus the final documentation and verification-evidence commit. The candidate includes the original implementation, the four release-test fixes (#233, #235, #238, #239), the WTF-P extension-resource merge, the `$ARGUMENTS` fidelity fix (#240), and the extension-agent resolution fix (#241). `origin/v0.3.8` remains at `af6546b2`, 17 commits behind the final local tip. |
-| `package.json` version | `0.3.8`; `package-lock.json` agrees at both version fields; the top changelog heading is `## 0.3.8 - 2026-08-29`. |
-| `main` | `598be99c`, the v0.3.7 release SHA; it is an ancestor of the final `v0.3.8` candidate and moves only at Part 4. |
-| `origin/main` | `598be99c`, matching local `main` and still an ancestor of the final candidate. |
-| Tags | `v0.3.7` exists on `598be99c`; no `v0.3.8` tag exists locally or remotely. The redundant `wtfp-safety` tag was deleted. The eight local `tmp-032-*` recovery tags remain and must never be pushed. |
-| GitHub Release | `v0.3.7` is published; no GitHub Release exists for `v0.3.8`. |
-| npm registry | `@iowarp/clio-coder@0.3.8` is absent; `latest` is `0.3.7`; the 0.3.8 dist-tag is undecided. |
-| npm history | Published versions are 0.3.0 through 0.3.4, 0.3.6, and 0.3.7. Version 0.3.5 was published and withdrawn and can never be reused. |
-| Milestone | `v0.3.8` has six open issues, all fixed on the branch: #233, #235, #238, #239, #240, and #241. They close from their `Fixes` trailers when the final candidate reaches `main`. |
-| Interactive release test | The original three-round report is `docs/release-notes/v0.3.8-release-test.md` (57 PASS / 8 FAIL / 3 PARTIAL / 6 OBSERVATION / 2 NOT RUN). The continuation is `docs/release-notes/v0.3.8-verification.md` (44 PASS / 6 non-blocking FAIL / 7 OBSERVATION / 1 NOT RUN), which closes the blocker, verifies the three later merges, and carries the final `CUT` verdict. |
-| Commit provenance identity | Still a post-release maintainer follow-up rather than a release gate; unchanged from 0.3.7. |
-
----
-
-## Part 1: verification (repeatable)
-
-Run against the exact final candidate with `NO_COLOR` unset and
-`TERM=xterm-256color`, so the color-sensitive tests see a real terminal.
-
-1. `npm run typecheck`
-2. `npm run lint` (Biome plus the hygiene checks, which include the boundary invariants and the skills pin check)
-3. `npm run skills:check`
-4. `npm run build`
-5. `npm run test`
-6. `npm run test:trace-viewer`
-7. `npm run ci` (runs 1 through 6)
-8. `npm run ci:release` (7 plus `scripts/check-release.mjs`: dist shebang
-   integrity, version coherence between `package.json` and the top
-   `CHANGELOG.md` heading, the deterministic 26-scenario behavioral machinery
-   corpus against its checked baseline, the forbidden-file list, the required
-   runtime resources, and the tarball and unpacked size budgets). A baseline
-   mismatch prints reviewable evidence and names prompt- or recipe-affected
-   corpus results. For an intentional change, inspect that diff, run
-   `node benchmarks/eval/check-behavioral-release.mjs --update` (with `TMPDIR` on a disk-backed path if `/tmp` is a small tmpfs),
-   review `benchmarks/eval/behavioral-machinery-baseline.json`, and commit it
-   with the change.
-9. Optional: step 8 again under Node 24. Hosted CI gates on Node 22 alone,
-   the `engines` floor; the weekly `flake-hunt` workflow carries Node 24.
-   Repeat locally only when the cut touches runtime-sensitive code.
-10. `npm run live:smoke -- --target <id>` for one real headless turn through
-    the built binary against a configured target, which is the one release
-    check a deterministic suite cannot give. The packaged-install lifecycle
-    (pack, install into a clean prefix, run the installed launcher) is
-    `tests/smoke/pack-install.test.ts` and already ran under step 5.
-11. `npm pack --dry-run`, then a real `npm pack` into a temporary directory.
-    Inspect the complete file list: `skills/`, `docs/*.md`, the builtin
-    agents, the model catalogs, and `damage-control-rules.yaml` are present;
-    `docs/html/`, `apps/workbench`, `.superpowers`, `tests/`, `scripts/`,
-    `benchmarks/`, scratch files, and source maps are absent. Record the
-    filename, packed and unpacked sizes, integrity, and shasum.
-12. Install that tarball into a clean temporary prefix with an empty
-    `CLIO_CODER_HOME` and verify `--version`, `--help`, an empty-state non-TTY
-    launch, `doctor`, and `uninstall --dry-run` without developer-local state.
-13. Before interactive release testing, run the model-required public
-    behavioral corpus manually against the release target and built CLI:
-    `node dist/cli/index.js eval run --suite benchmarks/eval/behavioral-model.yaml --target mini --clio-coder-entry dist/cli/index.js`
-    and
-    `node dist/cli/index.js eval run --suite benchmarks/eval/behavioral-model-negative-control.yaml --target mini --clio-coder-entry dist/cli/index.js`.
-    Retain both Artifact v4 files as release evidence. The positive corpus must
-    report its scenario and role rows without an undeclared envelope mismatch;
-    the negative control must still record violated exploration and safety
-    labels. These model-dependent runs are manual and are never required by
-    ordinary deterministic CI. Continue with interactive release testing,
-    which this cut added because the release is
-    almost entirely interactive surface: a tester agent drives the step-12
-    install through real TUI sessions in a throwaway repository, one session
-    per shipped feature, against local targets for the main session and a
-    cloud target for council members and advice, and writes a per-feature
-    PASS / FAIL / BLOCKED table with evidence. A FAIL on a deterministic
-    behavior (a refusal, a file, a receipt field, CLI output) blocks the cut;
-    a BLOCKED(model) on a model decision does not.
-
-## Part 2: version and notes (repeatable)
-
-14. Files carrying a version reference, to update together if the number
-    changes: `package.json` and `package-lock.json`, the `## 0.3.8 - <date>`
-    heading in `CHANGELOG.md`, the `(Version: 0.3.8)` markers in `docs/*.md`,
-    the `Blueprint (v0.3.8)` titles in `docs/html/*.html`, the `--branch`
-    pin in the README install block (the hygiene lint checks it), and the
-    measured-at figures in `scripts/check-release.mjs` if the package size
-    moved materially. For 0.3.7 the tarball measured 6.5 MB packed and
-    37.9 MB unpacked; re-measure for 0.3.8, inside the 10 MB and 50 MB ceilings set for 0.3.6.
-15. Confirm the `## 0.3.8` section of `CHANGELOG.md` describes every
-    user-visible behavior change under `### Added`, and every change to an
-    existing behavior under `### Changed`, and carries no Workbench release
-    narrative. The release workflow uses this section verbatim as the GitHub
-    Release body.
-16. `docs/artifact-versions.md` lists every persisted artifact this release
-    added or re-versioned. For 0.3.8 that is run receipt integrity v20, which
-    adds `pathProvenance` on dispatch intent and the resolved `pathScope`, and
-    whose entry must also record that a receipt below v20 is reported as
-    retired rather than invalid, and the durable assignment record, which now
-    carries its owner pid, process birth token, and acquisition time.
-17. Re-run `npm run ci:release` after any version edit and commit as one
-    commit on `v0.3.8`.
+# v0.4.1 Release-Cut Checklist
+
+This is the ordered procedure for turning the prepared `v0.4.1` branch into a
+published release. Everything above the **AUTHORIZATION BOUNDARY** is local,
+repeatable, and reversible. Everything below it changes a remote ref, creates a
+release, or publishes an immutable package and therefore requires the
+operator's explicit approval of the exact candidate SHA and commands.
+
+## Part 1: verify the exact candidate
+
+1. Resolve and record the exact candidate SHA. Confirm `package.json` and both
+   version fields in `package-lock.json` are `0.4.1`, and confirm the first
+   version heading in `CHANGELOG.md` is exactly
+   `## 0.4.1 - 2026-09-01`. Work from the branch ref explicitly when a branch
+   and tag share the name: `refs/heads/v0.4.1` is the branch and
+   `refs/tags/v0.4.1` is the tag.
+2. Confirm the tracked worktree is clean. Do not fold unrelated local or
+   ignored release evidence into the candidate.
+3. Install exactly from the lockfile:
+
+   ```sh
+   npm ci --prefer-offline --no-audit --no-fund
+   ```
+
+4. Run the one local release gate:
+
+   ```sh
+   npm run ci:release
+   ```
+
+   `ci:release` runs `ci` and then `scripts/check-release.mjs`. The `ci` script
+   performs typecheck; Biome and repository hygiene; the shipped-skill pin
+   check; the build; the 35-file `node --test` suite; and the trace-viewer
+   tests. The release audit then checks the built launcher and dist contents,
+   version/changelog coherence, required package resources, dependency audit,
+   and tarball size and contents. Run individual subcommands only to diagnose a
+   failure; rerunning each one before `ci:release` does not add coverage.
+5. Confirm the hosted push/PR configuration still has one CI workflow, one
+   Node 22 job, and one release-gate step in `.github/workflows/ci.yml`. There
+   is no repeat/shuffle job, shard matrix, or Node 24 lane.
+   `.github/workflows/release.yml` is a separate tag-only publication workflow;
+   it reruns the same `ci:release` gate on the tagged tree rather than inheriting
+   another workflow's result.
+6. Keep evals outside the gate. The engine under `src/domains/eval/` and the
+   reference suites under `evals/` ship for explicit operator measurements,
+   but neither CI nor `ci:release` runs an eval. When a release-specific model
+   measurement is requested, run it and retain its artifacts separately:
+
+   ```sh
+   node dist/cli/index.js eval run --suite evals/behavioral-model.yaml --target <id> --clio-coder-entry dist/cli/index.js
+   node dist/cli/index.js eval run --suite evals/behavioral-model-negative-control.yaml --target <id> --clio-coder-entry dist/cli/index.js
+   ```
+
+   These runs can inform an operator decision, but they are not CI or release
+   gates. The model-free `evals/behavioral-machinery.yaml` suite is likewise a
+   maintained reference suite, not a checked release baseline.
+7. When a configured target is available, run one real built-binary turn:
+
+   ```sh
+   npm run live:smoke -- --target <id>
+   ```
+
+   Record a missing or unauthorized target as a deferred live check; never
+   substitute a model-dependent result for the deterministic gate.
+8. Inspect the package twice: first with `npm pack --dry-run`, then with a real
+   `npm pack` directed to a temporary directory. Record the filename, integrity,
+   shasum, packed size, and unpacked size. Confirm `dist/`, `src/`, `skills/`,
+   `evals/`, the Markdown guides, package metadata, and required runtime assets
+   are present. Confirm `docs/html/`, `apps/workbench/`, `.superpowers/`,
+   `tests/`, `scripts/`, scratch files, and source maps are absent.
+9. Install that tarball into a clean temporary prefix with an empty
+   `CLIO_CODER_HOME`. Verify `clio-coder --version`, `--help`, an empty-state
+   non-TTY launch, `doctor`, and `uninstall --dry-run` without using
+   developer-local state. The in-suite installed-package smoke already proves
+   a packed install can launch from a foreign working directory; this step
+   inspects the exact final tarball.
+10. Run the interactive release matrix against the clean install. Cover fresh
+    onboarding, v1 settings migration, all seven `/settings` deep links,
+    retired-command tombstones, slash autocomplete, `@` references, public and
+    private bang operators, paste inertness, marketplace promotion, and the
+    opt-in workers dock. Record PASS / FAIL / BLOCKED with concrete evidence.
+    A deterministic behavior failure blocks the cut; a model-choice outcome is
+    reported as model-dependent rather than rewritten into a deterministic
+    claim.
+
+## Part 2: notes and package coherence
+
+11. Confirm the `## 0.4.1 - 2026-09-01` changelog section tells the complete
+    release story in release-body order and contains no `Unreleased` section
+    above it. The tag workflow extracts this section verbatim for the GitHub
+    Release.
+12. Confirm README quickstart and source-install commands name real commands,
+    current paths, and `v0.4.1`. Confirm current eval documentation points to
+    `src/domains/eval/` and `evals/`, not to a retired parallel tree.
+13. Confirm `docs/artifact-versions.md` includes every persisted artifact added
+    or re-versioned by the candidate, including any canonical naming schema
+    identifiers. A compatibility reader does not make a newly emitted schema
+    optional to document.
+14. After any version, changelog, package-list, or release-note edit, rerun
+    `npm run ci:release` and commit the coherent result on `v0.4.1`.
 
 ## Part 3: present the gate
 
-18. Report to the operator before touching `main`: the exact final `v0.3.8`
-    SHA and clean status, the commits added since the handoff SHA, the gate
-    commands with pass/fail totals, the package version and changelog heading,
-    the tarball audit, the clean-install results, the interactive test table,
-    and any deferred live check, confirmation that no tag, GitHub Release, or
-    npm version exists yet, the proposed commands for Parts 4 through 6, and
-    the npm dist-tag. The dist-tag is the operator's call; for 0.3.7 the
-    operator chose `latest` on 2026-08-24; 0.3.8's dist-tag is undecided.
+15. Before touching a remote ref, report the exact final candidate SHA and
+    tracked status; commits added since the prior handoff; the local
+    `ci:release` result; the GitHub Actions URL for the candidate when one
+    exists; package and changelog versions; tarball audit; clean-install and
+    interactive results; any deferred live or eval measurement; and the
+    proposed commands for the remaining parts.
+16. Reconfirm whether `refs/tags/v0.4.1`, a v0.4.1 GitHub Release, or
+    `@iowarp/clio-coder@0.4.1` already exists. Obtain the operator's npm
+    dist-tag decision explicitly; do not infer `latest` or `next` from a prior
+    release.
 
 ---
 
 ## AUTHORIZATION BOUNDARY
 
-Every step below leaves the local checkout, is externally visible, or cannot be
-undone by a local `git` command. None of them runs without the operator
-confirming the exact SHA and the commands.
+Every step below is externally visible or cannot be undone by an ordinary
+local Git command. Do not execute any of it until the operator approves the
+exact SHA and commands.
 
 ## Part 4: fast-forward `main`
 
-19. `git fetch origin` immediately before integrating; require `origin/main`
-    to be an ancestor of the reviewed `v0.3.8` tip and confirm no other
-    worktree has `main` checked out.
-20. `git checkout main && git merge --ff-only v0.3.8`. No merge commit, no
-    rebase, no reset. Verify `main` equals the reviewed SHA and is clean.
-21. `git fetch origin` once more; stop on any unexpected remote movement. Then
-    `git push origin main`. Never `--force` or `--force-with-lease`. The push
-    closes the six milestone issues through their `Fixes` trailers.
-
-## Part 5: exact-SHA CI, tag, GitHub Release
-
-22. The `main` push triggers the `ci` workflow. Require that exact-SHA run to
-    finish green before tagging; `release.yml` then runs the same gate again on
-    the tagged tree itself. A red run blocks the cut: investigate it rather than
-    tagging around it, and never silence a flake with an unrelated change.
-23. Reconfirm that tag `v0.3.8` and the GitHub Release do not exist, then
-    `git tag -a v0.3.8 -m "Clio Coder 0.3.8"` on the green SHA and
-    `git push origin refs/tags/v0.3.8`.
-24. The tag push triggers `.github/workflows/release.yml`, which verifies the
-    tag matches `package.json`, runs `npm run ci:release` on the tagged tree,
-    extracts the `## 0.3.8` section of `CHANGELOG.md` as the release body, and
-    attaches the tarball. Do not create a release by hand. Verify the run's
-    SHA, the notes, the attached tarball, and the URL.
-
-## Part 6: npm publication (irreversible)
-
-25. `npm whoami` and confirm the registry and account; reconfirm
-    `@iowarp/clio-coder@0.3.8` is still absent.
-26. Obtain the operator's explicit dist-tag decision. `latest` makes this the
-    default install for every user; `--tag next` keeps `0.3.7` as the default.
-27. Run `npm publish` once. `prepublishOnly` re-runs `ci:release` as a safety
-    net; it is not a substitute for Part 1.
-28. A published version cannot be replaced. `npm unpublish` is restricted and
-    time-limited; a mistake is corrected by publishing a higher version.
-
-## Part 7: post-publish verification and follow-ups
-
-29. `npm view @iowarp/clio-coder@0.3.8` and the selected dist-tag.
-30. On a clean machine, `npm install -g @iowarp/clio-coder` from the registry
-    rather than from a local tarball, then repeat step 12 against it, plus
-    `configure` to a real target and one real turn when one is authorized.
-    This is the only step that tests what users actually receive.
-31. From an installation of 0.3.7, verify `clio-coder upgrade` finds and
-    applies 0.3.8.
-32. Record the SHA, CI URL, tag, GitHub Release URL, npm version and dist-tag,
-    tarball evidence, and the post-publish verification in the release report.
-33. Maintainer follow-up, independent of the release: verify the commit
-    provenance email `clio-coder@iowarp.ai` on IOWarp-controlled GitHub and
-    GitLab identities such as `clio-coder-bot` or `iowarp-clio`, and upload
-    `assets/clio-coder-avatar-512.png` as the account avatar where PNG is
-    required. Commit data itself cannot carry a logo, so this affects only how
-    those platforms render the trailers, never whether attributed commits or
-    the release work. Clio never creates accounts or performs remote
-    operations for this.
+17. `git fetch origin` immediately before integrating. Require `origin/main`
+    to be an ancestor of the reviewed candidate and confirm no other worktree
+    has `main` checked out.
+18. Fast-forward local `main` to `refs/heads/v0.4.1`; do not create a merge
+    commit, rebase the candidate, or reset a published branch. Verify `main`
+    equals the reviewed SHA and is clean.
+19. Fetch once more and stop on unexpected remote movement. Push `main` without
+    force.
+
+## Part 5: exact-SHA CI, tag, and GitHub Release
+
+20. The `main` push triggers the single `ci` workflow. Require its one Node 22
+    job for the exact reviewed SHA to finish green before tagging. A red run
+    blocks the cut and is investigated on its own evidence.
+21. Reconfirm the tag and GitHub Release do not exist. Create annotated tag
+    `v0.4.1` on the green SHA and push only `refs/tags/v0.4.1`.
+22. The tag triggers `.github/workflows/release.yml`. It verifies the tag
+    matches `package.json`, independently runs `npm run ci:release` on the
+    tagged tree, packs the tarball, extracts the v0.4.1 changelog section, and
+    creates the GitHub Release. It does not publish to npm. Verify the run SHA,
+    release notes, attached tarball, and URL.
+
+## Part 6: npm publication
+
+23. Run `npm whoami`; confirm the registry, account, package scope, and that
+    `@iowarp/clio-coder@0.4.1` is still absent.
+24. Reconfirm the operator's dist-tag decision, then run `npm publish` once
+    with that decision. `prepublishOnly` reruns `ci:release`; it is a final
+    safety net, not a substitute for Parts 1 and 5.
+25. Treat publication as irreversible. A published version cannot be replaced;
+    correct a mistake with a higher version rather than attempting to reuse
+    `0.4.1`.
+
+## Part 7: post-publish verification
+
+26. Verify `npm view @iowarp/clio-coder@0.4.1` and the selected dist-tag.
+27. On a clean machine, install from the registry rather than the local
+    tarball. Repeat the version/help/doctor lifecycle checks, then configure a
+    real target and run one real turn when authorized.
+28. From a supported pre-v0.4.1 installation, run `clio-coder upgrade` and
+    verify settings v2 plus the recorded Clio Coder naming migration. Confirm
+    canonical writers use the new machine identifiers and a released legacy
+    identifier remains read-compatible within the documented v0.5/v0.6 window.
+29. Record the final SHA, CI and tag-workflow URLs, tag, GitHub Release URL,
+    npm version and dist-tag, tarball evidence, and post-publish verification in
+    the release report.
 
 ---
 
 ## Rollback
 
-There is no rollback for step 27. Before it, every step is reversible: steps
-23 and 24 by deleting the local and remote tag and the draft release, steps 19
-through 21 by a new forward commit on `main` (never by rewriting it), and
-everything in Parts 1 and 2 by `git checkout`.
+There is no rollback after npm publication. Before publication, delete only
+newly created release artifacts that the operator explicitly authorizes for
+removal. Correct a pushed `main` branch with a new forward commit, never by
+rewriting it. Local verification and note edits remain ordinary reversible Git
+work until they cross the authorization boundary.

package/docs/safety-model.md

@@ -1,7 +1,7 @@
 # Clio Coder Safety Model
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/safety_blueprint.html](html/safety_blueprint.html) (Version: 0.3.9).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/safety_blueprint.html](html/safety_blueprint.html) (Version: 0.4.0).
 
 Clio Coder's safety posture is code-enforced, not prompt-only. As the orchestrator coding agent in the [IOWarp](https://iowarp.ai) ecosystem developed by the [Gnosis Research Center](https://grc.iit.edu) at Illinois Tech under NSF Award [#2411318](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2411318), Clio gates execution by target capabilities, the tool registry, the safety policy engine, project policies, protected-artifact checks, and audit receipts.
 
@@ -13,7 +13,7 @@ Source of truth: `src/domains/safety/**`, `src/tools/registry.ts`, `src/tools/bo
 
 The `autonomy` setting (`read-only` | `suggest` | `auto-edit` | `full-auto`) is an enforced dial. It controls exactly one thing: which action classes run immediately, which park for operator approval, and which are auto-denied. The safety net (damage-control rules, path policy, protected artifacts, loop guard, dispatch scope admission) is independent of the dial and identical at every level. When a `[safety-net]` notice appears at full-auto, that is the always-on net working as designed, not a contradiction of the level.
 
-In Clio Coder v0.3.7, effective autonomy resolution is strictly centralized in `src/entry/orchestrator.ts` through `resolveEffectiveAutonomy` and `resolveBaselineAutonomy`. Every admission surface (tool registry admission, dispatch plan provenance, and ACP session snapshots) delegates to this pair of functions so that fallback paths cannot diverge across execution contexts. `resolveBaselineAutonomy` evaluates dispatch settings overrides, headless CLI options, and configuration settings before applying the default `auto-edit` level. `resolveEffectiveAutonomy` combines any active ACP session autonomy level with the baseline resolution.
+In Clio Coder v0.4.0, effective autonomy resolution is strictly centralized in `src/entry/orchestrator.ts` through `resolveEffectiveAutonomy` and `resolveBaselineAutonomy`. Every admission surface (tool registry admission, dispatch plan provenance, and ACP session snapshots) delegates to this pair of functions so that fallback paths cannot diverge across execution contexts. `resolveBaselineAutonomy` evaluates dispatch settings overrides, headless CLI options, and configuration settings before applying the default `auto-edit` level. `resolveEffectiveAutonomy` combines any active ACP session autonomy level with the baseline resolution.
 
 ### Autonomy levels
 

package/docs/scientific-validation.md

@@ -1,11 +1,11 @@
 # Clio Coder Scientific Validation Contracts
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive numerical tolerance calculator and HPC queue execution simulator is located at [docs/html/validation_blueprint.html](html/validation_blueprint.html) (Version: 0.3.9).
+> **Interactive Spec Available:** An interactive numerical tolerance calculator and HPC queue execution simulator is located at [docs/html/validation_blueprint.html](html/validation_blueprint.html) (Version: 0.4.0).
 
 Scientific software development cannot treat simple file presence as proof of correctness. A simulation script that crashes on rank 48, or writes out NetCDF arrays filled with `NaN`s, may still successfully write a file to the disk. 
 
-Clio Coder recognizes **scientific validation contract files** as an opt-in signal for a higher evidence bar. In v0.3.7, the session rigor resolver does not parse or enforce a scientific contract schema. The presence of `.clio-coder/validation.yaml`, `.clio-coder/validation.yml`, `validation.yaml`, `validation.yml`, or `VALIDATION.md` at the workspace root raises the default rigor level to `high`; the file contents are advisory material for developers, project agents, and external validators.
+Clio Coder recognizes **scientific validation contract files** as an opt-in signal for a higher evidence bar. In v0.4.0, the session rigor resolver does not parse or enforce a scientific contract schema. The presence of `.clio-coder/validation.yaml`, `.clio-coder/validation.yml`, `validation.yaml`, `validation.yml`, or `VALIDATION.md` at the workspace root raises the default rigor level to `high`; the file contents are advisory material for developers, project agents, and external validators.
 
 This advisory convention is separate from the executable project verifier catalog at `.clio-coder/verifiers.yaml`. The verifier catalog has a strict version-1 schema and admits exact argv vectors to the `verify` tool. Scientific validation contracts and handbook expectations do not grant command authority: prose such as `validators: ["python tools/check_grid.py"]` remains guidance until the project owner confirms the equivalent argv, cwd, timeout, and tags in `verifiers.yaml`. The executable catalog does not interpret numerical tolerances or artifact expectations; it only runs the explicitly declared process vector through safe-exec.
 
@@ -95,7 +95,7 @@ Comparing floating-point values in scientific computations must accommodate roun
 
 ## Common Scientific Artifact Families
 
-The following labels are useful project conventions for validation contracts and reports. They are not a closed, core-enforced enum in v0.3.7:
+The following labels are useful project conventions for validation contracts and reports. They are not a closed, core-enforced enum in v0.4.0:
 
 - **`HDF5` / `NetCDF` / `Zarr`:** Multi-dimensional scientific array files.
 - **`FITS`:** Flexible Image Transport System (used in astrophysics).

package/docs/session-lifecycle.md

@@ -1,6 +1,6 @@
 # Session Lifecycle
 
-This document is the authoritative specification for Clio Coder interactive and headless session lifecycles, on-disk ledger structures, tree-based conversation branching, checkpoints, and recovery protocols in `v0.3.7`.
+This document is the authoritative specification for Clio Coder interactive and headless session lifecycles, on-disk ledger structures, tree-based conversation branching, checkpoints, and recovery protocols in `v0.4.0`.
 
 Source implementations: `src/engine/session.ts` and `src/domains/session/`.
 

package/docs/skills-marketplace.md

@@ -1,7 +1,7 @@
 # Skills Marketplace
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/skills_blueprint.html](html/skills_blueprint.html) (Version: 0.3.9).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/skills_blueprint.html](html/skills_blueprint.html) (Version: 0.4.0).
 
 The Skills Hub (`/skill`) shows project skills, user skills, and the marketplace. Every marketplace row comes from the same local lookup that `clio-coder skills install <name>` and `/skill <name>` resolve through, so the hub lists nothing it cannot install.