@iowarp/clio-coder 0.4.1 → 0.4.3

package/docs/{built-in-agents.md → guide/built-in-agents.md}

@@ -1,9 +1,9 @@
 # Clio Coder Agent Fleet
 
-Clio Coder dispatches focused fleet agents from Markdown recipes. Recipes are data files, not hidden code plugins: YAML frontmatter declares identity, tool requirements, skill bindings, audience, capability and latency classes, budget, and result contract; the Markdown body is the agent instruction text.
+> **Visual blueprint:** The source checkout includes the complete
+> [Clio Coder Agent Fleet visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/agents_blueprint.html).
 
-> [!TIP]
-> **Interactive Spec Available:** An interactive dashboard for the agent registry and dispatch admission check gates is located at [docs/html/agents_blueprint.html](html/agents_blueprint.html) (Version: 0.4.1).
+Clio Coder dispatches focused fleet agents from Markdown recipes. Recipes are data files, not hidden code plugins: YAML frontmatter declares identity, tool requirements, skill bindings, audience, capability and latency classes, budget, and result contract; the Markdown body is the agent instruction text.
 
 The source of truth is `src/domains/agents/**`. Clio's agent dispatch engine and execution boundaries are built upon the [@earendil-works/pi-agent-core](https://www.npmjs.com/package/@earendil-works/pi-agent-core) library.
 
@@ -16,25 +16,27 @@ Clio's agent architecture distinguishes between authoring configurations and run
 *   **Recipe**: An authored Markdown file containing frontmatter configuration and an instruction body.
 *   **AgentSpec**: The normalized runtime and catalog policy object derived from a recipe.
 *   **audience**: Determines visibility and routing (`base` | `shadow` | `custom` | `internal`).
-*   **source**: Origin of the recipe (`builtin` | `user` | `project`).
+*   **source**: Origin of the recipe (`builtin` | `extension` | `user` | `project`).
 
 ### Discovery, Overrides, and Precedence
-At startup, Clio loads recipes from three roots:
+At startup, Clio loads recipes in four precedence tiers:
 
 | Source | Root | Notes |
 | --- | --- | --- |
 | **Built-in** | `src/domains/agents/builtins/*.md` in the installed package | Shipped defaults. |
+| **Extension** | Each enabled extension's `agents` resource root | Loaded in stable extension-source order. An extension recipe may bind only skills from the same extension. |
 | **User** | `<configDir>/agents/*.md` | Per-user recipes. `<configDir>` follows Clio's XDG/platform config directory. |
 | **Project** | `.clio-coder/agents/*.md` under the current repo | Repository-local overrides and additions (custom/domain agents). |
 
 Recipe IDs are derived from filenames (e.g., `architect.md` -> `architect`). Recipes must live directly under their respective directories.
 
 *   **Customization**: User-level agents can override/customize shipped base agents.
+*   **Extension Protection**: Extension recipes cannot override any shipped builtin.
 *   **Shadow Protection**: User or project agents can **never** override shadow or internal agents.
 *   **Built-in Protection**: Project agents cannot override any shipped built-ins; they are strictly treated as custom/domain agents.
-*   **Reserved IDs**: The IDs `worker` and `delegate` are strictly reserved for custom/internal contexts and cannot be registered as custom agent IDs.
+*   **Reserved IDs**: The IDs `worker`, `delegate`, and `auto` cannot be registered outside the builtin tier.
 *   **Local Ignored Custom Examples**: Local examples (e.g., `benchmark-runner`, `clio-dev`, `implementer`, `scientific-validator`) may exist under `.clio-coder/agents` for documentation or test purposes, but are ignored if they collide with reserved/built-in rules.
-*   **Fleet Contracts**: Shipped builtin fleet contracts (`build-test`, `build-review`, `sdlc`) live under `src/domains/agents/fleets/*.md`. Library-installed contracts live at `<configDir>/fleets/<name>.md`. Project contracts at `.clio-coder/fleets/<name>.md` take highest precedence. Deterministic code steps reference commands declared in `.clio-coder/fleets/commands.yaml`. Contract v4 requires per-step write boundaries (`writes`).
+*   **Fleet Contracts**: Shipped builtin fleet contracts (`build-test`, `build-review`, `sdlc`) live under `src/domains/agents/fleets/*.md`. Enabled-extension contracts load next, user contracts at `<configDir>/fleets/<name>.md` load after them, and project contracts at `.clio-coder/fleets/<name>.md` take highest precedence. The parser accepts contract versions 1 through 5. Version 4 introduces enforced per-step `writes` boundaries; version 5 adds plan and gate steps, per-step target or profile routes, and the `writers: 1` single-writer declaration. Deterministic code steps reference commands declared in `.clio-coder/fleets/commands.yaml`.
 
 ---
 
@@ -47,25 +49,26 @@ User-facing agents visible in `clio-coder agents` and `/agents`.
 
 | Agent ID | Primary tools | Purpose | Capability | Latency |
 | --- | --- | --- | --- | --- |
-| `architect` | read, grep, find, ls, code_nav, git, artifact, context, ledger | Designs changes across boundaries, contracts, migrations, and validation gates. | `artifact-write` | `deep` |
-| `coder` | read, write, edit, grep, find, ls, web_fetch, git, bash, verify, code_nav, ledger | Implements bounded code changes and behavior-preserving refactors. | `workspace-edit` | `balanced` |
-| `debugger` | read, grep, find, ls, git, verify, code_nav, ledger | Diagnoses failing code, tests, or receipts without making edits. | `verification` | `balanced` |
-| `documenter` | read, write, edit, grep, find, ls, git, verify, code_nav, context, ledger | Updates developer-facing docs, examples, and operational runbooks. | `workspace-edit` | `balanced` |
-| `git-master` | read, write, edit, context, git, bash, grep, find, ls, code_nav, ledger | Executes bounded git operations: history, commits, worktrees, and PR prep. | `workspace-edit` | `balanced` |
-| `tester` | read, write, edit, grep, find, ls, git, verify, code_nav, ledger | Adds focused deterministic tests for regressions and missing coverage. | `workspace-edit` | `balanced` |
-| `verifier` | read, grep, find, ls, git, verify, code_nav, ledger | Independently runs and reports test, lint, build, review, and release gates. | `verification` | `fast` |
-| `wiki-writer` | read, write, edit, grep, find, ls, code_nav, context, ledger | Plans one repository wiki, or researches and writes one wiki page. | `workspace-edit` | `balanced` |
+| `architect` | read, grep, find, ls, code_nav, git, artifact, context, ledger | Designs a change across boundaries and slices it into a sprint: contracts, migrations, validation gates, and cut-it sprint slicing. | `artifact-write` | `deep` |
+| `coder` | read, write, edit, grep, find, ls, web_fetch, git, bash, verify, code_nav, ledger | Implements bounded code changes, repairs, and refactors, behavior-preserving by default. | `workspace-edit` | `balanced` |
+| `debugger` | read, grep, find, ls, git, verify, code_nav, ledger | Diagnoses failing code, tests, or runs without editing, reading receipts, logs, and runtime behavior. | `verification` | `balanced` |
+| `documenter` | read, write, edit, grep, find, ls, git, verify, code_nav, context, ledger | Updates developer docs, examples, and operational runbooks. | `workspace-edit` | `balanced` |
+| `git-master` | read, write, edit, context, git, bash, grep, find, ls, code_nav, ledger | Runs bounded git operations end to end: history, commits, worktrees, integration merges, and PR prep. | `workspace-edit` | `balanced` |
+| `tester` | read, write, edit, grep, find, ls, git, verify, code_nav, ledger | Adds focused deterministic regression and coverage tests. | `workspace-edit` | `balanced` |
+| `verifier` | read, grep, find, ls, git, verify, code_nav, ledger | Runs test, lint, build, review, and release gates and reports each independently. | `verification` | `fast` |
+| `wiki-writer` | read, write, edit, grep, find, ls, code_nav, context, ledger | Plans a repository wiki or writes one wiki page against a supplied plan. | `workspace-edit` | `balanced` |
 
 ### Shipped Shadow and Internal Agents
