@iowarp/clio-coder 0.4.1 → 0.4.3

package/docs/{environment-variables.md → guide/environment-variables.md}

@@ -1,24 +1,11 @@
 # Environment Variables
 
-Every environment variable the shipped `src/` tree reads, grouped by role. Settings.yaml is the durable home for operator policy; env vars exist for per-process overrides (CI, one-off experiments), directory layout, debugging, and internal plumbing. When prose and source disagree, prefer the source; the table cites the read site.
+> **Visual blueprint:** The source checkout includes the complete
+> [Environment Variables visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/environment_blueprint.html).
 
-This page is the complete inventory, and the `environment-variable-inventory` check in `scripts/check-hygiene.ts` (run by `npm run lint`) fails if `src/` reads a variable that has no row here.
+This page inventories Clio-specific runtime variables and the ambient variables that materially change documented operator behavior. `settings.yaml` is the durable home for operator policy; environment variables support per-process overrides, directory layout, debugging, credentials, terminal integration, and internal plumbing. When prose and source disagree, prefer the cited read site.
 
-> [!TIP]
-> [docs/html/environment_blueprint.html](html/environment_blueprint.html) is a browsable walkthrough of the most commonly set variables with an effective-path resolver. It covers a curated subset, so use the tables below when you need the full list.
-
-## Guardrail overrides
-
-Durable values live in the `guardrails:` section of settings.yaml (see [configuration-and-targets.md](configuration-and-targets.md)). These env vars override them for one process; resolution is env > settings > built-in default, and every value is a positive integer. Resolution lives in `src/core/guardrails.ts`.
-
-| Variable | Settings key | Default | Controls |
-| --- | --- | --- | --- |
-| `CLIO_CODER_TURN_TOOL_CALL_BUDGET` | `guardrails.turnToolCallBudget` | 60 | Orchestrator per-turn soft tool-call budget; the hard interrupt ceiling sits 15 above it (`src/engine/loop-guard.ts`). |
-| `CLIO_CODER_WORKER_TOOL_CALL_CAP` | `guardrails.workerToolCallCap` | 150 | Lifetime ceiling on tool calls one dispatched worker may execute. Calls the harness refused (reserve steering, synthesis-lockout denials) never spend it. Agent recipe budgets may narrow but never widen it (`src/engine/loop-guard.ts`). |
-| `CLIO_CODER_MAX_DISPATCH_RUNS` | `guardrails.maxDispatchRuns` | 1000 | Dispatch run-ledger retention cap (`src/domains/dispatch/state.ts`). The older `CLIO_CODER_MAX_RUNS` spelling still reads when the canonical name is unset. |
-| `CLIO_CODER_READ_MAX_BYTES` | `guardrails.readMaxBytes` | 51200 | Per-call byte cap for the read tool, floored at 1024 (`src/tools/read.ts`). |
-| `CLIO_CODER_OBSERVATION_TURN_BUDGET_BYTES` | `guardrails.observationTurnBudgetBytes` | 196608 | Shared per-turn byte pool across observation tools (`src/tools/observation.ts`). |
-| `CLIO_CODER_INTERNAL_DISPATCH_TIMEOUT_MS` | `guardrails.internalDispatchTimeoutMs` | 900000 | Wall-clock cap for one internal generator dispatch: the wiki documenter and the bootstrap scout (`src/cli/internal-dispatch.ts`). |
+The `environment-variable-inventory` check in `scripts/check-hygiene.ts`, run by `npm run lint`, enforces coverage for Clio's `CLIO_*` variables and `NO_COLOR`. It intentionally does not treat every operating-system or provider convention as a Clio knob. Examples outside that enforced family include `PATH`, `HOME`, terminal capability variables, and provider API-key names selected dynamically by `src/engine/env-api-keys.ts`.
 
 ## Behavior knobs without a settings key
 
