@iowarp/clio-coder 0.4.2 → 0.4.3

package/docs/architecture/model-catalog.md

@@ -20,7 +20,11 @@ Configured `wireModels` and a target `defaultModel` remain selectable before a
 live catalog is known; Clio labels those rows as `configured` or `default`.
 Once a target returns a live catalog, that catalog is authoritative and models
 the runtime no longer reports stop resolving. Live probe discoveries are labeled
-`live` and carry load-state metadata when the runtime exposes it. This preserves
+`live` and carry load-state metadata when the runtime exposes it. Runtime model
+labels are separate metadata: the stable slug remains the wire identity while
+`clio-coder models` and target status may show the human label beside it. Slugs,
+labels, source, and freshness round-trip through the generic target model
+snapshot; a cached label never replaces a live slug. This preserves
 operator-curated defaults while still letting runtime discovery take over after
 newly installed local models or newly entitled cloud models appear. Catalog YAML
 entries are loaded when the provider domain is built, so bundled or overlay
@@ -32,8 +36,9 @@ Live provider probes are the preferred source for loaded context and per-model m
 `probeCapabilitiesForModel` is the one exact-id selector. When a router serves several models, capability resolution queries `probeCapabilitiesForModel` to ensure probe data is extracted only from the `/v1/models` row keyed to its own exact wire model ID.
 
 Transient probe failures preserve the last-good catalog, load states,
-capabilities, and notes for the same target identity, but the target health is
-reported as down or unavailable with the probe error as the reason. Worker
+labels, capabilities, and notes for the same target identity, but those model
+rows are marked cached/stale and target health is reported as down or unavailable
+with the probe error as the reason. Worker
 dispatch canonicalizes requested model ids against the live catalog when one is
 available, so a short alias can resolve to the canonical live id before the
 worker spec and receipt are written.
@@ -185,14 +190,19 @@ override the applicable setting.
 - **Ollama Native (`ollama-native`):** Ollama utilizes the native `thinking` field in the request and response payloads. The engine handles Ollama-specific effort levels and streams reasoning increments cleanly through the native thinking channel.
 - **LM Studio (`lmstudio`):** Chat uses the OpenAI-compatible `/v1/chat/completions` surface, including its `reasoning` stream field. Clio controls thinking only with `reasoning_effort` and never sends `chat_template_kwargs` to LM Studio. See <https://lmstudio.ai/docs/developer/openai-compat/chat-completions>.
 - **LiteLLM (`litellm`):** This is a gateway runtime, not an `openai-compat`
-  alias. Discovery checks `/health/liveliness`, reads aliases and capability
+  alias. Discovery checks `/health/liveliness`, reads routed names and capability
   metadata from `/v1/model/info`, and records the physical deployment reported
-  by `x-litellm-*` response headers. Defaults stay conservative when metadata is
-  absent: tools, vision, and reasoning are not inferred. The runtime advertises
-  standard `json_schema` structured output and treats schema-plus-tools as a
-  conflict because the gateway alias does not identify one stable upstream.
-  Residency is observe-only because LiteLLM owns loading and eviction behind the
-  alias.
+  by `x-litellm-*` response headers. Deterministic gateways should publish one
+  `node/model` name per deployment; genuine multi-deployment aliases expose only
+  the capabilities guaranteed by every route and use the smallest unanimously
+  published context/output limits. Defaults stay conservative when metadata is
+  absent: tools, vision, reasoning, and structured output are not inferred.
+  Explicitly advertised schema support uses standard `json_schema` on the wire.
+  Gateway requests use no hidden OpenAI SDK retries, and LiteLLM failures bypass
+  Clio's interactive transient retry ladder so the operator can select another
+  route. Stable session ids, request tags, optional request-level timeouts, and
+  observed server retry/fallback headers remain supported. Residency is
+  observe-only because LiteLLM owns loading and eviction behind the route.
 - **OpenAI Completions (`openai-completions`):** The OpenAI-compatible completions provider preserves reasoning blocks within assistant messages. It replays thinking blocks via the `reasoning_content` parameter in the message history, ensuring that the model maintains its chain-of-thought across conversational turns without stripping the data.
 - **Anthropic OAuth / API (`anthropic-max`):** Uses the `anthropic-extended` thinking format. The engine supports Anthropic's native extended thinking block protocol, streaming thinking increments and outputting them wrapped appropriately or natively depending on target capabilities.
 - **Reasoning-Never Models (`thinking.mechanism: none`):** When a model is configured or cataloged with `thinking.mechanism: none`, it is treated as a reasoning-never model. For these models, Clio must not send any thinking fields or parameters in requests, must not replay thinking blocks, must not surface thinking events to the TUI, and must not preserve or log reasoning token usage in metrics.
@@ -206,6 +216,7 @@ Subscription models are registered and managed as standard HTTP/cloud targets:
 - **`openai-codex` (ChatGPT Plus/Pro OAuth):** Maps to catalog-backed Codex model ids surfaced by `clio-coder configure --list` and `clio-coder models` via a browser-minted subscription OAuth token, supporting complete chat, vision, and tool-use capabilities.
 - **`anthropic-max` (Claude Pro/Max OAuth):** Powers chat and workers using catalog-backed Claude model ids surfaced by `clio-coder configure --list` and `clio-coder models`. It relies on the engine's Anthropic OAuth provider. During auth initialization, it alerts the operator to usage-terms caveat via:
   `Connects with your Claude Pro/Max subscription via OAuth (the same path Claude Code uses). Using subscription credentials outside Anthropic's first-party apps may not align with their terms of service; enable at your own discretion.`
+- **`antigravity-code` (experimental local delegation):** Is not an HTTP model provider and is never orchestrator-eligible. It invokes the operator's own authenticated official `agy` executable only for dispatch work, consumes structured `stream-json` results and token accounting, and discovers model slugs and labels from the non-generating JSON `models` command. Descriptor models are cold-start hints only; a successful target probe is authoritative for that account, including the disappearance of a former model.
 
 ---
 

package/docs/architecture/observability.md

@@ -151,7 +151,18 @@ A row has the following schema:
 
 `repoIdentity` is the same cwd hash the session ledger is filed under, which is what lets `usage report --repo <path>` select these rows with the hash it already computes for the ledgers.
 
