@iowarp/clio-coder 0.4.9 → 0.5.0

package/docs/guide/configuration-and-targets.md

@@ -6,6 +6,20 @@ Clio's engine is built on the pi SDK (see [docs/architecture/pi-boundary.md](../
 
 Source of truth: `src/core/defaults.ts`, `src/core/config.ts`, `src/domains/providers/**`, `src/cli/configure.ts`, `src/cli/targets.ts`, `src/cli/models.ts`, and `src/cli/auth.ts`.
 
+### Start here
+
+| If you want to | Go to |
+| --- | --- |
+| Get a first target working | [First-run flow](#first-run-flow), then `clio-coder configure` |
+| Know what to set for a local server | [Recommended defaults](#recommended-defaults) |
+| Look up one setting's default and validation | [Settings inventory](#settings-inventory) |
+| Look up a flag, environment variable, or project file | [Configuration reference](configuration-reference.md) |
+| Fix a target that will not connect | [Troubleshooting checklist](#troubleshooting-checklist) |
+| Sign in to a subscription or OAuth provider | [Auth](#auth) |
+
+The rest of this page is ordered from setup to reference. Deep mechanics sit in
+collapsed sections; the tables stay open.
+
 ---
 
 ## Directory locations
@@ -71,7 +85,7 @@ Quick Connect detects LM Studio, Ollama, and LiteLLM where their discovery APIs
 are available; other servers use the OpenAI- or Anthropic-compatible protocol.
 It checks live model discovery, without sending a generation request. An
 unreachable endpoint or empty model list stays in setup with a useful error.
-Use **Settings → Targets & Auth → Add a target** for browser sign-in,
+Use **Settings → Connections → Add a target** for browser sign-in,
 subscriptions, AWS credentials, explicit runtime selection, or a server that
 needs a manually entered model id.
 
@@ -96,7 +110,7 @@ These aim to make one coding session useful on a laptop or a shared endpoint:
 | --- | --- |
 | Connection | One endpoint and model for chat and the fleet default on first setup. No separate model assignments to learn. |
 | Autonomy | `auto-edit`: workspace edits are allowed; unrecognized commands need approval. The safety policy still applies. |
-| Parallel work | One worker at a time, so a single local model or shared endpoint is not flooded by default. Explicit `auto` still allows four workers. |
+| Parallel work | `auto`: local workers are sized from usable CPUs, available memory, and any cgroup memory limit, up to eight. Per-endpoint slot limits still keep a single local model or shared endpoint from being flooded. Set a number for an exact limit. |
 | Worker permissions | Deny worker tool requests that need approval (`deny`), returning a structured denial so the worker can continue. This works across native and external runtimes. Interactive operator escalation is available for mediated runtimes in Settings. |
 | Cost | $5 tracked session budget. This depends on reported usage and known pricing; it is not a provider billing cap. |
 | Thinking | Low for chat, off for workers; actual support depends on the chosen model. |
@@ -109,8 +123,8 @@ These aim to make one coding session useful on a laptop or a shared endpoint:
 
 Newly initialized settings contain these values. Existing explicit values are
 preserved; omitted keys inherit the current shipped defaults. For this release,
-the changed defaults are worker concurrency `1`, prewarm `false`, and smooth
-streaming `auto`. See the
+the changed default is worker concurrency `auto`; an explicit
+`fleet.concurrency` already in `settings.yaml` is kept. See the
 [full settings reference](configuration-reference.md) for every key.
 
 ## Advanced settings
@@ -118,29 +132,56 @@ streaming `auto`. See the
 Choose **Settings**, or run `clio-coder configure --settings`, to open the full
 configuration menu:
 
-- **Targets & Auth**: add, edit, rename, or remove a target; choose chat, fleet,
-  and background-memory defaults. Add and Edit share the full target wizard.
-  Adding a target preserves existing defaults. Editing preserves its other
-  capabilities, gateway settings, and role-specific model overrides. Rename
-  updates the target name and its references together.
-- **Models & Thinking**, **Chat Defaults**, **Fleet**, **Permissions & Autonomy**,
-  **Panes & Layout**, and **Skills & Extensions** cover common settings.
-- **Diagnostics** shows paths, runs the read-only doctor, and displays saved YAML.
-- **All Settings** opens a validated editor for every settings key, including
-  fleet profiles, routing, memory, compaction, plugins, hooks, and keybindings.
-
-Escape returns to the parent menu, which remembers the selected row. Each
-accepted setting is saved immediately; leaving another field does not undo
-previously accepted settings. Clear a model override or list by deleting its
-prefilled text before accepting it. The full target wizard instead saves at
-**Save target** after review. Pasted keys wait for Save; browser sign-in stores
-credentials when sign-in succeeds. Optional delegation review follows Save.
+The configure menu and TUI `/settings` use the same sections, in the same order:
+
+| Section | What belongs here | Direct link |
+| --- | --- | --- |
+| **Connections** | Providers, endpoints, credentials, and available models | `targets` |
+| **Chat** | Chat model, thinking, favorites, output tokens, and retries | `chat` |
+| **Fleet** | Worker models, profiles, routing, concurrency, retries, and run limits | `fleet` |
+| **Context & Memory** | Compaction, working set, context limits, and proactive memory | `context` |
+| **Permissions & Limits** | Autonomy, worker approvals, external-agent governance, spending, and safety review | `safety` |
+| **Appearance** | Display mode, streaming, notifications, panes, and keyboard shortcuts | `interface` |
+| **Integrations** | Project skills, external agents, plugins, library, and Git attribution | `integrations` |
+| **Advanced** | Diagnostics, configuration files, and the full settings editor | `advanced` |
+
+Use `clio-coder configure --section <name>` or `/settings <name>` to open an
+area directly. Previous names such as `models`, `permissions`, `panes`, and
+`skills` remain aliases for their new homes. `/settings` groups related controls
+within each section; `/` filters by label, description, or settings path.
+
+Connections manages the provider inventory. Chat, Fleet, and Context & Memory
+choose which connection and model their work uses. Adding a connection preserves
+existing defaults. Editing preserves its other capabilities, gateway settings,
+and role-specific model overrides. Rename updates references together.
+
+Configure puts common actions first. **All controls in this section** opens the
+complete shared catalog, grouped by purpose and searchable by name or settings
+path. Each control explains its meaning, current value, shipped default, and
+when changes take effect. Both interfaces validate edits against the existing
+settings schema.
+
+Collections such as keybinding overrides, remote nodes, and rosters accept JSON;
+Connections and Fleet also retain their guided actions. Library remote confirmation
+remains owned by the library's trust flow. Advanced opens the validated full-file
+editor and diagnostics; the TUI links to those commands. The launcher retains a
+Diagnostics shortcut, and `configure --section diagnostics` still opens that screen
+directly.
+
+Escape returns to the parent menu, which remembers the selected row. Common
+actions save when accepted; the complete catalog asks you to review and save
+each edit. Leaving another field does not undo previously saved settings. Clear
+a model override or list by deleting its prefilled text before accepting it.
+
+The full target wizard instead saves at **Save target** after review. Pasted keys
+wait for Save; browser sign-in stores credentials when sign-in succeeds. Optional
+delegation review follows Save.
 
 Open a section directly, or open the full editor:
 
 ```bash
 clio-coder configure --section targets
-clio-coder configure --section models
+clio-coder configure --section chat
 clio-coder configure --edit
 ```
 
@@ -151,16 +192,41 @@ never replace the saved file. A save keeps the previous file at
 `settings.yaml.bak` and refuses to overwrite concurrent changes. `--edit` also
 works when malformed settings prevent the regular menu from loading.
 
-These commands edit user settings. Approved project settings and session
-choices can override them; use `clio-coder config inspect` to see the active
-sources. Without a terminal, `--section` prints its values and exits; `--json`
-and `--list` inspect settings and runtimes without initializing an installation.
-Dumb terminals retain the numbered prompt fallback; Quick Connect requires a
-regular interactive terminal. Use explicit flags for unattended target setup.
+Configure saves user defaults globally. The TUI offers session-only or global
+saves for live controls and identifies changes that require a restart.
+
+Clio can explain these settings herself: ask “What can you do without asking?”
+or “What are my worker limits?” Her `context(scope="settings")` tool reads the
+running session's effective configuration, including overrides, and returns
+specific `/settings` and configure commands.
+
+Every response includes the chat and fleet default routes, configured profiles and
+agent bindings, and target runtime IDs; these are configuration facts, not backend
+health checks. Multiword searches rank partial matches. It reports configured
+ceilings, not remaining spending or call counts. It omits credentials, endpoint
+URLs, external-agent commands, and arbitrary free-form values. This tool is
+read-only; Clio guides you through changes and does not raise permissions or
+budgets to work around a denial. Workers without an authoritative settings
+snapshot say so instead of assuming the parent's settings.
+
+The shipped `auto-edit` level allows workspace edits, recognized checks, and
+routine delegation. Unfamiliar commands, reads outside the permitted workspace
+roots, declared outward actions, and larger dispatch plans need approval.
+Worker mode `deny` only denies calls that need approval; permitted worker work
+continues. Choose `escalate` when you want supported worker runtimes to ask you,
+with a timeout and explicit fallback. `full-auto` skips autonomy approvals but
+still passes through the safety policy. No level disables hard safety blocks.
+
+Approved project settings and session choices can override them; use
+`clio-coder config inspect` to see the active sources. Without a terminal,
+`--section` prints its values and exits; `--json` and `--list` inspect settings
+and runtimes without initializing an installation. Dumb terminals retain the
+numbered prompt fallback; Quick Connect requires a regular interactive terminal.
+Use explicit flags for unattended target setup.
 
 Start one local runtime and register exactly one target first. Clio integrates with popular local inference engines:
 - **[LM Studio](https://lmstudio.ai):** A desktop application to run LLMs locally. Target runtime ID: `lmstudio`.
-- **[Ollama](https://ollama.com):** A lightweight, extensible framework for building and running LLMs locally. Target runtime ID: `ollama-native`.
+- **[Ollama](https://ollama.com):** A lightweight, extensible framework for building and running LLMs locally. Target runtime ID: `ollama`.
 - **[llama.cpp](https://github.com/ggerganov/llama.cpp):** A minimal C/C++ implementation for local LLM inference. Target runtime ID: `llamacpp`.
 - **[vLLM](https://github.com/vllm-project/vllm):** A high-throughput and memory-efficient LLM serving engine. Target runtime ID: `vllm`.
 - **[SGLang](https://github.com/sgl-project/sglang):** A fast serving framework for large language models. Target runtime ID: `sglang`.
@@ -179,7 +245,7 @@ Common local runtime IDs and default URLs are:
 | Runtime | Target runtime id | Example local URL |
 | --- | --- | --- |
 | LM Studio | `lmstudio` | `http://127.0.0.1:1234` |
-| Ollama | `ollama-native` | `http://127.0.0.1:11434` |
+| Ollama | `ollama` | `http://127.0.0.1:11434` |
 | llama.cpp server | `llamacpp` | `http://127.0.0.1:8080` |
 | vLLM | `vllm` | `http://127.0.0.1:8000` |
 | SGLang | `sglang` | `http://127.0.0.1:30000` |
@@ -245,9 +311,10 @@ Terminology used in code and receipts:
 | Background target | Optional proactive-memory model target. Unset means deterministic rules-only memory. |
 | Worker target | Fleet dispatch target. HTTP/native engine-backed, or one of the sanctioned subscription worker runtimes such as `claude-sdk`, `claude-code`, or `antigravity-code`. |
 
-This abbreviated example uses the current version-2 information architecture.
-The [settings inventory](#settings-inventory) below lists every accepted leaf
-and its shipped default.
+This abbreviated example illustrates the version-2 schema organization across targets, chat, fleet, context, safety, interface, and integrations. The [settings inventory](#settings-inventory) below details every accepted leaf key and its shipped default.
+
+<details>
+<summary>A complete annotated `settings.yaml`</summary>
 
 ```yaml
 version: 2
@@ -279,7 +346,7 @@ fleet:
   rosters: {}
   agentProfiles: {}
   nodes: []
-  concurrency: 1
+  concurrency: auto
 
 context:
   workingSet:
@@ -330,12 +397,19 @@ integrations:
     commitAttribution: true
 ```
 
+</details>
+
 Target capability overrides may include `chat`, `tools`, `toolCallFormat`, `reasoning`, `thinkingFormat`, `structuredOutputs`, `vision`, `audio`, `embeddings`, `rerank`, `fim`, `contextWindow`, and `maxTokens`.
 
 ### LiteLLM gateways
 
-Register LiteLLM with its first-class runtime so discovery reads
-`/v1/model/info` rather than treating routed names as bare OpenAI models. For a
+Register LiteLLM with its first-class runtime. The authenticated `/v1/models`
+listing controls selectable aliases. `/v1/model/info` (with `/model/info` fallback)
+enriches matching aliases with capability and deployment metadata. An explicitly
+empty inference listing stays empty; admin metadata cannot broaden it. If the
+inference listing is unavailable, detail rows are unverified hints, not a healthy
+catalog. A restricted `/health/liveliness` endpoint does not invalidate a successful
+authenticated listing. For a
 gateway where placement matters, publish one deterministic `node/model` name
 per deployment instead of task categories such as `chat` or `code`:
 
@@ -344,7 +418,7 @@ targets:
   - id: ai-gateway
     runtime: litellm
     url: http://gateway.example:4000
-    defaultModel: dynamo/qwen3.8-27b
+    defaultModel: node-1/qwen3.8-27b
     auth:
       apiKeyEnvVar: CLIO_AI_GATEWAY_KEY
     litellm:
@@ -361,47 +435,180 @@ Clio adds the `clio-coder` request tag and forwards its stable session id by
 default. Explicit `x-litellm-*` headers on the target or request take
 precedence. Set `sendSessionId: false` when the gateway must not correlate calls.
 The timeout values and `numRetries` become LiteLLM request headers and override
-the proxy's defaults only for this target. Clio disables the OpenAI SDK's
-client-side retry layer on LiteLLM requests. A failed interactive LiteLLM call
-also bypasses Clio's transient retry ladder even when `chat.retry` is enabled:
-the provider error names the selected route and tells the operator to choose a
-different one with `/model`. Configure `numRetries: 0` and no server fallback
-maps when `node/model` is a placement guarantee. Context-overflow compaction is
-still a local correction, not a route substitution.
-
-When the gateway reports these fields, Clio records LiteLLM's selected model group, physical model,
-sanitized upstream host, fallback/retry counts, and proxy timing in the session
-and worker receipt. A nonzero fallback or retry is also announced in the live
-transcript, making server-policy drift visible. Self-describing physical routes
-are summarized in probe diagnostics instead of expanding into a giant list of
-tautological mappings. If a genuine alias has multiple deployments, discovered
-capabilities are the conservative intersection and numerical limits are the
-smallest limits published by every deployment, so routing cannot select a
-weaker backend than Clio planned for. If `/v1/model/info` omits a capability,
-Clio does not invent it; that includes structured-output support.
-
-Upstream `model_info.runtime` declarations may identify the thinking-control dialect of a routed model. Clio accepts only recognized declarations shared by every deployment of that alias; unknown or mixed declarations remain unguessed. A resolved LM Studio dialect uses its explicit off effort, while llama.cpp uses template controls. This metadata does not turn the target into a native management endpoint: LiteLLM continues to own authentication, routing, loading and eviction. Thinking off is a request to the selected runtime/model, not evidence that the server complied or that every route has been live-validated.
+the proxy's defaults only for this target.
+
+Clio disables the OpenAI SDK's client-side retry layer on LiteLLM requests. A
+failed interactive LiteLLM call also bypasses Clio's transient retry ladder even
+when `chat.retry` is enabled: the provider error names the selected route and tells
+the operator to choose a different one with `/model`. Configure `numRetries: 0`
+and no server fallback maps when `node/model` is a placement guarantee.
+Context-overflow compaction is still a local correction, not a route substitution.
+
+When the gateway reports these fields, Clio records LiteLLM's selected model
+group, physical model, sanitized upstream host, fallback/retry counts, and proxy
+timing in the session and worker receipt. A nonzero fallback or retry is also
+announced in the live transcript, making server-policy drift visible.
+Self-describing physical routes are summarized in probe diagnostics instead of
+expanding into a giant list of tautological mappings.
+
+If a genuine alias has multiple deployments, discovered capabilities are the
+conservative intersection and numerical limits are the smallest limits published
+by every deployment, so routing cannot select a weaker backend than Clio planned
+for. If `/v1/model/info` omits a capability, Clio does not invent it; that includes
+structured-output support.
+
+Upstream `model_info.runtime` declarations may identify the thinking-control
+dialect of a routed model. Clio accepts only recognized declarations shared by
+every deployment of that alias; unknown or mixed declarations remain unguessed.
+A resolved LM Studio dialect uses its explicit off effort, while llama.cpp uses
+template controls. This metadata does not turn the target into a native management
+endpoint: LiteLLM continues to own authentication, routing, loading and eviction.
+Thinking off is a request to the selected runtime/model, not evidence that the
+server complied or that every route has been live-validated.
+
+### Current user and machine awareness
+
+At session startup Clio includes the local OS account, machine hostname, and
+workspace in the model’s prompt context. This lets it answer where it is running
+without invoking `whoami` or a shell. The account name is not a verified personal
+identity, and the machine is the Clio host, not the inference server. No new
+configure question, stored profile, or settings migration is required.
+
+### Local inference and server management
+
+Clio connects to running inference servers. The server remains responsible for
+model downloads, runtime/driver installation, GPU placement, KV allocation, MTP,
+and scheduling. Clio’s target configuration selects a protocol and model, applies
+supported request controls, and uses available metadata for planning and admission.
+It does not guarantee that a model fits in VRAM or that a requested knob took effect.
+
+| Runtime | Chat transport | Additional controls and limits |
+| --- | --- | --- |
+| `ollama` | Native HTTP `/api/chat` | Native thinking, sampling, `num_ctx`, and owned-load keep-alive; `/api/ps` reports residency. |
+| `lmstudio` | Shared OpenAI-compatible chat | REST catalog and optional explicit load settings; loaded-instance resolution. Use `reasoning_effort` for thinking control. |
+| `llamacpp` | Shared OpenAI-compatible chat | Router residency, context/slot metadata and `cache_prompt`; server flags determine KV layout, MTP and parallelism. |
+| `lemonade` | Shared OpenAI-compatible chat | Advertised model labels distinguish chat, tools, reasoning, vision, embedding and reranking support. Configure the backend and model loading in Lemonade. |
+| `litellm` | Shared OpenAI-compatible chat | Gateway aliases and capability metadata; upstream loading and eviction remain the gateway/server’s responsibility. |
+
+The hidden `lemonade-anthropic` runtime exposes Lemonade’s Anthropic-compatible
+surface when that protocol is needed. Generic runtime defaults do not establish
+capabilities for every model in a server’s catalog. Use a live tool/reasoning check
+when those abilities matter to a workflow.
+
+`lifecycle: user-managed` disables Clio’s explicit load/unload management. A chat
+request may still trigger the server’s own automatic load policy. LM Studio REST
+load options cover only the supported fields in the target schema; they do not
+promise SDK-only GPU guardrails or KV quantization controls. If explicit loading
+is required, unavailable management metadata is an error; otherwise Clio can
+attempt inference despite a temporary metadata outage. Capacity-specific load
+failures may trigger eviction of Clio-owned instances and bounded restoration on
+failure. Authentication or invalid-option errors do not authorize eviction.
 
 ### `maxConcurrentRequests`
 
 `maxConcurrentRequests` is a per-target integer of at least 1, validated with the rest of the target block, and it is the operator's override for how many requests the inference endpoint behind that target can serve at once. It is not a settings-file default and has no shipped value, so it does not appear in the settings inventory below.
 
-Set it only when discovery is wrong. Clio resolves the limit in this order: this override; then a `parallelSlots` count cached on the target's probe result; then a persisted discovery result that is still fresh and matches the runtime; then one slot for any other `local-native` runtime; then no invented endpoint bound for a cloud runtime, LiteLLM, vLLM, or SGLang. llama.cpp discovery reads `total_slots` from the router's `/props`, falls back to the selected worker's `/props?model=<id>` when the router reports none, and falls back again to the `--parallel` argv on the selected `/v1/models` entry. LM Studio reads `config.parallel` off the loaded instance and otherwise reports one; Ollama reads `OLLAMA_NUM_PARALLEL` from the environment the Clio process can see and otherwise reports one.
+Set it only when discovery is wrong. Clio resolves the limit in this order:
+
+1. this override;
+2. a `parallelSlots` count cached on the target's probe result;
+3. a persisted discovery result that is still fresh and matches the runtime;
+4. one slot for any other `local-native` runtime;
+5. no invented endpoint bound at all for a cloud runtime, LiteLLM, vLLM, or SGLang.
+
+Per-runtime discovery differs. llama.cpp reads `total_slots` from the router's `/props`, falls back to the selected worker's `/props?model=<id>` when the router reports none, and falls back again to the `--parallel` argv on the selected `/v1/models` entry. LM Studio reads `config.parallel` off the loaded instance and otherwise reports one.
+
+Ollama exposes no native API slot count, so Clio conservatively reports one. Set `maxConcurrentRequests` explicitly when the daemon supports more; the client process’s `OLLAMA_NUM_PARALLEL` does not describe the server.
 
 The limit is keyed on the endpoint rather than the target, so two targets pointed at the same normalized URL share it. Raising it above what the server will actually serve does not create capacity; it removes the refusal that would have told you the server was full. See [capacity-and-scheduling.md](../architecture/capacity-and-scheduling.md) for the admission model and the exact denial text.
 
 ### The `local-native` tier
 
-Three behaviors in this release are gated on a runtime's tier being `local-native` rather than on a target id or a server name, so it is worth stating what the tier is. It is a property of the runtime descriptor (`RuntimeTier` in `src/domains/providers/types/runtime-descriptor.ts`), and the runtimes that carry it are `llamacpp` with its completion, embedding, rerank, and Anthropic-surface variants, `lmstudio`, `ollama-native`, `vllm`, `sglang`, and the two `lemonade` surfaces. Everything else is `cloud`, `protocol`, or `subscription`.
+Three behaviors in this release are gated on a runtime's tier being `local-native` rather than on a target id or a server name, so it is worth stating what the tier is. It is a property of the runtime descriptor (`RuntimeTier` in `src/domains/providers/types/runtime-descriptor.ts`), and the runtimes that carry it are `llamacpp` with its completion, embedding, rerank, and Anthropic-surface variants, `lmstudio`, `ollama`, `vllm`, `sglang`, and the two `lemonade` surfaces. Everything else is `cloud`, `protocol`, or `subscription`.
 
 The tier means "an inference server the operator runs, whose prefix cache and resident model Clio's own behavior can displace." That is what the three gates are actually asking:
 
-- **Pre-warm** requires `chat.prewarm: true` and a verified, loaded and idle native deployment binding. The first supported path is the pinned llama.cpp deployment described below. Other native runtimes, unknown gateway routes and paid routes remain passive. Checks run before preparation and again before the request; a runtime tier alone grants no load or eviction authority.
+- **Pre-warm** requires `chat.prewarm: true` and a verified deployment binding. Pinned llama.cpp deployments require a loaded, idle server. Local LM Studio deployments require an additional `cache.warm.startup: true` opt-in and verified residency/capacity, including when reached through LiteLLM. Unknown gateway routes and paid routes remain passive. Checks run before preparation and again before the request; a runtime tier alone grants no load or eviction authority.
 - **Endpoint capacity** defaults to one slot here when discovery reports nothing, and to unbounded elsewhere. vLLM and SGLang are the deliberate exceptions inside the tier: both serve genuinely concurrent requests, so an undiscovered limit is left unbounded rather than guessed at one.
 - **Five of the eight expected-cold reasons** are stamped only here, because a single-slot local cache is the only one an interleaved run actually displaces. The other three moved the prompt bytes themselves and are stamped on every tier. The full split is in [context-engine.md](../architecture/context-engine.md#cache-divergence-honesty).
 
 The tool-prose-loop detector is keyed on the same tier, for the same reason: narrating a tool call instead of emitting one is a behavior of open-weight models served locally, and a list of server names would have left an Ollama or vLLM run with no cutoff at all.
 
+### Startup preparation
+
+The terminal paints the welcome and accepts input before session initialization finishes. Submitted text waits for the normal safety, tools, and session setup. Routine initialization stays silent; failures remain visible. Opening a home, system, or shared root folder requires confirmation before project settings load. This confirmation applies to that launch and does not grant trust to project settings or hooks.
+
+After the interactive frame commits and the session is idle, Clio prepares connections for up to four distinct local worker endpoints from the fleet default, profiles, and rosters. These are passive metadata requests, made sequentially with a 1.5-second timeout each. Cloud endpoints, remote-node profiles, and the main agent's endpoint are excluded. Headless commands and worker processes never run this interactive preparation. Node's compile cache is published while the parent is alive so worker processes can reuse it before the parent exits.
+
+For an already loaded local worker model with a verified `cache.deployment` binding, opt into one tiny inference warm-up per endpoint per launch:
+
+```yaml
+# Inside the worker target's existing cache configuration:
+cache:
+  # Keep the verified deployment binding here.
+  warm:
+    startup: true
+```
+
+`startup` defaults to false. The optional request has no system prompt, history, or tools, allows one output token, and is capped at 256 estimated input tokens and two seconds. Lower `maxInputTokens` or `maxDurationMs` bounds are honored. Paid routes, busy endpoints, and unknown or unsupported deployments remain ineligible. Usage is recorded under `prewarm`, including unknown usage when a request fails. This warms the serving path; it does not claim to cache a future worker's task-specific prompt. Server-side cancellation is backend-dependent, so even a bounded client request can briefly contend with a worker dispatched afterward.
+
+### Local LM Studio warming through LiteLLM
+
+Bind the target to one local deployment; Clio checks the gateway's authenticated route inventory before warming. Model requests remain opt-in:
+
+```yaml
+# Inside the existing target (runtime: litellm):
+cache:
+  deployment:
+    backend: lmstudio
+    controlUrl: http://192.168.1.20:1234
+    model: my-local-model
+    gatewayDeploymentId: deployment-id-from-litellm
+  warm:
+    startup: true
+    maxInputTokens: 20000
+    maxDurationMs: 30000
+    cooldownMs: 60000
+```
+
+The main agent also requires `chat.prewarm: true`. After a one-second startup delay, warming stands down for an editor draft, active turn, or dispatch. If the verified local model is absent, an opted-in tiny request may wake it. Once resident, Clio requires at least two configured LM Studio parallel slots before sending its actual instruction/tool prefix with one output token. The input budget includes tools; the default 8192-token limit may be too small for a full Clio prompt. Warm requests disable LiteLLM retries and fallbacks. Direct `runtime: lmstudio` targets use the same binding without `gatewayDeploymentId`.
+
+LM Studio does not expose an idle-slot API. Configured parallelism and Clio's endpoint leases reduce contention but cannot detect all external traffic or guarantee immediate foreground service. Submitting detaches an already-running warm; it does not await it, and server-side loading/prefill may still finish. Warm-up never gates the welcome or hydration. Headless runs and worker processes do not schedule main-session warming. The interactive worker preparation described above may warm separately configured local bindings, but never the main deployment, including aliases that share its bound endpoint.
+
+Results and skip reasons are written silently to `$XDG_STATE_HOME/clio-coder/startup/YYYY-MM-DD.jsonl` (normally `~/.local/state/clio-coder/startup/`), including before a session exists. Usage remains attributed to `prewarm`. A missing provider cache-read count is displayed as unknown, not a cold-cache claim. Old session records retain their original recorded verdicts.
+
+### Ollama runtime id
+
+The canonical runtime id is `ollama`. The former `ollama-native` id remains an accepted alias scheduled for removal in v0.7.0. `--runtime ollama-native` still resolves and prints one deprecation warning naming `ollama`, a `settings.yaml` that still names `ollama-native` keeps loading unchanged, and `clio-coder upgrade` rewrites persisted targets to the canonical id. An unknown runtime id in `configure --runtime` or `targets convert --runtime` names the closest registered id when one is near.
+
+### Ollama context window (`ollama.numCtx`)
+
+An `ollama` target sends no `num_ctx` by default, so Ollama opens the model at whatever window its server is configured for (`OLLAMA_CONTEXT_LENGTH`, a `num_ctx` in the Modelfile, or the server default). Clio reads that window back from `/api/ps` once the model is resident and plans against it. Before the model is resident, Clio plans against the smaller of the model maximum and 131,072 tokens. To ask for a specific window instead, set it on the target:
+
+```yaml
+targets:
+  - id: local-ollama
+    runtime: ollama
+    url: http://127.0.0.1:11434
+    defaultModel: qwen3:30b-a3b-instruct-2507-q4_K_M
+    ollama:
+      numCtx: 65536
+```
+
+`numCtx` is a positive integer. When it is set, every chat request carries `options.num_ctx`, and Clio plans against that number capped by the model maximum from `/api/show` and by any smaller `capabilities.contextWindow`. `clio-coder targets --probe` then prints `ctx 65536 (num_ctx; serving 32768; model max 262144)` until the first request reloads the model.
+
+Ollama reloads a model whenever a request asks for a `num_ctx` different from the one it is loaded at. On a server other clients share, that reload evicts the window they opened it at, and the next request from them reloads it back, so two clients with different windows will thrash the model. Leave `numCtx` unset on a shared server and raise `OLLAMA_CONTEXT_LENGTH` there instead.
+
+### Ollama residency and release on exit
+
+Requests for managed Ollama loads that Clio can own and release send `keep_alive: -1` to keep them warm between turns. Pre-existing, user-managed, and otherwise unowned models retain the server’s normal keep-alive policy; a failed preflight does not grant pinning authority. Ollama places and fits models itself, so Clio never unloads a model it did not load: models the operator or another client loaded, and models that were already resident when Clio first used them, stay loaded. When an interactive session switches models, Clio releases the model it loaded earlier before the next turn.
+
+When the process exits, Clio sends `keep_alive: 0` for each model this process loaded and pinned, so a finished `clio-coder run` does not hold its weights after it ends. A model counts as loaded by Clio when it was absent from `/api/ps` before Clio's first request for it and that request then answered. The release runs on every coordinated exit: a headless run that completes or fails, `run --timeout` (exit 124), SIGINT, SIGTERM, interactive quit, and a `clio-coder acp` session whose client closes the connection. It is bounded at two seconds, and a server that is unreachable or slow leaves the model loaded without changing the exit code. A target with `lifecycle: user-managed` is observe-only, so nothing is released there.
+
+Dispatched workers do not release on their own exit, because the next sequential dispatch would reload the model and a parallel sibling would lose it mid-turn. When a worker's request loads a model, the worker reports the target and model ids to the orchestrator over its control lane, and the orchestrator releases that model when it exits. Until then the model stays warm for later dispatches, and no chat or dispatch in the same session evicts it. The orchestrator reaches the server through its own settings for that target. A worker on a fleet node whose target URL is a loopback address loaded the model on that node, which the orchestrator cannot reach, so that model is not released. Fleet nodes observe residency by default and report nothing unless the node sets `residency: manage`.
+
+A process that crashes or is killed with SIGKILL releases nothing, and its models stay pinned until something unloads them, for example `ollama stop <model>`. A model whose first request never answered, such as a load that failed or was interrupted before the first response, is not recorded as Clio's and is not released either.
+
 ### LM Studio transport and settings
 
 The canonical runtime id is `lmstudio`. The former `lmstudio-native` id remains an accepted alias scheduled for removal in v0.7.0,
@@ -416,8 +623,12 @@ use the native REST API, with `GET /api/v1/models` as the preferred catalog
 Leave `lmstudio.load` absent to preserve LM Studio's just-in-time loading behavior. Clio then observes
 residency but sends no explicit load request. When `lmstudio.load` is present and the selected model
 is unloaded, Clio calls `POST /api/v1/models/load` with `echo_load_config: true`; LM Studio documents
-the load operation at <https://lmstudio.ai/docs/developer/rest/load>. Clio sends only fields that the
-target explicitly configured:
+the load operation at <https://lmstudio.ai/docs/developer/rest/load>.
+
+<details>
+<summary>Which settings key maps to which LM Studio load and chat field</summary>
+
+Clio sends only fields that the target explicitly configured:
 
 | Settings key | REST load field |
 | --- | --- |
@@ -427,6 +638,16 @@ target explicitly configured:
 | `numExperts` | `num_experts` |
 | `offloadKvCacheToGpu` | `offload_kv_cache_to_gpu` |
 
+The request settings map as follows:
+
+| Settings key | Chat request behavior |
+| --- | --- |
+| `ttlSeconds` | Sends `ttl`, using LM Studio's auto-eviction TTL (<https://lmstudio.ai/docs/developer/core/ttl-and-auto-evict>). |
+| `draftModel` | Sends `draft_model` on the OpenAI-compatible chat request (<https://lmstudio.ai/docs/developer/openai-compat/chat-completions>). |
+| `reasoning` | `off` sends `reasoning_effort: none`; `on` sends `low`; a literal `low`, `medium`, or `high` outranks the thinking dial but is still clamped to the efforts the model advertises (a model reporting only `[off, on]` receives `low`); `auto` maps the active Clio thinking level. |
+
+</details>
+
 Loaded instances are addressed by their instance ids when Clio calls
 `POST /api/v1/models/unload` (<https://lmstudio.ai/docs/developer/rest/unload>). Clio records the
 instance id returned by each successful load in this process and refuses to unload every other
@@ -436,14 +657,6 @@ the model key or one of its loaded instance ids. The probe reports both forms an
 instance's echoed load configuration from the native model listing
 (<https://lmstudio.ai/docs/developer/rest/list>).
 
-The request settings map as follows:
-
-| Settings key | Chat request behavior |
-| --- | --- |
-| `ttlSeconds` | Sends `ttl`, using LM Studio's auto-eviction TTL (<https://lmstudio.ai/docs/developer/core/ttl-and-auto-evict>). |
-| `draftModel` | Sends `draft_model` on the OpenAI-compatible chat request (<https://lmstudio.ai/docs/developer/openai-compat/chat-completions>). |
-| `reasoning` | `off` sends `reasoning_effort: none`; `on` sends `low`; a literal `low`, `medium`, or `high` outranks the thinking dial but is still clamped to the efforts the model advertises (a model reporting only `[off, on]` receives `low`); `auto` maps the active Clio thinking level. |
-
 Clio maps the active thinking level through the model family's runtime resolver map. If the model family specifies an explicit effort map (such as mapping `max` to `xhigh`), Clio sends that exact effort; otherwise it falls back to the default `off` to `none`, `minimal`/`low` to `low`, `medium` to `medium`, and `high`/`xhigh`/`max` to `high`. For model families that declare a `none` or `always-on` reasoning mechanism, the `reasoning_effort` field is omitted. A model reporting only `[off,on]` clamps every
 non-off level to `low`. Clio uses only `reasoning_effort` on LM Studio's documented chat surface
 (<https://lmstudio.ai/docs/developer/openai-compat/chat-completions>) and never sends
@@ -458,7 +671,12 @@ LM Studio can require bearer authentication for its HTTP APIs
 
 A model id on an LM Studio target is resolved against that host's loaded instances. A key with a loaded instance is never sent bare (which would JIT-load a second copy). An instance id reported loaded by two configured LM Studio targets on different hosts is an LM Link peer projection. When a bare model key is requested and multiple instances of it are loaded, Clio selects an instance in this order: the target's configured `defaultModel`, then an instance not cross-listed by another configured LM Studio target, and finally the first loaded instance. This behavior tracks issue #113.
 
-When the selected instance is also loaded on a peer, a request may be answered by that peer (#185). Clio separates the requested model id, the response observation, and the model id used for accounting. Every new assistant ledger entry carries `responseModelIdObservation` in one of these explicit shapes:
+When the selected instance is also loaded on a peer, a request may be answered by that peer (#185). Clio separates the requested model id, the response observation, and the model id used for accounting.
+
+<details>
+<summary>The four `responseModelIdObservation` states and what each attributes cost to</summary>
+
+Every new assistant ledger entry carries `responseModelIdObservation` in one of these explicit shapes:
 
 | State | Meaning | Accounting attribution |
 | --- | --- | --- |
@@ -467,8 +685,14 @@ When the selected instance is also loaded on a peer, a request may be answered b
 | `{ "state": "not-observed" }` | This provider path did not expose response model-id presence to the stream tap. | A differing `responseModel` when available, otherwise the requested model id. |
 | `{ "state": "legacy-difference-only", "differingModelId": "<id>" }` or the same shape with `null` | The ledger predates #193 and recorded only whether the response `model` differed from the request. This state is produced while reading historical rows; new rows do not write it. | The historical differing id when available, otherwise the requested model id. |
 
-The adapter retains `responseModel` as the differing response id because providers outside the stream tap still supply that fact. `clio-coder usage report` emits `attributedModelId`, `requestedModelIds`, and `responseModelIdObservationCounts`. Its text table and the `/cost` overlay use the labels `attributed model`, `requested model ids`, and `response model id observation`; requested ids are printed as ids rather than as `same`. The footer's last-turn line uses `response model id observation <state>`, with the id after `reported` or a historical `legacy difference-only` state. Dispatch receipt `upstreamResponses` entries carry `requestedModelId`, `responseModelIdObservation`, `differingResponseModelId`, and `providerResponseId`. The peer warning is said once per process per distinct fact (target, requested id, resolved instance, peer set), not once per turn.
+</details>
+
+The adapter retains `responseModel` as the differing response id because providers outside the stream tap still supply that fact. `clio-coder usage report` emits `attributedModelId`, `requestedModelIds`, and `responseModelIdObservationCounts`. Its text table and the `/cost` overlay use the labels `attributed model`, `requested model ids`, and `response model id observation`; requested ids are printed as ids rather than as `same`.
 
+The footer's last-turn line uses `response model id observation <state>`, with the id after `reported` or a historical `legacy difference-only` state. Dispatch receipt `upstreamResponses` entries carry `requestedModelId`, `responseModelIdObservation`, `differingResponseModelId`, and `providerResponseId`. The peer warning is said once per process per distinct fact (target, requested id, resolved instance, peer set), not once per turn.
+
+
+### What LM Studio owns rather than Clio
 
 Prompt-template overrides, system prompts, GPU-offload ratios, KV-cache quantization, parallel slots,
 context checkpoints, and speculative-decoding variants are not writable through this Clio settings
@@ -478,6 +702,8 @@ block. Set them in LM Studio's My Models load settings or with `lms load`; the C
 configuration that `GET /api/v1/models` exposes instead of pretending it applied settings the REST
 load endpoint did not accept (<https://lmstudio.ai/docs/developer/rest/list>).
 
+### Output, tool-result, and retry budgets
+
 `chat.maxOutputTokens` is a global output budget requested for every turn. Its
 default `0` uses each model's known maximum-output cap, still clamped to the
 remaining context window. Models with no known cap use a 32,768-token ceiling
@@ -511,7 +737,10 @@ The `fleet.permissions.escalation` block defines parameters for escalation:
 - `fallback` (default `deny`): The fallback posture (`deny` or `fail`) applied upon timeout.
 
 `fleet.retry.routeCooldownMs` is the cooldown between retries on a failed
-route.
+route. `fleet.retry.breakerThreshold` is how many consecutive target failures
+open the route; after the cooldown one probe run tests it, and each failed
+probe doubles the cooldown up to five minutes. See
+[fleet-dispatch.md](fleet-dispatch.md#assignments-attempts-and-failover).
 
 `fleet.adaptiveRouting` controls the two independent activation boundaries for
 measured dispatch. Joint target/model/runtime/node selection becomes active
@@ -525,20 +754,25 @@ Agent automation is separately shadowed. Each
 `{agentId, executionRole}` pair. An `agent: auto` request may change agents only
 for a listed pair whose readiness report passes.
 
-Version 2 places numeric backstops beside the behavior they govern.
-`safety.limits.chatToolCallsPerTurn` (default `60`) is the main-agent soft
-tool-call budget; the hard interrupt ceiling remains 15 calls above it.
-`fleet.limits.toolCallsPerRun` (default `150`) is the independent lifetime cap
-for one worker and can only narrow a recipe budget. `fleet.history.maxRuns`
-(default `1000`) bounds durable dispatch history.
-`safety.limits.readBytesPerCall` (default `51200`) bounds one read, while
-`safety.limits.observationBytesPerTurn` (default `196608`) is the shared
-per-turn observation pool. `fleet.limits.internalRunTimeoutMs` (default
-`900000`) bounds an internal generator dispatch. These settings are the only
-operator-facing policy paths for the limits and refresh with the effective
-session view.
-
-Agent recipe budgets define a normal admitted-call phase inside `workerToolCallCap`; they do not replace it. A declared phase boundary is clamped down to the cap, and when the two are equal the last call may complete and the graceful synthesis transition happens without requiring an over-cap call. The recipe's `readReserve` is the tail of that phase. It admits canonical `read` plus whatever mutation tools the agent was actually granted, because the reserve exists to end broad discovery rather than to stop an agent from delivering: a writer whose product is files has to be able to write them in its last calls. An agent with no mutation tools keeps a read-only reserve and the request-level `require_tool(read)` lock. The reserve becomes zero when `read` is absent from the admitted schema surface, and never installs a nonexistent read requirement. Calls the reserve refuses are steering rather than work: they neither run nor spend the cap, and a model that keeps calling discovery tools there reaches the same bounded synthesis lockout a spent budget ends in.
+Version 2 places numeric backstops beside the behavior they govern:
+
+| Key | Default | What it bounds |
+| --- | --- | --- |
+| `safety.limits.chatToolCallsPerTurn` | `60` | The main agent's soft tool-call budget. The hard interrupt ceiling stays 15 calls above it. |
+| `fleet.limits.toolCallsPerRun` | `150` | One worker's independent lifetime cap. It can only narrow a recipe budget. |
+| `fleet.limits.internalRunTimeoutMs` | `900000` | One internal generator dispatch. |
+| `fleet.history.maxRuns` | `1000` | Durable dispatch history. |
+| `safety.limits.readBytesPerCall` | `51200` | One read. |
+| `safety.limits.observationBytesPerTurn` | `196608` | The shared per-turn observation pool. |
+
+These are the only operator-facing policy paths for those limits, and they
+refresh with the effective session view.
+
+Agent recipe budgets define a normal admitted-call phase inside `workerToolCallCap`; they do not replace it. A declared phase boundary is clamped down to the cap, and when the two are equal the last call may complete and the graceful synthesis transition happens without requiring an over-cap call.
+
+The recipe's `readReserve` is the tail of that phase. It admits canonical `read` plus whatever mutation tools the agent was actually granted, because the reserve exists to end broad discovery rather than to stop an agent from delivering: a writer whose product is files has to be able to write them in its last calls. An agent with no mutation tools keeps a read-only reserve and the request-level `require_tool(read)` lock.
+
+The reserve becomes zero when `read` is absent from the admitted schema surface, and never installs a nonexistent read requirement. Calls the reserve refuses are steering rather than work: they neither run nor spend the cap, and a model that keeps calling discovery tools there reaches the same bounded synthesis lockout a spent budget ends in.
 
 ### Local model co-residency and scouts
 
@@ -553,8 +787,13 @@ slower even though the target still responds.
 For llama.cpp router targets, Clio observes `/v1/models` and `/props`. It can
 tell which models are loaded and whether the resident count is within the
 router's `max_instances`, so an allowed two-model setup is reported as an
-informational co-residency notice. A model reporting a `sleeping` state counts as resident, because the router wakes it on the next inference request. Clio's residency manager never evicts a resident model when the requested replacement model is not in the router's catalog. The router response does not expose free
-VRAM or per-model loaded footprint, so Clio cannot prove the loaded set fits.
+informational co-residency notice. A model reporting a `sleeping` state counts
+as resident, because the router wakes it on the next inference request, and
+Clio's residency manager never evicts a resident model when the requested
+replacement is not in the router's catalog.
+
+The router response does not expose free VRAM or per-model loaded footprint, so
+Clio cannot prove the loaded set fits.
 Use host tools such as `nvidia-smi`, `rocm-smi`, Vulkan memory telemetry, or
 the runtime's own dashboard to confirm headroom after loading the main coding
 model and the scout model. Lower `--ctx-size`, KV cache precision, parallel
@@ -591,11 +830,16 @@ at CPU speed instead of failing.
   role and describe co-residency without claiming that an operator-owned model
   can be evicted.
 
-A turn whose token rate collapses below 2 tokens per second for 30 seconds
-surfaces a `degraded` notice listing what is resident on the target. That is
-what a spill to CPU looks like from outside, and it is reported while the turn
-is still running rather than left as an indefinite spinner. The notice never
-cancels the turn.
+On Ollama, llama.cpp, and LM Studio targets, a turn whose output plus
+reasoning token rate is still below 2 tokens per second 30 seconds after the
+server starts answering surfaces one `degraded` warning for that turn. It names
+the elapsed time, the token count, the rate, and the models resident on the
+target at that moment, with the GPU share of each model when Ollama reports it.
+That is what a spill to CPU looks like from outside, and it is reported while
+the turn is still running rather than left as an indefinite spinner. The notice
+never cancels the turn, and a turn aborted before the check emits none.
+Interactive sessions show it as a notice, and headless runs and workers write
+it to stderr.
 
 
 ---
@@ -612,6 +856,11 @@ install metadata, and records fleet preflight results. It validates
 `settings.yaml` directly against the current schema but never rewrites removed
 keys or migrates an old settings shape. Any unknown or retired key remains a
 validation error on that doctor run.
+
+Doctor reports no dispatch breaker state, because the breaker lives in the
+memory of the session that dispatches and a doctor process never dispatches. See
+the targets rows in `/settings` inside the session instead.
+
 Registered `clio-coder upgrade` migrations are the narrow exception. Upgrade
 moves a version-1 or unversioned settings document into the version-2 areas,
 records the migration, and keeps the byte-exact original as
@@ -736,9 +985,11 @@ This is the version-2 durable schema shipped in `DEFAULT_SETTINGS`. Validation i
 | `fleet.permissions.mode` | `deny` | `deny`, `fail`, `escalate` | next dispatch |
 | `fleet.permissions.escalation.timeoutMs` | `120000` | integer ≥ 1 | next dispatch |
 | `fleet.permissions.escalation.fallback` | `deny` | `deny` or `fail` | next dispatch |
-| `fleet.concurrency` | `1` | `auto` or integer ≥ 1 | restart |
+| `fleet.concurrency` | `auto` | `auto` or integer ≥ 1 | restart |
 | `fleet.retry.maxRetries` | `2` | integer ≥ 0 | next dispatch |
 | `fleet.retry.routeCooldownMs` | `15000` | integer ≥ 0 | next dispatch |
+| `fleet.retry.breakerThreshold` | `1` | integer ≥ 1 | next dispatch |
+| `fleet.worktrees.root` | `disk` | `disk`, `tmpfs`, `auto`, or an absolute path | next dispatch |
 | `fleet.limits.toolCallsPerRun` | `150` | integer ≥ 1 | next dispatch |
 | `fleet.limits.internalRunTimeoutMs` | `900000` | integer ≥ 1 | next dispatch |
 | `fleet.history.maxRuns` | `1000` | integer ≥ 1 | next dispatch |
@@ -766,7 +1017,9 @@ This is the version-2 durable schema shipped in `DEFAULT_SETTINGS`. Validation i
 | `context.memory.maxOutputTokens` | `2000` | integer ≥ 1 | next turn |
 | `context.memory.timeoutMs` | `60000` | integer ≥ 1 | next turn |
 
-The compaction and memory controls serve different roles. An unset `context.compaction.model` uses active chat; an explicit model must uniquely resolve to an available eligible summary route or fail visibly. `context.compaction.systemPrompt` is a nonempty UTF-8 prompt file, at most 65,536 bytes, read at compaction time and resolved relative to the session workspace. Configure `context.memory.target` and `context.memory.model` to opt into model-based memory; unset roles remain rules-only. Memory prefers its dedicated route and can use active chat when that route is unavailable and request capacity permits. Known dedicated saturation skips the step rather than initiating failover; neither routing choice edits saved settings.
+The compaction and memory controls serve different roles. An unset `context.compaction.model` uses active chat; an explicit model must uniquely resolve to an available eligible summary route or fail visibly. `context.compaction.systemPrompt` is a nonempty UTF-8 prompt file, at most 65,536 bytes, read at compaction time and resolved relative to the session workspace.
+
+Configure `context.memory.target` and `context.memory.model` to opt into model-based memory; unset roles remain rules-only. Memory prefers its dedicated route and can use active chat when that route is unavailable and request capacity permits. Known dedicated saturation skips the step rather than initiating failover; neither routing choice edits saved settings.
 
 ### Safety
 
@@ -788,6 +1041,7 @@ The safety-limit leaves have no one-process `CLIO_CODER_*` overrides in the curr
 | Key | Default | Validation | When it applies |
 | --- | --- | --- | --- |
 | `interface.terminalProgress` | `false` | boolean | next turn |
+| `interface.demo` | `true` | Project-work capability guidance and contextual footer tips; `--demo` / `--no-demo` override one interactive session | tips immediately; persona next turn |
 | `interface.outputDetail` | `standard` | `compact`, `standard`, `detailed` | immediately |
 | `interface.mode` | `regular` | `regular` or `fullscreen` | restart |
 | `interface.fullscreenScrollbar` | `auto` | `hidden`, `auto`, `always` | restart |
@@ -981,6 +1235,20 @@ integrations:
 ```
 Then invoke it using `/delegate claude-code <task>`.
 
+`/delegate [--share] <agent-id> <task>` does not accept `--model` in v0.5.0.
+`/run --model <id>` selects a model for a Clio fleet worker; it does not configure
+an external ACP session. External model selection depends on the adapter's own
+supported configuration. Clio does not currently expose an ACP model selector.
+
+Antigravity's `antigravity-code` runtime is a separate subprocess integration;
+detection of the `agy` executable does not register an ACP delegation recipe.
+An ACP integration needs a verified ACP entry point or adapter, not merely a
+CLI that supports stream-JSON output. This describes Clio's current integration;
+it does not establish that every Antigravity version or third-party adapter lacks ACP.
+The `world-knowledge` shadow agent remains internal-dispatch-only, even when bound
+to an Antigravity target/profile: ask Clio to use it; do not invoke it with `/run`
+or `/delegate`.
+
 ### 5. Antigravity CLI — Experimental Local Delegation (Worker-Only)
 
 The `antigravity-code` runtime is a local external delegation agent. It lets Clio ask an official Antigravity CLI (`agy`) installed and authenticated by the operator for research, world knowledge, a second opinion, or a bounded subtask. It is deliberately **not** a Gemini chat provider and can never become the Clio orchestrator.
@@ -1047,7 +1315,7 @@ Useful flags:
 ## Target management
 
 ```bash
-clio-coder targets [--json] [--probe] [--target <id>]
+clio-coder targets [--json] [--probe [--reasoning] [--tools [--tools-timeout <seconds>]]] [--target <id>]
 clio-coder targets add [configure flags]
 clio-coder targets use <id> [--model <id>] [--orchestrator-model <id>] [--background-model <id>]
                       [--fleet-target <id>] [--fleet-model <id>]
@@ -1065,21 +1333,65 @@ clio-coder targets remove <id>
 clio-coder targets rename <old> <new>
 ```
 
+The `clio-coder targets` listing shows no breaker column, because the dispatch breaker lives in the memory of the session that dispatches and the listing process never dispatches. Inside a session, each `/settings` targets row shows its routes' breaker state: an open route takes over the health cell with its remaining cooldown (`○ open 42s`), a route whose probe is in flight shows `◐ probing`, and the row's detail line lists one phrase per route, such as `qwen open 42s after target-transient` or `coder 1 failure (target-overloaded)` for a closed route that has failed below the threshold.
+
+`clio-coder targets --probe` checks reachability and model metadata without
+requesting generation. Two optional flags add generating checks, which cost
+tokens and can load a cold model, so they run only when asked:
+
+| Flag | What it does | Timeout |
+| --- | --- | --- |
+| `--probe` | Reachability and model metadata. No generation. | 5s HTTP |
+| `--probe --reasoning` | Generating reasoning check. | Owned by the runtime descriptor's reasoning probe. |
+| `--probe --tools` | Generating tool-call check through the engine stream path. | 120s, set by `--tools-timeout <seconds>` |
+
+Declared capabilities alone are not live verification. Reasoning generation that
+produces no reasoning, errors, or times out is inconclusive. `--target <id>`
+probes one target; SDK and subprocess runtimes report as skipped because they do
+not stream through the engine.
+
+<details>
+<summary>What the tool probe sends, what counts as a pass, and what it leaves loaded</summary>
+
+`clio-coder targets --probe --tools` sends one small request with a single
+typed tool through the same engine stream path a chat turn uses, against the
+chat model when the target is the chat target and the target's default model
+otherwise. It never picks another model.
+
+The check passes only when the response streamed in more than one frame, carried
+a call to the probe tool, and the call's arguments parsed as JSON and matched the
+tool schema.
+
+The result appears in the notes column as `tools verified (<model>, <ms>)` or
+`tools failed (<model>): <reason>`, and as `toolProbe` in `--json`. A verified
+probe marks `tools` true for that model and runtime resolution then reports the
+provenance as `toolsVerification`; a failed probe adds a `tools-probe-failed`
+warning to the next turn or dispatch on that model. The result lives only in the
+running process.
+
+A model the probe loaded and pinned on a local server such as Ollama is released
+before the command returns, whether the probe passed, failed, or was cancelled. A
+model that was already resident before the probe is left loaded.
+
+</details>
+
 `clio-coder targets use <id>` sets the orchestrator target. It refuses any target whose runtime is not a registered HTTP/native runtime because the selected target must be valid for chat.
 
 Without `--fleet-target` the default fleet target follows the orchestrator, which is the single-node case. Pass `--fleet-target <id>` to keep them apart when one node orchestrates and another runs the fleet. The fleet target is validated for fleet dispatch through the same check a fleet profile uses, so it can be a worker-only runtime such as `claude-sdk`, `claude-code`, or `antigravity-code`. Its model defaults to that target's own default rather than the orchestrator's, because a model id resolved against one target means nothing on another; `--fleet-model <id>` names it explicitly. `clio-coder configure --set-fleet-default` and `clio-coder targets profile` remain the routes for per-agent fleet routing.
 
 ### Target-Profile Subcommands
 
-The command `clio-coder targets profile` supports several subcommands to manage fleet worker profiles and agent bindings:
+`clio-coder targets profile` manages fleet worker profiles and agent bindings:
 
-- **list**: Show configured fleet profiles. Use `clio-coder targets profile list [--json]` to output details in JSON format.
-- **set**: Create or update a named fleet profile. Use `clio-coder targets profile set <name> <id> [--model <id>] [--thinking <level>]`; the compatibility form `clio-coder targets profile <name> <id> ...` is also accepted.
-- **remove**: Remove a profile from settings. Use `clio-coder targets profile remove <name> [--force]`. The `--force` flag is required if the profile has active agent bindings.
-- **rename**: Rename a fleet profile. Use `clio-coder targets profile rename <old> <new>`. Active agent bindings are updated to point to the new profile name automatically.
-- **bind**: Bind an agent to a fleet profile. Use `clio-coder targets profile bind <agentId> <profileName>`. Active ACP delegation agents are rejected.
-- **unbind**: Unbind an agent from its profile. Use `clio-coder targets profile unbind <agentId>`.
-- **bindings**: List active agent-to-profile bindings. Use `clio-coder targets profile bindings [--json]` to output details in JSON format.
+| Command | Effect |
+| --- | --- |
+| `targets profile list [--json]` | Show configured fleet profiles. |
+| `targets profile set <name> <id> [--model <id>] [--thinking <level>]` | Create or update a named profile. The older `targets profile <name> <id> ...` form is still accepted. |
+| `targets profile remove <name> [--force]` | Remove a profile. `--force` is required when the profile has active agent bindings. |
+| `targets profile rename <old> <new>` | Rename a profile. Active bindings follow the new name automatically. |
+| `targets profile bind <agentId> <profileName>` | Bind a native agent to a profile. Active ACP delegation agents are rejected. |
+| `targets profile unbind <agentId>` | Remove an agent's binding. |
+| `targets profile bindings [--json]` | List active agent-to-profile bindings. |
 
 Inside the TUI, `/settings targets` opens the operational target console.
 Targets render with `HEALTH`, `ID`, `ROLES`, `RUNTIME`, and `LATENCY`, plus a
@@ -1097,12 +1409,31 @@ Target status resolution tracks provenance explicitly in `TargetStatus.contextWi
 
 When a probed target reports no context window, Clio uses the runtime descriptor default as an unverified guess. In `clio-coder targets` text output, this renders as `ctx <N> (unverified runtime default)`. In JSON output, `contextWindowProvenance` is set to `"runtime-default"`. During target creation via `clio-coder configure`, Clio emits a warning: `warning: the target reported no context window; Clio will use the runtime default as a guess. Set one with --context-window.`. This design ensures that a number the operator never chose and the server never claimed will not read like a verified capability.
 
+<details>
+<summary>How each runtime's probe resolves a window, and the Ollama cold-model cap</summary>
+
+`capabilities.contextWindow` declares an existing serving limit; it does not
+resize the server or override a smaller observed limit. One-run context limits
+likewise cap Clio’s planning budget, not the server’s allocation. Slot count does
+not establish independent context capacity: a server may share one KV pool across
+several concurrent requests. Confirm allocation semantics in the server before
+multiplying a context figure by its slot count.
+
+A runtime that reports the window a resident model is loaded at (LM Studio, and Ollama through `/api/ps`) bounds the session by that serving window, because a model open at 32,768 tokens rejects a longer prompt whatever its weights allow. The text output then names both numbers, as in `ctx 32768 (serving; model max 262144)`, so the operator can see which one a run is planned against. In JSON output the serving window is `discoveredModelStates.<model>.contextLength` and the maximum is `capabilities.contextWindow`.
+
+An `ollama` probe reads the model maximum from `/api/show` for the target's default model, using `model_info["<architecture>.context_length"]` capped by any `num_ctx` baked into the Modelfile. When `/api/tags` rows carry `details.context_length`, as newer Ollama releases do, those maxima are recorded for every listed model. Ollama 0.18 does not report it there. When no model is resident, Clio plans against the smaller of that maximum and 131,072 tokens, because Ollama opens a cold model at `OLLAMA_CONTEXT_LENGTH` or its server default and no API reports that window before load. The text output names both, as in `ctx 131072 (cold; model max 262144)`; a model whose maximum is below the cap shows its maximum alone. Once `/api/ps` reports the model loaded, its serving window replaces the cold figure. Set `ollama.numCtx` to plan against a window Clio requests rather than one it infers; it applies whether or not the model is resident.
+
+</details>
+
 ---
 
 ## Local Model Quirks
 
 Local models often require specific engine configurations to perform optimally. Clio parses local model quirks from catalog entries and applies them during target execution. Keep target inventory in `settings.yaml` (`wireModels`, `defaultModel`, URL/auth), and keep per-model semantics in catalog YAML. For local experiments, use `$CLIO_CODER_CONFIG_DIR/model-catalog.d` or `.clio-coder/model-catalog.d`; promote entries into the bundled source catalog only after the model family is verified for broader Clio use.
 
+<details>
+<summary>Every quirk field: KV-cache quantization, sampling, and thinking mechanisms</summary>
+
 ### 1. KV-Cache Quantization
 You can optimize the GPU memory usage of the key and value caches for local inference engines. Quirks parameters include:
 - `kQuant`: Quantization type for the key cache. Supported values are `f32`, `f16`, `q8_0`, `q4_0`, `q4_1`, `iq4_nl`, `q5_0`, and `q5_1`. Set to `false` to disable quantization and run in full precision.
@@ -1124,6 +1455,7 @@ Local models use different mechanisms to control and parse reasoning steps. The
 - `always-on`: The model emits chain-of-thought tokens unconditionally.
 - `none`: The model does not support thinking or reasoning states.
 
+</details>
 
 ### Local reasoning-token budgets
 
@@ -1176,7 +1508,7 @@ Representative built-in runtime IDs:
 | Protocol-compatible | `openai-compat`, `anthropic-compat` generic surfaces for additional OpenAI-compatible or Anthropic-compatible APIs, including APIs such as InceptionAI when configured with the appropriate base URL and credentials. |
 | Cloud | `alcf`, `anthropic`, `bedrock`, `deepseek`, `google`, `groq`, `mistral`, `openai`, `openrouter` |
 | Subscription and worker harnesses | `openai-codex` for ChatGPT OAuth, `anthropic-max` for Anthropic OAuth, `claude-sdk` for Claude Agent SDK workers, `claude-code` for `claude -p` subprocess workers, and `antigravity-code` for structured `agy` external delegation |
-| Local native | `llamacpp`, `lmstudio`, `ollama-native`, `vllm`, `sglang`, `lemonade`, `lemonade-anthropic` |
+| Local native | `llamacpp`, `lmstudio`, `ollama`, `vllm`, `sglang`, `lemonade`, `lemonade-anthropic` |
 
 Some hidden aliases exist for backward compatibility or special surfaces; use `clio-coder configure --list --all` to see them.
 
@@ -1251,7 +1583,7 @@ establish an actual hit. A compiler memoization hit or a forked transcript canno
 
 | Responsibility | Existing owner | Clio correction or limit |
 | --- | --- | --- |
-| Native request conversion, thinking history and cache controls | Pi 0.85.1 | Target retention reaches all instrumented native Pi APIs; explicit call options still win. |
+| Native request conversion, thinking history and cache controls | Pi 0.86.1 | Target retention reaches all instrumented native Pi APIs; explicit call options still win. |
 | Exclusive input/read/write buckets, cost tiers and one-hour write cost | Pi | Preserve the full catalog cost and per-call calculated total instead of flattening tiers or repricing an aggregate. |
 | Main, worker, failed/aborted and out-of-turn usage | Clio | Preserve optional `cacheWrite1h` as a subset of writes; retain billed failed calls. Missing provider usage remains unknown. |
 | Main and warm preparation | Pi public transforms and Clio payload hooks | Warm calls use the caller's transforms, ordered tools, thinking and payload replacement without executing tools or adding messages to history. |
@@ -1274,22 +1606,30 @@ own environment/default. Targets reload on the next turn, including when the
 id and model stay the same. The active conversation survives the runtime refresh.
 There are no duplicate model, recipe or fleet retention knobs.
 
+<details>
+<summary>Per-API cache retention policy and how each one was verified</summary>
+
 | API/deployment | Effective policy and current verification |
 | --- | --- |
 | Native OpenAI Responses, older supported models | Pi's model compatibility flags select `24h` for `long`. `none` omits controls; it does not universally disable automatic caching. Payload fixtures cover this path. |
 | Native OpenAI Responses, explicit-mode models | Pi selects `prompt_cache_options`; `none` requests explicit mode without breakpoints, and `long` selects `30m` TTL. Clio adds no extra breakpoints or weaker instruction roles. Payload fixtures cover this path. |
 | Native Anthropic Messages | Pi selects eligible short or one-hour cache-control blocks. `none` removes these controls. Real serializer/HTTP usage fixtures cover normalization and the one-hour subset. |
-| Direct llama.cpp | Normal calls retain `cache_prompt: true`; `retention: none` selects false. Optional warming requires the binding and evidence below. |
+| Direct llama.cpp | Normal calls retain `cache_prompt: true`; `retention: none` selects false. Clio sends no `id_slot`. Optional warming requires the binding and evidence below. Slot selection, idle-slot eviction and hybrid-model checkpoints are in the [self-hosted prefix-cache contract](../architecture/context-engine.md#self-hosted-prefix-cache-contract). |
 | LiteLLM/generic OpenAI compatibility | Passive provider usage is retained. Generic synthesis does not advertise OpenAI `24h` retention. A declared route alone does not prove native controls or timings survive translation. Gateway warming stays disabled. |
 | vLLM | Normal inference and passive provider usage continue. A declared build can be checked, but version alone proves neither APC enablement nor idle scheduler/memory capacity. Warming stays disabled; no fixed-slot model is imposed. |
 | Claude Agent SDK, subscription/OAuth and other harnesses | Harness-specific transport and usage remain intact. Native Pi controls and direct API prices are not promises about another harness. |
 | Gemini explicit cache objects, Bedrock/platform cache administration | No new object lifecycle or administration is added. Existing Pi/provider support remains responsible for supported passive observations and requests. |
 
+</details>
+
 For a direct llama.cpp **already loaded** worker at the audited commit, an
 operator can opt into a bounded pilot. Use the worker's actual `build_info`,
 exact model alias and endpoint; the values below are examples, not deployment
 measurements:
 
+<details>
+<summary>A pinned llama.cpp server configuration for reproducible prompt reuse</summary>
+
 ```yaml
 chat:
   prewarm: true
@@ -1311,6 +1651,14 @@ targets:
         cooldownMs: 60000
 ```
 
+</details>
+
+Warming only runs against a deployment Clio could inspect and bind, and every
+refusal is recorded rather than retried. The rules below are the whole gate.
+
+<details>
+<summary>Deployment discovery, gateway binding, warm bounds, and admission checks</summary>
+
 Discovery uses GET requests with a two-second total deadline and refuses
 redirects. The control endpoint receives no inferred credentials. An authenticated
 control endpoint therefore remains unavailable to this initial reader. For a
@@ -1331,9 +1679,12 @@ validated on the configured gateway. No gateway credentials are forwarded to
 native discovery.
 
 The warm owns one request and at most one newer pending trigger. Pending work
-expires after 30 seconds. The default bound is 8192 estimated input tokens and
-a 30-second client deadline, with a 60-second cooldown; configured deadlines
-cannot exceed two minutes. Context transforms run before the input estimate.
+expires after 30 seconds. The default bound is 8192 estimated input tokens
+(`cache.warm.maxInputTokens`) and a 30-second client deadline
+(`cache.warm.maxDurationMs`), with a 60-second cooldown; configured deadlines
+cannot exceed two minutes. The separate LM Studio startup wake that
+`cache.warm.startup` enables is not the exact-prefix warm and is clamped to 256
+input tokens regardless of the configured bound. Context transforms run before the input estimate.
 The one-token output and dummy suffix do not enter the conversation. The warm
 uses observe-only residency and `autoload=false` on native llama requests, so
 it cannot use the ordinary turn's implicit administrative authority.
@@ -1354,6 +1705,8 @@ as `deployment-unbound`, `model-not-loaded`, `deployment-build-mismatch`,
 `vllm-scheduler-unverified`, `cooldown` and `expired`. These records contain no
 prompt payloads. Diagnostic payload capture remains a separate explicit opt-in.
 
+</details>
+
 Turn off speculative work with `chat.prewarm: false`. Remove `cache.deployment`
 to return an individual target to passive operation. `cache.retention: none`
 selects the API's supported cache-off request policy and also refuses Clio
@@ -1367,11 +1720,17 @@ accounting, but the worker's context guard and payload hooks must be included
 in any future headless warm composition. There is no main-to-worker cache
 transfer based on ancestry.
 
+Automated warming is opt-in. The historical measurements below illustrate why
+faster first-token timing alone does not establish lower total work or cost.
+
+<details>
+<summary>The dated 2026-09-11 TTFT run these settings were validated against</summary>
+
 ### Validation status for this change
 
-Live validation on 2026-09-11 exercised mini's `ornith1.5-35b-moe` on
-llama.cpp (`b1-c841aee`) and dynamo's `qwen3.8-27b` on LM Studio, first directly
-and then through blade's LiteLLM 1.98.0. The selected models were allowed to
+Historical validation on 2026-09-11 exercised an example MoE model on llama.cpp
+(`b1-c841aee`) and a 27B model on LM Studio, first directly and then through an
+intermediate LiteLLM 1.98.0 gateway host. The selected models were allowed to
 wake/load for inference; no serving configuration or administrative API was
 changed. The same native models and thinking-off intent were retained.
 
@@ -1381,13 +1740,13 @@ exactly `OK`. Median client TTFT was:
 
 | Route | New prefix | Repeated prefix | After a separate warm |
 | --- | ---: | ---: | ---: |
-| Mini native | 1,691 ms | 183 ms | 163 ms |
-| Dynamo native | 1,255 ms | 156 ms | 155 ms |
-| Mini through LiteLLM | 1,706 ms | 196 ms | 173 ms |
-| Dynamo through LiteLLM | 1,259 ms | 163 ms | 162 ms |
+| llama.cpp (MoE) native | 1,691 ms | 183 ms | 163 ms |
+| LM Studio (27B) native | 1,255 ms | 156 ms | 155 ms |
+| llama.cpp through LiteLLM | 1,706 ms | 196 ms | 173 ms |
+| LM Studio through LiteLLM | 1,259 ms | 163 ms | 162 ms |
 
-Mini reported roughly 2,834 cached tokens directly and 2,837 through the
-gateway after warming. Dynamo's OpenAI-compatible responses did not expose a
+llama.cpp reported roughly 2,834 cached tokens directly and 2,837 through the
+gateway after warming. LM Studio's OpenAI-compatible responses did not expose a
 cache-read breakdown; their normalized zero must not be presented as measured
 cache misses. Its timing improvement is an observation, not a per-request
 cache-token measurement. Gateway response metadata identified the expected
@@ -1401,20 +1760,20 @@ reduction alone is not a total-work improvement. An idle-time or foreground
 contention benefit requires its own controlled measurement before rollout.
 
 Four full Clio main-agent CLI runs also completed with no tool calls and
-matching native/gateway outputs per model: mini returned `OK.`, dynamo `OK`.
-The punctuation means mini did not meet a literal exact-`OK` instruction in
+matching native/gateway outputs per model: llama.cpp returned `OK.`, LM Studio `OK`.
+The punctuation means llama.cpp did not meet a literal exact-`OK` instruction in
 those full-prompt smoke runs; it is not hidden by the transport success. The
 engine workload above enforced the exact output separately.
 
 Four custom-worker CLI runs then returned exactly `OK`, with zero tool calls
 and succeeded outcomes. Each emitted receipt matched its persisted receipt and
-passed Clio's integrity verifier against its persisted run envelope. The mini
+passed Clio's integrity verifier against its persisted run envelope. The llama.cpp
 worker through LiteLLM reported 719 cache-read tokens in that verified receipt.
 These checks establish transport and accounting continuity; the synthetic
 worker's task quality was not independently graded.
 
 The first exploratory driver omitted the public capability update that
-production applies after model synthesis. That made dynamo through LiteLLM
+production applies after model synthesis. That made LM Studio through LiteLLM
 spend its output budget on thinking. Those samples were preserved and marked
 invalid for semantic comparisons; the reported rerun includes the existing
 public update and checks visible output. This was a driver error, not a newly
@@ -1436,3 +1795,5 @@ The run does not establish replica affinity guarantees, eviction/TTL behavior,
 foreign-traffic fairness, paid-provider savings, or a complete deployment pin
 for every model binary/tokenizer. Those limits prevent a general performance
 claim or enabling automatic gateway/worker warming.
+
+</details>