@iowarp/clio-coder 0.3.0 → 0.3.2

package/docs/configuration-and-targets.md

@@ -1,11 +1,11 @@
 # Configuration, Targets, Runtimes, and Auth
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive configuration validator, target resolver, and CLI command generator is located at [docs/html/configuration_blueprint.html](html/configuration_blueprint.html) (Version: 0.3.0).
+> **Interactive Spec Available:** An interactive configuration validator, target resolver, and CLI command generator is located at [docs/html/configuration_blueprint.html](html/configuration_blueprint.html) (Version: 0.3.2).
 
-Clio Coder is target-first: chat and fleet dispatch resolve through configured targets in `settings.yaml`, not through provider-specific ad hoc flags. Chat and print targets are HTTP/native/pi-ai-backed runtimes. Fleet dispatch can also target the sanctioned Claude Code subscription runtimes described below.
+Clio Coder is target-first: chat and fleet dispatch resolve through configured targets in `settings.yaml`, not through provider-specific ad hoc flags. Chat and print targets are HTTP and native engine-backed runtimes. Fleet dispatch can also target the sanctioned Claude Code subscription runtimes described below.
 
-Clio is built on top of pi-ai. Broad provider/model support comes from pi-ai-backed descriptors and from the generic `openai-compat` and `anthropic-compat` targets. Clio adds orchestration, local/native runtime ergonomics, target configuration, dispatch, safety, and receipts rather than creating a first-class descriptor for every pi-ai provider.
+Clio's engine is built on the pi SDK (see [docs/pi-boundary.md](pi-boundary.md)). Broad provider/model support comes from engine-backed descriptors and from the generic `openai-compat` and `anthropic-compat` targets. Clio adds orchestration, local/native runtime ergonomics, target configuration, dispatch, safety, and receipts rather than creating a first-class descriptor for every provider.
 
 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`.
 
@@ -29,7 +29,7 @@ Default config file:
 <configDir>/settings.yaml
 ```
 
-Role contents: config holds user-authored files (settings, credentials, agents, skills, prompts, extensions, runtimes); data holds durable artifacts (memory, evidence, evals); state holds machine-produced session state (sessions, audit, receipts, runs.json, recent-models.json, install.json, interviews, scratch); cache holds disposable derived files.
+Role contents: config holds user-authored files (settings, credentials, agents, skills, prompts, extensions, runtimes); data holds durable artifacts (memory, evidence, evals); state holds machine-produced session state (sessions, audit, receipts, runs.json, recent-models.json, install.json, interop.json, interviews, scratch); cache holds disposable derived files.
 
 `clio-coder paths --json` prints the resolved directories and is the single source of truth for scripts.
 
@@ -56,7 +56,7 @@ clio-coder configure --list
 ```
 
 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-native`.