-Internal orchestration helpers and internal process agents. They are hidden from default displays (but visible via `clio-coder agents --all` and in a separate section of the prompt catalog).
+Internal orchestration helpers and internal process agents. They are hidden from default displays but visible via `clio-coder agents --all`. The full on-demand catalog has a separate shadow section and omits internal recipes; the compact session prompt likewise omits internal recipes and also excludes the operator-only `oracle`.
 
 | Agent ID | Primary tools | Purpose | Capability | Latency |
 | --- | --- | --- | --- | --- |
-| `scout` | read, grep, find, ls, context, code_nav, git, ledger | Broad repository reconnaissance, codebase orientation, structure and entry-point mapping, and multi-file symbol hunting. | `read-only` | `fast` |
-| `researcher` | read, web_fetch, context, ledger | Shadow docs and external-source researcher for coding decisions. | `read-only` | `deep` |
-| `provenance` | read, grep, find, ls, git, ledger | Shadow evidence, receipt, diff, and telemetry reader for handoffs. | `read-only` | `balanced` |
+| `scout` | read, grep, find, ls, context, code_nav, git, ledger | Broad repository reconnaissance with cited findings: orientation, structure and entry-point mapping, multi-file symbol hunting. | `read-only` | `fast` |
+| `researcher` | read, web_fetch, context, ledger | Extracts and compares concrete supplied URLs, standards, release notes, and papers through Clio-observed reads and URL retrieval. | `read-only` | `deep` |
+| `world-knowledge` | optional web_fetch, read, context, ledger | Current open-world discovery, ecosystem comparison, broad external context, and an advisory second opinion; reports when discovery is unavailable. | `read-only` | `deep` |
+| `provenance` | read, grep, find, ls, git, ledger | Reads receipts, diffs, and telemetry for evidence-backed handoffs. | `read-only` | `balanced` |
 | `oracle` | read, grep, find, ls, code_nav, context, ledger | Shadow advisor behind `/oracle` that protects consistency with prior decisions and returns the strongest challenge to a question. | `read-only` | `deep` |
-| `context-bootstrap` | read, grep, find, ls, context, code_nav, ledger | Internal agent behind `clio-coder context init` that parses repository and returns CLIO-CODER.md payload. | `read-only` | `balanced` |
+| `context-bootstrap` | read, grep, find, ls, context, code_nav | Internal agent behind `clio-coder context init` that parses repository and returns CLIO-CODER.md payload. | `read-only` | `balanced` |
 
 The builtin `architect` also serves as the default author for a version 5 fleet `plan` step. In that role it returns the coordinator-owned `delegation-plan` result shape instead of writing its ordinary plan artifact. It may name only agents from the contract roster. The coordinator supplies the plan step's target or profile to every admitted task.
 
@@ -73,6 +76,19 @@ The builtin `architect` also serves as the default author for a version 5 fleet
 
 Grounding is checked against the run's own reads, not just against the file. The worker records the exact line span every successful read returned, and a cited line must fall inside one. A line that exists in the file but was never read fails, which is what stops an approximated or inferred line number from passing as observation. `grep` and `code_nav` hits are leads: read the file before citing what they point at.
 
+The three discovery roles are deliberately non-overlapping. `scout` is
+repository-only reconnaissance with live `path:line` grounding and never browses
+external sources. `researcher` starts from concrete URLs or documents and uses
+Clio-observed `read`/`web_fetch` calls to extract and compare them; `web_fetch` is
+URL retrieval, not search. `world-knowledge` is for current open-world discovery,
+ecosystem comparison, broad context, and an independent advisory opinion. Its
+tools are all optional so it can run on a native Clio target or an opaque external
+worker. A native target without discovery must use caller-supplied sources or say
+discovery was unavailable. Its `world-knowledge-report` separates supported
+facts and supplied source identifiers from synthesis, uncertainty, and follow-up
+verification; it never fabricates citations. The capability class remains
+`read-only` regardless of the caller's requested autonomy.
+
 `oracle` is the only shadow agent an operator reaches directly, and only through
 `/oracle <question>`. It never receives a forked transcript. `/oracle` packs a
 bounded digest instead and sends it as dispatch briefing data: the settled