-`label` is one of `side-question`, `handoff`, `prewarm`, or `background-memory`. The last two joined for the same reason as the first two: a prompt pre-warm and a proactive-memory step are provider calls the operator did not ask for and would otherwise never see, and neither appends anything to the session JSONL. A row may also carry `timing { durationMs }` and a `promptCache` block built from the backend's own prefill facts when the server reported them; a backend that reports no timings simply omits the block, as LM Studio's OpenAI-compatible port does.
+`label` is one of `side-question`, `handoff`, `prewarm`, `background-memory`, or `failed-compaction`. Prompt pre-warm and proactive-memory calls are recorded here because neither appends an assistant call to the session JSONL; failed-compaction records preserve calls from an attempt that produced no checkpoint. A row may also carry `timing { durationMs }` and a `promptCache` block built from the backend's own prefill facts when the server reported them; a backend that reports no timings simply omits the block, as LM Studio's OpenAI-compatible port does.
+
+
+Failed compaction attempts record one `failed-compaction` row per invoked summary stream when no checkpoint is produced. `callOutcome` distinguishes a completed first stream (`success`) from an `error` or `aborted` stream; a completed call can belong to an unsuccessful split-compaction attempt. The rows capture the originating session/repository and selected target/model before asynchronous work can switch context. Successful compactions keep usage solely on their checkpoint, and their live accounting uses the same selected route. Unset model controls retain the active chat route.
+
+New failed-compaction rows preserve missing usage fields as `null`. Positive partial-response facts survive an error that resets missing fields to zero. Ambiguous failed zeros remain unknown, reasoning is separate from ordinary output/total tokens, and an absent total is not inferred. Positive adapter prices are labeled `estimated`; zero or missing pricing is `unknown`, not a free-call claim. Existing numeric rows and historical checkpoints remain readable without rewriting them.
+
+`clio-coder usage report` includes these calls in its known subtotals, labels the failed-attempt count, and exposes `failedCompaction.knownUsage`, `erroredKnownUsage`, and per-field `unobservedUsageCalls` in the token and model JSON facts. A field with missing coverage and no known positive amount is `null`, including cost-only or wholly unobserved failures. Text output identifies incomplete subtotals. The live `/cost` view records positive known contributions under a failed-compaction label; its numeric token counters remain known subtotals. These figures do not certify provider billing or complete spending. The existing session-cost ceiling checks the numeric known sum, so unreported cost does not become an enforced complete-cost bound.
+
+Eval tracked/stdout folds do not include the failed-compaction sidecar, and live `/cost` reseeding reads the session ledger rather than this store. A later usage report can therefore include retained failed-compaction amounts that those views omit. This consumer reconciliation is deferred to v0.4.5 or later; the retained known amounts must not be presented as complete cross-surface billing.
+
+A failed or empty summary produces no checkpoint. Required failed-compaction usage appends are flushed and a write failure remains an explicit operation error; no model call is repeated to repair accounting. If checkpoint append throws, Clio checks that checkpoint's exact identity in the original ledger before choosing the sidecar: an already written checkpoint is not counted again, and proven absence permits the sidecar. An unreadable or malformed ledger that leaves persistence ambiguous fails visibly without a speculative duplicate write. This is the existing bounded usage store, not a new recovery store; its 1000-row retention and unknown telemetry limits still apply.
 
 ---
 

package/docs/architecture/prompt-envelope-and-tools.md

@@ -201,6 +201,8 @@ Compaction rewrites history, so the next turn on a local single-slot backend is
 
 Timing and cache behavior are persisted per API call, so a finished session can be inspected from its stored artifacts alone. Each assistant entry in the session ledger (`current.jsonl`, under the directory reported by `clio-coder paths`) carries `timing { ttftMs, apiMs }` and `promptCache { input, cacheRead, cacheWrite, backendVerdict }`, and the run's first persisted call also carries `expectedColdReasons`. Cache verdicts are `hot`, `partial`, `cold`, or `small`.
 
+Native session timing uses a monotonic clock from each stream invocation, before the provider's response-header wait, to its first observed output (`ttftMs`) and completion (`apiMs`). A tool-loop continuation starts a new clock; no output leaves TTFT null, and a genuine rounded zero remains zero. Historical values are not rewritten and may omit the pre-header wait. Eval prefers these durable native call records. Its stdout-only fallback starts at the provider's `message_start` event, which can arrive after headers, so fallback spans are not complete request latency and must not be compared as equivalent measurements.
+
 For aggregate cost and token facts across sessions, use `clio-coder usage report --days <n>`. Inside the TUI, `/cost` shows session totals and `/context` opens the context-window ledger overlay.
 
 ## Self-documentation retrieval

package/docs/architecture/provider-adapter-cookbook.md

@@ -170,6 +170,69 @@ inherited from the pinned Pi dependency; Clio no longer carries a separate
 contract test that reconstructs Pi's whole adaptive or budget payload.
 
 
