@iowarp/clio-coder 0.4.2 → 0.4.4

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. |
@@ -103,7 +103,6 @@ For process exit codes, stdout deliverable guarantees, and machine-readable JSON
 | `--temperature <n>` / `--top-p <n>` / `--top-k <n>` / `--min-p <n>` | One-run sampler overrides when the selected runtime supports them. |
 | `--presence-penalty <n>` / `--frequency-penalty <n>` / `--repeat-penalty <n>` | One-run penalty overrides when the selected runtime supports them. |
 | `--max-context-tokens <n>` | One-run context-window override for supported local runtimes. |
-| `--kv-cache-mode <mode>` | One-run KV-cache override for supported local runtimes: `f16`, `f32`, `none`, `false`, `q8_0`, `q4_0`, `q4_1`, `iq4_nl`, `q5_0`, or `q5_1`. |
 | `--json` | Stream JSONL events for main-agent runs; dispatch streams events and receipt JSON. |
 | `--json-events <mode>` | Main-agent JSON stream mode: `full` or `terminal`; implies `--json`. |
 | `--session <id>` | Append this turn to an existing session identified by `<id>`. |
@@ -182,7 +181,7 @@ The registry table below lists the available interactive slash commands. On a ba
 | `/context` | `/context compact [instructions] \| /context recall <ref> \| /context init \| /context refresh \| /context reset` | Context hub: window overlay plus compact, recall, init, refresh, and reset |
 | `/fleet` | `/fleet run [--var <key=value>] <name>` | Open Settings → Fleet, or run a fleet contract with an approval preview |
 | `/decisions` | `/decisions` | Show settled interview decisions and operator revisions |
-| `/tasks` | `/tasks add <text> \| /tasks hand <id> \| /tasks done <id> \| /tasks drop <id>` | Show the session board or manage project operator tasks |
+| `/tasks` | `/tasks add [--expect <path>] [--verify <checkId>[:timeoutMs]] <text> \| /tasks hand <id> \| /tasks done <id> \| /tasks drop <id>` | Show the session board or manage project operator tasks |
 | `/memory` | `/memory seed` | Inspect, promote, or seed task memory |
 | `/view` | `/view [filter] \| /view verify <runId>` | Browse session artifacts and verify receipts |
 | `/panes` | `/panes show <run-or-agent> \| /panes open <preset-or-argv> \| /panes zoom [target] \| /panes close [target]` | Inspect the pane layer, watch a live run in a pane, or open a utility pane (`files`, `logs`, `shell`, `files --once`, or a command); a second open focuses the pane already there |
@@ -198,6 +197,22 @@ The registry table below lists the available interactive slash commands. On a ba
 | `/fork` | `/fork` | Fork from an assistant turn |
 | `/export` | `/export [path]` | Export a self-contained HTML transcript by default; a `.md` path writes Markdown |
 
+Operator tasks are durable project work in `.clio-coder/user-tasks.json`. Use
+`clio-coder tasks add "Fix the solver" --expect src/solver.ts --verify test:solver:60000`
+or `/tasks add Fix the solver --expect src/solver.ts --verify test:solver:60000`.
+Both `--expect <path>` and `--verify <checkId>[:timeoutMs]` are repeatable. Expected
+outputs use repository-relative paths; verification ids must exist in the project
+verifier catalog or package scripts when added. An omitted timeout uses the
+check's declared timeout, and requested timeouts are bounded as in dispatch
+intent. If a complete value matches a declared id containing colons, it names
+that check; otherwise the final numeric suffix is the timeout. Acceptance travels
+with the task when handed and picked, and seeds the board's required validation
+evidence. Under high rigor, a turn that changes files while this task is active
+must record a passing validation receipt for every named check or a successful
+`limitation` receipt whose `paths` array includes the exact check id. A task's
+completion note alone does not satisfy acceptance. `clio-coder tasks list`,
+`hand <uN>`, `done <uN>`, and `drop <uN>` manage the same inbox as `/tasks`.
+
 Retired spellings fail closed and print their exact replacement. In particular,
 `/targets` points to `/settings targets`, `/scoped-models` points to
 `/settings chat model-picker`, and `/library`, `/prompts`, and `/extensions`

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.
 
@@ -252,7 +312,7 @@ The tool-prose-loop detector is keyed on the same tier, for the same reason: nar
 
 ### LM Studio transport and settings
 
-The canonical runtime id is `lmstudio`. The former `lmstudio-native` id remains an accepted alias,
+The canonical runtime id is `lmstudio`. The former `lmstudio-native` id remains an accepted alias scheduled for removal in v0.7.0,
 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