@@ -107,19 +123,19 @@ Two rounds only help when the reason is actionable, so a validator reason names
 ```yaml
 ---
 version: 1                            # recipe schema version
-name: Coder                           # string; defaults to recipe id when absent
-description: Bounded code changes     # string; defaults to empty string
+name: Coder                           # required non-empty string
+description: Bounded code changes     # required non-empty string
 tools:                                # required/optional tool mapping, not a flat list
   required: [read, {anyOf: [write, edit]}, context]   # anyOf: at least one must admit
   optional: [grep, git, verify, bash, ledger]         # attached when the target carries them
 skills: [fix-issue, ship]             # knowledge attachments; require the context tool, never expand tool authority
-audience: base                        # base | shadow | internal
+audience: base                        # base | shadow | custom | internal
 category: implement                   # explore | plan | research | implement | quality | science | evolution | operations | internal
 capabilityClass: workspace-edit       # read-only | artifact-write | workspace-edit | verification | orchestration | internal
 latencyClass: balanced                # fast | balanced | deep
 projectContextTier: bounded           # how much project context the worker is briefed with
 tags: [implementation, repair]        # short lowercase routing hints for catalog display
-budget:                               # optional strict worker-loop phase policy
+budget:                               # required strict worker-loop phase policy
   toolCalls: 50                       # admitted calls before final response handling
   readReserve: 5                      # final admitted slots reserved for canonical read
   synthesis: true                     # true: text-only final round; false: stop immediately
@@ -133,7 +149,9 @@ optional `product` key also exists for product-scoped recipes. There are no
 `model`, `target`, `thinkingLevel`, or `output` frontmatter keys — target and
 model selection belong to dispatch, not the recipe.
 
-A custom source recipe may omit `budget`; admission then materializes a concrete WorkerSpec v3 budget from the operator's current `guardrails.workerToolCallCap`. Built-in recipes declare the field and fail startup if their strict frontmatter is malformed. When a source recipe includes `budget`, it must be a non-null YAML object containing `toolCalls`, `readReserve`, and `synthesis` (plus an optional `maximum` ceiling object, e.g. architect's `maximum: {toolCalls: 150, readReserve: 16}`): the numeric fields must be safe integers, `toolCalls > 0`, and `0 <= readReserve < toolCalls`; `synthesis` must be a boolean. Unknown, missing, quoted-numeric, floating-point, null, and relationally invalid values reject the recipe with its source path and property. Scout declares `18/4/true`; Coder declares `50/5/true`. The model-visible catalog shows declared policy or `operator-default`, never a mutable effective cap.
+Every recipe must declare `name`, `description`, `budget`, and every other key in the required set; no display defaults are synthesized. `budget` must be a non-null YAML object containing `toolCalls`, `readReserve`, and `synthesis`, plus an optional `maximum` ceiling object such as architect's `maximum: {toolCalls: 150, readReserve: 16}`. The numeric fields must be safe integers, `toolCalls > 0`, and `0 <= readReserve < toolCalls`; `synthesis` must be a boolean. Unknown, missing, quoted-numeric, floating-point, null, and relationally invalid values reject the recipe with its source path and property. Scout declares `18/4/true`; Coder declares `50/5/true`. The model-visible catalog shows the declared policy, never a mutable effective cap.
+
+Only shipped recipes may declare the `base`, `shadow`, or `internal` audience. Extension, user, and project recipes must declare `audience: custom`; the discovery root determines that provenance and the parser refuses a conflicting claim.
 
 The operator cap is independent and cannot be widened by a recipe. Dispatch clamps `toolCalls` to that cap and clamps `readReserve` to zero when canonical `read` is absent after tool admission. Reserve slots admit only `read`, not every read-class tool. Blocked non-read attempts do not consume admitted reserve slots, but they still count toward the operator attempt ceiling.
 
@@ -157,13 +175,13 @@ Skills are knowledge attachments declared under `skills: [...]` in the YAML fron
 
 An assignment may request `agent: auto`, but agent choice is advisory by default and is independent of target/model/runtime/node route activation. The coordinator first removes recipes that fail audience, capability-class, execution-role, tool-surface, result-contract, target, or policy constraints. Those are hard constraints and never become score weights. The remaining recipes are ranked deterministically with measured evidence and bounded cold-start priors.
 
-Active agent selection requires an exact `{agentId, executionRole}` entry in `routing.agentAutomation.activeAgentRoles` and a passing readiness report for that same agent and role. Empty activation settings are the default. If no eligible agent is ready, active automation fails closed instead of falling back to the fixed requested recipe.
+Active agent selection requires an exact `{agentId, executionRole}` entry in `fleet.adaptiveRouting.agentRoles` and a passing readiness report for that same agent and role. Empty activation settings are the default. If no eligible agent is ready, active automation fails closed instead of falling back to the fixed requested recipe.
 
 Scout is the bounded escalation path for broad reconnaissance, not an authority shortcut. Its strict `scout-report` may return grounded findings or a split recommendation with typed subtasks. The coordinator validates the transition, assigns fresh authority and an absolute deadline to each child, and records the decision. A recovery attempt uses the dedicated recovery role and may not silently inherit broader builder authority.
 
 ### ACP Delegation Agents as First-Class Workers
 
-ACP delegation agents (registered under `delegation.agents` in `settings.yaml`) are integrated as first-class workers:
+ACP delegation agents (registered under `integrations.externalAgents.entries` in `settings.yaml`) are integrated as first-class workers:
 - **Automatic Routing:** When a task is dispatched to an agent ID matching a configured ACP delegation agent, the dispatch engine automatically routes the execution to that delegation agent.
 - **Dynamic Spec Discovery:** The agent registry automatically synthesizes complete AgentSpecs for configured ACP delegation agents. They are visible via `clio-coder agents` and in slash command menus.
 
@@ -177,9 +195,9 @@ To ensure security and proper boundary isolation, shadow and internal agents are
 In addition to standard HTTP targets and [Agent Client Protocol (ACP)](https://agentclientprotocol.com) delegation agents, Clio dispatches subagents to sanctioned subscription worker runtimes:
 - **`claude-sdk` (Claude Agent SDK):** Serves as a main worker runtime for driving fleet agents. It integrates with [@anthropic-ai/claude-agent-sdk](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) alongside Clio's native subagent workers (like a local [llama.cpp](https://github.com/ggerganov/llama.cpp), [Ollama](https://ollama.com), [LM Studio](https://lmstudio.ai), [vLLM](https://github.com/vllm-project/vllm), or [SGLang](https://github.com/sgl-project/sglang) fleet) to execute tasks under a Claude subscription. Every tool call is mediated by Clio (`canUseTool` plus a `PreToolUse` hook): the safety net and autonomy matrix apply, and the run's admitted tool surface, which is narrowed by any `tool_profile`, is enforced authoritatively. Consequently, an out-of-profile tool (for example `bash` under `minimal-local`) is denied even though the underlying preset offers it. The narrowed surface is also translated into the SDK's `disallowedTools` option as defense in depth. Because it routes tool calls through Clio safety, it behaves as a native worker.
 - **`claude-code` (Claude Subprocess):** Runs `claude -p` as a subprocess worker, mapping autonomy levels to the CLI's permission modes. It is a black box: tool calls run inside the `claude` process and are not routed through Clio's per-tool mediation, so Clio cannot enforce a per-tool profile on it. Dispatching a narrowing `tool_profile` (`minimal-local` or `science-local`) to this runtime is refused; use `full-agent` (or a native / `claude-sdk` worker) instead.
-- **`antigravity-code` (Antigravity CLI):** Runs an Antigravity CLI subprocess as a subscription worker target for fleet dispatch. Like `claude-code`, it is a black box with no per-tool mediation and no per-tool allowlist, so a narrowing `tool_profile` is refused rather than silently ignored.
+- **`antigravity-code` (Antigravity CLI — experimental local delegation):** Runs the operator-installed and authenticated official `agy` command as a local external delegation worker. It is useful for a `world-knowledge` pass, a second opinion, or another bounded one-shot subtask; it is never an orchestrator or Gemini chat backend. Clio consumes agy's structured stream and live model catalog but cannot mediate individual tools, so a narrowing `tool_profile` is refused rather than silently ignored. The `world-knowledge` binding is permanently read-only.
 
-Agent budgets follow the same mediation boundary. Native workers and `claude-sdk` enforce canonical call counting, the canonical-`read` reserve, and the synthesis transition. `claude-code` and `antigravity-code` reject recipes that explicitly declare `budget`, because silently ignoring numeric bounds would be unsafe; a custom source recipe without the field receives the concrete operator-default budget at admission. Claude vendor aliases never appear in recipes or prompt authority and cannot reintroduce a canonical tool removed by admission.
+Agent budgets follow the same mediation boundary. Native workers and `claude-sdk` enforce canonical call counting, the canonical-`read` reserve, and the synthesis transition. An opaque external loop instead receives an `external-one-shot` enforcement classification: Clio enforces one subprocess launch, its deadline, output cap, cancellation, and result-contract validation, while recording recipe per-tool numbers as `unobserved-not-enforced`. Receipts and status never label those internal per-tool limits enforced, and Clio never automatically retries a generating external-agent run. Claude vendor aliases never appear in recipes or prompt authority and cannot reintroduce a canonical tool removed by admission.
 
 Interactive TUI:
 
@@ -241,7 +259,7 @@ over run:
   `pipeline` provenance (source run, step position, input bytes, whether the
   cap truncated it). Step 1 and every non-pipeline run get none. The `pipeline`
   and `personaOverride` field shapes and their stability labels are documented
-  in the [receipt provenance schema](./observability.md#receipt-fields-for-dispatch-provenance).
+  in the [receipt provenance schema](../architecture/observability.md#receipt-fields-for-dispatch-provenance).
 
 ---
 
@@ -260,19 +278,19 @@ Subagent runs that terminate with retryable outcomes are placed in an in-memory
 Scheduled retries use an exponential backoff state to calculate subsequent retry delays. Furthermore, targets that fail are subject to a cooldown period. The retry engine ensures that a retried task waits for the maximum of the exponential backoff delay or the remaining target cooldown duration. Retries are brand-new runs that must re-pass all admission checks. If target policies or budgets deny a retry, the task chain terminates as denied.
 
 ### 3. Concurrency Limits
-The setting `budget.concurrency` restricts the number of concurrent subagent tasks. Setting it to `auto` determines the concurrency limit dynamically based on system capabilities.
+The setting `fleet.concurrency` restricts the number of concurrent subagent tasks. At this revision, `auto` resolves to the compiled default of four local workers; it does not probe the host dynamically.
 
 ### 4. Heartbeats and Reconciler
 For native subprocess workers, Clio uses a heartbeat mechanism. The reconciler monitors the active heartbeat timestamp. If a worker stops responding and updates no heartbeats, the reconciler terminates the stalled subprocess automatically.
 
 ### 5. Worker Permission Postures
-A dispatched worker has no operator by default, so a tool call that requires interactive permission must resolve within bounded time. The `workers.onPermission` setting picks the posture:
+A dispatched worker has no operator by default, so a tool call that requires interactive permission must resolve within bounded time. The `fleet.permissions.mode` setting picks the posture:
 
 - `deny` (default): the parked call becomes a structured tool denial and the run continues.
 - `fail`: the run finalizes immediately with outcome `failed`/`permission_required`.
-- `escalate`: the parked call is handed up to the interactive operator. The worker emits a `clio_permission_escalated` event over its stdout; the dispatch domain republishes it on the bus as a permission request tagged with the run id; the operator resolves it in the TUI permission overlay; and the decision travels back down the worker's stdin as a `permission_decision` line (the same pipe steers use). No model can approve a worker permission; resolution is human-only.
+- `escalate`: the parked call is handed up to the interactive operator. The worker emits a `clio_coder_permission_escalated` event over its stdout; the dispatch domain republishes it on the bus as a permission request tagged with the run id; the operator resolves it in the TUI permission overlay; and the decision travels back down the worker's stdin as a `permission_decision` line (the same pipe steers use). No model can approve a worker permission; resolution is human-only.
 
-Escalate is only meaningful with an interactive operator attached. Headless sessions have no subscriber, so the escalation resolves by the timeout fallback. The bounds are `workers.escalation` (`{ timeoutMs, fallback }`, defaults 120000 ms and `deny`): a parked ask that no operator answers within `timeoutMs` applies the fallback deny/fail, so an escalate-posture run can never hang forever. The heartbeat timer runs independently of the parked call, so an escalated worker keeps reporting alive while it waits. Each escalation and its resolution (operator or timeout) is tallied on the receipt's `safety.decisions` escalation counters, documented with their stability labels in the [receipt provenance schema](./observability.md#receipt-fields-for-dispatch-provenance); a timed-out or denied escalation also raises an `escalation` finding in the evidence bundle. ACP delegations are out of scope: they resolve permissions through their own mediator and have no worker stdin channel.
+Escalate is only meaningful with an interactive operator attached. Headless sessions have no subscriber, so the escalation resolves by the timeout fallback. The bounds are `fleet.permissions.escalation` (`{ timeoutMs, fallback }`, defaults 120000 ms and `deny`): a parked ask that no operator answers within `timeoutMs` applies the fallback deny/fail, so an escalate-posture run can never hang forever. The heartbeat timer runs independently of the parked call, so an escalated worker keeps reporting alive while it waits. Each escalation and its resolution (operator or timeout) is tallied on the receipt's `safety.decisions` escalation counters, documented with their stability labels in the [receipt provenance schema](../architecture/observability.md#receipt-fields-for-dispatch-provenance); a timed-out or denied escalation also raises an `escalation` finding in the evidence bundle. ACP delegations are out of scope: they resolve permissions through their own mediator and have no worker stdin channel.
 
 ---
 
@@ -283,9 +301,21 @@ Create `.clio-coder/agents/my-agent.md`:
 
 ```md
 ---
