@iowarp/clio-coder 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -9,6 +9,95 @@ produced it.
 Versions follow semantic versioning for a pre-1.0 project: minor versions may
 still change interfaces.
 
+## 0.3.2 - 2026-08-20
+
+This release upgrades the engine and hardens the terminal agent. The three engine SDK libraries move to 0.84.0, and a pass over the interactive surface ported the behaviors listed first below. A day of audits against the live code and a Qwen3.8-27B fleet on llama.cpp and LM Studio then produced the defects listed after them; every one is fixed here, each code fix carries a regression test, and the tickets (#110 through #136) carry the evidence.
+
+- Added default-on, evidence-aware Git commit provenance. Commits created through Clio receive only the `Assisted-by`, `Tested-by`, `Reviewed-by`, and contributor-compatible `Co-authored-by` trailers justified by trusted material authorship, successful validation commands, and independent passing review; the human author and committer remain unchanged, normal external commits are untouched, replayed history is skipped, and Settings -> Advanced can disable attribution with byte-for-byte message preservation.
+- Made the `/settings` filter narrow the catalog per keystroke (#135), matching `/model` and `/resume`. The `[/]` editor's draft is now the live query, so rows, section match counts, and the empty state track each character; Enter commits the query and Esc restores the committed one.
+- Named the winning project handbook in `/context` (#136). The overlay showed the preload class only (`full (0.3kB, 11 lines)`) and never said which `CLIO-CODER.md` or `CLIO-CODER.override.md` produced it, which the override semantics make ambiguous; it now lists the effective chain, ancestor to nearest, with workspace-relative paths.
+- Proved at the process boundary that the real built worker entry consumes Clio's injected compile-cache pair before any descendant it spawns can see it (#148). A hermetic smoke drives `dist/worker/entry.js` through one stubbed inference turn whose tool call is a real bash descendant launching a generic Node child; neither inherits Clio's cache directory or marker, while an operator-supplied `NODE_COMPILE_CACHE` reaches both unchanged through matching and mismatched spoofed markers on the direct `clio-coder worker` path.
+- Admitted prompts in the order they were typed during the instant shell's boot window. Two submissions in that window could be answered out of order: `ChatLoop.submit` had no admission gate, so a second submit arriving while the first was still awaiting its target probe and prompt compile ran the same pipeline concurrently, reached the engine first, and left the first recorded in the ledger but never sent. Each submit now waits for the previous one to own the stream or return, then lands as the next steer or follow-up, and the engine's raw active-prompt invariant no longer leaks into the transcript.
+- Made the fullscreen TUI render its transcript. `terminal.tuiMode: fullscreen` painted the header, composer, and footer but left the transcript region blank because the Stage 0 to Stage 1 terminal-lease handoff never attached the transcript to the alternate-screen root.
+- Made the footer's live `↓` and `⚡` counters report the streaming turn instead of the previous turn's totals. A turn cancelled while the model was still reasoning now settles the footer, the `turn · in/out` receipt, and the ledger's closing row to the same estimated spend instead of `↑0 ↓0`.
+- Kept the draft editable when an unknown slash command is rejected. `/compact` and `/skill:foo` failed closed correctly but cleared the editor; rejected input now stays in place and never enters prompt history.
+- Stopped shipping `docs/html` in the npm package. The Markdown guides under `docs/` remain bundled; `clio-coder docs` serves the interactive blueprints from a source checkout and, from an npm install, says where they are instead of serving nothing.
+- Replaced the bold experimental warning in the launchpad, the one-line session header, and the CLI banner with facts. The session header now names where Clio is working, which route answers, and what the context is ready for; the maturity caveat is stated once, in the README.
+
+- Upgraded the three Pi SDK libraries to 0.84.0, bringing Clio the release's provider, OAuth cancellation, terminal rendering, and platform fixes while preserving its own agent loop, session store, and regular-screen TUI behavior. Clio now uses Pi's explicit `TuiMainScreen` renderer and forwards concrete abort signals through built-in and ALCF OAuth refreshes, so a cancelled authentication flow no longer leaves token work running in the background.
+- Added the redacted action class, asking safety axis, and target beneath a tool row parked for approval. The facts use the same transient view as the permission overlay, disappear when the call resumes or settles, and never enter the session ledger.
+- Added Page Up and Page Down navigation to the `/resume` picker, moving by the 12 visible rows while preserving Clio's existing session filtering and ledger behavior.
+- Rendered successful `edit` and `write` calls as numbered diffs in their live tool rows, with word-level emphasis and Clio's add/remove theme colors in regular and fullscreen modes. Replayed and exported diffs remain plain text.
+- Made `/export` write a themed, self-contained, size-bounded HTML transcript by default, with terminal styling converted to HTML and each tool call kept in a semantic row. Passing a `.md` path preserves the existing plain Markdown export.
+- Added durable task, decision, and workspace-output inspection. `/tasks` now combines live work, terminal board history, recorded workspace outputs, and a project operator inbox; `/decisions` preserves settled interviews and operator corrections; `/view` renders task-ledger snapshots and active-branch workspace outputs. The model-facing task ledger and inbox bookkeeping intentionally stays audited as read class without granting workspace mutation authority, and `Alt+B` plus `Alt+D` are approved application-boundary shortcuts for the two boards. Workspace output loading re-resolves the current workspace root and target before every read, refuses symlink swaps outside that root, and retains the recorded missing-file result.
+- Ranked `/model` search with fuzzy matching over provider-qualified search text. Direct `target/model` matches outrank proxy-carried model ids while Clio's availability, authentication, health, runtime, favorites, and recent-model facts remain intact.
+- Routed prompt-template arguments through the engine's command-argument parser and substitution, retiring Clio's second parser. Templates support quoted arguments, `$1` through `$9`, `$@`, `$ARGUMENTS`, and argument slices.
+- Added a maintained engine SDK ownership table, thin-wrapper watch list, regression net, and five-step dependency-upgrade checklist (`docs/pi-boundary.md`) so each release identifies upstream fixes that Clio should inherit and Clio-owned deltas that must remain.
+- Added a checked engine declaration-surface snapshot (`docs/pi-surface.json`). Dependency upgrades now fail lint when an imported SDK symbol changes or disappears and report newly exported primitives for review.
+- Set `AI_AGENT=clio-coder` for spawned commands, fleet workers, registered code steps, and hooks so generic developer tooling can attribute child processes to Clio Coder.
+- Rebuilt the tool transcript as one stable lifecycle block from streamed arguments through live progress and settlement. Expanded calls now expose typed secondary arguments, exit status, counts, displayed and total bytes, truncation, timeouts, usage, added tools, context exclusion, and full-output paths; mixed image results never print base64, admission refusals never masquerade as executions, and operator `!`/`!!` bash commands stream and settle with the same grammar as model tools.
+- Let the engine assemble Anthropic thinking requests from the active thinking level, including adaptive effort and bounded token budgets. Clio removed its competing Anthropic payload rewrite and retains only the OpenAI Responses summary field that the engine's agent loop does not expose.
+- Aligned resumed and forked custom session entries with the engine's model-facing message text. Compaction summaries, branch summaries, and local bash executions now reach the model through the engine's message-text helpers instead of Clio-maintained copies, while Clio keeps its own durable ledger format.
+- Replaced Clio's TypeBox `anyOf` string-enum helper with the engine's compact string-enum schema. Tool schemas keep their exact accepted values and descriptions while avoiding a duplicate schema implementation and preserving the simpler wire form across providers.
+- Connected native tool progress to the engine's cumulative tool-update callback. Bash now streams a throttled, bounded output tail into its existing live transcript row while it runs, so operators see useful command progress without changing approval decisions, final result shaping, or the session ledger.
+- Replaced Clio's copied tool-output truncation implementation with the engine's UTF-8-safe head, tail, line, and size-formatting primitives. Read, search, context, and shell output retain Clio's 16 KiB per-observation ceiling while sharing the engine's maintained byte and line handling.
+- Gave every slash operation one canonical spelling across parsing, autocomplete, help, documentation, and skill guidance. `/quit`, `/context compact`, `/model`, `/settings`, `/skill <name>`, `/run --agent-profile`, and `/run --runtime` are now the only accepted forms; retired aliases fail closed and remain editable, and prompt templates that collide with built-in commands are diagnosed and ignored consistently in interactive and headless runs.
+- Completed fullscreen prompt navigation by marking every Clio user turn with the OSC 133 semantic prompt sequence, so `Ctrl+Shift+Up` and `Ctrl+Shift+Down` now move between real transcript prompts. Clio's editor chrome and transcript export now use the engine's terminal-sequence stripper instead of partial local ANSI regexes, and the optional presentation-settings path retains regular-screen defaults.
+- Made OAuth cancellation reach the complete production credential path. Active agent and background-request signals now cross `providers.auth`, credential mutations carry the engine's signal-aware operation options, cancelled lock waiters leave the live holder alone, and a token aborted before persistence never appears in Clio's in-memory credential view.
+- Fixed refused local commands and unresolved worker steering so the editor's pre-submit clearing restores the draft instead of losing it or recording rejected input in prompt history.
+- Replaced Clio's copied transient-provider regex with the engine's retryable-error classifier. DNS and WebSocket failures now enter the bounded retry ladder, quota, usage-limit, and billing failures stop immediately even when they contain an HTTP retry status, and Clio retains only its longer local-model loading delay and cancellable countdown.
+- Added directory-scoped `CLIO-CODER.override.md` handbooks with an explicit subtree boundary. An override replaces inherited guidance for its directory and descendants without affecting siblings, deeper handbooks may add narrower instructions, prompt blocks retain source paths, malformed overrides fail closed, and reset never deletes an override.
+- Added `Ctrl+P` and `Ctrl+N` prompt history through the editor's dedicated history actions. Accepted chat, slash, local-command, steering, follow-up, and interrupt inputs are available in process-local history, consecutive duplicates collapse, rejected inputs remain editable without polluting history, and browsing forward restores the unfinished draft.
+- Added an opt-in fullscreen TUI built on the engine's alternate-screen layout. Settings → Terminal can select a sticky composer and footer beneath an independently scrollable transcript, with follow-end behavior and a mouse-draggable scrollbar whose visibility is configurable; regular terminal scrollback remains the default.
+- Added terminal-native Mermaid diagrams and Unicode LaTeX to finalized assistant transcripts. Supported `mermaid` fences now become themed box-drawing diagrams when they fit, inline and display math render without a browser, and unsupported or oversized diagrams remain readable as their original source.
+- Made generic OpenAI-compatible, llama.cpp, LM Studio, and vLLM streams tolerant of servers that omit `finish_reason`. The engine now infers a normal or tool-use stop at the clean end of those local streams, so a complete answer is no longer reported as a provider failure solely because its server omitted the optional marker.
+- Routed local OpenAI-compatible sampling through the engine's typed sampling-parameter request path and enabled its bounded `thinking_token_budget` support for vLLM. Family-specific temperature, top-p, top-k, min-p, presence-penalty, and repetition-penalty values still reach llama.cpp and LM Studio byte for byte, while vLLM now reserves room for the final answer instead of allowing reasoning to consume the complete response ceiling.
+- Kept the local `!` bash row live until its command settles. The row froze at its first frame (`running · 7ms`, `no output yet`) because the chat panel classified every replay block as settled; a replay block can now declare itself live, so the elapsed counter ticks, output streams in, and the row leaves the frozen history prefix only when the execution record says it finished.
+- Kept a one-column gutter between a truncated model id and the context column in the `/model` overlay, so a long id no longer runs into the ctx figure and reads as one token.
+- Made the persisted post-compaction token count report what compaction freed. The `/tree` compaction row echoed the pre-compaction figure (`~16276 -> ~16276 tokens`) because the estimator anchored on an assistant message whose usage described the old prompt; the after figure now drops the summarized history, matching the footer's reclaimed-context notice.
+- Made an LM Studio model id mean one loaded instance on one host (#113). LM Studio lists a downloadable key next to its loaded instances and, with LM Link, next to a peer's instances too, and sending the bare key made the server load a second copy of a 27B model behind the operator's back. Clio now resolves a requested id against the target host's loaded instances, never sends a bare key that already has an instance, prefers the target's `defaultModel` and then an instance no other configured LM Studio target reports, flags an id reported loaded by two hosts as an LM Link peer projection and never auto-selects it, and never triggers a load for a key that already has a resident instance. A key with no instance still loads just in time as before.
+- Stopped the llama.cpp residency path from taking a node out of service (#127, #134). Asking for a model id the router does not know used to unload the resident model first and then fail the load, leaving the router empty; the reconciler now refuses the eviction when the replacement is not in the router catalog and reloads what it evicted when a load is rejected for any other reason. A router that reports an idle model as `sleeping` is read as resident instead of being asked to load it again, which had failed every turn with `400 model is already running`.
+- Fixed `/new`, `/resume`, `/tree`, and `/fork` issued while a turn was streaming (#114). The session was switched before the turn settled, so the aborted assistant record landed in the new session as a phantom root and the original session kept a question with no answer; each path now cancels and awaits the in-flight turn so it seals into the session that owns it.
+- Made two dispatch processes stop overwriting each other's run ledger (#118). A ledger persisted every row it had read at open time, reverting a sibling's settled run to `running`, and orphan recovery then stamped that run `dead` with exit 1 without reading its own receipt, which said it succeeded. Only rows a process mutated win on merge, and recovery seals from a verified receipt before declaring a run abandoned.
+- Accepted a target whose settings still say `runtime: lmstudio-native` in the worker spec contract (#119), resolving the alias instead of failing three attempts with an internal mismatch string, and stopped retrying a spec-contract rejection at full cost.
+- Stopped a damaged `credentials.yaml` from wedging `clio-coder upgrade` forever (#121): the provider-rename migration no longer throws on a damaged store when it has nothing to rename, each successful migration is recorded before the next runs, and the upgrade error names `--skip-migrations`.
+- Made the headless JSON stream honor its documented contract (#122). `--json` no longer re-emits every message in full after streaming its deltas, and `--json-events terminal` emits only `session`, `turn_start`, `agent_end`, `turn_end`, and `notice` instead of 40 KB of message bodies for a one-word answer.
+- Brought CLI exit codes back to the documented table (#123): `trace` validates its command and arguments before the no-database courtesy message, `trace sql` mutation refusal and bare `extensions`/`skills` exit 2 with usage on stderr, `trace runs --json` exists, `fleet` rejects unknown flags, `$COLUMNS` widens piped `targets` output, and a real `upgrade` no longer says "would write it".
+- Restored the gemma-4 channel-marker stream filter (#126), now applied on every runtime whenever the resolved family is gemma-4 rather than only on the removed LM Studio SDK path, so chain-of-thought and tool-call channel text no longer leak into the transcript.
+- Fixed `--thinking max` resolving to the lowest active level on families whose effort map stops at `high` (#128); the effective level is now monotonic across the seven configured levels for every catalog family.
+- Made the probed context window win over the catalog's in every consumer (#129). The orchestrator's engine model was sized from the catalog's 262144 while the server served 131072, so `max_tokens` overran the real window on long turns and auto-compaction never fired before the limit; deployment limits now override model metadata at resolution time.
+- Made the LM Studio request carry the resolver's effective reasoning effort (#130), so `xhigh` reaches models that accept it, `mechanism: none` families are not asked to reason, and always-on families are not told `none`. A target's literal `lmstudio.request.reasoning` override of `low`, `medium`, or `high` now outranks the thinking dial but is clamped to the efforts the model advertises, so a model that reports only on and off receives `low`; `auto` keeps the resolver's mapping.
+- Made a stalled stream fail with its reason instead of `Request aborted` (#131). The reclassified stall (`stream stalled: no output from <target> for <n>s`) is now the assistant message and the receipt's `outcomeDetail`, each stalled attempt leaves one assistant row rather than an aborted row beside a corrected one, and a headless provider failure on stderr names the target, runtime, and endpoint it was talking to.
+- Bounded the estimated reasoning-token count to the reported output tokens (#132), gave every receipt the same `node` block on success and failure (#120), made `/export` reject unknown flags and extra arguments like every other command (#115), and marked truncated rows in the expanded notices panel with an ellipsis (#116).
+- Rewrote the Qwen3.8-27B catalog entry's prose as portable hardware classes (#133), removing one operator's node names, one-off timings, and a citation of a deleted source file, and added a catalog test that every cited source path exists.
+- Corrected two documentation claims (#117): `docs/session-lifecycle.md` described `/resume <sessionId>`, an argument the command does not take, and the configuration knob table said `defaults.maxTokens` must be at least 1 while 0 is accepted.
+- Isolated the test suite from the developer's machine (#110, #111). A contract test resolved the real `~/.config/clio-coder/settings.yaml`, overwrote it with malformed YAML, and deleted it; the shared harness now redirects every Clio root into the run's scratch home with `CLIO_CODER_REQUIRE_HOME_PREFIX`, guards it with a canary test, and the welcome-dashboard test no longer reads the checkout it runs in.
+- Gated `npm publish` on version coherence (#124): `scripts/check-release.mjs` fails when `package.json` and the top `CHANGELOG.md` heading disagree or the heading is still `Unreleased`, and the release checklist is rewritten for this version.
+- Replaced the LM Studio SDK path with one HTTP adapter. The canonical runtime is now `lmstudio`, with `lmstudio-native` retained as an in-memory compatibility alias and an upgrade migration for persisted runtime ids, websocket URLs, and stored credentials. Chat, reasoning streams, tools, and usage use `/v1/chat/completions`; probing and residency prefer `/api/v1/models` with v0 and OpenAI listing fallbacks; explicit load and unload use native REST and carry bearer authentication. A target without `lmstudio.load` keeps server just-in-time defaults, while an explicit block controls context length, flash attention, eval batch size, expert count, and KV-cache GPU offload. Every successful load records its returned instance id for this process, and unload or fallback swap refuses every pre-existing or LM Link instance. Same-key LM Link instances are independent, not duplicates. Request settings cover TTL, draft model, and reasoning effort. The LM Studio path never sends `chat_template_kwargs`; its seven Clio thinking levels map to `none`, `low`, `medium`, or `high`, with on/off-only models clamped to `low`. Configure verifies the exact LM Studio greeting before saving, direct and legacy ids both persist canonically, the model catalog no longer promises SDK behavior, and scripted HTTP contract tests cover v1, v0, auth, migration, configuration, loading, ownership-safe release, reasoning defaults, split tool calls, and usage without live model calls.
+- Extended the strict ACP v1 server into the durable control surface an external session-managing client needs without weakening generic clients. A process may now bind its one chat runtime with either `session/new` or standard `session/load`; load authorizes against canonical-workspace history, refuses any unended record it cannot prove is free, resets provider context to the durable pinned branch, and emits only bounded original transcript replay before its response. Namespaced methods list, label, and delete workspace sessions; expose and atomically patch only target, model, thinking level, and global autonomy; list and explicitly probe credential-free target projections; and read or override a bound session's autonomy for its next prompt. New/load results and durable metadata record bind-time target/model attribution, including the TUI `/new` path. Clients may opt into one permanent versioned `clio-coder/event` envelope whose first kind forwards loop-block detector counts without a fabricated tool id, command shape, path, or timestamp authority; clients that do not opt in receive no extension notification. A server-side approval timeout is now audited as `expired`, aborts the turn, suppresses model continuation, and fails the prompt with `permission_expired` instead of inventing a denial the model can retry. Workspace Git identity treats ignored nested scratch roots as non-Git and path-scopes dirty status and recent history for legitimate monorepo subdirectories while preserving the exact workspace as the authority boundary. ACP output additionally bounds live tool titles and location paths, session-list aggregate frames, live tool-call cardinality, and replay tool-call cardinality to fixed reader limits a client can rely on.
+- Hardened `clio-coder acp` into a strict, truthful ACP v1 server so an external client can drive it safely, and corrected `docs/acp.md` to the methods that actually exist. `initialize` must come first, exactly once, with `protocolVersion: 1`; the launch `--cwd` is realpath-canonicalized and is the process's only workspace, so every session opener must carry an absolute `cwd` that canonicalizes to it and the server never falls back to another directory or calls `chdir` after boot (the first `session/new` used to retarget the whole process to any existing directory it named). One successful new or load per process, since one chat instance backs the server and a second session id would share provider context and ledger ancestry. A prompt Clio cannot start (no orchestrator target, no model, unknown target, runtime resolution failure) now fails the `session/prompt` request with `prompt_not_admitted` and a closed-set reason instead of returning an empty `end_turn` with zero usage, which the ACP client could not tell from a model that chose to say nothing. Every error carries its machine-readable detail under `error.data._meta["clio-coder/error"]` and nothing else: no `Error.stack`, no echoed frame, no absolute path, no provider prose (`turn_failed` and `internal_error` messages are fixed host text and the original goes to stderr). Text, thought, tool `content`, `rawInput`, `rawOutput`, and `toolCallId` are bounded in UTF-8 bytes; each tool call has one wire identity across `tool_call`, `tool_call_update`, and `session/request_permission`, the permission request reuses the exact `rawInput`/`locations` snapshot the client already rendered and binds only to a currently open call, and only the exact `allow-once` option grants. `session/cancel` while a permission is parked settles the permission, the parked tool, and the prompt; `session/close` refuses under an active prompt and is idempotent otherwise; a cancelled or failed turn closes every open tool call with a terminal update; stdin EOF waits for the in-flight prompt to settle before the session store stops. The stdio transport bounds an input line at 1 MiB and answers `id: null` requests instead of dropping them. Protected by the ACP contract suites plus a spawned real-server smoke test that drives the built CLI with an isolated `CLIO_CODER_HOME` and a loopback provider stub through a text turn, an admission failure, a tool call with permission allow and reject, and cancel while a permission is parked.
+- Loaded the two wiki dispatch prompts through the same fragment loader every other prompt fragment uses instead of a hand-rolled `readFileSync` (#92). `prompts/fragments/wiki/{page,plan}.md` sat inside the directory `fragment-loader.ts` walks, but `walk()` explicitly skipped any directory named `wiki`; `context/wiki/prompts.ts` read the two files directly and did its own `{{token}}` substitution, with no id, no version, no content hash, and no hot reload. The skip was not an oversight: neither file had real YAML frontmatter, only a decorative leading and trailing `---` line, and `page.md`'s body has its own literal `---` fences (the front matter format the wiki *writer* must produce) that the loader's first-`---`-to-next-`---` frontmatter regex would have matched against instead of a real closing delimiter, corrupting the split and throwing at every Clio startup. Both files now carry real `id`/`version`/`description` frontmatter above their unchanged body, so the loader's existing delimiter search closes on the new marker instead; the old decorative `---` lines are kept as ordinary body text rather than stripped, so the substituted, trimmed prompt text `context/wiki/prompts.ts` sends as a dispatch's `task` is byte-identical to before, verified by comparing the old hand-rolled substitution against the new loader-backed one for both files. `{{token}}` substitution still has no home in the loader itself, the same division `identity.self-awareness`'s `{TOKEN}` placeholders already use in `compiler.ts`: the loader hands back a raw body and the one caller that needs live per-dispatch values fills them in. Grepped `src/` for other hand-rolled prompt-text `readFileSync` calls; the only other `{{token}}` users found (`agents/fleet-contract.ts`, `dispatch/code-step.ts`, the fleet `.md` templates) already have their own strict, validated template contracts and are a different system. No builtin worker system prompt changes size: the wiki fragments were never part of `compileWorker`'s output, only ever a dispatch's dynamic task text.
+- Gave `compileWorker` the `additionalFragments` channel `compile()` already had, so active project rules and the operator profile reach a dispatched worker (#96). Both are built once per compile in `prompts/extension.ts` and were injected for the main session only; a coder worker editing a file under an active `.clio-coder/rules/**` path never saw the rule that governed it, the layer inversion the user-editable configuration is supposed to prevent. Project rules are scoped to the worker's inferred working context, so a worker whose task never touches a ruled path does not carry that rule's text. That context is `writeRoots`, when the caller sets them, plus path-like tokens recalled from the task and briefing text, since the model-facing `dispatch` tool has no structured path field; a missed path token means a rule can go unseen, never fabricated, because `selectActiveRules` still requires a real glob match. The operator profile renders unconditionally, the same as it does for the session, because it governs how the worker should do the task (validation preference, commit-message style, local-only paths), not only how the orchestrator talks to the operator. The channel is `additionalFragments`, rendered last after persona: nothing splices into an existing worker section, the pattern a7faa133 removed. Measured with a matching rule and a profile both firing: +289 bytes per builtin (+3,468 across the twelve, 66,472 to 69,940); the operator profile alone is +178 bytes per builtin; a worker whose task touches nothing ruled pays 0.
+- Made `/tree` switch and `/fork` of the same turn reconstruct the same state, and fixed the task board following the abandoned branch after a switch (#94). Live replay after a `/tree` switch kept every unanchored sidecar (`taskLedger`, routing notices, a leafless `workerRun`) regardless of where it sat in the file, while `/fork` dropped anything written after the fork point; `filterEntriesToActivePath` (`src/domains/session/tree/active-path.ts`) and `fork.ts`'s `sessionEntryBelongsToPath` now share one `entryBelongsToPath` verdict, so both surfaces exclude a sidecar written after the leaf's position. The task board's own fold (`task-board.ts:181-187`) was a second, independent copy of the same bug: it took the last `taskLedger` entry in raw file order with no branch filter at all, so a plain `/resume` on a branched session could show whichever branch happened to write last, not just a `/tree` switch; `readEntries` now runs through the same active-path filter (`src/entry/orchestrator.ts`). The board's session-id-keyed cache (`task-board.ts:327-336`) also never noticed a `/tree` switch, since that only moves the append point inside the same session; a new `SessionTurnSwitched` bus event and a `TaskBoardStore.invalidate()` method fix that. Also: the `/tree` pin is now persisted to `meta.pinnedLeafTurnId` and cleared on the next append, so a switch made without a follow-up message survives quit and resume instead of reverting to the abandoned tip via timestamp inference; `/tree` marks the active tip with its own glyph; and Enter on a compaction or branch row is inert with a status message instead of throwing `turn not found`.
+- Replaced the doc routing table in the system prompt with a directive to call `context(scope="docs")`. `identity.self-awareness` carried a 42-row "topic -> docs/file.md" table, 2,410 bytes of every session prompt, guarded by its own first line ("read these only when the user asks about Clio herself; never for ordinary coding work") and growing by one row per doc. The docs engine already indexes every bundled `docs/*.md` and every search response lists the whole corpus, so the table was resident knowledge the model could fetch in one call; measured on the current index, 39 of the 42 rows rank their document in the top five from the bare row label and all 42 from a natural question. The new `identity.docs-routing` fragment tells the model to call `context(scope="docs", query=<the question>)` before answering and before any grep, find, or read when asked about Clio herself, phrased as an instruction rather than a note that docs exist, because a note is what once sent the model grepping the workspace for a skill; it renders only when `context` is on the surface, the same gate the Skills passage uses. The paths, the code-outranks-docs rule, and the configuration locations stay unconditional. Session prompt drops from 15,724 to 13,314 bytes; workers are unchanged.
+- Added a `skills-pin` check to `scripts/check-hygiene.ts`, run by `npm run lint`. `skills/registry.yaml` drifting from an edited skill's content was only caught by `npm run skills:check`, which runs inside the full `ci` chain and nowhere else; a5d50940 landed a stale `clio-test` pin from `be2b5ccb` that sat unnoticed for two days because nobody's local lint run ever exercised it. The new check shells out to `pin-skills.ts --check`, the same command `skills:check` runs, so lint and the full gate share one definition of "stale" instead of two. `npm run lint` wall time moves from 4.4s to 5.1s.
+- Made the worker read the same safety text the session reads, and corrected two things that text said. The four `safety.<level>` fragments were rendered for the session only; a dispatched worker got a hand-written copy of the four levels from a `switch` in `compiler.ts`, and the copy drifted: its full-auto branch said "Writes, dispatches, and ordinary commands run" for workers none of which admit dispatch, and its auto-edit branch never said which commands are recognized or that `$(...)` is always approval-required, so a worker learned those only from its first denied call. The `switch` is gone; both renderers read the one fragment body, and the fragments now speak in the safety net's action classes and never name a tool, so nothing in them can be false for a surface that lacks one. Two session-side statements were wrong against the engine and are fixed in passing. `safety/auto-edit.md` said "Commands with pipes, `&&`, or redirects count as unrecognized and ask", while `policy-engine.ts` recognizes and runs a `&&` chain whose every step is recognized; it now says "a `&&` chain whose every step is recognized runs too" and lists pipes, `;`, `||`, redirects, newlines, and a chain with an unrecognized step as the unrecognized forms. `safety/read-only.md` said only "The safety net applies at every autonomy level" where the other three levels name `git_destructive`; it now carries the same sentence. Workers gain the auto-edit detail (about 500 bytes per builtin) and no authority: the worker's engine loads the same builtin allowlist and the same `.clio-coder/safety.yaml`, and already denies the same calls.
+- Removed `test:isolated` from the package scripts. It ran the same contracts and smoke globs `test:coverage` runs, minus the coverage flags, through the same per-file `test:file` invocation, so `npm run test:file -- 'tests/contracts/**/*.test.ts' 'tests/smoke/**/*.test.ts'` reproduces it exactly. `test:repeat` stays: it is the one lane that reruns smoke shuffled to catch order- and timing-dependent flakes a single deterministic pass cannot, and `.github/workflows/ci.yml` runs it on every push. The CI workflow already runs one release gate on both node lanes with no `if: matrix.node-version` guard hiding a check from either one; the single remaining guard skips the coverage summary step on node 24 because coverage is a report about the suite rather than a check of it, and paying node's per-file instrumentation twice would only post the same numbers to the job summary twice.
+- Said each routing rule once. The session prompt told the model seven times, in five places, that broad repository exploration goes to a worker, and the phrasings disagreed: the operating contract and two Tool Contract lines said use `agent:"auto"`, while `FLEET_ROUTING_GUIDANCE` said auto "is a fallback, not a router" and the Fleet roster said broad recon goes to `scout`. Skills guidance was stated in five places. The Tool Contract now keeps only what nothing else says (complete surface, harness model, inventory rule, narrow-orientation tools, validate before claims, retry-shape recovery, the fleet pin rule); the Retrieval Hints keep only what is and is not preloaded; and the single surviving broad-exploration rule, in `operating.delegation`, is the pinned one: hand it to a worker before repo-wide reads, pinning `scout` when the roster lists it. The session prompt loses 1,360 bytes and no capability: every deleted sentence has one surviving statement in a passage that renders exactly when its tool does.
+- Split the operating contract into a constitutional layer and role layers. One file, `operating/contract.md`, was carrying the coordinator's delegation and receipt discipline, the `/share` note, the skills passage, and the shared posture, and the worker compiler was regex-splicing it into a second document; every one of the 12 builtin workers was told to use `dispatch` and `agent:"auto"` although no builtin admits `dispatch` (#91). `operating.contract` now holds only what is true for every reader; `operating.delegation` renders for the session only when `dispatch` is on its tool surface and `operating.skills` only when `context` is, the same rule the Fleet block already followed; `operating.worker` holds the assigned-task contract that used to be inline TypeScript with no fragment provenance. The worker operating contract shrinks from 3,638 to 1,575 bytes for every builtin, the twelve worker prompts from 84,952 to 60,196 bytes total, and no session sentence was removed: the one-shot approval semantics moved from the contract paragraph into the session's safety section, where the level fragments they qualify are.
+- Gave an installed Clio a skills marketplace she can see. Asked how a catalog skill worked, an installed Clio grepped the operator's own project for the skill's name, found nothing, and gave up; asked to list the marketplace, she returned the operator's personal skills. Three defects produced that. `discoverMarketplaceSkills` resolved its index to `<configDir>/skill-marketplace.json`, which nothing ever writes, and never consulted `resolvePackageRoot`, so the `skill-marketplace.json` the tarball ships was read by nothing and an install had no marketplace at all; both the index and the package's own catalog now fall back to the package root, so bare-name search and install work offline against local files. `context(scope="skills")` read installed roots only and never consulted the marketplace, so the one skills surface the model has could not show an installable skill however well configured the marketplace was; it now renders a marketplace section, and loading an uninstalled name explains how to install it rather than reporting an unknown skill. Every prompt string said "installed skills" and the retrieval hint routed questions about where skills live to grep, which is exactly what the model did; the prompt text now names installable skills and routes those questions to `context`. The package ships all 31 skills rather than 7, plus `skills/registry.yaml` so provenance pinning resolves for an installed copy, costing 0.2MB unpacked and 0.08MB on the wire. A new fresh-install suite exercises the path from a foreign working directory with the catalog environment variables blanked, which is the configuration every existing skills test missed and the reason this shipped.
+- Kept the marketplace out of workers and made the skills reminder fire on a fresh install. An unbound worker holding the context tool began seeing marketplace rows it could do nothing with, alongside prose telling it to suggest the skill to an operator it has no channel to address; marketplace rows are now suppressed for every worker registry and the skills passage is stripped for all workers, leaving a worker the skills it was given and nothing else. Bound workers were never affected and the capability boundary is unchanged. Separately, the once-per-session skills reminder is the one channel that reliably makes a model consider a skill, and it was gated on the installed count being above zero, so the operator most likely to benefit from learning that skills exist was the one operator never told; it now counts installed plus installable and says both.
+- Moved the static-analysis checks out of the test runner. Nine files under `tests/` read source, docs, README, config, and script text off disk and asserted on their structure while executing no product code; `export-hygiene` alone cost 57.9 seconds, the second most expensive file in the suite. `scripts/check-hygiene.ts` now runs all ten rules in one process against one read of the tree, wired into `npm run lint`, and every assertion moved with them. `npm test` drops from 1,760 CPU-seconds to 1,465 and from 160 seconds wall to 124. The boundaries test lane is gone; `check-boundaries.ts` remains as a library the lint imports.
+- Restored the streaming display coalescer. The raw engine wrapper that precedes every derived text and thinking delta was classified as a synchronous event, so each provider chunk cancelled the pending 16 ms display frame and forced an immediate render request; the coalescer was defeated exactly while a response streamed, which is the one time it exists for. Wrappers carrying text or thinking deltas, which the panel has always ignored, now stop at the renderer instead of reaching it; tool-call formation keeps its synchronous path, and every event the panel acts on arrives in the same order as before.
+- Enabled Node's V8 compile cache for the boot-path module graphs: interactive chat, `run`, `acp`, and native fleet workers. Locally spawned workers inherit the directory through their spawn environment and consume it before any of their children can see it; SSH-placed workers enable the remote install's own cache in-process at the worker entry, with nothing exported to their children. Read-only and dry-run commands never enable it, `paths` and bare `doctor` keep their promise that nothing is created, and the cache enables only on an initialized install so a home Clio never set up stays untouched. `NODE_COMPILE_CACHE` and `NODE_DISABLE_COMPILE_CACHE` always win, and a cache failure never affects a command. The import-only and real-PTY fill/hit observations, with their deliberately narrower endpoint names, are recorded in `docs/performance-methodology.md` rather than generalized into a per-command saving.
+- Corrected boot and TUI performance instrumentation before using it for 0.3.2 decisions. `first TUI paint` is now marked only after the first real frame has issued all of its stdout writes; explicit frame ids group diff, ANSI, hardware-cursor, and IME writes; canonical event and input ids correlate queue, panel, and committed-frame high-water marks; and stdout return, backpressure, and drain are recorded. The trace writer is bounded, asynchronous, awaited at shutdown, and nonfatal on storage failure. A deterministic contract plus a real built-CLI PTY harness cover first frame, input, resize, grouped writes, paused output, and process reaping. The documented metrics are stdout/PTY endpoints, never an in-process claim of literal glass latency.
+- Added the adaptive stream pacer as `terminal.smoothStreaming: off | auto | on`, with the conservative 0.3.2 default left at `off`. Only derived visible text and thinking are paced, through one ordered generation queue; raw text/thinking wrappers remain transparent and public events, transcript persistence, tool formation, cumulative tool state, and ordered boundaries remain synchronous. Pacing is grapheme-safe, arrival-credit and oldest-age bounded, self-stopping, folded-thinking aware, and forced to settle before abort, retry, submit, mode change, final return, or teardown. Fullscreen frozen scrolling and resize survive paced updates, and stdout backpressure gates frame construction rather than creating a second unbounded SSH buffer. `auto` bypasses non-TTY, remote/multiplexed, CI, accessibility-marked, and backpressured sessions; `CLIO_CODER_SMOOTH_STREAM=off` is the immediate per-process escape hatch. Deterministic fake-clock, ordering, grapheme, reset, folded-thinking, scroll/resize, no-drain, and built-CLI PTY contracts cover the rollout.
+- Added a measured instant interactive shell through one `TerminalLease`, enabled by default with `CLIO_CODER_INSTANT_SHELL=0` as the immediate rollback. Stage 0 and Stage 1 share the exact terminal, TUI, root host, editor, raw mode, decoder, resize subscription, terminal queries, signal router, and stop lifecycle; hydration swaps roots and delegates atomically instead of adopting reconstructed state. Typed drafts and cursor state survive, early submissions are visible immutable FIFO admissions dispatched exactly once after the application attaches, and diagnostics are serialized into the hydrated TUI or emitted after terminal restoration. Boot failure, Ctrl+C before or after attachment, SIGTERM, and a stale hydration all converge on exactly-once terminal restoration and recover accepted input. ACP, headless, ordinary non-TTY invocation, help, and subcommands never mount Stage 0; the explicit force-interactive non-TTY override is preserved. Built-graph contracts keep its closure at five chunks/90,654 bytes and out of provider/tool/codewiki graphs; real PTY acceptance covers early input, multiple submits, resize during hydration, protocol initialization once, failure recovery, signals, and raw-mode restoration. Corrected Stage 0 commit, PTY receipt, and Stage 1 hydration observations are reported separately in `docs/performance-methodology.md`.
+- Removed the eager userland Undici graph from `web_fetch` and use the Node 22.19+ built-in Fetch, Headers, Request, Response, stream, and abort implementation. Localhost contracts preserve request headers/body, redirects, UTF-8 streaming and cancellation at the byte ceiling, external abort, timeout, HTTP previews, binary rejection, and transport errors on both supported Node lines; an installed-tarball turn invokes the real tool from a foreign working directory. The built graph contains no Undici source or dependency, while the measured size and deliberately mixed import-time observations are recorded without turning host noise into a boot claim.
+- Made codewiki's tree-sitter graph genuinely lazy and moved runtime indexing off the interactive event loop. Lightweight schema, artifact, and path modules preserve synchronous cached reads without evaluating the builder; actual full, stale, and incremental builds run in a dedicated worker and load only the required grammars. Session startup, parallel `code_nav` demand, mutation batches, explicit index/refresh, bootstrap, wiki grounding, and reset now share one per-workspace generation queue and cross-process lease, so an older build cannot overwrite newer state or resurrect a reset artifact, and shutdown drains admitted work. Built-source and installed-tarball coverage prove nested help is tree-sitter-free and write-free while a real foreign-cwd build loads the runtime and its vendored grammar; measurements and deliberately scoped import observations are in `docs/performance-methodology.md`.
+- Split `context`, `code_nav`, `verify`, `web_fetch`, `dispatch`, `monitor`, and `steer` into immutable lightweight tool surfaces and first-use implementation chunks. Registration order, provider schemas and descriptions, policy metadata, execution modes, argument normalization, admission, permissions, middleware, result shaping, and worker surface attestation remain registry-owned and eager; only an admitted runner imports code. Dispatch keeps its trusted plan and capacity-reservation identities in one synchronous admission controller shared with the lazy runner, deeply freezes every execution-affecting control before middleware or approval can observe it, binds the `apply_winner` repository destination into the approval hash and text, and releases a guard-blocked prepared admission exactly once. Workers import only the core tool bootstrap, so their built entry never evaluates the three orchestrator-only runners. Concurrent first calls share one import, an implementation whose surface drifted fails closed, unrelated tools remain absent, and a missing Clio-owned chunk carries the same named reinstall guidance as a missing command chunk. V8 coverage repeats the absent-before-use/present-on-invocation proof for every tool and the worker exclusion against both the source build and an installed tarball from a foreign working directory.
+- Removed the eager `pi-ai/compat` and all-provider aggregates from ordinary engine startup. Clio's engine boundary now owns the ordered API dispatcher and its pinned synchronous environment-key lookup while composing only the nine Pi provider factories backed by current Clio runtimes; Pi still owns their public lazy APIs, catalog data, authentication and headers, Bedrock loader, OAuth flows, faux provider, and image registrar. A configured out-of-tree runtime activates a one-time compatibility bridge immediately before plugin evaluation, preserving the existing process-global registry identity and last-writer-wins overrides; a failed bridge prevents that plugin from evaluating. Without a plugin the aggregate, unconfigured provider catalogs, legacy aliases, unrelated provider bodies, OAuth flows, and image generator remain unevaluated. Source and installed foreign-cwd coverage prove both sides of the graph boundary, provider contracts preserve payload and cancellation behavior, every credential mapping is parity-checked against Pi 0.84, and an installed plugin overrides a known API through the shared external Pi instance.
+
 ## 0.3.1 - 2026-08-16
 
 - Made a dispatched worker visible while it runs. `/run` and `/delegate` stream into the transcript as a worker block: an attributed header naming the agent, its route or protocol, and its run id; the worker's prose down a rail; a coalesced tool line; and a receipt footer whose failure reason wraps as prose above it. Dispatch lifecycle events fold into one entry per assignment, so a failover reads as one run with an ↻ line per earlier attempt, and a late event from a superseded attempt moves nothing. A model-started run lands folded under the tool call that spawned it, so a fan-out of three reads top to bottom in spawn order, folded cards stack without blank rows, and `Alt+O` folds or unfolds the newest tool call or worker block. Every board row, footer chip, and transcript block leads with who asked for the run: hollow for the operator, filled for the model, a quiet dot for Clio's own. The session records a `workerRun` entry where a block opens, so a `/resume` redraws the block from that entry plus the sealed receipt, bounded exactly like a live one, and a run whose receipt is gone settles as `receipt unavailable`. `--share` on `/run` and `/delegate`, and `/share [runId]` afterwards, hand a worker's bounded receipt text to the main agent as operator text under a `[worker result] <agent> · run <id> · <outcome> · shared by the operator` header, which the operating contract now names so the model treats it as steering rather than an unattributed tool result; bare `/share` picks the newest finished run the operator started and skips agent-origin runs the model already holds. A structured worker answer renders as prose on the rail instead of one line-wrapped JSON string, a mutation report reading as its changed paths, validations with verdict glyphs, summary, and commit line, while the model still receives the raw payload. A replayed operator turn after `/fork` or `/resume` shows what the operator typed rather than the composed prompt with its system-reminder scaffolding. The transcript ledger prints a written file's byte count rather than the length of its confirmation sentence.
@@ -96,9 +185,8 @@ still change interfaces.
 - Made `clio-coder reset` and `clio-coder uninstall` say what they are about to destroy and what survives. The reset preview lists each root's real children with counts and gives every scope a note, and the help defers to that listing rather than describing it. Uninstall enumerates the per-project `.clio-coder/` directories recorded in session metadata and names `clio-coder context reset --all` before the roots and the launcher are touched, because the record it reads lives inside a root it is about to remove and the cleaner is a subcommand of the binary `--remove-binary` is about to delete. Per-project directories are still not removed by uninstall; this makes the ordering visible rather than closing the gap.
 - Made a failed settings reload render as one width-clamped notice from the shared settings formatter instead of an inspect dump and a stack trace that corrupted the frame. Read, parse, and schema failures are distinguished, the remedy matches the kind and leads the detail so frame clamping cuts context rather than the fix, the raw YAML source fragment is gone, and the previous good configuration stays active. Doctor's settings row and the thrown error use the same helpers.
 - Fixed `clio-coder targets --probe` writing fixed-width rows that ignored the terminal. The id column never truncates, url and model truncate with an ellipsis, `--json` stays untruncated, and surplus width goes to url and model before the tier column, which had let four distinct hosts render identically at 120 columns while the group header already carried the tier.
-- Added slash aliases for the spellings people actually type: `/exit` resolves to `/quit`, `/config` to `/settings`, and `/compact` to `/context compact`, with aliases offered in tab completion ranked below their canonical commands. A rejected unknown command now clears the composer rather than leaving the text to concatenate with the next keystrokes into a message to the model.
 - Made the TUI tell the truth about a denied tool call and about usage the ledger was hiding. A denial renders as the dialog outcome and status alone, the collapsed row reads `bash(id) ✗ blocked` instead of claiming the call `ran`, and no parked-approval line survives the decision. `/context compact` persists its summarization usage on the compaction entry and moves `/cost` immediately, so a real model call stops being invisible to every usage surface. A cancelled turn now persists estimated usage marked `estimated: true` in the shape a completed turn uses, rather than the all-zero block the cancel path used to write beside real streamed text, and `/cost` readers skip it. `/tree` shows the fork parent and the compaction and branch nodes, and replay no longer dumps `custom:promptRecompiled` JSON into the transcript. The stop-turn notice no longer doubles the usage line onto the empty assistant entry it splits open, and a settled entry holding nothing renders nothing instead of an empty bubble.
-- Made overlay footers say what Esc will do from where the overlay is right now. The verb was derived from whether an overlay committed anything, which produced `cancel` on half of them and `close` on the other half while neither word described the key: a list overlay clears a typed filter on the first Esc and closes on the second, and the footer said `close` through both. The caller names the action now, out of a fixed vocabulary of `close`, `clear filter`, and `back`, and `/models` and `/resume`, which close on the first Esc, say so instead of advertising a filter they do not clear. Every overlay uses one filter vocabulary.
+- Made overlay footers say what Esc will do from where the overlay is right now. The verb was derived from whether an overlay committed anything, which produced `cancel` on half of them and `close` on the other half while neither word described the key: a list overlay clears a typed filter on the first Esc and closes on the second, and the footer said `close` through both. The caller names the action now, out of a fixed vocabulary of `close`, `clear filter`, and `back`, and `/model` and `/resume`, which close on the first Esc, say so instead of advertising a filter they do not clear. Every overlay uses one filter vocabulary.
 - Fixed a repair masquerading as an install. `initializeClioHome` stamped `installedAt` when it had only repaired an existing home, so the install date moved every time doctor rebuilt the skeleton. A repair writes `repairedAt`, `install.json` accepts either stamp, and doctor prints whichever exist. The doctor damage row groups identical messages instead of repeating one error three times.
 - Made every cost surface claim only what something measured. The cost aggregate could not tell nothing-priced from priced-at-zero, so the footer asserted `$0.00` before any turn had run while `/cost` on the same session said no usage was recorded, and after a real turn against a target that publishes no pricing both printed the literal words `cost unknown` where a number belongs. The aggregate carries its call count, one formatter answers every surface, and a surface with no priced call shows no cost field at all. Usage and cost are separate claims: the tokens were counted whatever the pricing did, so the session total stays on screen and only the cost field disappears. A fixed-width cell that owns a cost column cannot drop the field, so it says `not measured` in words rather than inventing a number.
 - Made the footer describe the branch on screen rather than the whole ledger file. `current.jsonl` is append-only, so after a `/tree` switch the abandoned sibling turns are still in the file: the transcript stopped showing them while the session total, `/cost`, and the last-turn status line kept counting and describing them. All three now fold through the same active-path lineage the transcript replays, on `/tree`, `/resume`, and `/fork`. The footer's chip strip also ranks its chips, so the chip budget and the width budget both shed per-turn detail first and the session total last; it used to slice whatever sat at the end of the list, which cost an 80-column terminal both the total and the cost chip while spending the whole budget on per-turn detail. Two fields the ledger does not record are left neutral on a rescoped line rather than reconstructed: the watchdog peak, and reasoning tokens no provider reported.

package/CONTRIBUTING.md

@@ -63,25 +63,26 @@ output in-process while the reporter runs.
 
 ## Releasing
 
-Releases are tag-driven and publish from CI. Nothing is published from a
-workstation.
+Releases are cut from a tag. The GitHub release is created by CI; the npm
+publish is a manual maintainer step. The ordered procedure for a cut lives in
+[docs/release-cut-checklist.md](docs/release-cut-checklist.md).
 
-1. Bump `version` in `package.json` and retitle the `unreleased` section in
-   `CHANGELOG.md` to the version being cut.
+1. Bump `version` in `package.json` and retitle the top section of
+   `CHANGELOG.md` to the version being cut. `scripts/check-release.mjs` fails
+   when the two disagree or the heading still says `Unreleased`.
 2. Run `npm run ci:release`. It runs the full `ci` gate, then
    `scripts/check-release.mjs`, which verifies the built `dist/` and audits
    the exact npm package contents.
-3. Land the release commit through the normal PR flow.
-4. Tag and push: `git tag vX.Y.Z && git push origin vX.Y.Z`. The tag must
+3. Land the release commit on `main` and let the `ci` workflow go green on
+   that commit.
+4. Tag and push: `git tag -a vX.Y.Z && git push origin vX.Y.Z`. The tag must
    match `package.json`'s version; the release workflow refuses mismatches.
-5. `.github/workflows/release.yml` verifies the tag against `package.json`,
-   reruns the full gate, and creates the GitHub release with the tarball
-   attached. The npm publish step runs only when the repository variable
-   `NPM_PUBLISH` is `true` and the `NPM_TOKEN` secret holds an automation
-   token that can publish `@iowarp` packages; with the variable unset the
-   step is skipped and the GitHub release is still created. A maintainer may
-   run the first publish manually (`npm login && npm publish`);
-   `prepublishOnly` runs the same `ci:release` gate either way.
+5. `.github/workflows/release.yml` requires a successful `ci` run for the
+   tagged commit, verifies the tag against `package.json`, builds `dist/`,
+   runs `scripts/check-release.mjs`, and creates the GitHub release with the
+   tarball attached. It does not publish to npm.
+6. A maintainer publishes from the tagged commit with `npm publish`;
+   `prepublishOnly` runs the same `ci:release` gate first.
 
 What `scripts/check-release.mjs` enforces, and how to respond when it fails:
 
@@ -92,14 +93,15 @@ What `scripts/check-release.mjs` enforces, and how to respond when it fails:
   a forbidden file appears, fix the `files` allowlist in `package.json`
   rather than deleting the file from the repo.
 - Runtime resources must resolve from the installed package root: prompt
-  fragments, builtin agents, model catalogs, `docs/html`, the 128px logo,
+  fragments, builtin agents, model catalogs, the Markdown guides in `docs/`, the 128px logo,
   and `damage-control-rules.yaml`. A new runtime resource must be listed in
   both package.json `files` and the required list in `check-release.mjs`.
   The double bookkeeping is deliberate: neither edit can silently drop a
   resource the CLI needs at runtime.
-- Size budgets: 2 MB tarball, 6 MB unpacked. If a legitimate change exceeds
-  them, raise the budget in the same PR with a justification, never as a
-  drive-by.
+- Size budgets: 15 MB tarball, 40 MB unpacked, set in `check-release.mjs`.
+  They are a tripwire for packaging defects such as a leaked `node_modules`
+  or a doubled `dist/`, not a diet. If a legitimate change exceeds them,
+  raise the budget in the same PR with a justification, never as a drive-by.
 
 Build shape, for anyone changing `tsup.config.ts`: two ESM entries with code
 splitting on. `src/cli/index.ts` imports every subcommand dynamically, so a
@@ -130,11 +132,9 @@ The boundary checker enforces these:
   all other worker domain imports must be type-only.
 - Domain independence: cross-domain flows go through `SafeEventBus`.
 
-Run:
-
-```bash
-npm run check:boundaries
-```
+The checker runs as part of `npm run lint` (`scripts/check-hygiene.ts` imports
+`tests/boundaries/check-boundaries.ts`), so a boundary violation fails the
+same lint every PR runs.
 
 ## Branches