@@ -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,39 @@ 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 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.
 
-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.
+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.
 
-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.
+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.
 
-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)`.
+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 |
 
-**Configuration Example:**
+Launch flags are a request to agy rather than a guarantee. Headless agy reports `permission_mode: always-proceed` even under `--mode plan --sandbox`, and Clio grades autonomy enforcement as `approximated` in execution receipts. The only Clio-enforced read-only boundary is the receipt grade.
+
+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 +935,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 +1053,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 +1080,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. |  |
@@ -191,6 +196,7 @@ Read from the process environment at boot unless the row says otherwise.
 | `CLIO_CODER_CACHE_DIR` | `platform default (`$XDG_CACHE_HOME/clio-coder`, else `~/.cache/clio-coder`)` | Absolute path for the cache root; beats `CLIO_CODER_HOME/cache` and the platform default, and the fleet-view pane child re-pins it from argv. | env > `CLIO_CODER_HOME/cache` > `XDG_CACHE_HOME` or platform default |
 | `CLIO_CODER_COMMIT_ASSISTED` | `unset` | Set by Clio to `1`/`0` per spawn from the run's attribution evidence; the managed `prepare-commit-msg` hook reads it to append the assisted trailer, and nested seams strip it. |  |
 | `CLIO_CODER_COMMIT_AUTHORED` | `unset` | Set by Clio to `1`/`0` per spawn from the run's attribution evidence; the managed `prepare-commit-msg` hook reads `1` to add the co-authored trailer, and nested seams strip it. |  |
+| `CLIO_CODER_COMMIT_DECISIONS` | `unset` | Set by Clio per spawn to the space-separated decision refs (`<interviewId>/<key>`) active on the session decision board; the managed `prepare-commit-msg` hook writes one `Clio-Decision:` trailer per well-formed ref, and nested seams strip it. |  |
 | `CLIO_CODER_CONFIG_DIR` | `platform default (`$XDG_CONFIG_HOME/clio-coder`, else `~/.config/clio-coder`)` | Absolute path for the config root; beats `CLIO_CODER_HOME/config` and the platform default, and the fleet-view pane child re-pins it from argv. | env > `CLIO_CODER_HOME/config` > `XDG_CONFIG_HOME` or platform default |
 | `CLIO_CODER_DATA_DIR` | `platform default (`$XDG_DATA_HOME/clio-coder`, else `~/.local/share/clio-coder`)` | Absolute path for the data root; beats `CLIO_CODER_HOME/data` and the platform default, and the fleet-view pane child re-pins it from argv. | env > `CLIO_CODER_HOME/data` > `XDG_DATA_HOME` or platform default |
 | `CLIO_CODER_DEBUG_SHUTDOWN` | `unset (disabled)` | Exactly `1` prints timed `[clio-coder:shutdown]` phase lines and full stack traces of failing domain `stop()` hooks to stderr during shutdown. |  |
@@ -219,8 +225,8 @@ Read from the process environment at boot unless the row says otherwise.
 | `CLIO_CODER_REDUCE_MOTION` | `unset (disabled)` | Exactly `1` makes smooth-streaming `auto` use the immediate coalescer; explicit `on` is unaffected. |  |
 | `CLIO_CODER_RENDER_TRACE` | `unset (disabled)` | File path for the versioned JSONL render-pipeline trace (timing only, no conversation text), truncated on open; off when unset or empty. |  |
 | `CLIO_CODER_REQUIRE_HOME_PREFIX` | `unset (disabled)` | Exactly `1` aborts startup when any resolved Clio directory lies outside `CLIO_CODER_HOME`; a test-harness guardrail that does nothing when `CLIO_CODER_HOME` is unset. |  |
-| `CLIO_CODER_RIGOR` | `repo-derived` | `high` or `normal` (case-insensitive) overrides the finish-contract evidence bar for the orchestrator and dispatched workers; any other value means no override. | env > workspace validation contract file (`.clio-coder/validation.yaml`, `validation.yaml`, `VALIDATION.md` raise it to `high`) > `normal`; no settings key |
-| `CLIO_CODER_RUN_OVERRIDES` | `unset` | JSON object (`maxContextTokens`, `kvCacheMode`, `sampling`) that `clio-coder run` and print modes write via `withRunOverrides` for the run's scope; workers inherit it and malformed input is dropped. |  |
+| `CLIO_CODER_RIGOR` | `repo-derived` | `high` or `normal` (case-insensitive) overrides the finish-contract evidence bar for the orchestrator and dispatched workers; any other value means no override. | env > a parsed workspace validation contract (`.clio-coder/validation.yaml` or `validation.yaml`, version 1) raises it to `high`; an invalid contract or a Markdown-only `VALIDATION.md` leaves `normal` > `normal`; no settings key |
+| `CLIO_CODER_RUN_OVERRIDES` | `unset` | JSON object (`maxContextTokens`, `sampling`) that `clio-coder run` and print modes write via `withRunOverrides` for the run's scope; workers inherit it and malformed input is dropped. |  |
 | `CLIO_CODER_SCREEN_READER` | `unset (disabled)` | Exactly `1` makes smooth-streaming `auto` use the immediate coalescer so a screen reader gets the low-motion update behavior; explicit `on` is unaffected. |  |
 | `CLIO_CODER_SHUTDOWN_HOOK_MS` | `500` | Positive integer milliseconds each shutdown and domain `stop()` hook may run before the coordinator moves on; non-positive or unparsable values use the default. |  |
 | `CLIO_CODER_SKILL_CATALOG_DIR` | `unset` | Path to a local skill catalog used by the marketplace and the provenance pin manifest; beats `<cwd>/skills` and the packaged catalog but not an explicit catalogDir option. | explicit catalogDir option > env > `<cwd>/skills` > packaged catalog |
@@ -609,7 +615,6 @@ Grouped by command. Global flags appear under `global`.
 | `--help` | Print the command's usage and exit. |
 | `--json` | Stream JSONL events for the main-agent turn (dispatch streams events plus the receipt JSON) instead of text output. |
 | `--json-events` | Main-agent JSON stream mode: `full` or `terminal`; implies `--json`. |
-| `--kv-cache-mode` | One-run KV-cache override for supported local runtimes: `f16`, `f32`, `none`, `false`, `q8_0`, `q4_0`, `q4_1`, `iq4_nl`, `q5_0`, or `q5_1`. |
 | `--max-context-tokens` | One-run context-window override (positive integer tokens) for supported local runtimes. |
 | `--min-p` | One-run min-p override (0 to 1) when the selected runtime supports it. |
 | `--model` | Wire model id for this run's main agent or dispatched worker instead of the target's default. |
@@ -880,7 +885,7 @@ Keys read from files under `.clio-coder/` in the repository.
 
 | Key | Controls | Precedence |
 |---|---|---|
-| `(presence)` | The file's presence (also `validation.yml`, root `validation.yaml`, or `VALIDATION.md`) raises the repo-derived rigor default from `normal` to `high`; its content is not read. | `CLIO_CODER_RIGOR` > presence of a validation contract > `normal` |
+| `version`, `task`, `runtime`, `artifacts`, `validators`, `notes` | The version-1 scientific validation contract (also `validation.yml`, root `validation.yaml`, or `validation.yml`). A contract that parses raises the repo-derived rigor default from `normal` to `high`; one that does not parse is diagnosed by `clio-coder doctor` and at interactive startup and leaves `normal`. `VALIDATION.md` is advisory prose and never raises rigor. Schema in [Scientific Validation](../process/scientific-validation.md). | `CLIO_CODER_RIGOR` > parsed validation contract > `normal` |
 
 ### `.clio-coder/verifiers.yaml`
 
@@ -893,7 +898,12 @@ Keys read from files under `.clio-coder/` in the repository.
 | `checks[].id` | Check id, at most 64 bytes; `frontend` is reserved for the built-in artifact check. |  |
 | `checks[].tags` | Free-form labels, at most 16 of 32 bytes, shown in the listing. |  |
 | `checks[].timeoutMs` | Required wall-clock cap for the check in ms, a positive integer at most 900000; a `verify` call may shorten it with `timeout_ms` but not exceed it. |  |
-| `version` | Catalog schema version; must equal the version this build speaks. |  |
+| `checks[].kind` | `command` (default, exit code), `numeric-compare` (stdout JSON judged against `reference` under `tolerance`), or `perf-budget` (wall time judged against `budget` or `baseline`). Requires `version: 2`. |  |
+| `checks[].reference` | `numeric-compare` only: repository-relative JSON file of `string -> number \| number[]` the command output is compared against. |  |
+| `checks[].tolerance` | `numeric-compare`: at least one of `relative`, `absolute`, `ulp`; every named bound must hold. `perf-budget` with `baseline`: `{relative}` headroom over the recorded time. |  |
+| `checks[].budget` | `perf-budget` only: `{wallTimeMs, tolerance?: {relative}}`; exclusive with `baseline`. |  |
+| `checks[].baseline` | `perf-budget` only: repository-relative JSON `{wallTimeMs}` written by `clio-coder verifiers baseline <id>`; exclusive with `budget`. |  |
+| `version` | Catalog schema version, `1` or `2`; version 1 files load with every check as `kind: command`. |  |
 
 ## Agent recipe frontmatter
 

package/docs/guide/environment-variables.md

@@ -96,10 +96,10 @@ Set by Clio for its own processes; not operator knobs.
 | --- | --- |
 | `AI_AGENT` | Clio sets this generic child-process attribution marker to `clio-coder` at both shipped entry points and reinforces it for bash tools, fleet workers, registered code steps, and command hooks. Child tooling may read it to identify the agent that launched it (`src/cli/index.ts`, `src/worker/entry.ts`, `src/core/bash-exec.ts`). |
 | `CLIO_CODER_GIT_COMMITS_ENABLED` | Carries the effective `integrations.git.commitAttribution` setting to Clio-controlled child-process seams. It is set from validated settings and is not an operator override (`src/core/git-commit-attribution.ts`). |
-| `CLIO_CODER_COMMIT_ASSISTED`, `CLIO_CODER_COMMIT_AUTHORED` | Per-spawn inputs to the managed `prepare-commit-msg` hook, which also requires `AI_AGENT=clio-coder` and `CLIO_CODER_GIT_COMMITS_ENABLED=1`; normal external shells never receive this set. Only assistance and authorship cross the environment. Testing, review, and receipt trailers are composed in process by the fleet seam, so a child shell cannot forge them by exporting a variable (`src/core/git-commit-attribution.ts`). |
+| `CLIO_CODER_COMMIT_ASSISTED`, `CLIO_CODER_COMMIT_AUTHORED`, `CLIO_CODER_COMMIT_DECISIONS` | Per-spawn inputs to the managed `prepare-commit-msg` hook, which also requires `AI_AGENT=clio-coder` and `CLIO_CODER_GIT_COMMITS_ENABLED=1`; normal external shells never receive this set. Only assistance, authorship, and the space-separated decision refs the spawn was made under cross the environment. Testing, review, and receipt trailers are composed in process by the fleet seam, so a child shell cannot forge them by exporting a variable (`src/core/git-commit-attribution.ts`). |
 | `CLIO_CODER_GIT_CONFIG_BASE_COUNT`, `CLIO_CODER_GIT_DEFAULT_HOOKS_EQUIVALENT` | Bookkeeping that lets each managed hook wrapper remove only Clio's command-scope `core.hooksPath` pair before chaining the repository's own hook of the same name. Existing `GIT_CONFIG_COUNT` entries remain in force; an explicit `core.hooksPath` is treated as composable only when it resolves exactly to the repository's default hooks directory (`src/core/git-commit-attribution.ts`). |
 | `CLIO_CODER_INTERACTIVE` | Marks the interactive TUI process; scrubbed from bash-tool children so nested invocations do not inherit it (`src/cli/clio.ts`, `src/core/bash-exec.ts`). |
-| `CLIO_CODER_RUN_OVERRIDES` | JSON envelope for run-scoped CLI options (`--max-context-tokens`, `--kv-cache-mode`, sampling flags). One typed variable instead of one env var per option; worker subprocesses inherit it (`src/core/run-overrides.ts`). |
+| `CLIO_CODER_RUN_OVERRIDES` | JSON envelope for run-scoped CLI options (`--max-context-tokens`, sampling flags). One typed variable instead of one env var per option; worker subprocesses inherit it (`src/core/run-overrides.ts`). |
 | `CLIO_CODER_EVAL_RUNNER_STDOUT_FILE` | Set by the eval runner for the `clio-coder run` child it spawns; the child appends its stdout to that path so the runner can read it after exit (`src/domains/eval/suites/run.ts`). |
 | `CLIO_CODER_YAZI_PICK_TOKEN` | Per-session token the yazi file-pane integration hands its yazi child and expects back on a pick, so a pick from another session is ignored (`src/domains/mux/yazi/session.ts`, `src/domains/mux/yazi/profile.ts`). |
 | `CLIO_CODER_WORKER_LABELS` | Comma-separated labels a dispatched worker reports as its own (`src/domains/dispatch/transport.ts`, `src/worker/entry.ts`). |
@@ -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