+version: 1
 name: My Agent
 description: Focused local review helper.
-tools: [read, grep, find, ls, git, artifact]
+tools:
+  required: [read, artifact]
+  optional: [grep, find, ls, git]
+skills: []
+audience: custom
+category: quality
+capabilityClass: artifact-write
+latencyClass: balanced
+projectContextTier: bounded
+budget: {toolCalls: 20, readReserve: 4, synthesis: true}
+resultContract: {kind: artifact-report}
+tags: [review]
 ---
 
 You are My Agent. Inspect only the requested area. Never edit files. End by writing a concise review artifact (`artifact` kind="review") with risks, evidence, and follow-up tests.

package/docs/{commands-and-modes.md → guide/commands-and-modes.md}

@@ -1,12 +1,12 @@
 # Commands and Modes
 
-> [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/commands_blueprint.html](html/commands_blueprint.html) (Version: 0.4.0).
+> **Visual blueprint:** The source checkout includes the complete
+> [Commands and Modes visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/commands_blueprint.html).
 
-
-Clio Coder is a terminal-first alpha harness. This page keeps the command
-reference, interaction modes, dispatch surface, verification lanes, and common
-operator guidance out of the README so the release entry point stays short.
+Clio Coder is a terminal-first coding agent. This page is the detailed command
+reference for interactive sessions, headless runs, dispatch, verification, and
+common operator workflows; the README remains an approachable product and
+onboarding guide.
 
 Source of truth: `src/cli/index.ts`, `src/interactive/slash-commands.ts`,
 `src/domains/dispatch/**`, `src/tools/registry.ts`, and the current test suite.