+
+### 3.3 Thinking controls through LiteLLM
+
+Dedicated memory and compaction roles read a cold LiteLLM target's metadata
+before synthesizing the completion model. The read disables reasoning probes;
+it does not run an extra inference request. Each selected target owns its probe
+state, even when two targets share a gateway URL. A successful unknown or mixed
+runtime declaration remains unknown and is not repeatedly probed for a preferred
+answer. Memory includes discovery and auth in its existing generation/deadline
+boundary; cancellation cannot launch a later completion or mark the endpoint
+down. Fresh discovered output limits also bound its request. After metadata and auth,
+memory rechecks actual endpoint occupancy immediately before registering its
+inference hold. Late saturation stays a dropped `endpoint_busy` boundary with
+no usage or cache-disturbance claim. Compaction checks
+the originating session/branch after preparation and uses the existing simple
+stream API with thinking off, rather than inferring an active level from the
+model's reasoning capability.
+
+Native worker admission also prepares the selected cold LiteLLM target before
+freezing its capabilities and thinking controls into the worker specification
+and receipt. Tool cancellation and the original admission deadline bound that
+wait, including a delayed metadata response body. Failed preparation releases
+the existing plan reservation and cannot launch a late worker or publish
+cancelled health data. The approved target, model, endpoint and node remain
+binding; changed route identity requires fresh admission. Metadata discovery
+does not infer capacity or residency from another route sharing the gateway,
+and does not bypass the existing capacity or approved tool-surface checks.
+
+
+A gateway alias is not an upstream runtime identity. Clio consumes the optional
+`model_info.runtime` deployment declaration from LiteLLM's `/v1/model/info` only
+when every deployment of the alias names the same recognized control runtime:
+`lm-studio` or `llama.cpp`. Missing, unknown, or mixed declarations produce no
+runtime-specific control hint. The probe-only `thinkingControlRuntime` capability
+travels through the existing main, background and worker model capability path;
+`runtimeId`, authentication, the gateway URL and residency ownership stay LiteLLM.
+Clio never infers this declaration from ports or model names and never loads or
+unloads the gateway's upstream models.
+
+The family still determines whether thinking is switchable and which active
+levels exist. A declared LM Studio route receives `reasoning_effort: "none"` for
+an effective off choice; a llama.cpp route uses its template switch. LiteLLM's
+generic OpenAI adapter may silently filter a resolved effort for local model
+names. Clio therefore adds `allowed_openai_params: ["reasoning_effort"]` only when
+it sends that model/runtime's resolved `reasoning_effort`; unrelated parameters
+and unknown off mechanisms are not newly allowed. This is a request control,
+not a change to gateway configuration. See [LiteLLM parameter forwarding](https://docs.litellm.ai/docs/completion/drop_params).
+
+[Qwen3.8-27B's pinned template](https://huggingface.co/Qwen/Qwen3.8-27B/blob/1d4bf0f2ff6012fd82039f2fa52739d0dd7c60c0/chat_template.jinja)
+accepts active `low`, `medium`, and `xhigh`, with thinking enabled and `xhigh`
+when the template receives no override. Clio shows off/low/medium/xhigh and maps
+released high/max selections to xhigh. That vendor default does not overwrite
+Clio's explicit chat preference or saved low setting. Disabling thinking does
+not remove historical reasoning or discard reasoning a server actually returns.
+
+Controlled gateway filtering tests cover discovery, capability transfer, actual
+HTTP payloads, off/on switching, and built CLI persistence. Live same-route
+probes on the selected LiteLLM deployment returned reasoning with the flag or
+none alone, zero reasoning on two calls with none plus the explicit allowance,
+and positive reasoning for an allowed low control. This verifies the measured
+route and request contract; unknown or heterogeneous gateway aliases need their
+own declared capabilities and acceptance.
+
 ---
 
 ## 4. Configuring Reasoning & Thinking Formats

package/docs/architecture/safety-model.md

@@ -129,11 +129,12 @@ The `/view` workspace category treats a recorded successful write as a durable f
 
 A `SKILL.md` may declare `allowed-tools` and `disallowed-tools`. The declaration is enforced at tool admission, between the safety net and the autonomy mapping, on every surface that activates skills (interactive turns, headless `clio-coder run` turns, and dispatched workers whose recipes declare skills).
 
-- **Window.** Narrowing arms when `context` (scope="skills") successfully loads the skill and lasts for the lifetime of the pending-skill policy: to the end of the current turn for the main agent, and to the end of the run for a worker. A later turn is unrestricted until a skill is requested and loaded again.
+- **Window.** Narrowing arms when `context` (scope="skills") successfully loads the skill and lasts for the lifetime of the pending-skill policy. Interactively that is the session: the surface stays armed across the operator's later turns, because a multi-turn skill workflow is still the same workflow on the operator's next message. It ends when a different skill replaces it (the new skill's declaration replaces the old one, it is never merged into it), when the operator clears it with `/skill off`, or when the session ends. A worker keeps the run-scoped lifetime. Activation and clearing each emit one transcript line naming the armed skills.
+- **Who activates.** At `read-only` and `suggest` only the operator activates a skill: a model `context(scope="skills", name=...)` call is refused and the model's move is the suggestion anchor. At `auto-edit` and `full-auto` the model activates an installed skill itself, under the same per-run policy `/skill` produces, because the operator has already chosen to let it act and narrowing can only subtract from the surface. The autonomy level is the whole opt-in; there is no frontmatter flag. A skill that is not installed stays operator-gated at every level, and the transcript line names who activated. This holds on every surface that resolves effective autonomy through the chat loop, which is all three: interactive turns, headless `clio-coder run --autonomy ...`, and ACP prompts (including a per-session level an ACP client sets). Dispatched workers are unaffected: a worker loads only the skills its recipe declares.
 - **Merge.** Denials win: a tool named in any loaded skill's `disallowed-tools` is blocked. Allow-narrowing applies only while every loaded skill declares `allowed-tools`; the merged surface is the union of those lists. A loaded skill that declares no `allowed-tools` keeps the full surface for its own workflow, which lifts the allow-narrowing (never the denials) for that window.
 - **Exemptions.** `context` (the remaining requested skills of the turn must still load) and `ask_user` (the escape hatch the block message points at) are always admitted.
 - **Direction.** Narrowing only blocks. It never grants a tool the safety net, damage-control rules, or autonomy mapping would refuse, and an out-of-surface call blocks terminally instead of parking for confirmation.
-- **Block message.** The rejection names the tool, the active skill(s), and the merged surface, and states the remediation: work within the declared surface, or use `ask_user` (when available) to hand the step to the operator. The audit row carries reason code `skill_surface`.
+- **Block message.** The rejection names the tool, the active skill(s), the merged surface, and the lifetime that actually applies (session-scoped for a carried surface, turn/run-scoped otherwise), and states the remediation: work within the declared surface, or use `ask_user` (when available) to hand the step to the operator. The audit row carries reason code `skill_surface`.
 
 ---
 
@@ -236,7 +237,8 @@ Path-policy behavior:
 The default damage-control policy populates `noWritePaths` from the interop
 agent registry: `~/.claude/`, `.claude/`, `~/.codex/`, `.codex/`, `~/.config/opencode/`,
 `.opencode/`, `~/.gemini/`, `.gemini/`, `~/.copilot/`, `~/.cursor/`, `.cursor/`,
-`~/.antigravitycli/`, `.antigravitycli/`, `~/.agents/`, and `.agents/`. Clio never writes
+`~/.gemini/antigravity-cli/`, `.gemini/antigravity-cli/`, the legacy
+`~/.antigravitycli/` and `.antigravitycli/`, `~/.agents/`, and `.agents/`. Clio never writes
 into another coding agent's directory. It reads those roots for skills, prompts, and
 rule prose and has no reason to author them. A `write` or `edit` targeting any of
 these paths is refused at every posture including `auto-edit` and `full-auto`, with reason
@@ -290,14 +292,22 @@ Fleet dispatch is admitted only when the requested worker scope is a subset of t
 
 Dispatch workers can run the same HTTP or native runtimes as the orchestrator. Clio observes and governs those tool calls directly, so every worker run is subject to the same safety mapping and receipt accounting as an interactive turn.
 
-Three integration paths exist for driving Claude Code, ranging from fully enforced to advisory gating:
+Three worker-runtime safety categories range from fully enforced to advisory gating:
 
 - **`claude-sdk` (Enforced Safety):** Drives [@anthropic-ai/claude-agent-sdk](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) directly. This is the **strong safety path** because Clio enforces tool gating before execution. Clio registers a `PreToolUse` hook (which fires for all tool uses, including auto-allowed reads) and wraps `canUseTool` for permission paths. Every tool request is mapped into a Clio tool/action class, evaluated by the safety net, and passed through the active autonomy matrix. Because a dispatched worker is noninteractive, any `ask` decision is resolved as a non-stall denial (`fleet.permissions.mode=deny` returns denial; `fleet.permissions.mode=fail` terminates the run with a permission-required code).
-- **`claude-code` (Subprocess Gating):** Drives `claude -p` as a subprocess. Because the CLI lacks a direct callback hook, Clio cannot evaluate each tool invocation. Instead, Clio maps the active autonomy level to the binary's command-line parameters (such as `--permission-mode` and tool allowlists). Unrecognized tools are gated by the subprocess runtime itself. Dispatch at autonomy `suggest` is refused outright (the same applies to `antigravity-code`): a subprocess cannot park a tool call for approval, so `suggest` has no honest mapping and the runner fails closed before launching the external CLI. A dangerous bypass (`--allow-dangerously-skip-permissions`) is only sent when autonomy is `full-auto` and `CLIO_CODER_ALLOW_EXTERNAL_FULL_ACCESS=1`, and it is never silent: the run's receipt records it (see the enforcement grades below) and evidence raises an external-bypass finding.
+- **External CLI subprocesses:** `claude-code` drives `claude -p`; the experimental, dispatch-only `antigravity-code` runtime drives the operator's local `agy` through one literal stdin `stream-json` work order. Neither exposes a callback through which Clio can evaluate each tool invocation, so Clio maps autonomy onto each CLI's command-line controls. Antigravity launches always name an explicit mode and disable slash-command expansion rather than inheriting mutable interactive settings. Dispatch at autonomy `suggest` is refused outright: a subprocess cannot park a tool call for approval, so `suggest` has no honest mapping and the runner fails closed before launch. A dangerous bypass (`--allow-dangerously-skip-permissions` for Claude or `--dangerously-skip-permissions` for Antigravity) is sent only when autonomy is `full-auto` and `CLIO_CODER_ALLOW_EXTERNAL_FULL_ACCESS=1`; otherwise Antigravity full-auto is capped at `accept-edits`. A bypass is never silent: the run's receipt records it (see the enforcement grades below) and evidence raises an external-bypass finding. Clio sends an allowlisted child environment rather than its provider keys or external-full-access gate, bounds stdout/stderr and persisted diagnostics, validates the admitted workspace, and owns the deadline and cancellation. POSIX cancellation targets the process group with direct-child fallback and bounded SIGTERM-to-SIGKILL escalation; Windows uses the strongest honest direct-child termination available here.
 - **Claude Code over ACP (Advisory Gating):** Drives Zed's `@zed-industries/claude-code-acp` (or `@agentclientprotocol/claude-agent-acp`) bridge as an [Agent Client Protocol (ACP)](https://agentclientprotocol.com) delegation agent. Clio's ACP mediator intercepts tool calls and filters them against the safety net, but gating is ultimately **advisory** as Claude governs its own runtime execution. For strict, code-enforced per-tool safety, `claude-sdk` is preferred over ACP.
 
 All Claude Code runtimes rely on the user's existing CLI authentication and store no credentials in Clio.
 
+External one-shot receipts also say what budget Clio can and cannot enforce. Clio
+controls one process launch, its wall-clock deadline, cumulative output cap,
+cancellation, and result-contract validation. Recipe per-tool calls, read reserve,
+and synthesis numbers remain in the envelope but are explicitly
+`unobserved-not-enforced`, because Antigravity owns its internal tools, network,
+prompts, and approvals. Clio schedules no automatic retry of an external
+generating agent loop.
+
 ### Autonomy enforcement grades
 
 How faithfully a runtime can honor the autonomy model is a recorded fact, not an assumption. Worker receipts carry an optional `autonomyEnforcement` block sealed into the integrity digest:

package/docs/guide/built-in-agents.md

@@ -64,7 +64,8 @@ Internal orchestration helpers and internal process agents. They are hidden from
 | Agent ID | Primary tools | Purpose | Capability | Latency |
 | --- | --- | --- | --- | --- |
 | `scout` | read, grep, find, ls, context, code_nav, git, ledger | Broad repository reconnaissance with cited findings: orientation, structure and entry-point mapping, multi-file symbol hunting. | `read-only` | `fast` |
-| `researcher` | read, web_fetch, context, ledger | Researches external docs, standards, and papers for coding decisions. | `read-only` | `deep` |
+| `researcher` | read, web_fetch, context, ledger | Extracts and compares concrete supplied URLs, standards, release notes, and papers through Clio-observed reads and URL retrieval. | `read-only` | `deep` |
+| `world-knowledge` | optional web_fetch, read, context, ledger | Current open-world discovery, ecosystem comparison, broad external context, and an advisory second opinion; reports when discovery is unavailable. | `read-only` | `deep` |
 | `provenance` | read, grep, find, ls, git, ledger | Reads receipts, diffs, and telemetry for evidence-backed handoffs. | `read-only` | `balanced` |
 | `oracle` | read, grep, find, ls, code_nav, context, ledger | Shadow advisor behind `/oracle` that protects consistency with prior decisions and returns the strongest challenge to a question. | `read-only` | `deep` |
 | `context-bootstrap` | read, grep, find, ls, context, code_nav | Internal agent behind `clio-coder context init` that parses repository and returns CLIO-CODER.md payload. | `read-only` | `balanced` |
@@ -75,6 +76,19 @@ The builtin `architect` also serves as the default author for a version 5 fleet
 
 Grounding is checked against the run's own reads, not just against the file. The worker records the exact line span every successful read returned, and a cited line must fall inside one. A line that exists in the file but was never read fails, which is what stops an approximated or inferred line number from passing as observation. `grep` and `code_nav` hits are leads: read the file before citing what they point at.
 
+The three discovery roles are deliberately non-overlapping. `scout` is
+repository-only reconnaissance with live `path:line` grounding and never browses
+external sources. `researcher` starts from concrete URLs or documents and uses
+Clio-observed `read`/`web_fetch` calls to extract and compare them; `web_fetch` is
+URL retrieval, not search. `world-knowledge` is for current open-world discovery,
+ecosystem comparison, broad context, and an independent advisory opinion. Its
+tools are all optional so it can run on a native Clio target or an opaque external
+worker. A native target without discovery must use caller-supplied sources or say
+discovery was unavailable. Its `world-knowledge-report` separates supported
+facts and supplied source identifiers from synthesis, uncertainty, and follow-up
+verification; it never fabricates citations. The capability class remains
+`read-only` regardless of the caller's requested autonomy.
+
 `oracle` is the only shadow agent an operator reaches directly, and only through
 `/oracle <question>`. It never receives a forked transcript. `/oracle` packs a
 bounded digest instead and sends it as dispatch briefing data: the settled
@@ -181,9 +195,9 @@ To ensure security and proper boundary isolation, shadow and internal agents are
 In addition to standard HTTP targets and [Agent Client Protocol (ACP)](https://agentclientprotocol.com) delegation agents, Clio dispatches subagents to sanctioned subscription worker runtimes:
 - **`claude-sdk` (Claude Agent SDK):** Serves as a main worker runtime for driving fleet agents. It integrates with [@anthropic-ai/claude-agent-sdk](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) alongside Clio's native subagent workers (like a local [llama.cpp](https://github.com/ggerganov/llama.cpp), [Ollama](https://ollama.com), [LM Studio](https://lmstudio.ai), [vLLM](https://github.com/vllm-project/vllm), or [SGLang](https://github.com/sgl-project/sglang) fleet) to execute tasks under a Claude subscription. Every tool call is mediated by Clio (`canUseTool` plus a `PreToolUse` hook): the safety net and autonomy matrix apply, and the run's admitted tool surface, which is narrowed by any `tool_profile`, is enforced authoritatively. Consequently, an out-of-profile tool (for example `bash` under `minimal-local`) is denied even though the underlying preset offers it. The narrowed surface is also translated into the SDK's `disallowedTools` option as defense in depth. Because it routes tool calls through Clio safety, it behaves as a native worker.
 - **`claude-code` (Claude Subprocess):** Runs `claude -p` as a subprocess worker, mapping autonomy levels to the CLI's permission modes. It is a black box: tool calls run inside the `claude` process and are not routed through Clio's per-tool mediation, so Clio cannot enforce a per-tool profile on it. Dispatching a narrowing `tool_profile` (`minimal-local` or `science-local`) to this runtime is refused; use `full-agent` (or a native / `claude-sdk` worker) instead.
-- **`antigravity-code` (Antigravity CLI):** Runs an Antigravity CLI subprocess as a subscription worker target for fleet dispatch. Like `claude-code`, it is a black box with no per-tool mediation and no per-tool allowlist, so a narrowing `tool_profile` is refused rather than silently ignored.
+- **`antigravity-code` (Antigravity CLI — experimental local delegation):** Runs the operator-installed and authenticated official `agy` command as a local external delegation worker. It is useful for a `world-knowledge` pass, a second opinion, or another bounded one-shot subtask; it is never an orchestrator or Gemini chat backend. Clio consumes agy's structured stream and live model catalog but cannot mediate individual tools, so a narrowing `tool_profile` is refused rather than silently ignored. The `world-knowledge` binding is permanently read-only.
 
-Agent budgets follow the same mediation boundary. Native workers and `claude-sdk` enforce canonical call counting, the canonical-`read` reserve, and the synthesis transition. Every valid Markdown recipe declares a budget, so recipe-based runs are refused on `claude-code` and `antigravity-code`; those subprocess targets can accept only work that reaches admission without an explicit recipe or request budget. Silently ignoring numeric bounds would be unsafe. Claude vendor aliases never appear in recipes or prompt authority and cannot reintroduce a canonical tool removed by admission.
+Agent budgets follow the same mediation boundary. Native workers and `claude-sdk` enforce canonical call counting, the canonical-`read` reserve, and the synthesis transition. An opaque external loop instead receives an `external-one-shot` enforcement classification: Clio enforces one subprocess launch, its deadline, output cap, cancellation, and result-contract validation, while recording recipe per-tool numbers as `unobserved-not-enforced`. Receipts and status never label those internal per-tool limits enforced, and Clio never automatically retries a generating external-agent run. Claude vendor aliases never appear in recipes or prompt authority and cannot reintroduce a canonical tool removed by admission.
 
 Interactive TUI:
 

package/docs/guide/commands-and-modes.md

@@ -78,7 +78,7 @@ For process exit codes, stdout deliverable guarantees, and machine-readable JSON
 | `clio-coder extensions list\|discover\|install\|enable\|disable\|remove` | Manage installed extension packages and resource roots. `clio-coder ext` is an accepted alias. |
 | `clio-coder skills list\|search\|inspect\|validate\|install\|update\|sync\|eval` | Manage discovered skills, Clio-native skills, and local marketplace installs. |
 | `clio-coder docs [topic] [--no-open]` | Serve the interactive HTML docs of a source checkout on 127.0.0.1; the npm package ships the Markdown guides only. |
-| `clio-coder usage report [--repo <path>] [--days <n>] [--json]` | Cross-session usage facts and opportunities from the session and run ledgers. The window defaults to 30 days and the JSON schema is marked experimental. |
+| `clio-coder usage report [--repo <path>] [--days <n>] [--json]` | Cross-session usage facts from session/run ledgers and retained out-of-turn calls, including known failed-compaction spending and missing coverage. The window defaults to 30 days and the JSON schema is marked experimental. |
 | `clio-coder dev share export --out <path> [--project\|--user\|--both] [--context] [--prompts] [--skills] [--settings] [--extensions]` | Export project context, prompts, skills, settings fragments, and extension bundles. |
 | `clio-coder dev share import <path> [--dry-run] [--force] [--project\|--user] [--json]` | Import a share archive with conflict reporting. |
 | `clio-coder dev share inspect <path> [--json]` | Inspect a share archive without importing it. |

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

@@ -3,7 +3,7 @@
 > **Visual blueprint:** The source checkout includes the complete
 > [Configuration, Targets, Runtimes, and Auth visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/configuration_blueprint.html).
 
-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 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 sanctioned subscription and external-worker runtimes described below.
 
 Clio's engine is built on the pi SDK (see [docs/architecture/pi-boundary.md](../architecture/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.
 
@@ -72,6 +72,15 @@ Start one local runtime and register exactly one target first. Clio integrates w
 - **[llama.cpp](https://github.com/ggerganov/llama.cpp):** A minimal C/C++ implementation for local LLM inference. Target runtime ID: `llamacpp`.
 - **[vLLM](https://github.com/vllm-project/vllm):** A high-throughput and memory-efficient LLM serving engine. Target runtime ID: `vllm`.
 - **[SGLang](https://github.com/sgl-project/sglang):** A fast serving framework for large language models. Target runtime ID: `sglang`.
+- **[LiteLLM](https://docs.litellm.ai):** An OpenAI-compatible gateway that publishes routed models across multiple inference endpoints. Target runtime ID: `litellm`.
+
+First-run onboarding always completes a valid orchestrator before it offers any
+worker-only colleague. If `agy` is already on `PATH`, the final optional step is
+named **Antigravity CLI — experimental local delegation**. It runs only the
+non-generating model-catalog probe, explains that Clio uses the operator's
+existing local session without inspecting credentials, and can create and bind a
+read-only `world-knowledge-external` profile. Skipping or failing that step does
+not change the primary chat, background, or fleet-default pointers.
 
 Common local runtime IDs and default URLs are:
 
@@ -82,6 +91,7 @@ Common local runtime IDs and default URLs are:
 | llama.cpp server | `llamacpp` | `http://127.0.0.1:8080` |
 | vLLM | `vllm` | `http://127.0.0.1:8000` |
 | SGLang | `sglang` | `http://127.0.0.1:30000` |
+| LiteLLM gateway | `litellm` | `http://127.0.0.1:4000` |
 
 
 Example registration:
@@ -230,11 +240,61 @@ integrations:
 
 Target capability overrides may include `chat`, `tools`, `toolCallFormat`, `reasoning`, `thinkingFormat`, `structuredOutputs`, `vision`, `audio`, `embeddings`, `rerank`, `fim`, `contextWindow`, and `maxTokens`.
 
+### LiteLLM gateways
+
+Register LiteLLM with its first-class runtime so discovery reads
+`/v1/model/info` rather than treating routed names as bare OpenAI models. For a
+gateway where placement matters, publish one deterministic `node/model` name
+per deployment instead of task categories such as `chat` or `code`:
+
+```yaml
+targets:
+  - id: ai-gateway
+    runtime: litellm
+    url: http://gateway.example:4000
+    defaultModel: dynamo/qwen3.8-27b
+    auth:
+      apiKeyEnvVar: CLIO_AI_GATEWAY_KEY
+    litellm:
+      request:
+        tags: [homelab]
+        sendSessionId: true
+        # Optional proxy overrides. Keep retries at zero for physical routes.
+        timeoutSeconds: 300
+        streamTimeoutSeconds: 180
+        numRetries: 0
+```
+
+Clio adds the `clio-coder` request tag and forwards its stable session id by
+default. Explicit `x-litellm-*` headers on the target or request take
+precedence. Set `sendSessionId: false` when the gateway must not correlate calls.
+The timeout values and `numRetries` become LiteLLM request headers and override
+the proxy's defaults only for this target. Clio disables the OpenAI SDK's
+client-side retry layer on LiteLLM requests. A failed interactive LiteLLM call
+also bypasses Clio's transient retry ladder even when `chat.retry` is enabled:
+the provider error names the selected route and tells the operator to choose a
+different one with `/model`. Configure `numRetries: 0` and no server fallback
+maps when `node/model` is a placement guarantee. Context-overflow compaction is
+still a local correction, not a route substitution.
+
+When the gateway reports these fields, Clio records LiteLLM's selected model group, physical model,
+sanitized upstream host, fallback/retry counts, and proxy timing in the session
+and worker receipt. A nonzero fallback or retry is also announced in the live
+transcript, making server-policy drift visible. Self-describing physical routes
+are summarized in probe diagnostics instead of expanding into a giant list of
+tautological mappings. If a genuine alias has multiple deployments, discovered
+capabilities are the conservative intersection and numerical limits are the
+smallest limits published by every deployment, so routing cannot select a
+weaker backend than Clio planned for. If `/v1/model/info` omits a capability,
+Clio does not invent it; that includes structured-output support.
+
+Upstream `model_info.runtime` declarations may identify the thinking-control dialect of a routed model. Clio accepts only recognized declarations shared by every deployment of that alias; unknown or mixed declarations remain unguessed. A resolved LM Studio dialect uses its explicit off effort, while llama.cpp uses template controls. This metadata does not turn the target into a native management endpoint: LiteLLM continues to own authentication, routing, loading and eviction. Thinking off is a request to the selected runtime/model, not evidence that the server complied or that every route has been live-validated.
+
 ### `maxConcurrentRequests`
 
 `maxConcurrentRequests` is a per-target integer of at least 1, validated with the rest of the target block, and it is the operator's override for how many requests the inference endpoint behind that target can serve at once. It is not a settings-file default and has no shipped value, so it does not appear in the settings inventory below.
 
-Set it only when discovery is wrong. Clio resolves the limit in this order: this override; then a `parallelSlots` count cached on the target's probe result; then one slot for any other `local-native` runtime; then no bound at all for a cloud runtime, vLLM, or SGLang. llama.cpp discovery reads `total_slots` from the router's `/props`, falls back to the selected worker's `/props?model=<id>` when the router reports none, and falls back again to the `--parallel` argv on the selected `/v1/models` entry. LM Studio reads `config.parallel` off the loaded instance and otherwise reports one; Ollama reads `OLLAMA_NUM_PARALLEL` from the environment the Clio process can see and otherwise reports one.
+Set it only when discovery is wrong. Clio resolves the limit in this order: this override; then a `parallelSlots` count cached on the target's probe result; then a persisted discovery result that is still fresh and matches the runtime; then one slot for any other `local-native` runtime; then no invented endpoint bound for a cloud runtime, LiteLLM, vLLM, or SGLang. llama.cpp discovery reads `total_slots` from the router's `/props`, falls back to the selected worker's `/props?model=<id>` when the router reports none, and falls back again to the `--parallel` argv on the selected `/v1/models` entry. LM Studio reads `config.parallel` off the loaded instance and otherwise reports one; Ollama reads `OLLAMA_NUM_PARALLEL` from the environment the Clio process can see and otherwise reports one.
 
 The limit is keyed on the endpoint rather than the target, so two targets pointed at the same normalized URL share it. Raising it above what the server will actually serve does not create capacity; it removes the refusal that would have told you the server was full. See [capacity-and-scheduling.md](../architecture/capacity-and-scheduling.md) for the admission model and the exact denial text.
 
@@ -612,6 +672,8 @@ This is the version-2 durable schema shipped in `DEFAULT_SETTINGS`. Validation i
 | `context.memory.maxOutputTokens` | `2000` | integer ≥ 1 | next turn |
 | `context.memory.timeoutMs` | `60000` | integer ≥ 1 | next turn |
 
+The compaction and memory controls serve different roles. An unset `context.compaction.model` uses active chat; an explicit model must uniquely resolve to an available eligible summary route or fail visibly. `context.compaction.systemPrompt` is a nonempty UTF-8 prompt file, at most 65,536 bytes, read at compaction time and resolved relative to the session workspace. Configure `context.memory.target` and `context.memory.model` to opt into model-based memory; unset roles remain rules-only. Memory prefers its dedicated route and can use active chat when that route is unavailable and request capacity permits. Known dedicated saturation skips the step rather than initiating failover; neither routing choice edits saved settings.
+
 ### Safety
 
 The safety-limit leaves have no one-process `CLIO_CODER_*` overrides in the current schema. Resolution follows the normal settings stack, from session or project layers where supported through user `settings.yaml`, then the compiled default.
@@ -824,17 +886,37 @@ integrations:
 ```
 Then invoke it using `/delegate claude-code <task>`.
 
-### 5. Google Antigravity CLI Runtime (Worker-Only)
+### 5. Antigravity CLI — Experimental Local Delegation (Worker-Only)
 
-The `antigravity-code` runtime drives your local Google Antigravity CLI (`agy`) installation to execute subagent tasks. It runs the CLI as a subprocess using the `agy --print` command and maps Clio autonomy levels onto the CLI's permission flags.
+The `antigravity-code` runtime is a local external delegation agent. It lets Clio ask an official Antigravity CLI (`agy`) installed and authenticated by the operator for research, world knowledge, a second opinion, or a bounded subtask. It is deliberately **not** a Gemini chat provider and can never become the Clio orchestrator.
 
-Google Antigravity supports a context window of up to 1,000,000 tokens and is suitable for large-context codebase reasoning. Because `agy` emits plain text without structured events, Clio cannot perform fine-grained tool call interception. Gating is applied coarsely: read-only runs pass both `--mode plan` (the no-change agent posture) and `--sandbox` (terminal restrictions). Full-auto passes `--dangerously-skip-permissions` only when the environment variable `CLIO_CODER_ALLOW_EXTERNAL_FULL_ACCESS=1` is explicitly set.
+This integration is experimental and intended only for personal use on your own machine. Clio does not install Antigravity, initiate Google sign-in, copy credentials, or read the CLI's credential store. Install the [official Antigravity CLI](https://antigravity.google/docs/cli/overview), run `agy` yourself to sign in, and keep it current. Clio then starts that same local executable for an explicit delegation. The integration feature-probes the required structured catalog; if the installed CLI lacks it, Clio asks the operator to update `agy` rather than relying on a hard-coded minimum version.
 
-Configured targets use your existing local `agy` login and credentials. Supported model names include `Gemini 3.5 Flash (High)` as the default tier, `Gemini 3.5 Flash (Medium)`, `Gemini 3.5 Flash (Low)`, `Gemini 3.1 Pro (High)`, `Gemini 3.1 Pro (Low)`, `Claude Sonnet 4.6 (Thinking)`, `Claude Opus 4.6 (Thinking)`, and `GPT-OSS 120B (Medium)`.
+Clio sends one literal prompt as a `stream-json` stdin record, closes stdin, and validates agy's init, delta, and single terminal-result sequence, including the opaque conversation identifier and provider-reported token counts. Prompt text never appears in argv and slash-command expansion is disabled. `clio-coder targets --probe --target <id>` runs the non-generating `agy --output-format json models` command and distinguishes missing CLI, sign-in required, CLI update required, unavailable live catalog, and configured-model disappearance. A successful account catalog is authoritative. The five built-in slugs are cold-start hints only; live `{id,label}` rows and last-good cached labels are displayed without replacing the stable model slug, and cached fallback is marked stale.
 
-**Configuration Example:**
+Antigravity remains an external agent loop: Clio cannot intercept each tool call. Every launch disables slash-command expansion and sets an explicit posture rather than inheriting mutable CLI defaults:
+
+| Clio autonomy | Antigravity launch posture |
+| --- | --- |
+| `read-only` | `--mode plan --sandbox` |
+| `auto-edit` | `--mode accept-edits` |
+| `suggest` | Refused because a headless subprocess cannot pause for Clio approval |
+| `full-auto` | Capped at `accept-edits` unless the external full-access gate is explicitly enabled |
+
+Only `full-auto` together with `CLIO_CODER_ALLOW_EXTERNAL_FULL_ACCESS=1` passes `--dangerously-skip-permissions`. Treat that as an external safety bypass: agy, not Clio's tool registry, controls the resulting filesystem, shell, network, prompts, and approvals. The gate is never enabled by onboarding. A `world-knowledge` dispatch remains read-only even if the caller requests a stronger posture; use another agent for mutation work.
+
+**Setup and verification:**
 ```bash
-clio-coder configure --id agy-worker --runtime antigravity-code --model "Gemini 3.5 Flash (High)"
+# Install using Google's instructions, then authenticate directly in the CLI.
+agy
+agy models
+
+# Use a live model slug, then create and bind a read-only research profile.
+clio-coder configure --id agy-research --runtime antigravity-code \
+  --model gemini-3.8-flash-high \
+  --agent-profile world-knowledge-external \
+  --bind-agent world-knowledge
+clio-coder targets --probe --target agy-research
 ```
 
 
@@ -851,6 +933,7 @@ Useful flags:
 | `--fleet-model <id>` | Model to save for fleet default. |
 | `--agent-profile <name>` | Save this target/model as a named fleet profile. |
 | `--agent-profile-model <id>` | Model to save for the named fleet profile. |
+| `--bind-agent <agentId>` | Bind the agent to `--agent-profile` in the same configuration write; requires `--agent-profile`. |
 | `--api-key-env <VAR>` | Read API key from the environment at call time. |
 | `--api-key <literal>` | Store an API key in `credentials.yaml`. |
 | `--force` | Allow model/capability choices outside the local catalog guardrails. |
@@ -968,6 +1051,11 @@ Model rows combine:
 2. runtime-discovered models from probes;
 3. known models from bundled/provider catalogs.
 
+Each row reports its stable model id, optional human label, and source
+(`live`, cached, configured/default, or catalog). When a live authoritative
+catalog exists, a disappeared configured model is unavailable rather than being
+resurrected by a descriptor hint.
+
 Capability badges in CLI output are compact:
 
 | Badge | Capability |
@@ -990,7 +1078,7 @@ Representative built-in runtime IDs:
 | --- | --- |
 | Protocol-compatible | `openai-compat`, `anthropic-compat` generic surfaces for additional OpenAI-compatible or Anthropic-compatible APIs, including APIs such as InceptionAI when configured with the appropriate base URL and credentials. |
 | Cloud | `alcf`, `anthropic`, `bedrock`, `deepseek`, `google`, `groq`, `mistral`, `openai`, `openrouter` |
-| Subscription and worker harnesses | `openai-codex` for ChatGPT OAuth, `anthropic-max` for Anthropic OAuth, `claude-sdk` for Claude Agent SDK workers, `claude-code` for `claude -p` subprocess workers, and `antigravity-code` for `agy --print` subprocess workers |
+| Subscription and worker harnesses | `openai-codex` for ChatGPT OAuth, `anthropic-max` for Anthropic OAuth, `claude-sdk` for Claude Agent SDK workers, `claude-code` for `claude -p` subprocess workers, and `antigravity-code` for structured `agy` external delegation |
 | Local native | `llamacpp`, `lmstudio`, `ollama-native`, `vllm`, `sglang`, `lemonade`, `lemonade-anthropic` |
 
 Some hidden aliases exist for backward compatibility or special surfaces; use `clio-coder configure --list --all` to see them.

package/docs/guide/configuration-reference.md

@@ -29,8 +29,8 @@ Precedence, where several surfaces set the same value: a one-run CLI flag beats
 | `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`, Alt+J/K, `/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`, Alt+J/K, `/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.compaction.model` |  | Optional `provider/model` pattern resolved for the summary model when compaction runs; absent means the chat target summarizes; applies next turn. |  |
-| `context.compaction.systemPrompt` |  | Optional path to a prompt-override file read at compaction time to replace the built-in summary prompt; applies next turn. |  |
+| `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 |
@@ -165,6 +165,11 @@ Precedence, where several surfaces set the same value: a one-run CLI flag beats
 | `targets[].lmstudio.request.draftModel` |  | Sends `draft_model` on OpenAI-compatible chat requests for speculative decoding (model id string). |  |
 | `targets[].lmstudio.request.reasoning` |  | How `reasoning_effort` is sent: `auto` maps the active thinking level, `off` sends `none`, `on` sends `low`, `low`/`medium`/`high` are literal but clamped to the efforts the model advertises. |  |
 | `targets[].lmstudio.request.ttlSeconds` |  | Sends `ttl` on chat requests so LM Studio auto-evicts the model after this idle time in seconds (integer >= 1). |  |
+| `targets[].litellm.request.numRetries` |  | Optional LiteLLM router retry override sent as `x-litellm-num-retries` (integer >= 0); use `0` for deterministic physical routes. The OpenAI SDK and Clio interactive transient-retry layers remain disabled for LiteLLM failures. |  |
+| `targets[].litellm.request.sendSessionId` | `true` | Whether Clio forwards its stable session id as `x-litellm-session-id` (boolean); applies when the next LiteLLM agent runtime is created. |  |
+| `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[].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[].pricing.cacheRead` | `0` | USD rate for cache-read tokens (number >= 0); 0 when absent. |  |
 | `targets[].pricing.cacheWrite` | `0` | USD rate for cache-write tokens (number >= 0); 0 when absent. |  |

package/docs/guide/environment-variables.md

@@ -113,6 +113,8 @@ Set by Clio for its own processes; not operator knobs.
 | --- | --- |
 | `CLIO_CODER_WORKER_FAUX` (+ `_MODEL`, `_TEXT`, `_STOP_REASON`, `_ERROR_MESSAGE`) | Fake worker model for tests (`src/engine/ai.ts`). |
 | `CLIO_CODER_TEST_UPGRADE_NO_NETWORK` | Skips npm install during upgrade tests (`src/cli/upgrade.ts`). |
+| `CLIO_CODER_TEST_UPGRADE_AVAILABLE` | Sets mock available version for upgrade tests; `unreachable` stands for a registry that answered nothing (`src/cli/upgrade.ts`). |
+| `CLIO_CODER_TEST_UPGRADE_FAIL` | Injects mock failures (`npm` or `migration`) for upgrade tests (`src/cli/upgrade.ts`). |
 | `CLIO_CODER_TEST_STAGE1_DELAY_MS`, `CLIO_CODER_TEST_STAGE1_FAIL` | `NODE_ENV=test`-only, bounded instant-shell interleaving and injected hydration failure seams for the built PTY acceptance suite (`src/cli/clio.ts`). |
 | `CLIO_CODER_REQUIRE_HOME_PREFIX` | Test guardrail: abort if resolved directories escape `CLIO_CODER_HOME` (`src/core/init.ts`). |
 

package/docs/guide/installation-and-lifecycle.md

@@ -193,7 +193,7 @@ Runs a series of health sweeps across the environment:
 ### B. Upgrades (`clio-coder upgrade`)
 Refreshes state metadata and applies pending lifecycle migrations, which may update settings, state, or extension data.
 ```bash
-clio-coder upgrade [--dry-run] [--channel=<latest|beta|dev>] [--skip-migrations]
+clio-coder upgrade [--dry-run] [--channel=<latest|beta|dev>] [--skip-migrations] [--json]
 ```
 The command detects the install method from the running binary. On a source
 checkout it never runs `npm install -g`: it performs its safe local duties
@@ -289,7 +289,7 @@ keyboard-facing text; all other target versions use the generic form
 ### C. System Resets (`clio-coder reset`)
 Selective recovery wipes:
 ```bash
-clio-coder reset [--state|--data|--cache|--auth|--config|--all] [--dry-run] [--force]
+clio-coder reset [--state|--data|--cache|--auth|--config|--all] [--dry-run] [--force] [--json]
 ```
 Levels are combinable except `--all`. Each level clears exactly the root or file it names and nothing else, then bootstraps the missing structure again unless `--dry-run` is present. `--force` is required only for destructive execution.
 
@@ -311,7 +311,7 @@ new artifact is written into a root.
 removes all four roots (config, data, state, cache):
 
 ```bash
-clio-coder uninstall [--remove-binary] [--dry-run] [--force]
+clio-coder uninstall [--remove-binary] [--keep-config] [--keep-data] [--dry-run] [--force] [--json]
 ```
 
 Preview first, then remove:
@@ -325,7 +325,9 @@ hash -r
 `--dry-run` prints the roots and the optional launcher action without changing
 anything, and enumerates the same resolved absolute paths the real run would
 remove. It prints binary-removal guidance for the active launcher, npm-global
-installs, npm links, and the local source symlink.
+installs, npm links, and the local source symlink. Use `--keep-config` to preserve
+`settings.yaml` and `credentials.yaml`, or `--keep-data` to preserve memory and
+evidence.
 
 #### Per-project `.clio-coder/` directories
 
@@ -379,6 +381,37 @@ commands are idempotent, so the recovery is always the same: fix the permission
 or release the handle, then run the identical command again and it resumes from
 whatever is left. A partial delete never reports global success.
 
+### E. Interactive Configuration (`clio-coder configure`)
+`clio-coder configure` provides a structured, multi-section configuration wizard
+for model targets, runtime defaults, fleet limits, permissions, panes, and
+integrations:
+
+```bash
+clio-coder configure [--section <name>] [--json] [--interop] [--list] [--all]
+```
+
+When run against an unconfigured home (or when launched interactively with no
+model target), it routes immediately to the target category selection menu. Once
+targets are configured, launching `clio-coder configure` presents the 8 top-level
+runtime sections:
+
+1. **Targets & Auth**: manage providers, endpoints, credentials, and models.
+2. **Models & Thinking**: default models, thinking levels, model favorites, cycle set.
+3. **Chat Defaults**: smooth streaming, terminal progress, token limits, compaction.
+4. **Fleet**: concurrency, retries, tool call caps, worker timeouts, profiles.
+5. **Permissions & Autonomy**: autonomy level, worker permissions, cost limits, review watchdog.
+6. **Panes & Layout**: terminal panes capability, dock layout, TUI display mode, notifications.
+7. **Skills & Extensions**: trust project imports, external ACP agents, plugins, library sync.
+8. **Diagnostics**: version information, resolved directories, doctor check, raw settings inspection.
+
+Every section header indicates the exact settings file path being modified
+(`Source: ~/.config/clio-coder/settings.yaml`), prints the current active values,
+and provides a safe back/exit option (`b` or `q`).
+
+The `--section <name>` flag jumps directly into any section (e.g.,
+`clio-coder configure --section models` or `clio-coder configure --section fleet`).
+The `--json` flag emits the active settings in formatted JSON for scripting.
+
 ---
 
 ## 6. Residues Checklist for Manual Purging