@@ -26,11 +13,8 @@ Durable values live in the `guardrails:` section of settings.yaml (see [configur
 | --- | --- | --- |
 | `NO_COLOR` | unset | Set to any non-empty value to drop every foreground and background color. Bold, dim, italic, and underline stay, because they are what is left to read the interface by (`src/interactive/theme/tokens.ts`). |
 | `CLIO_CODER_RIGOR` | repo-derived | Finish-contract evidence bar, `normal` or `high`, layered over the repo-derived default (`src/domains/safety/rigor.ts`). |
-| `CLIO_CODER_RESIDENCY` | managed | `observe`/`off` stops Clio managing model residency on every local runtime path, llama.cpp routers included; per-target opt-out via `lifecycle: user-managed` (`src/engine/apis/residency.ts`). |
-| `CLIO_CODER_TRUST_PROJECT_RESOURCES` | settings value | `1` trusts third-party project resource imports for this process, overriding `integrations.projectResources.trustProjectImports`; otherwise the validated setting applies (`src/domains/resources/skills/loader.ts`). |
-| `CLIO_CODER_TRUST_PROJECT_SKILLS` | off | Deprecated alias for `CLIO_CODER_TRUST_PROJECT_RESOURCES`; `1` still trusts third-party project resource imports and emits a deprecation warning (`src/domains/resources/skills/loader.ts`). |
 | `CLIO_CODER_ALLOW_EXTERNAL_FULL_ACCESS` | off | `1` lets full-auto pass through to external CLI runtimes with their own full access (`src/engine/claude/subprocess-runtime.ts`, `src/engine/antigravity/subprocess-runtime.ts`). |
-| `CLIO_CODER_FORCE_COMPACT` | off | `1` forces compaction on the next interactive turn (`src/interactive/chat-loop.ts`). |
+| `CLIO_CODER_FORCE_COMPACT` | off | `1` forces compaction before every interactive turn for as long as it is set (`src/interactive/chat-loop.ts`). |
 | `CLIO_CODER_LEGACY_MASK` | off | `1` temporarily restores the destructive stale-observation mask before summary compaction; remove it after compatibility diagnosis. |
 | `CLIO_CODER_STATUS_STUCK_MS` | 180000 | Stuck-turn watchdog threshold (`src/interactive/status/watchdog.ts`). |
 | `CLIO_CODER_SHUTDOWN_HOOK_MS` | 500 | Wall-clock budget per shutdown hook (`src/core/termination.ts`). |
@@ -45,7 +29,6 @@ Durable values live in the `guardrails:` section of settings.yaml (see [configur
 | `CLIO_CODER_MODEL_CATALOG_DIRS` | unset | Extra model-catalog directories (`src/domains/providers/knowledge-base-path.ts`). |
 | `CLIO_CODER_ENDPOINT_SLOTS_TTL_MS` | 86400000 | How long a persisted endpoint slot count answers for an endpoint nothing has probed in this process. A record past the bound is ignored and pruned rather than allowed to over-admit (`src/domains/providers/endpoint-slots-store.ts`). |
 | `CLIO_CODER_NO_NETWORK_TOOLS` | off | `1` strips network tools from every registry in the process; the skills-eval harness sets it for hermetic arms; `--allow-network` clears it (`src/tools/network-policy.ts`). |
-| `CLIO_CODER_SMOOTH_STREAM` | settings value | Per-process override for `terminal.smoothStreaming`: `0`/`off`/`false`, `auto`, or `1`/`on`/`true`. A valid value wins over settings; an invalid value fails safely to `off`. |
 | `CLIO_CODER_REDUCE_MOTION` | off | `1` makes smooth-streaming `auto` use the immediate coalescer. Explicit `on` remains an operator request, while stdout backpressure still pauses frame production. |
 | `CLIO_CODER_SCREEN_READER` | off | `1` makes smooth-streaming `auto` use the immediate coalescer so a screen reader receives the existing low-motion update behavior. |
 | `CLIO_CODER_INSTANT_SHELL` | on | `0` disables the single-owner Stage 0 interactive shell for immediate rollback. Unset or `1` mounts one terminal/editor owner before service hydration; ACP, headless, ordinary non-TTY, and subcommand paths never mount it. An explicit `CLIO_CODER_INTERACTIVE=1` keeps its force-interactive non-TTY behavior. |
@@ -58,9 +41,26 @@ Durable values live in the `guardrails:` section of settings.yaml (see [configur
 | --- | --- | --- |
 | `CLIO_CODER_HOME` | unset | Single-tree install root; the per-role vars below beat it (`src/core/xdg.ts`). |
 | `CLIO_CODER_CONFIG_DIR`, `CLIO_CODER_DATA_DIR`, `CLIO_CODER_STATE_DIR`, `CLIO_CODER_CACHE_DIR` | XDG platform defaults | Per-role directory overrides (`src/core/xdg.ts`). |
+| `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`, `XDG_CACHE_HOME` | platform/user defaults | Linux base directories used when the corresponding `CLIO_CODER_*_DIR` and `CLIO_CODER_HOME` variables are unset (`src/core/xdg.ts`). |
+| `APPDATA`, `LOCALAPPDATA` | Windows profile defaults | Windows roaming and local base directories used when Clio-specific directory overrides are unset (`src/core/xdg.ts`). |
 | `CLIO_CODER_BIN_DIR` | `~/.local/bin` | Launcher symlink location (`src/cli/uninstall.ts`). |
 | `CLIO_CODER_PACKAGE_ROOT` | auto-detected | Package root for bundled-asset resolution (`src/core/package-root.ts`). |
 
+## Ambient provider, runtime, and terminal inputs
+
+These names follow an upstream or operating-system convention. They are not substitutes for settings keys, but source reads them when the associated integration is used.
+
+| Variable or family | Controls |
+| --- | --- |
+| Provider credential variables | `src/engine/env-api-keys.ts` maps the selected provider to its conventional key, including `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`, `GEMINI_API_KEY`, `AWS_*` Bedrock credentials, and Google Vertex application credentials. `clio-coder auth` remains the preferred managed credential path. |
+| `OLLAMA_NUM_PARALLEL` | Fallback concurrency advertised for an Ollama Native target when the runtime does not provide a stronger slot fact (`src/domains/providers/runtimes/local-native/ollama-native.ts`). |
+| `VISUAL`, `EDITOR` | External editor command, with `VISUAL` taking precedence (`src/interactive/external-editor.ts`). |
+| `TERM`, `COLORTERM`, `TERM_PROGRAM`, `WT_SESSION` | Terminal capability, color-depth, keybinding, and desktop-notification adaptation. These variables describe the terminal rather than Clio policy. |
+| `SSH_CONNECTION`, `SSH_TTY`, `TMUX`, `STY` | Remote-session and terminal-multiplexer detection used by the adaptive stream-pacing policy (`src/interactive/stream-pacing-policy.ts`). |
+| `COLUMNS` | Fallback text width for non-TTY CLI output (`src/cli/text-layout.ts`). |
+| `TZ` | Local timestamp formatting and daily audit-log date boundaries (`src/interactive/format-time.ts`, `src/domains/safety/audit.ts`). |
+| `CI`, `NODE_ENV` | CI-sensitive presentation behavior and test/development-only seams. Neither grants tool authority. |
+
 ## Debug and trace toggles
 
 All default off; enable with `1`.
@@ -69,7 +69,7 @@ All default off; enable with `1`.
 | --- | --- |
 | `CLIO_CODER_BUS_TRACE` | Event-bus channel tracing to stderr (`src/core/bus-trace.ts`). |
 | `CLIO_CODER_TRACE_BOOT` | Boot-phase timing trace (`src/core/boot-trace.ts`). |
-| `CLIO_CODER_TIMING` | Startup timing report (`src/entry/orchestrator.ts`). |
+| `CLIO_CODER_TIMING` | Startup timing report, printed only on the bannered non-interactive boot (`src/entry/orchestrator.ts`). |
 | `CLIO_CODER_DEBUG_SHUTDOWN` | Shutdown-path diagnostics (`src/core/termination.ts`). |
 | `CLIO_CODER_HOOK_BUDGET_DEBUG` | Per-overrun hook-budget diagnostics (`src/domains/middleware/runtime.ts`). |
 
@@ -79,7 +79,7 @@ These two take a path, not `1`. Setting either to `1` writes a file named `1` in
 
 | Variable | Contents | Controls |
 | --- | --- | --- |
-| `CLIO_CODER_RENDER_TRACE` | timing only | Versioned JSONL for the full interactive render pipeline, truncated on open so one file is one session. Records event/input sequence ranges, queue and panel high-water marks, explicit frames, grouped stdout commits, write return values, backpressure, and drain—but no conversation text. Output is bounded and asynchronous after the initial pre-TUI file open; trace failure is nonfatal. See [performance-methodology.md](performance-methodology.md) for endpoint definitions (`src/interactive/render-trace.ts`). |
+| `CLIO_CODER_RENDER_TRACE` | timing only | Versioned JSONL for the full interactive render pipeline, truncated on open so one file is one session. Records event/input sequence ranges, queue and panel high-water marks, explicit frames, grouped stdout commits, write return values, backpressure, and drain—but no conversation text. Output is bounded and asynchronous after the initial pre-TUI file open; trace failure is nonfatal. See [performance-methodology.md](../process/performance-methodology.md) for endpoint definitions (`src/interactive/render-trace.ts`). |
 | `CLIO_CODER_MEMORY_TRACE` | conversation text | Proactive task-memory step envelopes, including up to 8000 characters of the text each step saw. This is content-bearing by construction, so the file carries whatever the session carried. Do not enable it on work you would not paste, and do not attach the file to a bug report without reading it first (`src/domains/memory/task-memory-trace.ts`). |
 
 Example:
@@ -95,13 +95,13 @@ Set by Clio for its own processes; not operator knobs.
 | Variable | Purpose |
 | --- | --- |
 | `AI_AGENT` | Clio sets this generic child-process attribution marker to `clio-coder` at both shipped entry points and reinforces it for bash tools, fleet workers, registered code steps, and command hooks. Child tooling may read it to identify the agent that launched it (`src/cli/index.ts`, `src/worker/entry.ts`, `src/core/bash-exec.ts`). |
-| `CLIO_CODER_GIT_COMMITS_ENABLED` | Carries the effective `attribution.gitCommits` setting to Clio-controlled child-process seams. It is set from validated settings and is not an operator override (`src/core/git-commit-attribution.ts`). |
+| `CLIO_CODER_GIT_COMMITS_ENABLED` | Carries the effective `integrations.git.commitAttribution` setting to Clio-controlled child-process seams. It is set from validated settings and is not an operator override (`src/core/git-commit-attribution.ts`). |
 | `CLIO_CODER_COMMIT_ASSISTED`, `CLIO_CODER_COMMIT_AUTHORED` | Per-spawn inputs to the managed `prepare-commit-msg` hook, which also requires `AI_AGENT=clio-coder` and `CLIO_CODER_GIT_COMMITS_ENABLED=1`; normal external shells never receive this set. Only assistance and authorship cross the environment. Testing, review, and receipt trailers are composed in process by the fleet seam, so a child shell cannot forge them by exporting a variable (`src/core/git-commit-attribution.ts`). |
 | `CLIO_CODER_GIT_CONFIG_BASE_COUNT`, `CLIO_CODER_GIT_DEFAULT_HOOKS_EQUIVALENT` | Bookkeeping that lets each managed hook wrapper remove only Clio's command-scope `core.hooksPath` pair before chaining the repository's own hook of the same name. Existing `GIT_CONFIG_COUNT` entries remain in force; an explicit `core.hooksPath` is treated as composable only when it resolves exactly to the repository's default hooks directory (`src/core/git-commit-attribution.ts`). |
 | `CLIO_CODER_INTERACTIVE` | Marks the interactive TUI process; scrubbed from bash-tool children so nested invocations do not inherit it (`src/cli/clio.ts`, `src/core/bash-exec.ts`). |
 | `CLIO_CODER_RUN_OVERRIDES` | JSON envelope for run-scoped CLI options (`--max-context-tokens`, `--kv-cache-mode`, sampling flags). One typed variable instead of one env var per option; worker subprocesses inherit it (`src/core/run-overrides.ts`). |
-| `CLIO_CODER_RESUME_SESSION_ID` | Session id handed across a self-restart; consumed and deleted at boot (`src/entry/orchestrator.ts`). |
-| `CLIO_CODER_BOOTSTRAP_GENERATE_CHILD` | Marks the CLIO-CODER.md-generation child so it skips recursion (`src/domains/context/extension.ts`). |
+| `CLIO_CODER_EVAL_RUNNER_STDOUT_FILE` | Set by the eval runner for the `clio-coder run` child it spawns; the child appends its stdout to that path so the runner can read it after exit (`src/domains/eval/suites/run.ts`). |
+| `CLIO_CODER_YAZI_PICK_TOKEN` | Per-session token the yazi file-pane integration hands its yazi child and expects back on a pick, so a pick from another session is ignored (`src/domains/mux/yazi/session.ts`, `src/domains/mux/yazi/profile.ts`). |
 | `CLIO_CODER_WORKER_LABELS` | Comma-separated labels a dispatched worker reports as its own (`src/domains/dispatch/transport.ts`, `src/worker/entry.ts`). |
 | `CLIO_CODER_WORKER_PGID` | Process-group id the transport assigns a worker so its whole tree can be signalled (`src/domains/dispatch/transport.ts`, `src/worker/entry.ts`). |
 | `CLIO_CODER_WORKER_RUN` | Marks a dispatched worker process; a skill install run inside it is stamped `installed-by: worker` (`src/worker/entry.ts`, `src/domains/resources/skills/install.ts`). |
@@ -113,7 +113,12 @@ Set by Clio for its own processes; not operator knobs.
 | --- | --- |
 | `CLIO_CODER_WORKER_FAUX` (+ `_MODEL`, `_TEXT`, `_STOP_REASON`, `_ERROR_MESSAGE`) | Fake worker model for tests (`src/engine/ai.ts`). |
 | `CLIO_CODER_TEST_UPGRADE_NO_NETWORK` | Skips npm install during upgrade tests (`src/cli/upgrade.ts`). |
+| `CLIO_CODER_TEST_UPGRADE_AVAILABLE` | Sets mock available version for upgrade tests; `unreachable` stands for a registry that answered nothing (`src/cli/upgrade.ts`). |
+| `CLIO_CODER_TEST_UPGRADE_FAIL` | Injects mock failures (`npm` or `migration`) for upgrade tests (`src/cli/upgrade.ts`). |
 | `CLIO_CODER_TEST_STAGE1_DELAY_MS`, `CLIO_CODER_TEST_STAGE1_FAIL` | `NODE_ENV=test`-only, bounded instant-shell interleaving and injected hydration failure seams for the built PTY acceptance suite (`src/cli/clio.ts`). |
 | `CLIO_CODER_REQUIRE_HOME_PREFIX` | Test guardrail: abort if resolved directories escape `CLIO_CODER_HOME` (`src/core/init.ts`). |
 
-Variables used only by the Terminal-Bench agent under `benchmarks/community/` and by the install script are not part of the shipped runtime and are documented inline where they are consumed. The live drivers under `benchmarks/internal/` take no environment of their own: the target comes from `--target <id>`.
+Variables used only by external benchmark harnesses or install scripts are not
+part of the shipped runtime and should be documented with those harnesses. The
+reviewable reference suites under `evals/` use the ordinary eval runner and a
+configured `--target <id>` when a model is required.

package/docs/{exit-codes-and-output.md → guide/exit-codes-and-output.md}

@@ -1,6 +1,9 @@
 # Exit Codes & Machine-Readable Output Contracts
 
-This document specifies the process exit codes, machine-readable JSON streaming formats, standard I/O separation rules, and `--help` conventions across all Clio Coder CLI commands in `v0.4.0`.
+> **Visual blueprint:** The source checkout includes the complete
+> [Exit Codes & Machine-Readable Output Contracts visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/exit_codes_blueprint.html).
+
+This document specifies the process exit codes, machine-readable JSON streaming formats, standard I/O separation rules, and `--help` conventions across all Clio Coder CLI commands in the current source tree.
 
 Source implementations: `src/cli/` and `src/entry/`.
 
@@ -29,7 +32,7 @@ Every subcommand in Clio Coder adheres to the strict `--help` convention:
 
 ### Global vs Subcommand Flag Positioning
 
-Global options (such as `--api-key`, `--no-context-files`, and `-nc`) must precede the subcommand. Directory redirection is configured via the `CLIO_CODER_*_DIR` environment variables (see [docs/environment-variables.md](environment-variables.md)). If a global flag is placed after the subcommand name, Clio prints a remediation guide to `stderr` and exits with code `2`:
+Global options (such as `--api-key`, `--no-context-files`, and `-nc`) must precede the subcommand. Directory redirection is configured via the `CLIO_CODER_*_DIR` environment variables (see [docs/guide/environment-variables.md](environment-variables.md)). If a global flag is placed after the subcommand name, Clio prints a remediation guide to `stderr` and exits with code `2`:
 
 ```text
 --api-key is a global option and must come before the subcommand: clio-coder --api-key <key> <command> ...
@@ -59,7 +62,7 @@ Many Clio CLI subcommands provide structured JSON output for integration with sc
 
 | Subcommand | Flag | Output Structure |
 | :--- | :--- | :--- |
-| `clio-coder run` | `--json` | Stream of incremental NDJSON event frames (`session`, `agent_start`, `turn_start`, `message_start`, `message_end`, `thinking_delta`, `text_delta`, `tool_execution_start`, `tool_execution_end`, `turn_end`, `agent_end`). |
+| `clio-coder run` | `--json` | Stream of incremental NDJSON event frames. Core frame kinds include `session`, `agent_start`, `turn_start`, `message_start`, `message_end`, `thinking_delta`, `text_delta`, `tool_execution_start`, `tool_execution_end`, `turn_end`, and `agent_end`. Full streams can also carry registered `clio_coder_*` tool, permission, plan, and lifecycle frames; consumers must dispatch on `type` and tolerate additive kinds. |
 | `clio-coder run` | `--json-events terminal` | Emits the `session` header, a synthesized `turn_start` (`startedAt`), the `agent_end` and `notice` events that pass the filter, and a synthesized `turn_end` carrying `startedAt`, `endedAt`, `exitCode`, and `error` when the turn failed. Per-segment token usage rides `agent_end`. Excludes multi-kilobyte intermediate message bodies (#122). |
 | `clio-coder run` | `--json-events full` | Emits complete event stream with projected assistant messages (`streamed: true`, `textLength`, `thinkingLength`) to eliminate duplicate wire tokens (#122). |
 | `clio-coder agents` | `--json` | JSON array of registered agent recipe metadata objects. |

package/docs/{extensions-and-sharing.md → guide/extensions-and-sharing.md}

@@ -1,9 +1,9 @@
-# Extensions, Prompt Templates, Skills, and Share Archives
+# Extensions, Resources, and Share Archives
 
-> [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/extensions_blueprint.html](html/extensions_blueprint.html) (Version: 0.4.0).
+> **Visual blueprint:** The source checkout includes the complete
+> [Extensions, Resources, and Share Archives visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/extensions_blueprint.html).
 
-Clio Coder has lightweight community-oriented resource packaging. Extensions are filesystem bundles that contribute prompts and skills. Share archives are portable JSON files for moving project/user Clio resources between machines or collaborators. Themes are built into the engine and are no longer loaded from extensions.
+Clio Coder has lightweight community-oriented resource packaging. Extensions are filesystem bundles that can contribute prompts, skills, agent recipes, and fleet contracts. Manifests may also reserve a theme root, but the runtime does not apply extension themes. Share archives are portable JSON files for moving project and user Clio resources between machines or collaborators.
 
 Source of truth: `src/domains/extensions/**`, `src/domains/resources/**`, `src/domains/share/**`, `src/cli/extensions.ts`, and `src/cli/share.ts`.
 
@@ -61,7 +61,7 @@ Return:
 Use in the TUI:
 
 ```text
-/prompts
+/resources prompts
 /bugfix src/parser.ts empty input crashes
 ```
 
@@ -71,7 +71,12 @@ Templates without frontmatter are accepted; Clio derives a fallback description
 
 A Claude Code slash command in `.claude/commands`, a Codex prompt in `.codex/prompts`, and an OpenCode command in `.opencode/command` are prompt templates Clio reads directly, at both user and project scope. A foreign prompt is text substituted into a message the operator typed, so it keeps the untrusted-by-project default that skills have and never gains an execution grant of its own.
 
-User-scope foreign prompts are trusted the way user-scope foreign skills are: they came from the operator's own machine. A project-scope one lists in `/prompts` with an `untrusted` marker and refuses to substitute into a message until the trust flag is set, because an unreviewed checkout would otherwise get to write part of the operator's next message. Setting `skills.trustProjectCompatRoots: true` (or exporting `CLIO_CODER_TRUST_PROJECT_SKILLS=1`) is the opt-in for both kinds. Typing `/name` for an untrusted prompt template prints `prompt template <name> comes from an untrusted project root; set skills.trustProjectCompatRoots to use it` and sends nothing to the model. Headless `clio-coder run /name` prints the same refusal and exits 1. A token that names neither a command nor a template reports `is not a command`.
+User-scope foreign prompts are trusted because they came from the operator's
+machine. A project-scope prompt lists in `/resources prompts` with an
+`untrusted` marker and refuses substitution until
+`integrations.projectResources.trustProjectImports: true` opts in. An untrusted
+template sends nothing to the model. A token naming neither a command nor a
+template reports `is not a command`.
 
 ---
 
@@ -125,7 +130,7 @@ Recognized frontmatter fields:
 
 Shared user roots are model-visible by default, like the Clio user root. Project-local compatibility roots are discovered but **untrusted by default**: they appear in `/skill` with an `untrusted` marker, but they are excluded from the model-visible catalog and cannot be loaded through `context`. This prevents an unreviewed project checkout from injecting skills the model will act on.
 
-Opt in to model-visible project compatibility roots by setting `skills.trustProjectCompatRoots: true` in `settings.yaml`. `CLIO_CODER_TRUST_PROJECT_SKILLS=1` remains an environment override. `.clio-coder/skills` is always trusted as the Clio-native project root.
+Opt in to model-visible project compatibility roots by setting `integrations.projectResources.trustProjectImports: true` in `settings.yaml`. `.clio-coder/skills` is always trusted as the Clio-native project root.
 
 ### Loading with context, writing directly
 
@@ -152,7 +157,7 @@ baseline, treatment, and judge runs; see
 verifies. Fixture commands in an `evals.md` are real shell and only run with
 `--trust-fixtures`.
 
-Every arm runs hermetic in a disposable workspace at autonomy `full-auto`: the network tool plane is stripped from child runs so a scenario measures the skill against its workspace and not against the open web. `--allow-network` keeps the web tools, and the run reports which network policy was in force. The per-arm execution timeout is set with `--timeout <seconds>`.
+Every arm runs hermetic in a disposable workspace: the network tool plane is stripped from child runs so a scenario measures the skill against its workspace and not against the open web. Baseline and treatment arms run with `full-auto` autonomy; the judge does not receive that flag. `--allow-network` keeps the web tools, and the run reports which network policy was in force. The per-arm execution timeout is set with `--timeout <seconds>`.
 
 Exit code is 1 when a treatment bullet fails. Exit code is 3 when a scenario goes unmeasured, such as when judge output is truncated, missing, or unparseable, or when a run dies at a permission wall. Permission-wall deaths and harness infrastructure failures are classified as unmeasured infrastructure errors rather than negative verdicts on the skill.
 
@@ -188,12 +193,14 @@ description: Prompts and skills for this lab
 resources:
   prompts: prompts
   skills: skills
+  agents: agents
+  fleets: fleets
   themes: themes
 compatibility:
   clio: ">=0.2.0"
 ```
 
-Required fields are `manifestVersion: 1`, `id`, `version`, and `description`. `name` defaults to `id` when absent. Clio loads `prompts` and `skills`. A manifest may reserve a `themes` path for forward compatibility, but Clio does not load theme resources.
+Required fields are `manifestVersion: 1`, `id`, `version`, and `description`. `name` defaults to `id` when absent, and `resources` is optional. When `resources` is present it must be an object containing only `prompts`, `skills`, `agents`, `fleets`, and `themes`, each with a non-empty relative directory path. Clio consumes prompt, skill, agent, and fleet roots. A manifest may reserve a `themes` path for forward compatibility, but Clio does not apply theme resources.
 
 IDs must be lowercase and may include numbers, dots, underscores, and hyphens; they must start/end alphanumeric.
 
@@ -221,7 +228,7 @@ inference over its task and briefing text, and the request is refused only when
 it states a contradiction, such as a legacy `writeRoots` disagreeing with a
 declared `write_roots`. Declaring is what stops an applicable project rule from
 being missed because the task text happened not to spell a path. See
-[dispatch-typed-intent.md](dispatch-typed-intent.md).
+[dispatch-typed-intent.md](../architecture/dispatch-typed-intent.md).
 
 ---
 
@@ -245,6 +252,18 @@ Install locations:
 
 Project extensions shadow user extensions with the same ID. Use `--all` to list shadowed/disabled entries.
 
+Installed packages are admitted only when their current tree matches the SHA-256 digest in `extensions/state.json`. `clio-coder upgrade` adds digests to pre-digest v1 install records after validating and hashing each installed tree, preserves `disabled`, `source`, and `installedAt`, and backs up the original state before the atomic rewrite. Invalid or changing trees are not blessed: they stay visible and inactive with reinstall guidance. Listing extensions, booting Clio, inspection, and plain doctor runs never perform this migration.
+
+### Generations and reload
+
+A running session does not read installed packages on every resource load. While domains start, the extensions domain publishes nothing: readers use an ephemeral generation-0 projection. The composition root then asks the extensions domain to build an immutable candidate for the session's working directory and builds the matching user-hook registration table from it. After validating that both candidates are still current, the composition root publishes the snapshot and hooks with two adjacent reference assignments. That paired boot snapshot is generation 1. It contains package identity and provenance, the resolved skill, prompt, agent, fleet, and theme roots of each loadable package, and the parsed `hooks.yaml` declarations captured from the exact bytes the install digest covered. Every consumer in the process then reads the committed generation, so consecutive loads within one turn agree on the package set.
+
+`/resources extensions reload` is the only in-session way to publish a later generation. It rebuilds the snapshot from disk, re-verifies every installed tree against `state.json`, builds the user-hook registrations for the candidate, validates both candidates, and then performs the same two adjacent assignment-only publications. No callback, event, log, or refusal sits between them; conflict diagnostics and the `extensions.reloaded` event run only after both references are live. Observers therefore see the previous resources with the previous hooks or the new ones with the new ones, never an intermediate pairing. The command reports the new generation, which packages were added, removed, or modified, and how many hooks were registered, dropped, or rejected. A tree that no longer verifies is listed as inactive and contributes nothing until it is reinstalled. A build failure or stale candidate publishes neither side and reports why.
+
+Reloading an unchanged tree still publishes a new generation with the same content digest; content identity is the digest, not the generation number. Installs, enables, disables, and removes performed by `clio-coder extensions` in another process are invisible to a running session until the operator reloads or restarts. There is no filesystem watcher, so a CLI mutation never becomes an implicit mid-turn hook change. Resource files themselves (skill and prompt bodies, agent and fleet recipes) are still read at use time; a package mutated on disk after its generation was built can serve changed files until the next reload detects the drift and deactivates it.
+
+If extension state is corrupt, loading remains fail-closed. A normal reinstall refuses it; `extensions install <valid-source> --force` backs up the corrupt state and parks the previous package bytes before installing and recording the verified replacement. `extensions remove <id>` can also remove an unverifiable package from the load path while preserving both its bytes and any corrupt state in the paths printed by the command. These recovery backups are deliberately not treated as installed packages.
+
 ### Skill pack distribution
 
 Clio Coder should not grow built-in skills in the harness. Distribute reusable Clio skills as extension packages instead. A future `iowarp/clio-kit` bundle can carry `clio-coder-extension.yaml` plus a `skills/` directory, and users can install it with `clio-coder extensions install <path> --user` or `--project`.
@@ -273,11 +292,11 @@ Share archives are single JSON files:
 
 ```json
 {
-  "kind": "clio-share-archive",
+  "kind": "clio-coder-share-archive",
   "formatVersion": 1,
   "manifest": {
-    "format": "clio.share.v1",
-    "clioVersion": "0.3.7",
+    "format": "clio-coder.share.v1",
+    "clioCoderVersion": "0.4.2",
     "createdAt": "...",
     "files": []
   },
@@ -286,6 +305,9 @@ Share archives are single JSON files:
 ```
 
 Every file entry is base64 encoded and SHA-256 checked on import.
+Readers continue to accept the released legacy identities `clio-share-archive`,
+`clio.share.v1`, and `clioVersion`, then normalize them to the canonical shape.
+New exports use only the `clio-coder` names above.
 
 ### Export
 
@@ -312,7 +334,10 @@ Options:
 
 If no include flags are supplied, export includes all supported classes for the selected scope.
 
-Settings fragments include non-secret UI/runtime preferences such as `autonomy`, `scope`, `budget`, `theme`, `terminal`, `keybindings`, `compaction`, and `retry`. Targets and credentials are not included.
+Settings fragments are version 2 documents containing only
+`chat.modelPicker.cycleSet`, `chat.retry`, `fleet.concurrency`,
+`context.compaction`, `safety.autonomy`, `safety.limits.sessionCostUsd`, and the
+`interface` settings block. Targets and credentials are not included.
 
 ### Import and inspect
 
@@ -324,6 +349,8 @@ clio-coder share import project.clio-coder-share.json --force
 
 Dry-run imports produce a plan and report conflicts without writing. Without `--force`, conflicting destination files block writes. With `--force`, conflicting files are overwritten and supported settings-fragment keys are merged into the current settings file.
 
+Extension entries are grouped into complete packages, staged, strictly validated, and passed through the canonical extension installer. A successful import therefore records the installed content digest before the package can contribute resources. A destination tree is skipped only when it already matches a verified install record; an unrecorded, drifted, or corrupt destination requires `--force`, which uses the same backup-preserving recovery contract as `extensions install --force`. Invalid archived packages fail preflight before destination writes.
+
 Archives accept `agent` and `fleet` file entry types alongside prompts and skills. Agent entries import into the user agent root and must pass the recipe parser and policy checks. Fleet entries import into the user fleet root and must pass `parseFleetContract` before any write. Dry-run plans report both types by kind.
 
 Aliases:

package/docs/{fleet-dispatch.md → guide/fleet-dispatch.md}

@@ -1,6 +1,7 @@
 # Fleet Dispatch
 
-> **Interactive Spec Available:** An interactive fleet node topology planner, scout router, receipt verifier, and failure taxonomy simulator is located at [docs/html/fleet_dispatch_blueprint.html](html/fleet_dispatch_blueprint.html) (Version: 0.4.0).
+> **Visual blueprint:** The source checkout includes the complete
+> [Fleet Dispatch visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/fleet_dispatch_blueprint.html).
 
 Clio Coder dispatches bounded worker agents. With a fleet configured, those
 workers run on remote machines over SSH while the orchestrator keeps every
@@ -8,7 +9,7 @@ guarantee it makes locally: one admission path, one autonomy matrix, one
 receipt chain. This page covers the architecture, node setup, the doctor
 preflight, placement, topologies, failure semantics, and the residency
 default. For the end-to-end demo see
-[fleet-demo-runbook.md](fleet-demo-runbook.md).
+[fleet-demo-runbook.md](../process/fleet-demo-runbook.md).
 
 Source of truth: `src/domains/dispatch/**`, `src/domains/scheduling/cluster.ts`,
 `src/tools/dispatch.ts`, `src/tools/monitor.ts`, and the contract tests under
@@ -59,9 +60,10 @@ Design decisions that shape everything else:
   can be activated only for named roles/postures after exact-tuple readiness,
   and hard constraints always eliminate before any score.
 - Environment whitelist. The SSH command carries an explicit environment
-  (`CLIO_CODER_RESIDENCY=observe`, `CLIO_CODER_WORKER_PGID=$$`, and any configured
-  `CLIO_CODER_WORKER_LABELS`); the orchestrator's `process.env` never crosses the
-  wire. `CLIO_CODER_WORKER_PGID` names the remote process group so an abort escalates
+  (`CLIO_CODER_WORKER_PGID=$$` and any configured `CLIO_CODER_WORKER_LABELS`);
+  the orchestrator's `process.env` never crosses the wire. Node residency is
+  projected into the target lifecycle carried by the WorkerSpec.
+  `CLIO_CODER_WORKER_PGID` names the remote process group so an abort escalates
   against the whole group rather than one process.
 
 ## Worker prompt and budget admission
@@ -79,7 +81,7 @@ later mutation of raw arguments cannot change either field.
 
 Recipes declare a default with `budget: {toolCalls, readReserve, synthesis}`. They may also declare `maximum: {toolCalls, readReserve}` inside that object. A recipe without `maximum` is an exact pin, which preserves the fixed behavior of existing recipes. A ranged recipe admits the optional dispatch request `budget: {toolCalls, readReserve, retryRevision?}` only when the request is inside its maximum. `retryRevision` has the same two integer fields and preauthorizes the ceiling that a later automatic retry, bounded result-contract revision, or review revision may select. The loop guard raises a result-contract revision boundary only in this case. A phase without that ceiling cannot grow and retains the existing text-only repair behavior.
 
-`toolCalls` is the admitted-call phase boundary. The final `readReserve` slots accept canonical `read` plus the agent's granted mutation tools, so a writer can still deliver inside its own reserve. Admission requires integers and `0 <= readReserve < toolCalls` for every declared phase. `synthesis: true` forces a text-only final round, while `false` stops after the admitted phase. `guardrails.workerToolCallCap` remains the operator-controlled lifetime ceiling and always wins when lower. A default may be clamped by a lower operator cap so default callers retain their prior behavior; an explicit request outside the operator cap is denied.
+`toolCalls` is the admitted-call phase boundary. The final `readReserve` slots accept canonical `read` plus the agent's granted mutation tools, so a writer can still deliver inside its own reserve. Admission requires integers and `0 <= readReserve < toolCalls` for every declared phase. `synthesis: true` forces a text-only final round, while `false` stops after the admitted phase. `fleet.limits.toolCallsPerRun` remains the operator-controlled lifetime ceiling and always wins when lower. A default may be clamped by a lower operator cap so default callers retain their prior behavior; an explicit request outside the operator cap is denied.
 
 Admission computes one immutable envelope with the recipe policy, invocation request, effective worker budget, and every clamp or escalation reason. Native workers and Claude SDK enforce the effective budget. Claude Code, Antigravity, and ACP delegation reject invocation envelopes because their black-box loops cannot provide equivalent per-call mediation. Before launch, every admitted WorkerSpec v3 still contains one concrete effective budget and a settings fingerprint. The envelope provenance is sealed in the run ledger and receipt and appears in monitor, fleet status, and the live fleet card.
 
@@ -109,7 +111,7 @@ fleet:
 `clioCoderEntry` may override the remote invocation (default `clio-coder worker`).
 Node ids must be unique and `local` is reserved.
 
-Worker profiles can pin work to a node: `workers.profiles.<name>.node` routes
+Worker profiles can pin work to a node: `fleet.profiles.<name>.node` routes
 every dispatch bound to that profile. Settings → Fleet (`/fleet`) edits the
 pin on the profile's `node` row, and the dispatch tool accepts an explicit
 `node` argument per task.
@@ -150,7 +152,7 @@ Placement and admission are separate, deterministic authorities:
    queue preserves priority/FIFO order until its finite deadline instead of
    silently selecting another node.
 
-The durable capacity state file (`dispatch-admission.json`) uses schema version 2 and owns global and per-node leases, heartbeats, reservation transfer, retry rebinding, and the TTL-bounded operator drain (`DEFAULT_CAPACITY_DRAIN_TTL_MS` = 3,600,000 ms). A lease acts as durable expiring authority (`DEFAULT_CAPACITY_LEASE_TTL_MS` = 30,000 ms) and is reclaimed only with owner-liveness evidence when a process birth token cannot prove process death. A plan reserves its peak wave, and a retry rebinds the same assignment member to its actual node and cost bound so that an assignment retry belongs to its existing plan slot and cannot queue behind or outspend itself. Full leasing schema and locking protocols are specified in [capacity-and-scheduling.md](capacity-and-scheduling.md).
+The durable capacity state file (`dispatch-admission.json`) uses schema version 2 and owns global and per-node leases, heartbeats, reservation transfer, retry rebinding, and the TTL-bounded operator drain (`DEFAULT_CAPACITY_DRAIN_TTL_MS` = 3,600,000 ms). A lease acts as durable expiring authority (`DEFAULT_CAPACITY_LEASE_TTL_MS` = 30,000 ms) and is reclaimed only with owner-liveness evidence when a process birth token cannot prove process death. A plan reserves its peak wave, and a retry rebinds the same assignment member to its actual node and cost bound so that an assignment retry belongs to its existing plan slot and cannot queue behind or outspend itself. Full leasing schema and locking protocols are specified in [capacity-and-scheduling.md](../architecture/capacity-and-scheduling.md).
 
 Use `clio-coder fleet drain [--json]` before maintenance to close that shared
 admission authority. Existing workers continue, but new plans and every new
@@ -158,12 +160,13 @@ execution start—including a retry or a previously reserved member—fail close
 The drain expires after one hour so an abandoned operator process cannot wedge
 future dispatch; repeating the command renews the deadline. `clio-coder fleet
 status [--json]` reports the active deadline, requesting PID, and request time.
-Use `clio-coder fleet resume [--json]` to reopen admission early. Detailed drain mechanics are documented in [capacity-and-scheduling.md](capacity-and-scheduling.md).
+Use `clio-coder fleet resume [--json]` to reopen admission early. Detailed drain mechanics are documented in [capacity-and-scheduling.md](../architecture/capacity-and-scheduling.md).
 
 With no fleet configured and nothing requested, placement resolves to the
 implicit local path and optional fleet-node provenance may remain absent.
-Every new receipt uses strict integrity v19; older receipt formats are not
-accepted by the current reader.
+Every new receipt uses strict integrity v20. Older receipt formats are not
+accepted as current evidence; lower versions are reported as retired and are
+never migrated.
 
 ## Failure semantics
 
@@ -236,7 +239,7 @@ legitimately route a step to, so restating the contract's boundary there would
 mint a second grant in a second place and fail closed on contracts that run
 correctly today. A pre-v4 contract and every readonly step declare nothing and
 keep the legacy inference path. See
-[dispatch-typed-intent.md](dispatch-typed-intent.md) for the full producer
+[dispatch-typed-intent.md](../architecture/dispatch-typed-intent.md) for the full producer
 table and the refusal reason codes.
 
 The first checkout writer acquires a process-owned lease under the Clio state
@@ -272,7 +275,7 @@ The singular request and every object in `tasks` accept an optional `intent`:
 {
   "read_roots": ["src/domains/dispatch"],
   "write_roots": ["src/tools"],
-  "relevant_paths": ["docs/fleet-dispatch.md"],
+  "relevant_paths": ["docs/guide/fleet-dispatch.md"],
   "expected_outputs": ["dist/cli.js"],
   "verification": [{ "check": "test", "timeout_ms": 600000 }]
 }
@@ -315,8 +318,8 @@ Claude Code subprocess routes refuse them with
 
 Every topology that runs more than one worker at once opens an agent ledger, the
 bounded coordination board those workers share while they run: the parallel
-fan-out (`src/tools/dispatch.ts:3247`), a detached batch of two or more
-(`:538`), and compete (`:1549`). A worker reaches it through the `ledger` tool
+fan-out in `runBatch`, a detached batch of two or more in `runDetached`, and
+`runCompete`, all in `src/tools/dispatch-runner.ts`. A worker reaches it through the `ledger` tool
 and posts one of three typed entries. A `claim` stakes path prefixes so peers
 stop colliding, a `finding` reports one observation with the path and line that
 ground it, and a `review` judges another entry by its id. Nothing untyped is
@@ -432,7 +435,7 @@ operator inspection rather than silently auto-applied after restart.
 
 Council is the read-only sibling of compete. Two to five members run the same
 singular task concurrently on local HTTP or native targets. A request selects
-exactly one configured `workers.rosters` entry or supplies inline `members`.
+exactly one configured `fleet.rosters` entry or supplies inline `members`.
 Admission pins every member to `read-only` autonomy and to the `read`, `grep`,
 `find`, `ls`, `code_nav`, and `context` tool surface. A route that resolves to
 an SSH fleet node is refused before approval. Council never creates a worktree
@@ -519,7 +522,7 @@ Fleet contracts support schema versions 1 through 5:
 
 #### Contract v5: plan, gate, and per-step target
 
-A version 5 agent step, including an agent loop check or repair, may declare either `target: <targetId>` or `profile: <workers.profiles key>`. It may never declare both. Fleet preflight resolves these values through the same worker routing used by `/run --target` and `/run --agent-profile`. An unknown value refuses before approval and names the target or profile. Versions 1 through 4 continue to refuse both fields.
+A version 5 agent step, including an agent loop check or repair, may declare either `target: <targetId>` or `profile: <fleet.profiles key>`. It may never declare both. Fleet preflight resolves these values through the same worker routing used by `/run --target` and `/run --agent-profile`. An unknown value refuses before approval and names the target or profile. Versions 1 through 4 continue to refuse both fields.
 
 A `kind: gate` step asks its validator agent to write exactly one repository-relative `path`. The contract derives the step's write boundary from that path, so a separate `writes` property is refused. Its `run` property names a command whose argv contains one whole-token `{{path}}` placeholder. After the agent writes the executable acceptance check, the coordinator runs it without a shell against the otherwise untouched tree. A red result admits the gate. A green result refuses the run as `gate_not_discriminating`. The fleet ledger records the gate path hash. A loop may use `check: {kind: gate, gate: <stepId>}`. Only the bounded output lines beginning with `FAIL` cross that failed check edge into the repair agent.
 
@@ -693,7 +696,7 @@ exact tuple with `failover: "none"`; any other planned task seals
 Validation rejects `automatic` on a request carrying plan provenance, so an
 approved dispatch can only reroute to a tuple the approval actually showed.
 
-Retries are governed by `workers.maxRetries` and backoff, and by nothing else.
+Retries are governed by `fleet.retry.maxRetries` and backoff, and by nothing else.
 A target cooldown protects new work from a known-bad target; it does not gate
 an assignment already in flight, because that assignment's own retry budget is
 the correct and sufficient bound. A retry denied at admission settles the
@@ -701,7 +704,7 @@ assignment failed, reports the reason on stderr, and records it in the
 assignment's `outcomeDetail`.
 
 Assignment status, attempt ids, and terminal run id are stored separately in
-`assignments.json` while each attempt keeps its own strict v19 receipt.
+`assignments.json` while each attempt keeps its own strict v20 receipt.
 Pipelines and batches await assignment terminals, so downstream stages consume
 the successful fallback output rather than an earlier failed attempt.
 
@@ -728,7 +731,7 @@ closed while a winner remains unapplied.
 
 ## Receipts
 
-Receipts carry exactly one integrity version (`RUN_RECEIPT_INTEGRITY_VERSION = 19`), which authenticates the complete receipt and reconstructible ledger provenance surface. There is no historical verification path: any other version is invalid, and a receipt that fails verification is never read as evidence. The fleet provenance fields covered by the digest
+Receipts carry exactly one current integrity version (`RUN_RECEIPT_INTEGRITY_VERSION = 20`), which authenticates the complete receipt and reconstructible ledger provenance surface. There is no historical evidence reader: a lower version is reported as retired, is not migrated, and is never read as evidence; a malformed or future version is invalid. The fleet provenance fields covered by the digest
 include:
 
 - `node`: the fleet node the worker ran on (`id`, `kind`, `host`). The `node.id` explicitly identifies the worker process host executing the task, not the model host (which is represented by the `target` id). This behavior tracks issue #120.
@@ -777,7 +780,7 @@ policy all consume that same final classification.
 Receipt integrity, host verification, and evidence verification are separate axes. Integrity says
 that the sealed receipt matches its ledger envelope; evidence verification
 reports whether Clio observed an applicable validation tool (or marks the
-basis unknown/not applicable). A read-only Scout can therefore report `receipt_integrity=verified/v19/sha256` alongside
+basis unknown/not applicable). A read-only Scout can therefore report `receipt_integrity=verified/v20/sha256` alongside
 `evidence_verification=not_applicable/read-only-agent`. Host verification is
 rendered independently as `host_verification=verified|rejected|skipped|not_requested`.
 A host-executed successful check projects onto canonical validation grounding as
@@ -786,7 +789,7 @@ bounded `project_context` provenance are also rendered independently; neither
 hash substitutes for the other.
 
 The canonical terminology for these facts is the six-axis trust status in
-[`evidence-and-memory.md`](evidence-and-memory.md#canonical-trust-status).
+[`evidence-and-memory.md`](../architecture/evidence-and-memory.md#canonical-trust-status).
 Receipt integrity projects onto artifact integrity; receipt verification,
 typed quality, and validation grounding project onto validation grounding;
 gate decisions project onto independent review; briefing and project context
@@ -840,7 +843,7 @@ hard block.
   with the failure reason printed on the rail above the footer when a run fails.
 - Runs the model itself asked for through the dispatch tool (identified by
   parentToolCallId) render as folded `◆` cards under the spawning tool segment;
-  operator-typed runs are `◇` and open. The fold chord uses the `clio.tool.expand`
+  operator-typed runs are `◇` and open. The fold chord uses the `clio-coder.tool.expand`
   keybinding (`Alt+O`), which toggles the newest foldable item of either kind
   (tool call or worker block). `Ctrl+Alt+O` or `Alt+Shift+O` toggles every tool
   call and worker block at once.
@@ -939,30 +942,23 @@ disabling it changes nothing else.
 
 ## Residency
 
-Remote workers default to residency observe: the SSH transport exports
-`CLIO_CODER_RESIDENCY=observe`, so a worker on a node that serves resident models
-(for example a GPU box running the operator's inference server) never evicts
-them. A node opts into management explicitly with `residency: manage` in its
-fleet entry.
+Remote workers default to residency observe. The SSH transport projects that
+posture as `lifecycle: user-managed` in the worker's target, so a worker on a
+node that serves resident models (for example a GPU box running the operator's
+inference server) never evicts them. A node opts into management explicitly
+with `residency: manage` in its fleet entry. An explicit target
+`lifecycle: user-managed` remains authoritative even on a managing node.
 
 A model the router tags as pinned (`pinned:true` or `role:scout`) is never
 evicted once resident, so Clio refuses to load it by evicting a resident that
 settings still reference by role; on a one-slot router such an override
 declines with a `will-not-fit` notice instead of stranding the configured model.
 
-## Opt-in live regression
+## Manual fleet verification
 
-After `npm run build`, an operator with a configured model target can run the
-single-turn, read-only fleet lifecycle check explicitly:
-
-```bash
-npm run live:fleet-dispatch -- --target <id> [--model <wireId>] [--thinking medium]
-```
-
-It is not part of deterministic CI. The driver
-(`benchmarks/internal/live-fleet-dispatch.ts`) copies the repository into a
-committed temporary workspace, sandboxes all Clio config, state, data, and
-cache under a scratch home holding only the chosen target, exercises Scout,
-bounded spot-checking, detached Debugger briefing, steering, wait, and
-collect, and fails if any workspace content changes. A failed run retains its
-scratch tree for diagnosis.
+Use `clio-coder fleet validate <name>` and `clio-coder fleet graph <name>` for
+model-free contract checks. An operator with configured targets can then run
+the contract explicitly with `clio-coder fleet run <name>` and retain its
+receipts. The [fleet demo runbook](../process/fleet-demo-runbook.md) provides a bounded
+end-to-end scenario, including reviewer gates and verification commands. Live
+fleet execution is not hidden inside deterministic CI.