@@ -33,7 +33,7 @@ For process exit codes, stdout deliverable guarantees, and machine-readable JSON
 | `clio-coder config [inspect] [--json]` | Print the effective customization graph across settings, context files, rules, skills, prompts, agents, extensions, safety, memory, hooks, and operator profile. |
 | `clio-coder targets [--json] [--probe] [--target <id>]` | List configured targets, health, auth, runtime, model, and capabilities. |
 | `clio-coder targets add` | Add a target interactively or through configure flags. |
-| `clio-coder targets use <id> [--model <id>] [--orchestrator-model <id>] [--background-model <id>] [--fleet-target <id>] [--fleet-model <id>]` | Point the orchestrator at one target. Without `--fleet-target` the fleet default follows it; with `--fleet-target` the fleet runs on a different node. `--worker-target` and `--worker-model` are accepted aliases from before the worker/fleet rename. |
+| `clio-coder targets use <id> [--model <id>] [--orchestrator-model <id>] [--background-model <id>] [--fleet-target <id>] [--fleet-model <id>]` | Point the orchestrator at one target. Without `--fleet-target` the fleet default follows it; with `--fleet-target` the fleet runs on a different node. |
 | `clio-coder targets fleet [--json]` | List the configured fleet profiles with their target, runtime, model, and thinking level. `targets workers` is an accepted alias. |
 | `clio-coder targets profile list\|set\|remove\|rename\|bind\|unbind\|bindings` | Manage named fleet profiles and agent bindings. `clio-coder targets profile <name> <id>` is the short form of `profile set`, and `targets worker` is an accepted alias for `targets profile`. |
 | `clio-coder targets convert <id> --runtime <runtimeId>` | Convert older local target definitions to a runtime-specific target. |
@@ -51,6 +51,7 @@ For process exit codes, stdout deliverable guarantees, and machine-readable JSON
 | `clio-coder tools install <id> [--force] [--json]` | Download the platform asset, verify every declared checksum, and atomically vendor it. |
 | `clio-coder tools remove <id>\|--all [--json]` | Remove Clio-vendored copies without touching a program found on `PATH`. |
 | `clio-coder panes install` | Alias for `clio-coder tools install herdr`. |
+| `clio-coder panes theme` | Print Clio's theme tokens as a herdr `[theme.custom]` block to paste into herdr's `config.toml`; Clio never edits that file itself. See [Panes and the Files Pane](panes-and-files.md). |
 | `clio-coder reset [--state\|--data\|--cache\|--auth\|--config\|--all] [--dry-run] [--force]` | Reset selected Clio Coder state. `--state` is the default level. |
 | `clio-coder uninstall [--dry-run] [--remove-binary] [--force]` | Remove Clio Coder state and print uninstall guidance. |
 | `clio-coder upgrade [--dry-run] [--channel=<latest\|beta\|dev>] [--skip-migrations]` | Refresh state metadata, apply migrations, and update npm installs when applicable. |
@@ -69,6 +70,7 @@ For process exit codes, stdout deliverable guarantees, and machine-readable JSON
 | `clio-coder trace phases <runId> [--db PATH]` | Show one run's recorded phases. |
 | `clio-coder trace tail <runId> [--follow] [--db PATH]` | Tail one run's recorded events; `--follow` streams as they land. |
 | `clio-coder trace procs <runId> [--db PATH]` | Show the processes one run spawned. |
+| `clio-coder trace code-steps <rootId> [--json]` | Show the deterministic code-step records one fleet root wrote (argv, cwd, env names, exit code, duration, output digest, artifact paths). They are files beside the ledger, not rows in the mirror, so `--db` does not apply. |
 | `clio-coder trace prune [--max-age-days N] [--max-bytes N] [--db PATH] [--json]` | Apply the trace-retention policy while protecting queued and running runs; JSON reports the resolved policy, rows, runs and bytes removed, protected runs, and whether vacuum ran. |
 | `clio-coder trace sql <SELECT query> [--db PATH]` | Run one read-only query against the mirror. Only a single `SELECT` or read-only `WITH` statement is accepted; anything else exits 2. |
 | `clio-coder trace ui [--db PATH] [--port N]` | Serve the localhost-only waterfall viewer. The viewer is not part of the published package. |
@@ -76,7 +78,7 @@ For process exit codes, stdout deliverable guarantees, and machine-readable JSON
 | `clio-coder extensions list\|discover\|install\|enable\|disable\|remove` | Manage installed extension packages and resource roots. `clio-coder ext` is an accepted alias. |
 | `clio-coder skills list\|search\|inspect\|validate\|install\|update\|sync\|eval` | Manage discovered skills, Clio-native skills, and local marketplace installs. |
 | `clio-coder docs [topic] [--no-open]` | Serve the interactive HTML docs of a source checkout on 127.0.0.1; the npm package ships the Markdown guides only. |
-| `clio-coder usage report [--repo <path>] [--days <n>] [--json]` | Cross-session usage facts and opportunities from the session and run ledgers. The window defaults to 30 days and the JSON schema is marked experimental. |
+| `clio-coder usage report [--repo <path>] [--days <n>] [--json]` | Cross-session usage facts from session/run ledgers and retained out-of-turn calls, including known failed-compaction spending and missing coverage. The window defaults to 30 days and the JSON schema is marked experimental. |
 | `clio-coder dev share export --out <path> [--project\|--user\|--both] [--context] [--prompts] [--skills] [--settings] [--extensions]` | Export project context, prompts, skills, settings fragments, and extension bundles. |
 | `clio-coder dev share import <path> [--dry-run] [--force] [--project\|--user] [--json]` | Import a share archive with conflict reporting. |
 | `clio-coder dev share inspect <path> [--json]` | Inspect a share archive without importing it. |
@@ -114,8 +116,8 @@ For process exit codes, stdout deliverable guarantees, and machine-readable JSON
 | `--tool-profile <name>` | Restrict dispatched-agent tools: `minimal-local`, `science-local`, or `full-agent`. |
 | `--require <capability>` | Require a target capability for dispatch. Repeatable. |
 | `--steer-channel <path>` | Read live steering lines from a FIFO or an appended regular file to steer the active run. |
-| `--with-panes` | Activate guest pane integration for this invocation when Clio is already inside a reachable herdr session. It overrides `panes.enabled`. |
-| `--no-panes` | Disable pane integration for this invocation. It overrides `panes.enabled`. |
+| `--with-panes` | Activate guest pane integration for this invocation when Clio is already inside a reachable herdr session. It overrides `interface.panes.enabled`. |
+| `--no-panes` | Disable pane integration for this invocation. It overrides `interface.panes.enabled`. |
 
 `--with-panes` is an explicit first-class launch mode, not permission to start a
 pane server. Clio confirms `HERDR_ENV=1`, connects to an existing socket, and
