@iowarp/clio-coder 0.4.9 → 0.5.0

package/docs/guide/configuration-reference.md

@@ -1,63 +1,98 @@
 # Configuration reference
 
-Every switch that changes what Clio Coder does, in one place: settings keys, environment variables, CLI flags, project files under `.clio-coder/`, recipe and prompt-fragment frontmatter, tool arguments the model can send, and model knowledge-base tags. The source of truth is `src/`; this page is the audited inventory of what current source reads and is maintained alongside the code. The narrative guide is [configuration-and-targets.md](configuration-and-targets.md); operator prose for each environment variable is in [environment-variables.md](environment-variables.md).
+Look up settings, environment variables, command flags, project files, and extension metadata. For first-time setup, start with the [configuration guide](configuration-and-targets.md). For environment-variable explanations, use the [environment guide](environment-variables.md).
+
+This reference is maintained against `src/`. Use the links below to jump directly to the surface you need; lookup tables stay expanded.
+
+| Looking for | Go to |
+| --- | --- |
+| A `settings.yaml` key | [Settings keys](#settings-keys) |
+| An environment override | [Environment variables](#environment-variables) |
+| A command option | [CLI flags](#cli-flags) |
+| Repository configuration | [Project files](#project-files) |
+| Agent or prompt metadata | [Agent recipes](#agent-recipe-frontmatter) · [Prompt fragments](#prompt-fragment-frontmatter) |
+| A model-callable argument | [Tool arguments](#tool-arguments) |
+| Model capability annotations | [Model knowledge-base tags](#model-knowledge-base-tags) |
 
 Precedence, where several surfaces set the same value: a one-run CLI flag beats a session override (`/settings`, `/model`, `/thinking`), which beats `.clio-coder/settings.local.yaml`, which beats `.clio-coder/settings.yaml`, which beats the user `settings.yaml`, which beats the compiled default. Entries whose order differs say so in their precedence column.
 
 
 ## Settings keys
 
-`settings.yaml` (user, project, and project-local) and the `/settings` overlay. Defaults come from `src/core/defaults.ts`.
+`settings.yaml` (user, project, and project-local) and the `/settings` overlay. Defaults come from `src/core/defaults.ts`. Configure and `/settings` share the
+same section and control catalog: Connections, Chat, Fleet, Context & Memory,
+Permissions & Limits, Appearance, Integrations, and Advanced. Configure's
+**All controls in this section** includes less common fields with typed validation;
+structured collections accept JSON. Connection inventory and trust confirmation
+use their dedicated flows. The model can read an allowlisted view of effective
+session settings with `context(scope="settings")`; it guides the operator to
+these controls and cannot write configuration through that tool.
+
 
+### Reading the precedence column
+
+**Session override → saved settings** means `/settings` **apply-this-session**, then `.clio-coder/settings.local.yaml`, then `.clio-coder/settings.yaml`, then user `settings.yaml`, then the compiled default. Rows with a different routing or command override spell it out. Blank cells make no additional precedence claim.
+
+### Chat settings
 
 | Name | Default | Controls | Precedence |
-|---|---|---|---|
-| `chat.maxOutputTokens` | `0` | Global output-token budget requested on every chat turn (integer >= 0, `0` means per-model caps only); clamped to the model's max-output cap and remaining context window, with the product's 32,768-token ceiling used when the model cap is unknown; applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
+| --- | --- | --- | --- |
+| `chat.maxOutputTokens` | `0` | Global output-token budget requested on every chat turn (integer >= 0, `0` means per-model caps only); clamped to the model's max-output cap and remaining context window, with the product's 32,768-token ceiling used when the model cap is unknown; applies next turn. | [Session override → saved settings](#reading-the-precedence-column) |
 | `chat.model` | `null` | Saved default chat model id (string or null); null with a target set rebases to that target's `defaultModel` at validation; applies next session. | `run --model` > session routing (`/model`, `/thinking`, configured model-cycle actions, `/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `chat.modelPicker.cycleSet` | `[]` | Exact `target` or `target/model` refs configured model-cycle keys cycle through (refs with an empty target part are dropped); session-owned routing state, immediate this session, saved default next session. | session routing (configured model-cycle actions, `/settings`) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `chat.modelPicker.favorites` | `[]` | Exact `target/model` refs pinned in the focused model picker; refs naming an unconfigured target are dropped at validation; applies immediately. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `chat.modelPicker.recentLimit` | `12` | How many recently selected `target/model` refs `recent-models.json` keeps (integer >= 1); applies immediately. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `chat.prewarm` | `false` | Whether the known prompt prefix is sent to a `local-native` server at session start, after resume, and after compaction to fill its prefix cache (boolean; no effect on other tiers, workers, headless); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `chat.retry.baseDelayMs` | `2000` | First backoff delay in ms for chat-loop retries, doubled per attempt up to `maxDelayMs` (integer >= 0); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `chat.retry.enabled` | `true` | Master switch for transient-provider retries in the interactive chat loop (boolean); dispatched workers use `fleet.retry.maxRetries` instead; applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `chat.retry.maxDelayMs` | `60000` | Ceiling in ms on the exponential backoff between chat-loop retries (integer >= 0); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `chat.retry.maxRetries` | `3` | Maximum retry attempts for one transient provider failure in the chat loop (integer >= 0); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `chat.retry.streamStallMs` | `180000` | Silence after a call's first token longer than this many ms is treated as a wedged backend and the turn is aborted and retried (integer >= 0, `0` disables the stall timer); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `chat.retry.firstTokenStallMs` | `600000` | Silence allowed between sending a model call and its first token. It replaces `streamStallMs` for that window only, because a local server that slept reloads the model and prefills cold before it emits anything; the larger of the two values applies (integer >= 0, `0` never aborts a call that has not started streaming); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
+| `chat.modelPicker.favorites` | `[]` | Exact `target/model` refs pinned in the focused model picker; refs naming an unconfigured target are dropped at validation; applies immediately. | [Session override → saved settings](#reading-the-precedence-column) |
+| `chat.modelPicker.recentLimit` | `12` | How many recently selected `target/model` refs `recent-models.json` keeps (integer >= 1); applies immediately. | [Session override → saved settings](#reading-the-precedence-column) |
+| `chat.prewarm` | `false` | Opt into bounded prompt-prefix warming on supported local-native servers or a verified LiteLLM → LM Studio deployment. Eligibility, capacity, retention, and deployment settings still apply; workers and headless runs do not warm. See [prompt pre-warm](../architecture/context-engine.md#prompt-pre-warm). | [Session override → saved settings](#reading-the-precedence-column) |
+| `chat.retry.baseDelayMs` | `2000` | First backoff delay in ms for chat-loop retries, doubled per attempt up to `maxDelayMs` (integer >= 0); applies next turn. | [Session override → saved settings](#reading-the-precedence-column) |
+| `chat.retry.enabled` | `true` | Master switch for transient-provider retries in the interactive chat loop (boolean); dispatched workers use `fleet.retry.maxRetries` instead; applies next turn. | [Session override → saved settings](#reading-the-precedence-column) |
+| `chat.retry.maxDelayMs` | `60000` | Ceiling in ms on the exponential backoff between chat-loop retries (integer >= 0); applies next turn. | [Session override → saved settings](#reading-the-precedence-column) |
+| `chat.retry.maxRetries` | `3` | Maximum retry attempts for one transient provider failure in the chat loop (integer >= 0); applies next turn. | [Session override → saved settings](#reading-the-precedence-column) |
+| `chat.retry.streamStallMs` | `180000` | Silence after a call's first token longer than this many ms is treated as a wedged backend and the turn is aborted and retried (integer >= 0, `0` disables the stall timer); applies next turn. | [Session override → saved settings](#reading-the-precedence-column) |
+| `chat.retry.firstTokenStallMs` | `600000` | Silence allowed between sending a model call and its first token. It replaces `streamStallMs` for that window only, because a local server that slept reloads the model and prefills cold before it emits anything; the larger of the two values applies (integer >= 0, `0` never aborts a call that has not started streaming); applies next turn. | [Session override → saved settings](#reading-the-precedence-column) |
 | `chat.target` | `null` | Saved default chat target id (configured id or null); a dangling id normalizes to null and clears `chat.model`; seeds session routing at launch, so applies next session. | `run --target` > session routing (`/model`, `/thinking`, configured model-cycle actions, `/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `chat.thinkingLevel` | `low` | Saved default reasoning effort for the chat model: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, clamped to what the model supports at request time; applies next session. | `run --thinking` > session routing (`/model`, `/thinking`, configured model-cycle actions, `/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `context.compaction.auto` | `true` | Master switch for the pre-request compaction trigger when context pressure crosses `threshold` (boolean); manual `/context compact` still works when off; applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
+
+### Context and memory settings
+
+| Name | Default | Controls | Precedence |
+| --- | --- | --- | --- |
+| `context.compaction.auto` | `true` | Master switch for the pre-request compaction trigger when context pressure crosses `threshold` (boolean); manual `/context compact` still works when off; applies next turn. | [Session override → saved settings](#reading-the-precedence-column) |
 | `context.compaction.model` |  | Optional model pattern (prefer exact `target/model`) resolved when compaction runs. Must uniquely match an available HTTP chat model; invalid, ambiguous, unavailable, and worker-only selections fail explicitly. Absent means the current chat route summarizes. |  |
 | `context.compaction.systemPrompt` |  | Optional UTF-8 prompt file read on every compaction to replace the built-in system prompt. Relative paths use the current session workspace (`cwd`); absolute paths are supported. Must be a nonempty regular file of at most 65,536 bytes; read failures are explicit. `/context compact` focus instructions remain separate. |  |
-| `context.compaction.threshold` | `0.8` | Context pressure (estimated tokens over the context window, 0 through 1) at which eviction and then LLM summary compaction run; applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `context.toolResultMaxBytes` | `65536` | Maximum bytes returned from one tool result before the complete text spills to the session scratch file (integer >= 4096); applies to the next tool result. The unchanged `safety.limits.observationBytesPerTurn` default is 196608 bytes, so three full-size results consume the shared pool and a fourth finds it filled. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `context.memory.cadenceToolCalls` | `10` | Tool calls between proactive memory interventions inside a turn (integer >= 2); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `context.memory.enabled` | `true` | Master switch for proactive memory intervention during a turn (boolean); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `context.memory.maxOutputTokens` | `2000` | Output-token cap for one memory model call (integer >= 1); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
+| `context.compaction.threshold` | `0.8` | Context pressure (budgeted tokens over the effective window, 0 through 1) that triggers automatic eviction and, if still needed, summary compaction. Budgeting uses a trusted provider anchor when available with a structural-estimate floor; applies next turn. | [Session override → saved settings](#reading-the-precedence-column) |
+| `context.toolResultMaxBytes` | `65536` | Maximum bytes returned from one tool result before the complete text spills to the session scratch file (integer >= 4096); applies to the next tool result. The unchanged `safety.limits.observationBytesPerTurn` default is 196608 bytes, so three full-size results consume the shared pool and a fourth finds it filled. | [Session override → saved settings](#reading-the-precedence-column) |
+| `context.memory.cadenceToolCalls` | `10` | Tool calls between proactive memory interventions inside a turn (integer >= 2); applies next turn. | [Session override → saved settings](#reading-the-precedence-column) |
+| `context.memory.enabled` | `true` | Master switch for proactive memory intervention during a turn (boolean); applies next turn. | [Session override → saved settings](#reading-the-precedence-column) |
+| `context.memory.maxOutputTokens` | `2000` | Output-token cap for one memory model call (integer >= 1); applies next turn. | [Session override → saved settings](#reading-the-precedence-column) |
 | `context.memory.model` | `null` | Model id for the background memory model (string or null); null rebases to the target's `defaultModel`; session routing state, applies next turn. | session routing (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `context.memory.target` | `null` | Target id for the background memory model (configured id or null); null means deterministic rules-only memory; session routing state, applies next turn. | session routing (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `context.memory.timeoutMs` | `60000` | Timeout in ms for one memory model call (integer >= 1); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `context.memory.trajectorySteps` | `8` | Recent trajectory steps handed to the memory model per intervention (integer >= 1); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `context.workingSet.enabled` | `true` | Master switch for working-set eviction of stale tool results and thinking before summary compaction (boolean); off goes straight to summary compaction; applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `context.workingSet.minEvictableTokens` | `200` | Tool results estimated below this many tokens are never evicted because the marker would cost more than it saves (integer >= 0); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `context.workingSet.policy` | `structural-v1` | Eviction candidate rule set: `structural-v1` or `age-horizon`; applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `context.workingSet.protectLastTurns` | `6` | Most recent user turns whose observations are never evicted (integer >= 1); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `context.workingSet.target` | `0.6` | Used/window ratio an applied eviction batch reduces context to (number > 0 and < 1); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
+| `context.memory.timeoutMs` | `60000` | Timeout in ms for one memory model call (integer >= 1); applies next turn. | [Session override → saved settings](#reading-the-precedence-column) |
+| `context.memory.trajectorySteps` | `8` | Recent trajectory steps handed to the memory model per intervention (integer >= 1); applies next turn. | [Session override → saved settings](#reading-the-precedence-column) |
+| `context.workingSet.enabled` | `true` | Master switch for working-set eviction of stale tool results and thinking before summary compaction (boolean); off goes straight to summary compaction; applies next turn. | [Session override → saved settings](#reading-the-precedence-column) |
+| `context.workingSet.minEvictableTokens` | `200` | Tool-result bodies below this estimate are protected from low-yield eviction (integer >= 0). The engine separately rejects a replacement that saves no tokens; applies next turn. | [Session override → saved settings](#reading-the-precedence-column) |
+| `context.workingSet.policy` | `structural-v1` | Eviction candidate rule set: `structural-v1` or `age-horizon`; applies next turn. | [Session override → saved settings](#reading-the-precedence-column) |
+| `context.workingSet.protectLastTurns` | `6` | Most recent user turns whose observations are never evicted (integer >= 1); applies next turn. | [Session override → saved settings](#reading-the-precedence-column) |
+| `context.workingSet.target` | `0.6` | Used/window ratio an applied eviction batch reduces context to (number > 0 and < 1); applies next turn. | [Session override → saved settings](#reading-the-precedence-column) |
+
+### Fleet settings
+
+| Name | Default | Controls | Precedence |
+| --- | --- | --- | --- |
 | `fleet.adaptiveRouting.agentRoles` | `[]` | Exact `{agentId, executionRole}` pairs for which an `agent: auto` request may swap agents (no cross-product, `auto` reserved, duplicate pairs rejected); applies next dispatch. |  |
 | `fleet.adaptiveRouting.agentRoles[].agentId` |  | Native agent id the pair authorizes for automatic agent selection; required, `auto` is reserved. |  |
 | `fleet.adaptiveRouting.agentRoles[].executionRole` |  | Execution role of the pair: `builder`, `researcher`, `verifier`, `reviewer`, `judge`; required. |  |
-| `fleet.adaptiveRouting.postures` | `[]` | Requested postures (`quality`, `balanced`, `latency`, `economy`) for which joint routing is active; both the role and the posture must be listed; applies next dispatch. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `fleet.adaptiveRouting.roles` | `[]` | Execution roles (`researcher`, `verifier`, `reviewer`, `judge`) for which measured joint routing may change execution; unlisted roles only record a shadow recommendation; applies next dispatch. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `fleet.agentProfiles` | `{}` | Map of native agent id to a `fleet.profiles` name so that agent's dispatches use that route (`auto` is reserved; ACP agents cannot be bound); applies next dispatch. | `run --target` > `run --agent-profile` > session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
+| `fleet.adaptiveRouting.postures` | `[]` | Requested postures (`quality`, `balanced`, `latency`, `economy`) for which joint routing is active; both the role and the posture must be listed; applies next dispatch. | [Session override → saved settings](#reading-the-precedence-column) |
+| `fleet.adaptiveRouting.roles` | `[]` | Execution roles (`researcher`, `verifier`, `reviewer`, `judge`) for which measured joint routing may change execution; unlisted roles only record a shadow recommendation; applies next dispatch. | [Session override → saved settings](#reading-the-precedence-column) |
+| `fleet.agentProfiles` | `{}` | Map of native agent id to a `fleet.profiles` name so that agent's dispatches use that route (`auto` is reserved; ACP agents cannot be bound); applies next dispatch. | `run --target` > `run --agent-profile` > [Session override → saved settings](#reading-the-precedence-column) |
 | `fleet.agentProfiles.<key>` |  | One binding: the key is the native agent id, the value the `fleet.profiles` name used when that agent is dispatched without an explicit profile; applies next dispatch. |  |
-| `fleet.concurrency` | `1` | Maximum concurrently running local workers: `auto` currently resolves to the compiled default of 4, or set an integer >= 1; applies at restart. |  |
+| `fleet.concurrency` | `auto` | Worker limit for the global pool and the local node. An integer >= 1 is exact for both. Under `auto`, the global pool resolves to 8 (`AUTO_MAX_WORKERS`) while only the local node is dynamically sized from host facts: usable CPUs, available memory, and any cgroup memory limit (at most 8; see [Fleet dispatch](fleet-dispatch.md#worker-limits-and-fleetconcurrency-auto)); applies at restart. |  |
 | `fleet.default.model` | `null` | Saved default model id for workers (string or null; null rebases to the target's `defaultModel`); applies next session. | `run --model` > selected `fleet.profiles` route model > session routing (`/settings`) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `fleet.default.target` | `null` | Saved default target id for dispatched workers and `/run` (configured id or null; dangling ids become null); seeds session routing, so applies next session. | `run --target` > `run --agent-profile`/`--agent-runtime` > `fleet.agentProfiles` binding to a `fleet.profiles` route > session routing (`/settings`) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `fleet.default.thinkingLevel` | `off` | Saved default thinking level for workers (`off` through `max`); applies next session. | `run --thinking` > selected `fleet.profiles` route thinkingLevel > session routing (`/settings`) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `fleet.history.journal` | `true` | Whether each dispatched run writes an `events.ndjson` journal under the state `runs/` directory (boolean); applies next dispatch. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `fleet.history.maxRuns` | `1000` | Retention cap on the durable dispatch run ledger (integer >= 1); applies next dispatch. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `fleet.limits.internalRunTimeoutMs` | `900000` | Wall-clock cap in ms for one internal generator dispatch such as the wiki documenter or the bootstrap scout (integer >= 1); applies next dispatch. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `fleet.limits.toolCallsPerRun` | `150` | Lifetime cap on admitted tool calls for one dispatched worker (integer >= 1); a recipe budget can only narrow it; read from effective settings at dispatch, so applies next dispatch. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
+| `fleet.history.journal` | `true` | Whether each dispatched run writes an `events.ndjson` journal under the state `runs/` directory (boolean); applies next dispatch. | [Session override → saved settings](#reading-the-precedence-column) |
+| `fleet.history.maxRuns` | `1000` | Retention cap on the durable dispatch run ledger (integer >= 1); applies next dispatch. | [Session override → saved settings](#reading-the-precedence-column) |
+| `fleet.limits.internalRunTimeoutMs` | `900000` | Wall-clock cap in ms for one internal generator dispatch such as the wiki documenter or the bootstrap scout (integer >= 1); applies next dispatch. | [Session override → saved settings](#reading-the-precedence-column) |
+| `fleet.limits.toolCallsPerRun` | `150` | Worker tool-call baseline (integer >= 1), captured at dispatch. Ordinary dispatch currently uses advisory budgets: this value and recipe estimates do not enforce a tool-call cutoff. Legacy enforced envelopes use it as a lifetime cap. Use an explicit deadline for a wall-clock bound. | [Session override → saved settings](#reading-the-precedence-column) |
 | `fleet.nodes` | `[]` | SSH-reachable worker nodes (the implicit `local` node is never listed); a node becomes dispatch-eligible only after `clio-coder doctor --fix` records a passing fleet preflight for the project root (plain `doctor` probes and reports without recording); applies next dispatch. |  |
 | `fleet.nodes[].clioCoderEntry` | `clio-coder worker` | Remote worker-entry invocation run after `cd <projectRoot>`; also version-probed by the fleet preflight; defaults to `clio-coder worker` on the remote PATH. |  |
 | `fleet.nodes[].host` |  | SSH destination host (name or address); required. |  |
@@ -68,27 +103,70 @@ Precedence, where several surfaces set the same value: a one-run CLI flag beats
 | `fleet.nodes[].port` |  | SSH port passed as `ssh -p` (integer >= 1); absent omits the flag and defers to the SSH config. |  |
 | `fleet.nodes[].residency` | `observe` | Residency posture projected into the remote worker target lifecycle: `observe` (default) sets `user-managed`; `manage` sets `clio-coder-managed` unless the target already says `user-managed`. |  |
 | `fleet.nodes[].user` |  | SSH login user passed as `ssh -l`; absent defers to the SSH config. |  |
-| `fleet.permissions.escalation.fallback` | `deny` | Posture applied when an escalated call times out or no operator channel exists: `deny` or `fail`; applies next dispatch. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `fleet.permissions.escalation.timeoutMs` | `120000` | Wall-clock ms a parked `escalate` call waits for an operator decision before the fallback applies (integer >= 1); applies next dispatch. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `fleet.permissions.mode` | `deny` | What a noninteractive worker does with a tool call that asks for permission: `deny` returns a structured denial, `fail` ends the run (exit 3), `escalate` parks it for the operator; applies next dispatch. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `fleet.profiles` | `{}` | Named worker routes (`target`, `model`, `thinkingLevel`, `node` pin) picked by `run --agent-profile`, `fleet.agentProfiles`, or dispatch `workerProfile`; a null or unknown target drops the profile; applies next dispatch. | `run --target` (profile ignored) > `run --agent-profile`/`--agent-runtime` > `fleet.agentProfiles` binding > session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
+| `fleet.permissions.escalation.fallback` | `deny` | Posture applied when an escalated call times out or no operator channel exists: `deny` or `fail`; applies next dispatch. | [Session override → saved settings](#reading-the-precedence-column) |
+| `fleet.permissions.escalation.timeoutMs` | `120000` | Wall-clock ms a parked `escalate` call waits for an operator decision before the fallback applies (integer >= 1); applies next dispatch. | [Session override → saved settings](#reading-the-precedence-column) |
+| `fleet.permissions.mode` | `deny` | What a noninteractive worker does with a tool call that asks for permission: `deny` returns a structured denial, `fail` ends the run (exit 3), `escalate` parks it for the operator; applies next dispatch. | [Session override → saved settings](#reading-the-precedence-column) |
+| `fleet.profiles` | `{}` | Named worker routes (`target`, `model`, `thinkingLevel`, `node` pin) picked by `run --agent-profile`, `fleet.agentProfiles`, or dispatch `workerProfile`; a null or unknown target drops the profile; applies next dispatch. | `run --target` (profile ignored) > `run --agent-profile`/`--agent-runtime` > `fleet.agentProfiles` binding > [Session override → saved settings](#reading-the-precedence-column) |
 | `fleet.profiles.<key>.model` |  | Model id for the profile (string or null); null rebases to the target's `defaultModel` at validation; applies next dispatch. |  |
 | `fleet.profiles.<key>.node` |  | Optional fleet node pin (`local` or a `fleet.nodes[].id`; unknown ids are dropped): workers routed through this profile are placed on that node unless a failover excluded it; applies next dispatch. |  |
 | `fleet.profiles.<key>.target` |  | Configured target id the profile routes workers to; effectively required, because a profile whose target is null or unknown is dropped at validation; applies next dispatch. |  |
 | `fleet.profiles.<key>.thinkingLevel` | `off` | Thinking level for workers routed through this profile (`off` through `max`); `off` when absent; applies next dispatch. |  |
-| `fleet.retry.maxRetries` | `2` | Automated retries for retryable fleet run failures (integer >= 0, `0` disables retries); applies next dispatch. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `fleet.retry.routeCooldownMs` | `15000` | Cooldown in ms before a failed route is eligible again for retry placement (integer >= 0); applies next dispatch. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
+| `fleet.worktrees.root` | `disk` | Where the working tree of a `worktree: true` task is created, for local placement: `disk` (under `<checkout>/.clio-coder/worktrees`), `tmpfs` (`$XDG_RUNTIME_DIR` when it is tmpfs, else `/dev/shm`), `auto` (tmpfs when one exists and has room, else disk), or an absolute path. Off-disk roots fall back to disk with a notice when free space is below twice the tracked tree plus 256 MiB, and whenever `fleet.nodes` is non-empty. Compete candidates always stay under the project root. Applies next dispatch. | [Session override → saved settings](#reading-the-precedence-column) |
+| `fleet.retry.maxRetries` | `2` | Automated retries for retryable fleet run failures (integer >= 0, `0` disables retries); applies next dispatch. | [Session override → saved settings](#reading-the-precedence-column) |
+| `fleet.retry.routeCooldownMs` | `15000` | Cooldown in ms before a failed route is eligible again for retry placement (integer >= 0); applies next dispatch. | [Session override → saved settings](#reading-the-precedence-column) |
+| `fleet.retry.breakerThreshold` | `1` | Consecutive target failures that open a route's breaker (integer >= 1). After the cooldown one probe run tests the route; each failed probe doubles the cooldown up to five minutes. Applies next dispatch. | [Session override → saved settings](#reading-the-precedence-column) |
 | `fleet.rosters` | `{}` | Named councils for `/council` and roster dispatch: map of roster name to `members` (2 to 5 entries with unique labels and configured targets); a roster with any invalid member is dropped; applies next dispatch. |  |
 | `fleet.rosters.<key>.members[].color` |  | Optional display color for the member: a theme color name (`accent`, `success`, `warning`, `error`, ...) or a 6-digit hex `#rrggbb`; absent takes the accent color. |  |
 | `fleet.rosters.<key>.members[].label` |  | Council member label shown in council output, matching `[a-z][a-z0-9_-]{0,31}` and unique within the roster; required. |  |
 | `fleet.rosters.<key>.members[].model` |  | Optional model id for this member; absent means the target's default model. |  |
 | `fleet.rosters.<key>.members[].target` |  | Configured target id the council member runs on; required, and an unknown id is a validation error. |  |
 | `fleet.rosters.<key>.members[].thinkingLevel` |  | Optional thinking level for this member (`off` through `max`); absent means the dispatch default. |  |
+
+### Safety settings
+
+| Name | Default | Controls | Precedence |
+| --- | --- | --- | --- |
+| `safety.autonomy` | `auto-edit` | Baseline autonomy for tool admission: `read-only`, `suggest`, `auto-edit`, `full-auto`; applies immediately (an ACP session's own autonomy wins inside that session). | `run --autonomy` (stored as the session override `safety.autonomy`) > [Session override → saved settings](#reading-the-precedence-column) |
+| `safety.limits.chatToolCallsPerTurn` | `60` | Soft per-turn tool-call budget for the chat agent (integer >= 1); crossing it blocks further calls with a stop-and-summarize directive, the hard ceiling sits 15 above; applies next turn. | [Session override → saved settings](#reading-the-precedence-column) |
+| `safety.limits.observationBytesPerTurn` | `196608` | Shared per-turn byte pool across all observation-producing tools (integer >= 1); applies next turn. | [Session override → saved settings](#reading-the-precedence-column) |
+| `safety.limits.readBytesPerCall` | `51200` | Per-call byte cap for the read tool (integer >= 1; the tool clamps to a 1024-byte floor); applies next turn. | [Session override → saved settings](#reading-the-precedence-column) |
+| `safety.limits.sessionCostUsd` | `5` | Session spend ceiling in USD enforced by the scheduling budget (number >= 0); applies next turn. | [Session override → saved settings](#reading-the-precedence-column) |
+| `safety.review.cadenceToolCalls` |  | Also fire the watchdog review every this many tool calls inside a turn (integer of at least 2); absent means turn end only; applies next turn. |  |
+| `safety.review.enabled` | `false` | Opt-in turn-end review watchdog that dispatches a worker run after each mutating turn (boolean); applies immediately. | [Session override → saved settings](#reading-the-precedence-column) |
+| `safety.review.target` |  | Target id the turn-end watchdog review run is dispatched to when `safety.review.enabled` is true; absent means the session's active target; applies next dispatch. |  |
+
+### Interface settings
+
+| Name | Default | Controls | Precedence |
+| --- | --- | --- | --- |
+| `interface.desktopNotifications` | `false` | Content-free desktop notifications on turn end, detached batch settlement, and a parked approval, interactive TTY runs only (boolean); applies next turn. | [Session override → saved settings](#reading-the-precedence-column) |
+| `interface.fullscreenScrollbar` | `auto` | Fullscreen transcript scrollbar visibility: `hidden`, `auto`, `always`; applies at restart. |  |
+| `interface.keybindings` | `{}` | Map of binding id (`clio-coder.*`; legacy `clio.*` ids are renamed) to a key string or list of key strings; invalid bindings are reported at boot; applies immediately. | [Session override → saved settings](#reading-the-precedence-column) |
+| `interface.keybindings.<key>` |  | One rebinding: the key is a binding id such as `clio-coder.notifications.dismiss`, the value a key string or a list of alternatives; applies immediately. |  |
+| `interface.mode` | `regular` | Renderer: `regular` keeps scrollback, `fullscreen` uses the alternate screen with a sticky layout; applies at restart. |  |
+| `interface.demo` | `true` | Capability guidance during real project work and expiring footer hints. Tips update live; persona updates next turn. Headless runs and workers excluded. | `--demo` / `--no-demo` session override > project settings > user settings > default |
+| `interface.outputDetail` | `standard` | Output style: `compact`, `standard`, `detailed`; applies immediately. Legacy `minimal`/`default`/`verbose` values are accepted. | session override (Alt+O, `/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
+| `interface.panes.enabled` | `off` | Pane-host rung: `auto` detects a guest pane host, `embedded` is a reserved value that behaves as `auto` and is not offered by the editors, `off` skips detection; applies at restart. | `--no-panes` / `--with-panes` (`--with-panes` keeps a saved `embedded`, otherwise `auto`) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
+| `interface.panes.files.enabled` | `false` | Whether the files pane (yazi) may open (boolean); applies on the next files-pane open. | [Session override → saved settings](#reading-the-precedence-column) |
+| `interface.panes.files.followCwd` | `true` | Whether the files pane follows the conversation's working directory (boolean); applies on the next files-pane open. | [Session override → saved settings](#reading-the-precedence-column) |
+| `interface.panes.files.mode` | `companion` | Files pane mode: `companion` (picks flow back to the prompt) or `chooser`; applies on the next files-pane open. | [Session override → saved settings](#reading-the-precedence-column) |
+| `interface.panes.files.profile` | `managed` | Yazi configuration profile for the files pane: `managed` (Clio-owned) or `user`; applies on the next files-pane open. | [Session override → saved settings](#reading-the-precedence-column) |
+| `interface.panes.files.ratio` | `0.3` | Share of terminal height the files dock takes (number 0.05 through 0.5); applies at restart. |  |
+| `interface.panes.layout` | `off` | Docks composed at interactive boot in guest mode: `off` opens nothing, `workers` opens the workers dock, `cockpit` opens workers and files; applies at restart. |  |
+| `interface.panes.notifications` | `failures` | Which terminal run states raise a pane-host toast: `failures`, `all`, `off`; applies immediately. | [Session override → saved settings](#reading-the-precedence-column) |
+| `interface.panes.workers.ratio` | `0.34` | Share of terminal width the workers dock takes (number 0.05 through 0.5); applies at restart. |  |
+| `interface.smoothStreaming` | `auto` | Presentation-only pacing of streamed assistant text and thinking: `off`, `auto` (TTY heuristics), `on`; applies immediately. | [Session override → saved settings](#reading-the-precedence-column) |
+| `interface.terminalProgress` | `false` | Whether terminal progress (OSC progress) is emitted while a turn runs (boolean); applies next turn. | [Session override → saved settings](#reading-the-precedence-column) |
+
+### Integration settings
+
+| Name | Default | Controls | Precedence |
+| --- | --- | --- | --- |
 | `integrations.externalAgents.defaults.connectTimeoutMs` | `30000` | Default ms an ACP agent has to answer `initialize` (integer >= 1, at most the max timer delay); never zero-disabled; applies next dispatch. |  |
 | `integrations.externalAgents.defaults.permissionTimeoutMs` | `120000` | Default ms an ACP permission request may wait for an operator (integer >= 1); applies next dispatch. |  |
-| `integrations.externalAgents.defaults.toolGovernance` | `clio-coder-policy` | Default governance for ACP agents without their own: `clio-coder-policy`, `agent-managed`, `deny-all` (legacy `clio-policy` is normalized with a warning); applies next dispatch. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
+| `integrations.externalAgents.defaults.toolGovernance` | `clio-coder-policy` | Default governance for ACP agents without their own: `clio-coder-policy`, `agent-managed`, `deny-all` (legacy `clio-policy` is normalized with a warning); applies next dispatch. | [Session override → saved settings](#reading-the-precedence-column) |
 | `integrations.externalAgents.defaults.turnTimeoutMs` | `0` | Default ms one ACP turn may take before it is cancelled (integer >= 0; 0 disables); applies next dispatch. |  |
-| `integrations.externalAgents.entries` | `[]` | ACP delegation agents for `/delegate` and dispatch: list of stdio agent definitions with unique ids (`auto` reserved), each inheriting `defaults.*` where unset; applies next dispatch. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
+| `integrations.externalAgents.entries` | `[]` | ACP delegation agents for `/delegate` and dispatch: list of stdio agent definitions with unique ids (`auto` reserved), each inheriting `defaults.*` where unset; applies next dispatch. | [Session override → saved settings](#reading-the-precedence-column) |
 | `integrations.externalAgents.entries[].args` | `[]` | Argument list for the ACP stdio command (list of strings, duplicates dropped); empty when absent. |  |
 | `integrations.externalAgents.entries[].command` |  | ACP stdio command spawned for the agent (newline-delimited JSON-RPC per ACP v1); required. |  |
 | `integrations.externalAgents.entries[].connectTimeoutMs` |  | Per-agent ms allowed for ACP `initialize` (integer 1 through the max timer delay); absent inherits `defaults.connectTimeoutMs`. |  |
@@ -101,38 +179,18 @@ Precedence, where several surfaces set the same value: a one-run CLI flag beats
 | `integrations.externalAgents.entries[].stallTimeoutMs` | `300000` | Event-inactivity stall window in ms: when no `session/update` arrives for this long the reconciler cancels the turn and finalizes the run as stalled; `<= 0` disables; 300000 when absent. |  |
 | `integrations.externalAgents.entries[].toolGovernance` |  | Who governs the agent's tool calls: `clio-coder-policy` (Clio's autonomy matrix), `agent-managed`, `deny-all`; absent inherits `defaults.toolGovernance`; `agent-managed` refuses `run --autonomy`. |  |
 | `integrations.externalAgents.entries[].turnTimeoutMs` |  | Per-agent ms one ACP turn may take before cancellation (integer >= 0; 0 disables); absent inherits `defaults.turnTimeoutMs`. |  |
-| `integrations.git.commitAttribution` | `true` | Evidence-aware role trailers on commits created through Clio (boolean); applies immediately for subsequent commits. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `integrations.library.catalog` | `null` | Path of the private resource-library catalog (string or null); null means `<configDir>/library.yaml`; applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `integrations.library.confirmedRemote` | `null` | Remote URL written by `clio-coder library remote confirm <url>`; must equal `remote` before sync or push may run (string or null); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `integrations.library.remote` | `null` | Git remote URL of the library repository (string or null); the catalog repository must name that remote `library`; applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `integrations.library.sync` | `false` | Whether `library sync` and `library push` may spawn Git at all (boolean); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `integrations.projectResources.trustProjectImports` | `false` | Whether project-scope skills and prompts from other agents' compat roots become model-visible (boolean); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
+| `integrations.git.commitAttribution` | `true` | Evidence-aware role trailers on commits created through Clio (boolean); applies immediately for subsequent commits. | [Session override → saved settings](#reading-the-precedence-column) |
+| `integrations.library.catalog` | `null` | Path of the private resource-library catalog (string or null); null means `<configDir>/library.yaml`; applies next turn. | [Session override → saved settings](#reading-the-precedence-column) |
+| `integrations.library.confirmedRemote` | `null` | Remote URL written by `clio-coder library remote confirm <url>`; must equal `remote` before sync or push may run (string or null); applies next turn. | [Session override → saved settings](#reading-the-precedence-column) |
+| `integrations.library.remote` | `null` | Git remote URL of the library repository (string or null); the catalog repository must name that remote `library`; applies next turn. | [Session override → saved settings](#reading-the-precedence-column) |
+| `integrations.library.sync` | `false` | Whether `library sync` and `library push` may spawn Git at all (boolean); applies next turn. | [Session override → saved settings](#reading-the-precedence-column) |
+| `integrations.projectResources.trustProjectImports` | `false` | Whether explicitly imported foreign skills and prompts become usable, at user or project scope (boolean); never imports or activates loose other-agent files; applies next turn. | [Session override → saved settings](#reading-the-precedence-column) |
 | `integrations.runtimePlugins` | `[]` | npm package names loaded as provider runtime plugins at boot (list of strings); applies at restart. |  |
-| `interface.desktopNotifications` | `false` | Content-free desktop notifications on turn end, detached batch settlement, and a parked approval, interactive TTY runs only (boolean); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `interface.fullscreenScrollbar` | `auto` | Fullscreen transcript scrollbar visibility: `hidden`, `auto`, `always`; applies at restart. |  |
-| `interface.keybindings` | `{}` | Map of binding id (`clio-coder.*`; legacy `clio.*` ids are renamed) to a key string or list of key strings; invalid bindings are reported at boot; applies immediately. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `interface.keybindings.<key>` |  | One rebinding: the key is a binding id such as `clio-coder.notifications.dismiss`, the value a key string or a list of alternatives; applies immediately. |  |
-| `interface.mode` | `regular` | Renderer: `regular` keeps scrollback, `fullscreen` uses the alternate screen with a sticky layout; applies at restart. |  |
-| `interface.outputDetail` | `standard` | Output style: `compact`, `standard`, `detailed`; applies immediately. Legacy `minimal`/`default`/`verbose` values are accepted. | session override (Alt+O, `/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `interface.panes.enabled` | `off` | Pane-host rung: `auto` detects a guest pane host, `embedded` asks Clio to own a session (behaves as `auto` until implemented), `off` skips detection; applies at restart. | `--no-panes` / `--with-panes` (`--with-panes` keeps a saved `embedded`, otherwise `auto`) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `interface.panes.files.enabled` | `false` | Whether the files pane (yazi) may open (boolean); applies on the next files-pane open. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `interface.panes.files.followCwd` | `true` | Whether the files pane follows the conversation's working directory (boolean); applies on the next files-pane open. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `interface.panes.files.mode` | `companion` | Files pane mode: `companion` (picks flow back to the prompt) or `chooser`; applies on the next files-pane open. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `interface.panes.files.profile` | `managed` | Yazi configuration profile for the files pane: `managed` (Clio-owned) or `user`; applies on the next files-pane open. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `interface.panes.files.ratio` | `0.3` | Share of terminal height the files dock takes (number 0.05 through 0.5); applies at restart. |  |
-| `interface.panes.layout` | `off` | Docks composed at interactive boot in guest mode: `off` opens nothing, `workers` opens the workers dock, `cockpit` opens workers and files; applies at restart. |  |
-| `interface.panes.notifications` | `failures` | Which terminal run states raise a pane-host toast: `failures`, `all`, `off`; applies immediately. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `interface.panes.workers.ratio` | `0.34` | Share of terminal width the workers dock takes (number 0.05 through 0.5); applies at restart. |  |
-| `interface.smoothStreaming` | `auto` | Presentation-only pacing of streamed assistant text and thinking: `off`, `auto` (TTY heuristics), `on`; applies immediately. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `interface.terminalProgress` | `false` | Whether terminal progress (OSC progress) is emitted while a turn runs (boolean); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `safety.autonomy` | `auto-edit` | Baseline autonomy for tool admission: `read-only`, `suggest`, `auto-edit`, `full-auto`; applies immediately (an ACP session's own autonomy wins inside that session). | `run --autonomy` (stored as the session override `safety.autonomy`) > session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `safety.limits.chatToolCallsPerTurn` | `60` | Soft per-turn tool-call budget for the chat agent (integer >= 1); crossing it blocks further calls with a stop-and-summarize directive, the hard ceiling sits 15 above; applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `safety.limits.observationBytesPerTurn` | `196608` | Shared per-turn byte pool across all observation-producing tools (integer >= 1); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `safety.limits.readBytesPerCall` | `51200` | Per-call byte cap for the read tool (integer >= 1; the tool clamps to a 1024-byte floor); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `safety.limits.sessionCostUsd` | `5` | Session spend ceiling in USD enforced by the scheduling budget (number >= 0); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `safety.review.cadenceToolCalls` |  | Also fire the watchdog review every this many tool calls inside a turn (integer of at least 2); absent means turn end only; applies next turn. |  |
-| `safety.review.enabled` | `false` | Opt-in turn-end review watchdog that dispatches a worker run after each mutating turn (boolean); applies immediately. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `safety.review.target` |  | Target id the turn-end watchdog review run is dispatched to when `safety.review.enabled` is true; absent means the session's active target; applies next dispatch. |  |
+
+### Target settings
+
+| Name | Default | Controls | Precedence |
+| --- | --- | --- | --- |
 | `targets` | `[]` | Configured inference endpoints: a list of target descriptors with unique ids and registered runtime ids; a higher layer's list replaces the whole list; catalog applies next turn, saved routing next session. |  |
 | `targets[].auth.apiKeyEnvVar` |  | Environment variable read at call time for the API key (set by `--api-key-env`); the whole `auth` block is stripped from project layers. |  |
 | `targets[].auth.apiKeyRef` |  | Name of a stored credential in `credentials.yaml` that supplies the API key. |  |
@@ -168,6 +226,7 @@ Precedence, where several surfaces set the same value: a one-run CLI flag beats
 | `targets[].litellm.request.streamTimeoutSeconds` |  | Optional LiteLLM streaming timeout override sent as `x-litellm-stream-timeout` (number from 0.001 through 86400); omit it to keep gateway policy. |  |
 | `targets[].litellm.request.tags` | `[clio-coder]` | Additional LiteLLM request tags (list of non-empty strings without commas); Clio always adds `clio-coder`. |  |
 | `targets[].litellm.request.timeoutSeconds` |  | Optional LiteLLM request/upstream timeout override sent as `x-litellm-timeout` (number from 0.001 through 86400); omit it to keep gateway policy. |  |
+| `targets[].ollama.numCtx` |  | Ollama `num_ctx` sent as `options.num_ctx` on every `ollama` chat request (integer >= 1), and the window Clio plans against, capped by the model maximum. Unset sends nothing; a changed `num_ctx` makes Ollama reload the model, which evicts other clients' window on a shared server. |  |
 | `targets[].maxConcurrentRequests` |  | Explicit request-slot limit for this inference endpoint (integer >= 1); overrides live slot discovery and is shared by every target on the same normalized URL; applies next turn. |  |
 | `targets[].cache.retention` | SDK default | Native Pi request cache policy: `none`, `short`, or `long`. Meaning depends on the selected API/model; this grants no management or paid-warming authority. | explicit call > target > Anthropic environment fallback > SDK default |
 | `targets[].cache.deployment.backend` | unset | Read-only binding to `llamacpp` or `vllm`; absence leaves warming ineligible. | target |
@@ -182,9 +241,14 @@ Precedence, where several surfaces set the same value: a one-run CLI flag beats
 | `targets[].pricing.cacheWrite` | `0` | USD rate for cache-write tokens (number >= 0); 0 when absent. |  |
 | `targets[].pricing.input` |  | USD rate per input token unit used for cost accounting when set, taking precedence over catalog pricing (number >= 0); required together with `output`. |  |
 | `targets[].pricing.output` |  | USD rate per output token unit for cost accounting (number >= 0); required together with `input`. |  |
-| `targets[].runtime` |  | Runtime descriptor id such as `lmstudio`, `llamacpp`, `openai-compat`, `anthropic`, `claude-sdk` (aliases like `lmstudio-native` are accepted); required. |  |
+| `targets[].runtime` |  | Runtime descriptor id such as `lmstudio`, `llamacpp`, `openai-compat`, `anthropic`, `claude-sdk` (the released aliases `lmstudio-native` and `ollama-native` are accepted); required. |  |
 | `targets[].url` |  | Base URL for HTTP runtimes, the server root or its `/v1` mount; absent uses the runtime's default URL. |  |
 | `targets[].wireModels` |  | Wire model ids the target advertises for routing and the picker (list of strings, deduplicated); merged with probe and catalog discovery. |  |
+
+### Settings document version
+
+| Name | Default | Controls | Precedence |
+| --- | --- | --- | --- |
 | `version` | `2` | Schema version of the settings document; must be the integer `2` (a version-1 document is refused with a `clio-coder upgrade` hint); applies at restart. |  |
 
 ## Environment variables
@@ -275,7 +339,6 @@ Read from the process environment at boot unless the row says otherwise.
 | `NODE_COMPILE_CACHE` | `unset (Clio uses `<cache>/v8-compile-cache` once the cache root exists)` | Presence (even empty) means the operator owns the V8 compile cache: Clio calls `enableCompileCache()` with no directory and never injects its own cache into workers. |  |
 | `NODE_DISABLE_COMPILE_CACHE` | `unset` | Presence disables Clio's compile cache for this process and stops the worker spawn from injecting one. |  |
 | `NODE_OPTIONS` | `unset` | Scanned for `--trace-warnings`; when present, the trace store stops suppressing Node's `node:sqlite` ExperimentalWarning. |  |
-| `OLLAMA_NUM_PARALLEL` | `1` | Positive integer parallel slot count assumed for a local Ollama server during discovery; anything else counts as 1. |  |
 | `PATH` | `unset` | Searched for executables by interop CLI detection, toolchain resolution, the uninstall shadow check, and editor probing; the bash tool's login-env capture is discarded without it. |  |
 | `PBS_JOBID` | `unset` | Non-empty value records a PBS job in the run identity (`scheduler: pbs`), checked after the SLURM id and before LSF. |  |
 | `PBS_JOBNAME` | `unset` | Job name recorded beside `PBS_JOBID` in the PBS run identity; ignored without it. |  |
@@ -367,7 +430,7 @@ Grouped by command. Global flags appear under `global`.
 | `--settings` | Open the full settings menu directly. |
 | `--edit` | Open all user settings in VISUAL/EDITOR as a draft; validate and confirm before saving, retain settings.yaml.bak, and allow repair of malformed YAML. Requires a terminal. |
 | `--json` | Print effective user settings as JSON without initializing the installation. |
-| `--section` | Open targets, models, chat, fleet, permissions, panes, skills, diagnostics, or advanced (All Settings); without a terminal, print the section values and exit. |
+| `--section` | Open targets (Connections), chat, fleet, context, safety, interface (Appearance), integrations, or advanced. Previous section names remain accepted aliases; diagnostics opens the standalone diagnostics screen. Without a terminal, print the section values and exit. |
 | `--fleet-model` | Model id stored as the fleet default model when this target becomes the fleet default target (mutually exclusive with `--agent-profile`). |
 | `--force` | Save a model outside the runtime catalog, or one the target does not advertise, without refusing. |
 | `--gateway` | Mark the registered target as a gateway. |
@@ -422,17 +485,21 @@ Grouped by command. Global flags appear under `global`.
 
 | Flag | Controls |
 |---|---|
+| `--foreground` | Serve privately in this terminal until Ctrl+C, without reusing an installed background app or the shared documentation server. |
 | `--help` | Print the command's usage and exit. |
 | `--no-open` | Do not launch a browser; print the local documentation URL only. |
+| `--stop` | Stop the temporary documentation server. Takes no topic or other flags; does not stop an installed background app. |
 | `-h` | Short form of --help. |
 
 ### `doctor`
 
 | Flag | Controls |
 |---|---|
+| `--deep` | Add the live tool-call probe on every configured target and a dry run of the validation contract's validator commands against the policy engine at the configured autonomy. Executes no validator. |
 | `--fix` | Repair structure (missing directories and template files, credential file permissions) and record fleet preflight results instead of the read-only diagnosis. |
 | `--help` | Print the command's usage and exit. |
 | `--json` | Emit JSON instead of the human-readable rendering. |
+| `--tools-timeout` | With `--deep`, the tool probe's generation timeout in seconds (default 120). |
 | `-h` | Short form of --help. |
 
 ### `eval`
@@ -537,6 +604,20 @@ Grouped by command. Global flags appear under `global`.
 | `-r` | Short form of --resume, refused with the same /resume hint. |
 | `-v` | Short form of --version. |
 
+### `gui`
+
+Start the graphical app in the foreground. For the documentation journey, use [`docs`](#docs). Background-service and launcher subcommands are described in the [GUI guide](../gui/README.md).
+
+| Flag | Controls |
+| --- | --- |
+| `--open` | Open the private launch link in the default browser. |
+| `--no-open` | Print the launch link without opening a browser. |
+| `--port <0-65535>` | Bind the loopback listener; `0` selects an available port. |
+| `--path </app/path>` | Select an application page for the launch link. |
+| `--idle-exit <milliseconds>` | Stop the foreground server after its idle timeout. |
+| `--reuse-background` | Use this installation's configured background app when available; otherwise start in the foreground. |
+| `--help`, `-h` | Print usage without starting the server. |
+
 ### `init`
 
 | Flag | Controls |
@@ -664,7 +745,7 @@ Exit codes are 0 for success, 1 for operational failure, and 2 for invalid usage
 | `--max-context-tokens` | One-run context-window override (positive integer tokens) for supported local runtimes. |
 | `--min-p` | One-run min-p override (0 to 1) when the selected runtime supports it. |
 | `--model` | Wire model id for this run's main agent or dispatched worker instead of the target's default. |
-| `--no-skills` | Disable skill discovery for this run while still honoring explicit `--skill` paths. |
+| `--no-skills` | Disable skill discovery for this run and automatic skill/marketplace prompt guidance while still honoring explicit `--skill` paths. |
 | `--presence-penalty` | One-run presence-penalty override (number) when the selected runtime supports it. |
 | `--repeat-penalty` | One-run repeat-penalty override (number) when the selected runtime supports it. |
 | `--require` | Require a target capability for dispatch. Repeatable. |
@@ -848,6 +929,8 @@ Gateway discovery is lazy and session-cached. Untrusted or stale project declara
 
 Transport bounds are 4 MiB per incoming JSON-RPC line, 4 MiB pending outbound bytes, 16 KiB stderr tail, 1 MiB normalized result text, and at most 500 tools or 100 pages per server discovery. Gateway result shaping bounds one MCP result to 16 KiB in model context, offloading larger results to disk artifacts with preview and reference. Request timeout or per-call abort can fail one call without closing a ready server; discovery cancellation closes the shared connection. Teardown uses TERM, a 3000 ms grace, KILL, and 2000 ms bounded confirmation, reporting incomplete cleanup. Launching an MCP server is not sandboxing; remote MCP/OAuth and general OS isolation are deferred.
 
+A worked declaration, with how autonomy treats its tools: [Slurm through the clio-kit MCP server](slurm.md).
+
 ## Project files
 
 Keys read from files under `.clio-coder/` in the repository.
@@ -958,7 +1041,7 @@ Project safety, hooks, and settings are ignored until the operator reviews them
 
 | Key | Controls | Precedence |
 |---|---|---|
-| `(skill directories)` | Project skills (`<name>/SKILL.md`); third-party imports are inert until `integrations.projectResources.trustProjectImports` trusts them. | explicit `--skill` paths > project skills > user skills > catalog skills, by name |
+| `(skill directories)` | Native project skills (`<name>/SKILL.md`). Foreign packages installed through import/adoption separately require `integrations.projectResources.trustProjectImports`; loose other-agent roots remain discovery-only. | explicit `--skill` paths > project skills > user skills > catalog skills, by name |
 
 ### `.clio-coder/validation.yaml`
 
@@ -1046,12 +1129,12 @@ Arguments the model can send on `dispatch`, `bash`, `context`, and `verify`, gro
 | Argument | Class | Controls |
 |---|---|---|
 | `context.include_tree` | policy | scope=skills: list files under the skill base_dir. |
-| `context.limit` | policy | scope=recall discovery: max refs (default 8, max 12). |
+| `context.limit` | policy | scope=settings: max controls (default/max 12); scope=recall discovery: max refs (default 8, max 12). |
 | `context.name` | task | scope=skills: skill name to load; omit to list. |
-| `context.query` | task | scope=recall discovery: path, tool, or ref terms; omit to list. |
+| `context.query` | task | scope=settings: path, section alias, or search terms; scope=recall discovery: path, tool, or ref terms; omit to list. |
 | `context.ref` | task | scope=recall: ref of the evicted item, as named in its marker. |
-| `context.scope` | policy | workspace, skills, or recall. |
-| `context.offset` | policy | Zero-based recall discovery offset; follow nextOffset. |
+| `context.scope` | policy | workspace, settings, skills, or recall. |
+| `context.offset` | policy | Zero-based settings or recall discovery offset; follow nextOffset. |
 
 ### `gateway`
 

package/docs/guide/doctor.md

@@ -0,0 +1,127 @@
+# Doctor
+
+`clio-coder doctor` diagnoses a Clio install and the workspace it runs in. It
+reads, probes, and reports; plain `doctor` writes nothing. This page covers
+what the checks are, the deep checks, the in-session `/doctor`, and how to
+read the rows.
+
+## Running it
+
+| Command | What it does |
+| --- | --- |
+| `clio-coder doctor` | Every standard check. Read-only. |
+| `clio-coder doctor --fix` | Also repairs missing directories, template files, and credential permissions, and records fleet preflight results. |
+| `clio-coder doctor --json` | The same findings as JSON on stdout: `{ ok, fix, deep, findings: [{ ok, name, level, detail }] }`. |
+| `clio-coder doctor --deep` | The standard checks plus the live tool probe on every configured target and a dry run of the validation contract. |
+| `clio-coder doctor --deep --tools-timeout <seconds>` | Bounds each tool probe's generation. The default is 120 seconds, enough for a cold load of a large local model. |
+| `/doctor` | The standard checks, rendered in the session as one notice. |
+| `/doctor deep` | The deep checks against the session's targets and autonomy. |
+
+`--deep` composes with `--json` and `--fix`. `--tools-timeout` without
+`--deep` is a usage error (exit 2).
+
+## Reading a row
+
+Each row has a level:
+
+| Level | Badge | Meaning | Affects exit code |
+| --- | --- | --- | --- |
+| `ok` | `OK` | Healthy. | No |
+| `info` | `INFO` | A fact that needs no action, such as an optional tool that is not installed. | No |
+| `warn` | `WARN` | Worth attention; Clio still works. | No |
+| `error` | `!!` | Broken. | Yes: doctor exits 1 |
+
+Doctor exits 0 when no row is an error. See
+[Exit Codes and Output](exit-codes-and-output.md).
+
+## HPC toolchain rows
+
+Every run reports one `toolchain <name>` row for each of `cc`, `c++`, `clang`,
+`gfortran`, `mpicc`, `mpicxx`, `mpirun`, `nvcc`, `cmake`, `make`, `ninja`,
+`meson`, `python3`, and `sbatch`. The `cc` row accepts `gcc` when `cc` is
+absent, and the `c++` row accepts `g++`.
+
+A present tool shows its resolved path and the first line of `--version`
+output that carries a version number. Each `--version` runs for at most two
+seconds from a scratch directory, and all of them run at once.
+
+- An absent tool is `INFO`. Most workspaces need none of these.
+- An absent tool is `WARN` when the workspace
+  [validation contract](../process/scientific-validation.md) names it in a
+  validator command, or when the contract declares `runtime.kind: slurm` and
+  `sbatch` is missing.
+- An installed tool whose `--version` exits nonzero is `WARN`. An
+  unconfigured Slurm client, which cannot reach its controller, shows up this
+  way.
+
+## Task worktree rows
+
+In a git checkout, the `task worktree root` row gives the directory
+`fleet.worktrees.root` resolves to, its filesystem type, and its free space,
+and warns when an off-disk setting fell back to disk. Doctor then lists every `worktree: true` task worktree that
+outlived its run, one `task worktree <runId>` row each, or a single
+`task worktrees` row reading `none preserved`. A `settled` row is a worktree
+its run kept on purpose and is informational. An `abandoned` row is a crashed
+run's worktree that restart recovery kept because it holds work, and it is a
+warning, as is a claim whose owner is gone or that predates recovery. Each row
+gives the branch, the age, the `git log <base>..<branch>` command to inspect
+it, and the commands to drop it. Doctor never removes one. See
+[worktree per task](fleet-dispatch.md#worktree-per-task).
+
+## Slurm MCP rows
+
+`slurm clio-kit` names the `clio-kit` binary on `PATH` and whether its build
+ships the Slurm MCP server. `slurm mcp server` names the `mcp.yaml` that
+declares `clio-kit mcp-server slurm`, its scope, and its trust. `slurm
+scheduler` reports `sbatch` and `squeue`. An install with none of the three
+gets a single informational `slurm mcp` row. These rows never fail doctor. See
+[Slurm](slurm.md).
+
+## Deep checks
+
+`--deep` and `/doctor deep` add two groups of rows.
+
+### Tool probe: `tools <target>`
+
+The same streamed tool-call probe as `clio-coder targets --probe --tools` runs
+on every configured target. It checks that the target's chat model, or its
+default model when chat uses another target, streams a schema-valid tool call
+through the path a real turn uses.
+
+| Result | Level |
+| --- | --- |
+| The model streamed a valid tool call | `OK`, with the model and latency |
+| The probe ran and the call was missing or malformed | `WARN`, with the reason |
+| The probe could not run: no model is set, or the runtime does not stream through the engine | `INFO` |
+| The target did not answer its health probe | `WARN` |
+
+The probe generates tokens and can load a cold model on a local server. It
+unloads afterwards only the model it loaded itself, on the server it probed.
+A model that was already resident stays, and so does a model a chat turn
+loads while an in-session probe runs.
+
+### Validation contract dry run: `validator <n>`
+
+For each command under `validators:` in the workspace validation contract,
+doctor resolves the program (the first word after any `NAME=value`
+assignments) on PATH, or relative to the workspace when it contains a `/`.
+Then it asks the safety policy engine what it would decide for that command as
+a bash call, and applies the autonomy mapping at the configured
+`safety.autonomy`, or at the session's level for `/doctor deep`. Nothing is
+executed.
+
+The row is `OK` when the program resolves and the command would run without an
+approval ask. It is `WARN` when the program is missing, when the policy blocks
+the command, when a safety rule asks for approval at every level, or when the
+configured autonomy asks for or denies it. A command that asks only because
+it is unrecognized can be declared in `.clio-coder/safety.yaml` to run
+unattended.
+
+With no contract, or a contract with no validators, the dry run adds no rows.
+
+## In the session
+
+`/doctor` runs the same checks as the CLI and shows them as one notice headed
+by a tally, for example `doctor: 58 checks, 0 error(s), 3 warning(s)`. The
+notice takes the level of the worst row. `/doctor` never repairs anything;
+run `clio-coder doctor --fix` from a shell for that.