+- **[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`.
 - **[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`.
@@ -66,7 +66,7 @@ Common local runtime IDs and default URLs are:
 
 | Runtime | Target runtime id | Example local URL |
 | --- | --- | --- |
-| LM Studio | `lmstudio-native` | `http://127.0.0.1:1234` |
+| LM Studio | `lmstudio` | `http://127.0.0.1:1234` |
 | Ollama | `ollama-native` | `http://127.0.0.1:11434` |
 | llama.cpp server | `llamacpp` | `http://127.0.0.1:8080` |
 | vLLM | `vllm` | `http://127.0.0.1:8000` |
@@ -78,7 +78,7 @@ Example registration:
 ```bash
 clio-coder configure \
   --id local-lmstudio \
-  --runtime lmstudio-native \
+  --runtime lmstudio \
   --url http://127.0.0.1:1234 \
   --model your-model-id \
   --set-orchestrator \
@@ -102,7 +102,7 @@ Inside the TUI, verify the local surface with:
 /skill
 ```
 
-The `/targets` overlay is the interactive target hub. It shows one compact row per configured target, streams live probe updates, and keeps target actions on the selected row. Use `Enter` to show details, `u` to use the target for chat, `f` to set the target as the fleet default, `b` to set an eligible target as the background-memory default, `c` to connect or authorize it, `r` to probe the selected target, and `R` to probe all targets.
+`/targets` opens Settings → Targets: one row per configured target with its roles (chat, fleet, memory) and probe health, probed live when the section opens. `Enter` on a row offers use for chat and fleet dispatch, connect (API key or OAuth, then a probe), probe, and remove. The chat, fleet, and memory targets are also individual rows in the Orchestrator and Fleet sections.
 
 Only add `--context-window <tokens>`, `--max-tokens <tokens>`, or `--reasoning true` when you have runtime/model-specific values that should override live probe results.
 
@@ -119,22 +119,33 @@ Terminology used in code and receipts:
 | `RuntimeDescriptor` | Executable adapter, transport, or protocol implementation, for example `openai-codex`, `anthropic`, `openai-compat`, `llamacpp`, `claude-sdk`, or `claude-code`. |
 | Target / `TargetDescriptor` | Persisted user-configured target plus runtime id, model defaults, auth metadata, and capability overrides. |
 | Resolved target | Target spec combined with the runtime descriptor, model catalog/probe data, wire model id, and effective capabilities. |
-| Orchestrator target | Main chat/print target. HTTP/native/pi-ai-backed. |
+| Orchestrator target | Main chat/print target. HTTP/native engine-backed. |
 | Background target | Optional proactive-memory model target. Unset means deterministic rules-only memory. |
-| Worker target | Fleet dispatch target. HTTP/native/pi-ai-backed, or one of the sanctioned subscription worker runtimes such as `claude-sdk`, `claude-code`, or `antigravity-code`. |
+| 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`. |
 
 ```yaml
 version: 1
-identity: clio
 autonomy: auto-edit         # read-only | suggest | auto-edit | full-auto (enforced at tool admission; the safety net applies at every level)
 
 targets:
   - id: local-lmstudio
-    runtime: lmstudio-native
+    runtime: lmstudio
     url: http://127.0.0.1:1234
     defaultModel: your-model-id
     capabilities:
       reasoning: true       # optional; only if your model/runtime supports it
+    lmstudio:
+      # Omit load entirely to use LM Studio's just-in-time load defaults.
+      load:
+        contextLength: 131072
+        flashAttention: true
+        evalBatchSize: 512
+        numExperts: 8
+        offloadKvCacheToGpu: true
+      request:
+        ttlSeconds: 600
+        draftModel: your-draft-model-id
+        reasoning: auto      # auto | off | on | low | medium | high
 
 runtimePlugins: []
 
@@ -194,6 +205,9 @@ theme: default
 terminal:
   showTerminalProgress: false
   outputVerbosity: default
+  tuiMode: regular              # regular terminal scrollback or fullscreen sticky layout
+  fullscreenScrollbar: auto    # hidden, auto, or always in fullscreen mode
+  smoothStreaming: off         # off, conservative auto, or explicit on
 skills:
   trustProjectCompatRoots: false
 delegation:
@@ -215,6 +229,7 @@ retry:
   maxRetries: 3
   baseDelayMs: 2000
   maxDelayMs: 60000
+  streamStallMs: 180000
 guardrails:
   turnToolCallBudget: 60
   workerToolCallCap: 150
@@ -226,6 +241,71 @@ guardrails:
 
 Target capability overrides may include `chat`, `tools`, `toolCallFormat`, `reasoning`, `thinkingFormat`, `structuredOutputs`, `vision`, `audio`, `embeddings`, `rerank`, `fim`, `contextWindow`, and `maxTokens`.
 
+### LM Studio transport and settings
+
+The canonical runtime id is `lmstudio`. The former `lmstudio-native` id remains an accepted alias,
+and `clio-coder upgrade` rewrites persisted targets to the canonical id. It also converts `ws:` URLs
+to `http:` and `wss:` URLs to `https:` because this adapter is entirely HTTP. Chat uses LM Studio's
+OpenAI-compatible `POST /v1/chat/completions` endpoint
+(<https://lmstudio.ai/docs/developer/openai-compat/chat-completions>). Model discovery and residency
+use the native REST API, with `GET /api/v1/models` as the preferred catalog
+(<https://lmstudio.ai/docs/developer/rest/list>), `GET /api/v0/models` for older servers, and
+`GET /v1/models` as the final listing fallback.
+
+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:
+
+| Settings key | REST load field |
+| --- | --- |
+| `contextLength` | `context_length` |
+| `flashAttention` | `flash_attention` |
+| `evalBatchSize` | `eval_batch_size` |
+| `numExperts` | `num_experts` |
+| `offloadKvCacheToGpu` | `offload_kv_cache_to_gpu` |
+
+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
+instance. Models that were already resident and instances reported through LM Link remain
+observe-only. Model selection remains permissive: `defaultModel` and `wireModels` may name either
+the model key or one of its loaded instance ids. The probe reports both forms and exposes each
+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
+`chat_template_kwargs` to LM Studio.
+
+LM Studio can require bearer authentication for its HTTP APIs
+(<https://lmstudio.ai/docs/developer/core/authentication>). Clio sends the resolved target API key as
+`Authorization: Bearer ...` on chat, listing, load, and unload calls. Configure validates the exact
+`/lmstudio-greeting` response before saving a direct `lmstudio` target.
+
+### Loaded instances and LM Link peers
+
+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.
+
+
+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
+block. Set them in LM Studio's My Models load settings or with `lms load`; the CLI is documented at
+<https://lmstudio.ai/docs/cli>, and the broader load-config vocabulary is documented at
+<https://lmstudio.ai/docs/typescript/api-reference/llm-load-model-config>. Clio reads back the load
+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>).
+
 `defaults.maxTokens` is a global output budget requested for every turn (default `32768`). At request time it is always clamped down to the model's known max-output cap and the remaining context window, so a model that supports less automatically gets less and no per-model tuning is required. A per-target `capabilities.maxTokens` override still records the model's true cap; the request never exceeds it. Set `defaults.maxTokens: 0` to disable the global default and fall back to per-model caps only.
 
 The setting `workers.maxRetries` controls the maximum number of automated retries for retryable failures during fleet dispatch. Setting this value to `0` disables retries entirely.
@@ -262,7 +342,7 @@ 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. The router response does not expose free
+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.
 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
@@ -274,6 +354,38 @@ budgets. Workers routed to the same local target share that target's remaining
 VRAM with the orchestrator and scout model, so the same co-residency rule
 applies.
 
+LM Studio targets get three extra rules, because LM Studio reports no VRAM
+figure anywhere and `gpuStrictVramCap` caps GPU offload rather than refusing a
+load that will not fit. An oversized load therefore succeeds and then generates
+at CPU speed instead of failing.
+
+- **Context fit before load.** While another model is resident on the same
+  server, Clio caps a just-in-time load at 131,072 tokens and says so in a
+  warning naming the co-resident models. Raise or disable the ceiling with
+  `CLIO_CODER_LMSTUDIO_CORESIDENT_CONTEXT`. A target serving one model alone is
+  never clamped.
+- **Reuse an existing instance.** A load config is never sent for a model that is
+  already resident, because LM Studio answers that with a second instance
+  holding another copy of the weights and KV cache. A resident model is reused
+  as loaded, and the output budget follows the window the server actually has
+  open. Same-key instances reported by separate LM Link nodes are independent,
+  not duplicates, and remain untouched.
+- **Unload only process-owned instances.** Clio may release an instance only
+  when this adapter process loaded it and recorded the exact returned instance
+  id. Every pre-existing local instance and every LM Link instance is
+  observe-only. A fallback swap can therefore release an earlier Clio load but
+  cannot disturb the operator's resident models.
+- **Roles remain visible.** Every model the configuration references carries
+  the plane it serves (chat, memory, worker, target default). Notices name that
+  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.
+
 
 ---
 
@@ -298,7 +410,7 @@ The routing keys in `settings.yaml` (`orchestrator.*`, `background.*`, `workers.
 
 - Interactive changes (`/model`, Alt+L, `/settings`, Shift+Tab, `/thinking`, Alt+J / Alt+K, `/scoped-models`) apply to the current session immediately and are written back as the defaults for sessions launched later.
 - Writes from other processes, such as a second Clio session, `clio-coder targets use`, `clio-coder configure`, or a manual edit, update the defaults and the shared target catalog. These writes never redirect a running session's chat or fleet routing. The running session shows a notice when the saved defaults diverge from its active routing.
-- Non-routing settings (theme, keybindings, autonomy level, retry, compaction, target catalog entries) still hot-reload into running sessions as before.
+- Non-routing settings (theme, keybindings, autonomy level, retry, compaction, commit attribution, target catalog entries) still hot-reload into running sessions as before.
 - `/resume` and `/new` switch sessions, not routing: the terminal keeps its active target/model/thinking across session switches.
 
 This is what makes several concurrent Clio terminals safe: each one routes through its own state, and `settings.yaml` only decides where the *next* session starts.
@@ -314,49 +426,93 @@ Supporting mechanics:
 
 ## Settings Center
 
-Open `/settings` in the TUI to edit session-visible defaults in a full-screen Center. Wide terminals show sections on the left and the selected section's rows on the right. Narrow terminals stack the same sections inline. Each row shows a human label, a dim config path, the current value, and a bottom description with the edit affordance.
+Open `/settings` in the TUI to edit session-visible defaults in a full-screen transactional Center. Wide terminals (≥72 columns) show sections in a left sidebar and the selected section's rows in the main pane; ultrawide terminals (≥112 columns) expand the layout to include a dedicated right-hand inspector. Below 72 columns, the Center switches to a modal drill-down stack (section list → section rows → detail drawer) with breadcrumbs, `/` search filtering, and `Esc` backtracking. Below 60 columns, side margins drop to zero for full-width presentation.
 
-Targets are managed in `/targets`; keybindings are documented in `/help`.
+Every value change in Settings is transactional: selecting an editable row and pressing `Enter` opens a dedicated value picker, text input dialog, or provider-backed checklist (rather than immediately cycling values). Clio constructs an immutable change plan with preflight impact analysis and presents explicit destination choices:
+- `Apply this session` (for live-capable settings)
+- `Apply and save globally`
+- `Cancel` (or `Esc`)
 
-| Section | Editable rows |
-| --- | --- |
-| Autonomy & Safety | Autonomy level, Worker permission asks, Delegation governance, Safety net (read-only) |
-| Orchestrator | Thinking level, Target, Model |
-| Fleet | Default target, Default model |
-| Budget | Session ceiling (USD), Model cycle set |
-| Compaction | Auto-compact, Protected recent turns, Compaction threshold |
-| Retry | Retry transient errors, Max retries, Base delay (ms), Max delay (ms) |
-| Terminal | Terminal progress badges |
+For restart-required settings (`budget.concurrency`, `runtimePlugins`, `terminal.tuiMode`, `terminal.fullscreenScrollbar`), the session-only option is suppressed and global saving announces `Saved to settings.yaml · restart Clio to apply`. For destructive actions (removing a target or fleet profile), the confirmation preflight details affected chat, fleet, and memory routes before execution.
+
+The Settings Center organizes all configuration under four non-selectable group headers:
+
+| Group | Section | Rows, in order |
+| --- | --- | --- |
+| **CORE** | Autonomy & Safety (`safety`) | `autonomy`, `workers.onPermission`, `delegation.defaults.toolGovernance`, `skills.trustProjectCompatRoots`, and the read-only safety-net fact. |
+| **CORE** | Orchestrator (`orchestrator`) | `orchestrator.thinkingLevel`, `orchestrator.target`, `orchestrator.model`, the memory plane (`background.target`, `background.model`, `background.thinkingLevel`), and the proactive-memory knobs (`memory.intervention.enabled`, `.everyNTools`, `.windowSteps`, `.maxTokens`, `.timeoutMs`). Changing target rebases model and thinking choices. |
+| **ROUTING** | Fleet (`fleet`) | `workers.default.target`, `workers.default.model`, `workers.default.thinkingLevel`, `workers.maxRetries`, `workers.profiles`, and `workers.agentBindings`, rendered under the group headers `Defaults`, `Profiles`, `Agent routes`, and `Placement`. Profile rows carry a `◆ Edit` drill-down and a destructive removal preflight; placement rows are read-only node status. |
+| **ROUTING** | Targets (`targets`) | The `targets` console table (`HEALTH`, `ID`, `ROLES`, `RUNTIME`, `LATENCY`) with an in-place action and detail drawer for URL, default model, last probe, and failure reason. Actions include `Use`, `Connect`, `Probe`, and `Remove`. |
+| **ROUTING** | Models (`models`) | `scope`, `modelSelector.recentLimit`, and `modelSelector.favorites`, rendered as a provider-backed checklist with target-level and target/model entries, `Space` toggle, capability inspector, and a preserved `Unavailable` group. Deep link `/scoped-models`. |
+| **RUNTIME** | Budget (`budget`) | `budget.sessionCeilingUsd`, `defaults.maxTokens`, and `budget.concurrency` (restart required). |
+| **RUNTIME** | Compaction (`compaction`) | `compaction.auto`, `compaction.threshold`, and `compaction.excludeLastTurns`. |
+| **RUNTIME** | Retry (`retry`) | `retry.enabled`, `retry.maxRetries`, `retry.baseDelayMs`, and `retry.maxDelayMs`. |
+| **EXPERIENCE** | Terminal (`terminal`) | `terminal.showTerminalProgress`, `terminal.outputVerbosity` (`minimal`, `default`, `verbose`), `terminal.tuiMode` (`regular`, `fullscreen`), `terminal.fullscreenScrollbar` (`hidden`, `auto`, `always`), `terminal.smoothStreaming` (`off`, `auto`, `on`), and `theme`. |
+| **EXPERIENCE** | Advanced (`advanced`) | `runtimePlugins`, `attribution.gitCommits`, `compaction.model`, `compaction.systemPrompt`, `delegation.defaults.connectTimeoutMs`, `delegation.defaults.turnTimeoutMs`, `delegation.defaults.permissionTimeoutMs`, `keybindings`, and `delegation.agents`. |
+
+`retry.streamStallMs` has no Settings Center row; edit it in `settings.yaml`.
 
 Label to config path mapping:
 
 | Label | Config path |
 | --- | --- |
 | Autonomy level | `autonomy` |
-| Worker permission asks | `workers.onPermission` |
+| Fleet approvals routing | `workers.onPermission` |
 | Delegation governance | `delegation.defaults.toolGovernance` |
+| Trust project skill roots | `skills.trustProjectCompatRoots` |
+| Safety net | read-only fact, no config path |
 | Thinking level | `orchestrator.thinkingLevel` |
 | Target | `orchestrator.target` |
 | Model | `orchestrator.model` |
+| Memory target | `background.target` |
+| Memory model | `background.model` |
+| Memory thinking level | `background.thinkingLevel` |
+| Proactive memory | `memory.intervention.enabled` |
+| Memory cadence (tools) | `memory.intervention.everyNTools` |
+| Memory trajectory steps | `memory.intervention.windowSteps` |
+| Memory reminder tokens | `memory.intervention.maxTokens` |
+| Memory timeout (ms) | `memory.intervention.timeoutMs` |
 | Default target | `workers.default.target` |
 | Default model | `workers.default.model` |
-| Session ceiling (USD) | `budget.sessionCeilingUsd` |
+| Default thinking level | `workers.default.thinkingLevel` |
+| Fleet retries | `workers.maxRetries` |
+| Add profile | `workers.profiles` |
+| Add agent route | `workers.agentBindings` |
+| Configured targets | `targets` |
 | Model cycle set | `scope` |
+| Recent models kept | `modelSelector.recentLimit` |
+| Pinned favorites | `modelSelector.favorites` |
+| Session ceiling (USD) | `budget.sessionCeilingUsd` |
+| Output budget (tokens) | `defaults.maxTokens` |
+| Fleet concurrency | `budget.concurrency` (restart required) |
 | Auto-compact | `compaction.auto` |
-| Protected recent turns | `compaction.excludeLastTurns` |
 | Compaction threshold | `compaction.threshold` |
+| Protected recent turns | `compaction.excludeLastTurns` |
 | Retry transient errors | `retry.enabled` |
 | Max retries | `retry.maxRetries` |
 | Base delay (ms) | `retry.baseDelayMs` |
 | Max delay (ms) | `retry.maxDelayMs` |
 | Terminal progress badges | `terminal.showTerminalProgress` |
-| Transcript output detail | `terminal.outputVerbosity` (`minimal`, `default`, or `verbose`) |
+| Output detail | `terminal.outputVerbosity` (`minimal`, `default`, or `verbose`) |
+| TUI mode | `terminal.tuiMode` (`regular` or `fullscreen`, restart required) |
+| Fullscreen scrollbar | `terminal.fullscreenScrollbar` (`hidden`, `auto`, or `always`, restart required) |
+| Smooth streaming | `terminal.smoothStreaming` (`off`, `auto`, or `on`, live) |
+| Theme | `theme` |
+| Runtime plugins | `runtimePlugins` |
+| Clio commit provenance | `attribution.gitCommits` (`enabled` or `disabled`, live) |
+| Compaction model | `compaction.model` |
+| Compaction prompt | `compaction.systemPrompt` |
+| Delegate connect (ms) | `delegation.defaults.connectTimeoutMs` |
+| Delegate turn (ms) | `delegation.defaults.turnTimeoutMs` |
+| Delegate permission (ms) | `delegation.defaults.permissionTimeoutMs` |
+| Keybinding overrides | `keybindings` |
+| Delegation agents | `delegation.agents` |
 
 ---
 
 ## Settings inventory
 
-Every key `settings.yaml` accepts, with its shipped default, what validation admits, and when a change takes effect. `DEFAULT_SETTINGS` in `src/core/defaults.ts` is the one place a default is written; validation lives in `src/core/config.ts`. A key absent from this table is an unknown-key error, not a silently ignored typo.
+Every key `settings.yaml` accepts, with its shipped default, what validation admits, and when a change takes effect. `DEFAULT_SETTINGS` in `src/core/defaults.ts` is the one place a default is written; validation lives in `src/core/config.ts`. A key absent from this table is an unknown-key error, not a silently ignored typo. The one exception is `identity`, which pre-0.3.1 files carry: it is accepted and ignored so those files keep loading.
 
 "When it applies" has four values. **Immediately** means a running session picks the change up from the config watcher. **Next turn** means the running turn finishes on the old value. **Next session** means `settings.yaml` is a saved default that a launched session copies and then owns, so writing it never redirects a session already running. **Restart** means the process reads it once at boot.
 
@@ -382,7 +538,7 @@ These are saved defaults, not a live control surface. See [Live routing vs saved
 | Key | Default | Validation | When it applies |
 | --- | --- | --- | --- |
 | `autonomy` | `auto-edit` | `read-only`, `suggest`, `auto-edit`, `full-auto` | immediately |
-| `workers.onPermission` | `deny` | `deny`, `escalate` | next dispatch |
+| `workers.onPermission` | `deny` | `deny`, `fail`, `escalate` | next dispatch |
 | `workers.escalation.timeoutMs` | `120000` | integer ≥ 1 | next dispatch |
 | `workers.escalation.fallback` | `deny` | `deny`, `fail` | next dispatch |
 | `workers.maxRetries` | `2` | integer ≥ 0 | next dispatch |
@@ -391,6 +547,14 @@ These are saved defaults, not a live control surface. See [Live routing vs saved
 | `workers.agentBindings` | `{}` | map of agent id to a key present in `workers.profiles` | next dispatch |
 | `skills.trustProjectCompatRoots` | `false` | boolean | restart |
 
+### Git commit provenance
+
+| Key | Default | Validation | When it applies |
+| --- | --- | --- | --- |
+| `attribution.gitCommits` | `true` | boolean | immediately for subsequent commits |
+
+Enabled attribution adds the compiled identity `Clio Coder <clio-coder@iowarp.ai>` only through evidence-justified role trailers. Assistance requires material creation or editing, testing requires a successful recorded validation command, and review requires a passing independent verifier. `Co-authored-by` is the GitHub/GitLab contributor and avatar compatibility trailer and appears only for material authorship, never for testing or review alone. Disabling the setting leaves commit messages entirely unchanged. Full hook behavior, evidence semantics, and how GitHub and GitLab render the identity and avatar once maintainers verify the email are in [git-commit-provenance.md](git-commit-provenance.md).
+
 ### Guardrails
 
 Every one of these has an environment override for a single process; see [environment-variables.md](environment-variables.md). Resolution is env, then settings, then the built-in default.
@@ -411,13 +575,18 @@ Every one of these has an environment override for a single process; see [enviro
 | `compaction.auto` | `true` | boolean | next turn |
 | `compaction.threshold` | `0.8` | number in 0 to 1 | next turn |
 | `compaction.excludeLastTurns` | `6` | integer ≥ 1 | next turn |
-| `defaults.maxTokens` | `32768` | integer ≥ 1 | next turn |
+| `defaults.maxTokens` | `32768` | integer ≥ 0 | next turn |
 | `budget.sessionCeilingUsd` | `5` | number ≥ 0 | immediately |
 | `budget.concurrency` | `auto` | `auto` or integer ≥ 1 | next dispatch |
 | `retry.enabled` | `true` | boolean | next turn |
 | `retry.maxRetries` | `3` | integer ≥ 0 | next turn |
 | `retry.baseDelayMs` | `2000` | integer ≥ 0 | next turn |
 | `retry.maxDelayMs` | `60000` | integer ≥ 0 | next turn |
+| `retry.streamStallMs` | `180000` | integer ≥ 0, `0` disables | next turn |
+
+`retry.streamStallMs` covers the failure a request error never reports: the backend answers `/health` while the slot behind the stream is dead. A run whose stream produces nothing for that long is aborted and handed to the same retry ladder as any transient error, so a headless run or a fleet worker recovers without a human pressing Esc. Time inside a tool call and inside the post-tool compaction guard does not count against it, so a long build is never mistaken for a wedged stream. Set it to `0` to keep the old behavior, where a stalled stream waits forever.
+
+Generic provider and transport errors are classified by transient retry rules, including DNS and WebSocket failures while excluding quota, usage-limit, and billing exhaustion even when the message also contains `429` or `500`. Clio adds only its local-runtime policy: model-loading errors receive a longer bounded delay, the TUI shows a cancellable countdown, and recovery resumes through the existing agent loop.
 
 ### Proactive memory
 
@@ -437,7 +606,9 @@ Every one of these has an environment override for a single process; see [enviro
 | `delegation.defaults.connectTimeoutMs` | `30000` | integer ≥ 1 | next dispatch |
 | `delegation.defaults.turnTimeoutMs` | `300000` | integer ≥ 1 | next dispatch |
 | `delegation.defaults.permissionTimeoutMs` | `120000` | integer ≥ 1 | next dispatch |
-| `delegation.defaults.toolGovernance` | `clio-policy` | `clio-policy`, `runtime-native` | next dispatch |
+| `delegation.defaults.toolGovernance` | `clio-policy` | `clio-policy`, `agent-managed`, `deny-all` | next dispatch |
+
+`delegation.agents` is the one settings key Clio itself appends to, and only after an explicit answer in `clio-coder configure --interop` or `/interop`. Everything else here is operator-authored.
 
 ### Interface
 
@@ -446,6 +617,9 @@ Every one of these has an environment override for a single process; see [enviro
 | `theme` | `default` | string naming a registered theme | immediately |
 | `terminal.showTerminalProgress` | `false` | boolean | immediately |
 | `terminal.outputVerbosity` | `default` | `minimal`, `default`, `verbose` | immediately |
+| `terminal.tuiMode` | `regular` | `regular`, `fullscreen` | restart |
+| `terminal.fullscreenScrollbar` | `auto` | `hidden`, `auto`, `always` | restart |
+| `terminal.smoothStreaming` | `off` | `off`, `auto`, `on` | immediately |
 | `modelSelector.favorites` | `[]` | list of strings | immediately |
 | `modelSelector.recentLimit` | `12` | integer ≥ 1 | immediately |
 | `keybindings` | `{}` | map of binding id to a key string or list of them | restart |
@@ -457,7 +631,6 @@ Recently selected models are runtime state and live in `recent-models.json` unde
 | Key | Default | Validation | When it applies |
 | --- | --- | --- | --- |
 | `version` | `1` | integer, currently `1` only | restart |
-| `identity` | `clio` | string | restart |
 | `targets` | `[]` | list of target descriptors, each with a unique id and a registered runtime | immediately for the catalog, next session for routing |
 | `runtimePlugins` | `[]` | list of plugin descriptors | restart |
 | `fleet.nodes` | `[]` | list of node descriptors | next dispatch |
@@ -482,7 +655,7 @@ clio-coder configure --list
 clio-coder configure --list --all
 ```
 
-`clio-coder configure --list` outputs every registered runtime across all categories (local, cloud, subscription, worker-only) along with its auth type and catalog status. For catalog-backed runtimes, it reports the catalog size (for example, `models=38 in pi-ai catalog`). It also includes a reference to `clio-coder auth list` for runtimes that require authentication.
+`clio-coder configure --list` outputs every registered runtime across all categories (local, cloud, subscription, worker-only) along with its auth type and catalog status. For catalog-backed runtimes, it reports the catalog size (for example, `models=38 in catalog`). It also includes a reference to `clio-coder auth list` for runtimes that require authentication.
 
 When configuring a catalog-backed runtime non-interactively, `clio-coder configure` requires the `--model` flag to specify an explicit model from the catalog; it will not silently seed a generic default model.
 
@@ -500,6 +673,29 @@ clio-coder configure \
 
 Add capability overrides such as `--context-window <tokens>`, `--max-tokens <tokens>`, or `--reasoning true` only when live probes cannot infer the right values for your runtime/model.
 
+---
+
+## Interop with other coding agents
+
+Clio knows which other coding agents are installed on the machine and in the project, and it can propose connecting an ACP-capable one as a delegation peer. `src/domains/interop/registry.ts` holds one entry per known agent (`claude-code`, `codex`, `opencode`, `gemini`, `copilot`, `cursor`, `antigravity`, plus the `.agents` convention) carrying its binaries, the directories it owns, its skill and prompt roots, its instruction filenames, and its ACP launch recipe when it has one.
+
+Detection is bounded and fails open. It resolves binaries with `access(X_OK)` and no shell, checks install directories, and runs a `--version` with a two-second timeout only when the caller asks for it and only for a binary that already resolved. A probe that cannot answer reports `unknown` rather than `absent`, and detection never throws. It never spawns a foreign agent's work command, and it never reads under a foreign agent's `sessions`, `history`, `cache`, `projects`, or `state` directory: it records that a foreign session store exists, never its contents.
+
+Review and connect detected agents with:
+
+```bash
+clio-coder configure --interop
+```
+
+On a terminal this walks the pending proposals one at a time, showing the exact YAML entry before it asks, and writes only what you answer yes to. Without a TTY it prints the proposals and exits 0 with `settings.yaml` byte-identical, which is what `scripts/install-local.sh` runs after `doctor --fix`. The interactive `clio-coder configure` wizard ends with the same review, and `/interop` in the TUI is the same flow as an overlay.
+
+No code path writes `delegation.agents` without an operator decision, and `doctor --fix` is not such a path. An accepted proposal appends exactly one entry through the serialized settings writer, which re-reads the file under its lock, so two processes accepting different agents cannot drop each other's entry. The appended entry carries `toolGovernance: clio-policy` and no `projectContext` key, so the peer inherits `projectContext: "none"` and receives your task text rather than the project projection. Both facts are shown before you are asked.
+
+Decisions are recorded in `<CLIO_CODER_HOME>/state/interop.json`, schema v1, written atomically only when an explicit decision is taken; `doctor` and non-TTY `configure --interop` write nothing at all. Each decision is keyed by agent kind plus a fingerprint of the facts it was made against (version and path), so a declined agent stays silent while its binary path and version hold, and comes back as a fresh proposal when either moves. Accepting and declining in one review persists both decisions. A file this version cannot parse degrades to "no report" rather than acting on a half-read decision record. Project-scoped facts stay where they already live, in `.clio-coder/state.json` under `contextSources`.
+
+Clio never writes into a foreign agent's directory. The safety path policy carries a `noWritePaths` class populated from the same registry; see [safety-model.md](safety-model.md) for the enumerated classes.
+
+---
 
 ## Subscription-based Targets and Runtimes
 
@@ -668,7 +864,7 @@ The command `clio-coder targets profile` supports several subcommands to manage
 - **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.
 
-Inside the TUI, `/targets` is the target management surface. The hub lists health, auth, runtime, model, capabilities, ready or unavailable reason, URL, and discovered models. Press `u` on a row to switch the active orchestrator target; the model is rebased to that target's default, matching `/settings` and `clio-coder targets use`. Press `f` to set the selected target as the fleet default. Press `c` on a row for the same API-key, OAuth, or no-auth connection flow used by the auth system.
+Inside the TUI, `/targets` opens Settings → Targets, the operational target console. Targets are rendered in a compact console table with columns for `HEALTH`, `ID`, `ROLES`, `RUNTIME`, and `LATENCY`, paired with an in-place action/detail drawer for URL, default model, last probe timestamp, and failure reason. Available actions include `Use` (switches active orchestrator target and rebases model to target default), `Connect` (executes API-key, OAuth, or no-auth setup then probes), `Probe` (runs immediate reachability probe with live activity indicator), and `Remove` (with preflight analysis of affected chat, fleet, and memory routes). Adding a target is performed via `clio-coder targets add`.
 
 ### Context-Window Provenance
 
@@ -754,12 +950,12 @@ 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 `agy --print` subprocess workers |
-| Local native | `llamacpp`, `lmstudio-native`, `ollama-native`, `vllm`, `sglang`, `lemonade`, `lemonade-anthropic` |
+| Local native | `llamacpp`, `lmstudio`, `ollama-native`, `vllm`, `sglang`, `lemonade`, `lemonade-anthropic` |
 
 Some hidden aliases exist for backward compatibility or special surfaces; use `clio-coder configure --list --all` to see them.
 
 > [!NOTE]
-> Chat and print targets are HTTP/native/pi-ai-backed adapters. Dispatch workers also admit the sanctioned subscription worker runtimes: `claude-sdk`, `claude-code`, and `antigravity-code`.
+> Chat and print targets are HTTP and native engine-backed adapters. Dispatch workers also admit the sanctioned subscription worker runtimes: `claude-sdk`, `claude-code`, and `antigravity-code`.
 
 ---
 
@@ -794,6 +990,8 @@ You have two ways to give Clio an API key:
 - **Environment variable** (`--api-key-env <VAR>`, or the env choice in `clio-coder configure`). Clio stores nothing and reads `$VAR` at call time. This is the recommended default. The wizard suggests it for new credentials and offers `keep` first when a stored credential already exists.
 - **Stored credential** (`--api-key <literal>`, or `clio-coder auth login`). The key is written to `credentials.yaml` (see directory locations) as **plaintext**, protected only by file mode `0600`. There is no encryption and no OS-keychain integration. Any process running as your user, plus backups and dotfile sync, can read it. Clio prints a warning whenever it writes a literal key for this reason.
 
+OAuth refresh follows signal-aware credential mutation. Clio serializes the read, token exchange, and atomic `credentials.yaml` write under one lock, forwards the active agent or background-request abort signal through `providers.auth`, and cancels a queued lock wait immediately. A cancelled refresh neither continues later nor publishes an uncommitted token into the process-local credential view.
+
 Prefer `--api-key-env` for shared machines, HPC login nodes, and CI. Avoid committing literal secrets in settings or share archives. Stored keys are never printed back by `clio-coder auth status`, `clio-coder targets`, or `clio-coder configure`; only the source (env var name or `stored-api-key`) is shown.
 
 For interactive auth, open `/targets`, select the row, and press `c`. For a stored credential cleanup, use `clio-coder auth logout <target-or-runtime>`.

package/docs/context-engine.md

@@ -1,7 +1,7 @@
 # Context Engine
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/context_blueprint.html](html/context_blueprint.html) (Version: 0.3.0).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/context_blueprint.html](html/context_blueprint.html) (Version: 0.3.2).
 
 Clio Coder tracks context pressure, records per-turn snapshots, and protects the provider context with bounded tool results plus single-threshold compaction.
 
@@ -9,10 +9,14 @@ Source of truth lives in `src/domains/session/context-accounting.ts`, `src/domai
 
 ## Context window resolution
 
-Each target has a declared, desired, and effective context window. The effective window is the operating ceiling used by budget checks and compaction. It can come from a live loaded model config, a probe, a target override, a model hint, catalog knowledge, a local-native default, or a descriptor default.
+Each target has a declared, desired, and effective context window. The effective window is the operating ceiling used by budget checks and compaction. Sources rank most-live first: the window discovery reports the model is loaded at, then a probed window, then a target override, then a model hint, catalog knowledge, a local-native default, and finally a descriptor default.
+
+The loaded window outranks the declared one because it is the only figure describing what the backend will serve. LM Studio routinely opens a model well below its `max_context_length`, and a run planned against the larger number overruns the server before compaction ever fires. Discovery carries that number per model in `discoveredModelStates[<model>].contextLength`, and the residency notice reads the same entry, so a model Clio is budgeting a loaded window for is never announced as absent.
 
 Local-native runtimes use a recommended minimum desired window of 128,000 tokens. If the live model reports a smaller loaded context window, Clio re-resolves the target so accounting uses the actual ceiling.
 
+The `/context` overlay states which layer answered, next to the token total: `loaded`, `probed`, `configured`, `declared`, or `assumed`.
+
 ## Token accounting and snapshots
 
 The estimator in `context-accounting.ts` uses a four-characters-per-token family for hot-path accounting. It estimates system prompt, tools, messages, pending input, and runtime categories without calling a model tokenizer on every TUI refresh.
@@ -37,6 +41,8 @@ Marker format:
 
 Already-compacted entries are not masked again. Recent turns keep their full observations and thinking. If masking drops pressure below the threshold, Clio sends the request without an LLM summary. If pressure remains above the threshold, Clio runs the summary compaction path, appends a compaction summary entry, refreshes replay messages from the session, and continues.
 
+When the ledger is replayed to the model, compaction summaries, branch summaries, and bash executions become standardized user-role message text. Clio imports `COMPACTION_SUMMARY_PREFIX`, `BRANCH_SUMMARY_PREFIX`, their suffixes, and `bashExecutionToText` through `src/engine/messages.ts`; `src/interactive/chat-renderer.ts` maps Clio's entry shapes onto them and applies replay truncation.
+
 Manual `/context compact`, `CLIO_CODER_FORCE_COMPACT=1`, and overflow recovery force the LLM summary path directly. The overflow guard runs before the user turn is committed, so a blocked oversized request does not leave an unanswered user entry in the ledger.
 
 ## Cache-divergence honesty
@@ -66,26 +72,47 @@ Settings validation is strict: an older file still carrying the removed `compact
 
 ---
 
+## Directory-scoped project handbooks
+
+Project guidance is resolved from the filesystem root to the working directory. An ordinary `CLIO-CODER.md` adds a layer for its directory and descendants. `CLIO-CODER.override.md` starts a replacement boundary: it wins over `CLIO-CODER.md` in the same directory, discards all handbook layers inherited from ancestors, and remains effective below that directory. Ordinary handbooks in deeper directories may add new layers after the override. A sibling outside the override's subtree keeps its own inherited chain.
+
+For example, a session in `repo/src/parser/` loads `repo/src/CLIO-CODER.override.md` followed by `repo/src/parser/CLIO-CODER.md`; it does not load `repo/CLIO-CODER.md`. A session in `repo/docs/` still loads `repo/CLIO-CODER.md`. Surviving files are rendered in ancestor-to-descendant order as separate `<project-context path="...">` blocks, preserving the source of every instruction. The nearest surviving handbook supplies the project name used by compact reporting, while conventions, hard invariants, imported context, and custom sections layer in order.
+
+An unreadable or malformed override fails closed. Clio warns about that file but does not reactivate the inherited or same-directory handbook it replaced. `clio-coder config inspect` lists every effective handbook and its layer number.
+
+Handbook resolution is read-only. `/context init` and its CLI form are the only commands that author or update the exact `CLIO-CODER.md` in the current directory; `/context refresh` touches neither standard nor override handbooks. Neither command rewrites an inherited file or an override. A same-directory override therefore continues to shadow a standard handbook created or updated by init until the operator removes the override. Normal reset preserves both handbook names; `context reset --all` may remove the local standard `CLIO-CODER.md` after its second confirmation but always preserves `CLIO-CODER.override.md` as operator-authored context.
+
 ## Project-context preload class
 
-The compiled session prompt preloads the full rendered project context (the `CLIO-CODER.md` fragment plus project-type and codewiki markers) only when a parseable `CLIO-CODER.md` exists and the rendered text stays within 8000 characters and 220 lines; otherwise it preloads a compact synopsis. The rule lives in `src/domains/prompts/preload.ts` and every reporting surface classifies with it:
+The compiled session prompt preloads the full rendered project context (the effective handbook fragments plus project-type and codewiki markers) only when at least one selected handbook parses and the rendered text stays within 8000 characters and 220 lines; otherwise it preloads a compact synopsis. The rule lives in `src/domains/prompts/preload.ts` and every reporting surface classifies with it:
 
 - `/context init` and `clio-coder context init` print `preload: full (N.NkB, N lines)` or `preload: synopsis (reason: size|lines)` after the summary, and warn when a full preload is within 10% of either limit.
-- `clio-coder config inspect` shows the preload class in the `CLIO-CODER.md` entry's detail.
-- The `/context` overlay shows a `project preload:` line under the category legend once a session prompt has compiled.
+- `clio-coder config inspect` shows the shared preload class and layer position on every effective handbook entry.
+- The `/context` overlay shows a `project preload:` line under the category legend once a session prompt has compiled, followed by the effective handbook path(s): one `handbook:` line for a single file, or a `handbooks (ancestor → nearest):` list when layered handbooks apply. Paths render workspace-relative; a handbook above the workspace keeps a `~`-shortened or absolute path.
 
 ## Context refresh
 
 `/context refresh` and `clio-coder context refresh` rebuild the structural codewiki
-and restamp `.clio-coder/state.json` without reading or writing `CLIO-CODER.md`. The CLI
+and restamp `.clio-coder/state.json` without reading or writing inherited handbooks or overrides. The CLI
 flag `--wiki` is the only refresh path that may update the Markdown wiki, and
 it only runs when an existing wiki metadata file is present. Regenerating or
-updating handbook prose stays with `/context init`.
+updating the exact local standard handbook stays with `/context init`.
 
 `clio-coder context init` is model-driven by default. The `--heuristic` flag is the sole deterministic flag for offline handbook generation. The `--propose` flag writes ignored drafts to `.clio-coder/proposals/`, `--apply` updates from the existing handbook, and `--rewrite` generates a fresh handbook.
 
 When bootstrapping across local runtimes such as `llamacpp` where strict grammar/schema enforcement might be rejected by the endpoint, generator logic retries automatically using a bounded prompt-parser fallback. If `--rewrite` was requested but the model generation fails to produce a valid handbook rewrite, `clio-coder context init` prints a notice and exits with code 1 rather than leaving an inconsistent state.
 
+## Generated handbook structure and verification expectations
+
+During handbook generation (`context init` and `clio-coder context init`), Clio derives structural sections directly from workspace manifests and toolchains:
+
+- **Context retrieval**: Derived from the codewiki index, naming primary entry points and directing agents to use `code_nav` for navigation. To prevent staleness across repository mutations, exact volatile file counts are omitted.
+- **Verification expectations**: Synthesized from declared toolchain configuration and manifest files:
+  - **Node.js**: Detects the active package manager (`npm`, `pnpm`, `yarn`, or `bun`) and names declared non-mutating scripts (`typecheck`, `lint`, `format`, `build`, `test`, `ci`, `test:contracts`, `test:smoke`, `check:boundaries`).
+  - **CMake**: Inspects `CMakePresets.json` and emits declared configure, build, and test presets independently.
+  - **Rust / Cargo**: Names `cargo build` and `cargo test` when `Cargo.toml` is present.
+  - **Go**: Names `go build ./...` and `go test ./...` when `go.mod` is present.
+  - **Python**: Detects declared runners (`tox` via `tox.ini` or `[tool.tox]` in `pyproject.toml`; `pytest` via `pytest.ini` or `[tool.pytest.ini_options]` in `pyproject.toml`) and names them without guessing undeclared runners.
 
 ---