@@ -123,7 +125,7 @@ pings it before registering pane tools. The fleet watch pane runs
 `fleet view --watch` against a selection file. Clio writes only the selected run
 id, while the viewer reads journals itself, so dispatch remains independent of
 the pane host and a second terminal can use the same journal surface directly.
-`panes.enabled: embedded` does not start a host: it is an accepted but
+`interface.panes.enabled: embedded` does not start a host: it is an accepted but
 unimplemented rung that resolves to no panes, prints a refusal during boot, and
 is labelled `NOT IMPLEMENTED` in Settings. Use `auto` or `--with-panes` only
 when Clio is already inside a reachable herdr session.
@@ -167,18 +169,15 @@ The registry table below lists the available interactive slash commands. On a ba
 | `/quit` | `/quit` | Exit Clio Coder |
 | `/help` | `/help [query]` | Open the interactive help center showing commands and keys |
 | `/skill` | `/skill [name] [task]` | Open the Skills Hub or invoke a skill |
-| `/library` | `/library [kind]` | Open the Skills Hub on a resource library tab |
-| `/prompts` | `/prompts` | List prompt templates |
-| `/extensions` | `/extensions` | List installed extensions |
-| `/interop` | `/interop` | Review other coding agents detected on this machine |
-| `/share` | `/share [runId] \| /share export <path> \| /share import [--dry-run] [--force] <path>` | Share a worker result with the main agent, or export and import Clio archives |
+| `/resources` | `/resources [skills\|prompts\|library [kind]\|extensions [reload]]` | Browse installed resources and private library entries; `extensions reload` commits a new extension generation |
+| `/share` | `/share [runId]` | Share a worker result with the main agent |
+| `/archive` | `/archive export <path> \| /archive import [--dry-run] [--force] <path>` | Export or import a full Clio archive |
 | `/run` | `/run [--agent-profile <profile>] [--runtime <runtimeId>] [--target <id>] [--model <id>] [--thinking <level>] [--tool-profile <minimal-local\|science-local\|full-agent>] [--require <cap>] [--share] <agent> <task>` | Run a fleet agent |
 | `/delegate` | `/delegate [--share] <agent-id> <task>` | Run an ACP delegation agent |
 | `/btw` | `/btw <question>` | Ask a side question that never enters the session transcript |
 | `/oracle` | `/oracle <question>` | Ask a read-only advisor to challenge a question against this session's settled decisions |
 | `/council` | `/council [--roster <name>] [--rounds <n>] [--synthesis <judge\|vote\|none>] <task>` | Ask a roster of read-only members the same task, with an optional vote or judge synthesis |
-| `/agents` | `/agents` | List Clio agents and ACP delegation agents |
-| `/targets` | `/targets` | Open Settings → Targets: health, use, connect, probe, remove |
+| `/agents` | `/agents [list\|connect]` | List native and external agents, or review detected external-agent proposals |
 | `/cost` | `/cost` | Show session token and cost totals |
 | `/context` | `/context compact [instructions] \| /context recall <ref> \| /context init \| /context refresh \| /context reset` | Context hub: window overlay plus compact, recall, init, refresh, and reset |
 | `/fleet` | `/fleet run [--var <key=value>] <name>` | Open Settings → Fleet, or run a fleet contract with an approval preview |
@@ -186,12 +185,12 @@ The registry table below lists the available interactive slash commands. On a ba
 | `/tasks` | `/tasks add <text> \| /tasks hand <id> \| /tasks done <id> \| /tasks drop <id>` | Show the session board or manage project operator tasks |
 | `/memory` | `/memory seed` | Inspect, promote, or seed task memory |
 | `/view` | `/view [filter] \| /view verify <runId>` | Browse session artifacts and verify receipts |
-| `/panes` | `/panes show <run-or-agent> \| /panes open <preset-or-argv> \| /panes close [target]` | Inspect the pane layer, watch a live run in a pane, or open a utility pane |
+| `/panes` | `/panes show <run-or-agent> \| /panes open <preset-or-argv> \| /panes zoom [target] \| /panes close [target]` | Inspect the pane layer, watch a live run in a pane, or open a utility pane (`files`, `logs`, `shell`, `files --once`, or a command); a second open focuses the pane already there |
+| `/files` | `/files [open\|close\|pick]` | Toggle the files pane docked below the session; picks land in the composer as `@` mentions. See [Panes and the Files Pane](panes-and-files.md) |
 | `/thinking` | `/thinking [level]` | Set the chat thinking level, or open Settings → Orchestrator |
 | `/output` | `/output [verbosity]` | Set transcript detail (minimal, default, verbose), or open Settings → Terminal |
 | `/model` | `/model [pattern]` | Open model selector or set a model |
-| `/scoped-models` | `/scoped-models` | Open Settings → Models: the Alt+J / Alt+K cycle set and favorites |
-| `/settings` | `/settings [section]` | Open interactive settings |
+| `/settings` | `/settings [chat\|fleet\|targets\|context\|safety\|interface\|integrations] [group]` | Open interactive settings, optionally at a durable area and UI group |
 | `/resume` | `/resume` | Resume a past session |
 | `/new` | `/new` | Start a fresh session |
 | `/handoff` | `/handoff <goal>` | Hand this session's working state to a fresh session for a stated goal |
@@ -199,6 +198,12 @@ The registry table below lists the available interactive slash commands. On a ba
 | `/fork` | `/fork` | Fork from an assistant turn |
 | `/export` | `/export [path]` | Export a self-contained HTML transcript by default; a `.md` path writes Markdown |
 
+Retired spellings fail closed and print their exact replacement. In particular,
+`/targets` points to `/settings targets`, `/scoped-models` points to
+`/settings chat model-picker`, and `/library`, `/prompts`, and `/extensions`
+point to the corresponding `/resources` subcommand. They never fall through to
+the model as prompt text.
+
 `/context` with no arguments opens the context-window ledger overlay, including
 the working-set section (policy, evicted items and tokens, events, recalls, churn).
 The subcommands own the durable project-context noun: `compact` summarizes older
@@ -249,8 +254,8 @@ member's label, target, model, node, round count, and synthesis mode before
 anything runs. Members are pinned to read-only autonomy and the council tool
 surface by admission, exactly as they are for a council the model asks for.
 
-`--roster` names a `workers.rosters` entry. Without it the command takes
-`workers.rosters.default` when that roster exists, and with neither it refuses
+`--roster` names a `fleet.rosters` entry. Without it the command takes
+`fleet.rosters.default` when that roster exists, and with neither it refuses
 and names the setting to declare. A roster that is the only one configured is
 still not the default: seating a council from whichever roster happens to be
 present would run models the operator never chose. `--rounds` accepts one to
@@ -297,11 +302,11 @@ The `/resume` picker accepts Page Up and Page Down to move by its 12 visible row
 Only active commands run. Typing anything command-shaped that the registry does
 not own checks the loaded prompt templates across native and foreign prompt roots.
 Built-in command names are reserved across interactive and headless modes; a
-template with the same basename is omitted from `/prompts` with a collision
+template with the same basename is omitted from `/resources prompts` with a collision
 diagnostic instead of shadowing a command on one surface and expanding on another.
 If a matching template is found in an untrusted project root, Clio prints that the
 prompt template comes from an untrusted project root and directs the operator to set
-`skills.trustProjectCompatRoots`, sending nothing to the model. If the token names
+`integrations.projectResources.trustProjectImports`, sending nothing to the model. If the token names
 neither a command nor a template, it reports `is not a command` and points at `/help`;
 it is never sent to the model. That covers spellings removed outright, such as
 `/status` and `/receipts`, as well as ordinary typos. It replaces the earlier
@@ -394,7 +399,7 @@ stable board history and `userTaskId` pickup links survive `/resume` and `/fork`
 and can be audited from `current.jsonl`. Operator tasks persist separately in
 `.clio-coder/user-tasks.json`; the overlay can add, hand, finish, or drop them.
 The model-facing `tasks` tool's session-ledger and inbox bookkeeping is the
-documented read-class exception described in [the safety model](safety-model.md):
+documented read-class exception described in [the safety model](../architecture/safety-model.md):
 calls remain audited as `read` and do not grant workspace mutation authority.
 
 The `/decisions` overlay shows completed and cancelled `ask_user` interviews
@@ -411,24 +416,26 @@ and expanded dashboard summarize whether intervention is on, its rules or LLM
 tier, and current bank size.
 After `/resume`, Clio offers `/memory seed` when the newest handoff contains a
 structured snapshot. Seeding is explicit, deduplicated, and unavailable while
-`memory.intervention.enabled` is off.
+`context.memory.enabled` is false.
 
-The `/interop` overlay lists the other coding agents Clio found on this machine,
+The `/agents connect` overlay lists the other coding agents Clio found on this machine,
 grouped `Detected`, `Configured`, and `Declined`. A detected row's detail pane
-shows the exact `delegation.agents` entry that connecting it would append, plus
+shows the exact `integrations.externalAgents.entries` entry that connecting it would append, plus
 the two facts a new peer inherits: `projectContext: none`, so the peer receives
 the task text and never the project projection, and `toolGovernance:
-clio-policy`, so its tool calls are gated by Clio safety. Press `a` to connect
+clio-coder-policy`, so its tool calls are gated by Clio safety. Press `a` to connect
 one or `d` to decline; the overlay reads the report this process already produced
 at boot and never probes on a keystroke. Accepting applies to the live session,
 because `delegation` hot-reloads.
 
-Boot adds at most one line about interop, in the shape `clio: codex detected on
-PATH and not configured. Run /interop to review.` It names only agents that are
-installed, unconfigured, and undecided, it appears at most once per set of facts,
-and it is never emitted in headless or ACP mode. Declining an agent silences it
-until its binary version or path changes, at which point it becomes a fresh
-proposal.
+Boot adds at most one line about interop, in the current source shape
+`clio-coder: codex detected on PATH and not configured. Run /interop to review.`
+The `/interop` name is retained only as a retired-command tombstone and answers
+`Use /agents connect.`, so operators can open `/agents connect` directly. The
+hint names only agents that are installed, unconfigured, and undecided, appears
+at most once per set of facts, and is never emitted in headless or ACP mode.
+Declining an agent silences it until its binary version or path changes, at which
+point it becomes a fresh proposal.
 
 `clio-coder doctor` reports interop and never proposes anything. It emits one
 `ok` row per detected agent naming its version, its path, and whether it is
@@ -464,8 +471,9 @@ editor reserves and can be rebound through `settings.yaml.keybindings`.
 | `Alt+T` | Open the session tree navigator (`/tree`). |
 | `Alt+U` | Toggle the footer dashboard between compact (quiet 2-zone) and expanded (4-zone urgency) layouts. |
 | `Alt+L` | Open the model and targets selector. |
-| `Alt+J` / `Alt+K` | Cycle forward / backward through the scoped model set (when empty, displays a notice directing the operator to `/scoped-models`). |
+| `Alt+J` / `Alt+K` | Cycle forward / backward through the configured model set (when empty, directs the operator to `/settings chat model-picker`). |
 | `Alt+W` | Toggle the Fleet Runs board (task, run ID, live telemetry, retry, and terminal history). Inside it, `Enter` opens the selected run's live worker detail, `s` steers, and `x` cancels. |
+| `Alt+E` | Toggle the files pane docked below the session in a `--with-panes` session inside herdr; the same as `/files`. Rebind through `clio-coder.files.toggle`. |
 | `Alt+B` | Open the composite session and operator task board (`/tasks`). Approved application-boundary override of editor word-back. |
 | `Alt+D` | Open the settled interview decision board (`/decisions`). Approved application-boundary override of editor word-delete. |
 | `Alt+S` / `Ctrl+Alt+B` | Convert an active attached dispatch to a detached background batch. |
@@ -517,7 +525,7 @@ The `Alt+W` Fleet Runs board makes this control path discoverable: use
 Up/Down or `j`/`k` to select a run, `s` to close the board and prefill its
 exact `@<runId> ` steering prefix, and `x` to cancel a live worker or queued
 retry. A steer first reports `queued`; only the worker's
-`clio_steer_received` acknowledgement reports `received`. Single-shot
+`clio_coder_steer_received` acknowledgement reports `received`. Single-shot
 subprocess runtimes and ACP delegation do not expose a live steering channel
 and are labeled accordingly.
 
@@ -528,7 +536,7 @@ Clio Coder operates with a single, unified tool surface. There are no separate t
 Tool and command execution is governed by:
 - **Target Capabilities:** What the selected model target actually supports (such as tools, streaming, and vision).
 - **Safety Net:** Granular rule packs loaded from `damage-control-rules.yaml`, project policies, and protected artifact paths; always on, identical at every autonomy level.
-- **Autonomy Mapping:** Once the net passes a call, the level decides whether it runs, asks, or is denied. See [safety-model.md](safety-model.md) for the full matrix.
+- **Autonomy Mapping:** Once the net passes a call, the level decides whether it runs, asks, or is denied. See [safety-model.md](../architecture/safety-model.md) for the full matrix.
 
 When an action asks for confirmation, whether from a safety-net rail or from the autonomy level, the call parks and three surfaces say so at once. The transcript row reads `⏸ awaiting approval` with `action ·`, `axis ·`, and `target ·` lines under it; the footer phase pill reads `⏸ confirm`; and a consequence-tier dialog opens with the tool, target, action, authenticated requester, one-shot authority, reversibility, and deny and stop effects. Titles distinguish workspace authority, outward consequences, safety-net confirmation, system changes, and worker escalations. The dialog sits at bottom center with five rows reserved for the composer and footer, and it re-anchors on resize. The composer rail switches to `CONFIRM` and repeats the keys while the prompt owns the keyboard.
 
@@ -553,6 +561,7 @@ Fleet dispatch runs focused agent recipes through configured targets. The final
 | `scout` | `explore` / `shadow` | Read-only repository exploration, symbol mapping, and context assembly. |
 | `researcher` | `research` / `shadow` | Documentation, literature, and web-grounded investigation. |
 | `provenance` | `operations` / `shadow` | Reading evidence files, receipts, diffs, and telemetry for handoffs. |
+| `oracle` | `plan` / `shadow` | Challenging one question against the session's settled decisions through `/oracle`. |
 | `context-bootstrap` | `internal` / `internal` | Bootstrap agent behind `clio-coder context init` that inspects the repository and returns `CLIO-CODER.md`. |
 
 Examples:
@@ -563,9 +572,11 @@ clio-coder run --agent architect "Plan a minimal change to add JSON output to th
 clio-coder run --agent verifier "Run tests and confirm the build passes."
 ```
 
-Shadow agents (`scout`, `researcher`, `provenance`) are internal orchestration
-helpers. They appear in `clio-coder agents --all` and the main prompt catalog, but
-user-origin `/run` and `clio-coder run --agent` requests are rejected for them.
+Dispatchable shadow helpers (`scout`, `researcher`, `provenance`) appear in
+`clio-coder agents --all`, the full agent catalog, and the compact fleet prompt,
+but user-origin `/run` and `clio-coder run --agent` requests are rejected for
+them. `oracle` also appears in `--all` and the full catalog, but it is deliberately
+excluded from the compact prompt and is reached only through `/oracle`.
 For broad repository reconnaissance, the operating contract and Scout catalog
 description steer the model to author a Scout dispatch. The chat harness does
 not mechanically route the request. A threshold nudge advises Scout delegation
@@ -582,33 +593,23 @@ to execute through the existing engine worker path, the sanctioned Claude Code w
 | --- | --- |
 | `npm run ci` | Local and GitHub PR gate: typecheck, lint, skills pin check, build, the deterministic test suite, and the trace-viewer suite. |
 | `npm run ci:release` | Maintainer release gate: `npm run ci`, then the `check-release` dist and packaging audit. |
-| `npm run live:smoke -- --target <id>` | One real headless turn against a configured target. Add `--delegation` for the `opencode` and `copilot` ACP agents. The other operator-run drivers (`live:fleet-dispatch`, `live:tui`, `live:home`) are listed in `benchmarks/internal/README.md`. |
 | `npm run typecheck` | Strict TypeScript pass. |
 | `npm run lint` | Biome checks plus `scripts/check-hygiene.ts`, which runs the boundary invariants, the skills pin check, and the README and docs drift rules. |
-| `npm run test` | Contract and smoke tests through the sharded runner. |
+| `npm test` | Focused contract and smoke files through plain `node --test`. |
 | `npm run build` | Production bundle through `tsup`. |
 | `npm run dev` | `tsup --watch`. |
 | `npm run clean` | Remove `dist/`. |
 
-Live drivers pick their model with `--target <id>`, naming one of the targets
-`clio-coder targets` lists; `--model <wireId>` and `--thinking <level>`
-override that target's defaults for the run. The run happens in a scratch Clio
-home holding only that target, so nothing touches the operator's real state:
-
-```bash
-npm run build
-npm run live:smoke -- --target local-lmstudio --model qwen3.8-27b
-npm run live:smoke -- --target anthropic --delegation
-```
-
-Live checks cost tokens or local GPU time and are not deterministic CI. They
-are useful for OpenAI-compatible local gateways such as llama.cpp, LM Studio
-with Dynamo-backed workers, vLLM, and SGLang, plus cloud targets when
-credentials are configured.
+Live provider checks cost tokens or local GPU time and are deliberately not
+part of deterministic CI. Maintainers perform them explicitly against an
+isolated Clio home and a named configured target, recording the target, wire
+model id, serving configuration, and result with the release evidence. This is
+the appropriate lane for local gateways such as llama.cpp, LM Studio, vLLM,
+and SGLang, and for cloud targets with operator-provided credentials.
 
 ## Environment Variables
 
-Clio Coder's behavior can be customized or overridden using various environment variables (such as `CLIO_CODER_RIGOR`, `CLIO_CODER_HOME`, and guardrail overrides). For the complete, detailed, and maintained inventory of environment variables, please refer to [environment-variables.md](environment-variables.md).
+Clio Coder also reads environment variables for platform paths, diagnostics, lifecycle integration, tests, and process-local behavior such as `CLIO_CODER_RIGOR`. Durable guardrail policy lives only in settings. For the complete maintained inventory, see [environment-variables.md](environment-variables.md).
 
 ---
 
@@ -758,7 +759,11 @@ The Clio TUI has been enhanced to maximize readability, operational focus, and c
 - **Footer Notification Degradation Ladder:** The footer notification badge reserves the severity head (`glyph count noun`) and `[Alt+X] dismiss` tail first, allocating remaining width to an ellipsized message body. Under narrow terminal constraints, it degrades cleanly down the ladder without clipping action keys.
 - **Grouped Slash Command Palette:** Typing `/` opens an autocomplete command palette grouped by operational category (`Run`, `Inspect`, `Configure`, `Sessions`) with compact argument hints. Every suggestion is the command's one canonical spelling.
 - **Voice-First Transcript & Receipts:** User (`› `) and assistant (`✦ `) prose are formatted with a two-cell hanging indent, ensuring wrapped continuation lines remain visually tied to their voice prefix. Tool ledgers maintain full terminal width. Completed turn receipts honor output verbosity (`minimal` none, `default` compact dim `turn · in N · out M`, `verbose` full receipt with call counts, cache reads/writes, reasoning provenance, and verification caveats).
-- **Transactional Settings Center:** Open via `/settings` (or deep links `/targets`, `/fleet`, `/scoped-models`, `/thinking`, `/output`). Grouped into `CORE`, `ROUTING`, `RUNTIME`, and `EXPERIENCE` sections. Value edits are transactional: `Enter` opens value pickers/checklists and constructs immutable change plans offering `Apply this session`, `Apply and save globally`, or `Cancel`. Includes the Fleet entity workbench, Targets console table with in-place action drawer, scoped-model checklist, and narrow-terminal drill-down navigation below 72 columns.
+- **Transactional Settings Center:** Open `/settings` or deep-link to one of
+  `chat`, `fleet`, `targets`, `context`, `safety`, `interface`, or
+  `integrations`. Value edits construct change plans offering `Apply this
+  session`, `Apply and save globally`, or `Cancel`; narrow terminals use a
+  drill-down layout below 72 columns.
 
 ## Overlay and Presentation Conventions