@iowarp/clio-coder 0.4.7 → 0.4.9

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

@@ -1,8 +1,5 @@
 # Configuration, Targets, Runtimes, and Auth
 
-> **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 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.
@@ -399,7 +396,7 @@ Three behaviors in this release are gated on a runtime's tier being `local-nativ
 
 The tier means "an inference server the operator runs, whose prefix cache and resident model Clio's own behavior can displace." That is what the three gates are actually asking:
 
-- **Pre-warm** runs only here, whatever `chat.prewarm` says, because a cloud provider bills the request and caches on its own schedule. The check is made twice, once from configuration before any runtime is resolved and once against the resolved runtime, so an unreachable target does not pay for a capability probe at boot just to be told no.
+- **Pre-warm** requires `chat.prewarm: true` and a verified, loaded and idle native deployment binding. The first supported path is the pinned llama.cpp deployment described below. Other native runtimes, unknown gateway routes and paid routes remain passive. Checks run before preparation and again before the request; a runtime tier alone grants no load or eviction authority.
 - **Endpoint capacity** defaults to one slot here when discovery reports nothing, and to unbounded elsewhere. vLLM and SGLang are the deliberate exceptions inside the tier: both serve genuinely concurrent requests, so an undiscovered limit is left unbounded rather than guessed at one.
 - **Five of the eight expected-cold reasons** are stamped only here, because a single-slot local cache is the only one an interleaved run actually displaces. The other three moved the prompt bytes themselves and are stamped on every tier. The full split is in [context-engine.md](../architecture/context-engine.md#cache-divergence-honesty).
 
@@ -610,10 +607,11 @@ paths and stop startup so stale configuration does not silently change runtime
 behavior.
 
 Plain `clio-coder doctor` is read-only. `clio-coder doctor --fix` creates missing
-directories and template files, repairs credential permissions, and refreshes
-install metadata. It validates `settings.yaml` directly against the current
-schema but never rewrites removed keys or migrates an old settings shape. Any
-unknown or retired key remains a validation error on that doctor run.
+directories and template files, repairs credential permissions, refreshes
+install metadata, and records fleet preflight results. It validates
+`settings.yaml` directly against the current schema but never rewrites removed
+keys or migrates an old settings shape. Any unknown or retired key remains a
+validation error on that doctor run.
 Registered `clio-coder upgrade` migrations are the narrow exception. Upgrade
 moves a version-1 or unversioned settings document into the version-2 areas,
 records the migration, and keeps the byte-exact original as
@@ -717,6 +715,7 @@ This is the version-2 durable schema shipped in `DEFAULT_SETTINGS`. Validation i
 | `chat.retry.baseDelayMs` | `2000` | integer ≥ 0 | next turn |
 | `chat.retry.maxDelayMs` | `60000` | integer ≥ 0 | next turn |
 | `chat.retry.streamStallMs` | `180000` | integer ≥ 0; `0` disables the stall timer | next turn |
+| `chat.retry.firstTokenStallMs` | `600000` | integer ≥ 0; silence allowed before a call's first token; `0` never aborts before the first token | next turn |
 
 ### Fleet
 
@@ -812,7 +811,7 @@ The safety-limit leaves have no one-process `CLIO_CODER_*` overrides in the curr
 | `integrations.projectResources.trustProjectImports` | `false` | boolean | next turn |
 | `integrations.externalAgents.entries` | `[]` | list of validated ACP agent definitions | next dispatch |
 | `integrations.externalAgents.defaults.connectTimeoutMs` | `30000` | integer ≥ 1 | next dispatch |
-| `integrations.externalAgents.defaults.turnTimeoutMs` | `300000` | integer ≥ 1 | next dispatch |
+| `integrations.externalAgents.defaults.turnTimeoutMs` | `0` | integer ≥ 0; `0` disables the turn timeout | next dispatch |
 | `integrations.externalAgents.defaults.permissionTimeoutMs` | `120000` | integer ≥ 1 | next dispatch |
 | `integrations.externalAgents.defaults.toolGovernance` | `clio-coder-policy` | `clio-coder-policy`, `agent-managed`, `deny-all` | next dispatch |
 | `integrations.runtimePlugins` | `[]` | list of plugin package names | restart |
@@ -1241,3 +1240,199 @@ When opening issues, include the Clio version, Node version, target id/runtime,
 ## Explicit Antigravity continuity
 
 Antigravity resumes a conversation only when a caller explicitly supplies its conversation ID through the worker runtime. The dispatch tool exposes no resume argument. A nonempty ID must be at most 4096 UTF-8 bytes and contain no Unicode control characters; it is passed as a literal `--conversation` argument. Clio requires the first init conversation ID to match the requested ID and fails the run if agy starts a different conversation. An absent or empty ID starts fresh. Antigravity runs are never retried automatically.
+
+## Exact prompt reuse and bounded warming
+
+Normal provider caching does not require Clio to manage inference state. Pi
+serializes native requests and normalizes provider usage; Clio preserves those
+values through the session ledger, worker receipts and trace records. A matching
+serialized prefix is a reuse candidate. Only backend usage/timing evidence can
+establish an actual hit. A compiler memoization hit or a forked transcript cannot.
+
+| Responsibility | Existing owner | Clio correction or limit |
+| --- | --- | --- |
+| Native request conversion, thinking history and cache controls | Pi 0.85.1 | Target retention reaches all instrumented native Pi APIs; explicit call options still win. |
+| Exclusive input/read/write buckets, cost tiers and one-hour write cost | Pi | Preserve the full catalog cost and per-call calculated total instead of flattening tiers or repricing an aggregate. |
+| Main, worker, failed/aborted and out-of-turn usage | Clio | Preserve optional `cacheWrite1h` as a subset of writes; retain billed failed calls. Missing provider usage remains unknown. |
+| Main and warm preparation | Pi public transforms and Clio payload hooks | Warm calls use the caller's transforms, ordered tools, thinking and payload replacement without executing tools or adding messages to history. |
+| Session transport identity | Pi/Clio session ownership | `sessionId` remains the real session id. No fleet-wide cache key replaces it. |
+| Distinct cross-session cache affinity, separately configured one-hour rate | SDK contract gap | No duplicate serializer or price calculator is introduced. Pi's supported provider pricing remains authoritative. |
+
+A native Pi target can request retention without enabling warming:
+
+```yaml
+targets:
+  - id: direct-openai
+    runtime: openai
+    cache:
+      retention: long
+```
+
+Precedence is explicit request option, then target, then
+`CLIO_CODER_ANTHROPIC_CACHE_RETENTION` for native Anthropic Messages, then Pi's
+own environment/default. Targets reload on the next turn, including when the
+id and model stay the same. The active conversation survives the runtime refresh.
+There are no duplicate model, recipe or fleet retention knobs.
+
+| API/deployment | Effective policy and current verification |
+| --- | --- |
+| Native OpenAI Responses, older supported models | Pi's model compatibility flags select `24h` for `long`. `none` omits controls; it does not universally disable automatic caching. Payload fixtures cover this path. |
+| Native OpenAI Responses, explicit-mode models | Pi selects `prompt_cache_options`; `none` requests explicit mode without breakpoints, and `long` selects `30m` TTL. Clio adds no extra breakpoints or weaker instruction roles. Payload fixtures cover this path. |
+| Native Anthropic Messages | Pi selects eligible short or one-hour cache-control blocks. `none` removes these controls. Real serializer/HTTP usage fixtures cover normalization and the one-hour subset. |
+| Direct llama.cpp | Normal calls retain `cache_prompt: true`; `retention: none` selects false. Optional warming requires the binding and evidence below. |
+| LiteLLM/generic OpenAI compatibility | Passive provider usage is retained. Generic synthesis does not advertise OpenAI `24h` retention. A declared route alone does not prove native controls or timings survive translation. Gateway warming stays disabled. |
+| vLLM | Normal inference and passive provider usage continue. A declared build can be checked, but version alone proves neither APC enablement nor idle scheduler/memory capacity. Warming stays disabled; no fixed-slot model is imposed. |
+| Claude Agent SDK, subscription/OAuth and other harnesses | Harness-specific transport and usage remain intact. Native Pi controls and direct API prices are not promises about another harness. |
+| Gemini explicit cache objects, Bedrock/platform cache administration | No new object lifecycle or administration is added. Existing Pi/provider support remains responsible for supported passive observations and requests. |
+
+For a direct llama.cpp **already loaded** worker at the audited commit, an
+operator can opt into a bounded pilot. Use the worker's actual `build_info`,
+exact model alias and endpoint; the values below are examples, not deployment
+measurements:
+
+```yaml
+chat:
+  prewarm: true
+targets:
+  - id: local-llama
+    runtime: llamacpp
+    url: http://127.0.0.1:8080
+    lifecycle: user-managed
+    cache:
+      retention: short
+      deployment:
+        backend: llamacpp
+        controlUrl: http://127.0.0.1:8080
+        model: your-exact-model-id
+        build: b1-c841aee
+      warm:
+        maxInputTokens: 8192
+        maxDurationMs: 30000
+        cooldownMs: 60000
+```
+
+Discovery uses GET requests with a two-second total deadline and refuses
+redirects. The control endpoint receives no inferred credentials. An authenticated
+control endpoint therefore remains unavailable to this initial reader. For a
+router, Clio inspects `/models` before any model-qualified request. Sleeping,
+loading or unloaded models are ineligible; a build change, unknown model or busy
+slot also refuses warming. The verified llama protocol is commit `c841aee`.
+Other builds stay passive until their no-autoload and inspection behavior is
+verified. A missing process epoch stays unknown; discovery is repeated rather
+than persisting a warm handle across restarts.
+
+A gateway declaration uses the same `deployment` map plus
+`gatewayDeploymentId`, with `model` set to the native model and `controlUrl` to
+its native endpoint. The reader compares a single matching LiteLLM route's id,
+model and API base before contacting that control endpoint. Failover or multiple
+replicas invalidate that binding. Even a matching route remains passive:
+end-to-end native control transport and reliable request affinity have not been
+validated on the configured gateway. No gateway credentials are forwarded to
+native discovery.
+
+The warm owns one request and at most one newer pending trigger. Pending work
+expires after 30 seconds. The default bound is 8192 estimated input tokens and
+a 30-second client deadline, with a 60-second cooldown; configured deadlines
+cannot exceed two minutes. Context transforms run before the input estimate.
+The one-token output and dummy suffix do not enter the conversation. The warm
+uses observe-only residency and `autoload=false` on native llama requests, so
+it cannot use the ordinary turn's implicit administrative authority.
+
+Admission retains the blanket active-dispatch refusal, checks shared Clio
+worker leases/reservations, and reads live native slots for foreign traffic.
+These are conservative admission observations, **not a global endpoint
+reservation**. Another process can begin work after the check. A foreground
+submit detaches a non-preemptible warm; its usage and local endpoint occupancy
+remain owned until the client round actually settles. Shutdown aborts detached
+rounds as well. Client cancellation never proves the server has stopped;
+subsequent admission must observe the backend again.
+
+`prewarm` custom ledger entries contain the actual usage, backend timings and
+deployment observation. `prewarmSkipped` records changed refusal reasons such
+as `deployment-unbound`, `model-not-loaded`, `deployment-build-mismatch`,
+`gateway-route-mismatch`, `gateway-cache-transport-unverified`,
+`vllm-scheduler-unverified`, `cooldown` and `expired`. These records contain no
+prompt payloads. Diagnostic payload capture remains a separate explicit opt-in.
+
+Turn off speculative work with `chat.prewarm: false`. Remove `cache.deployment`
+to return an individual target to passive operation. `cache.retention: none`
+selects the API's supported cache-off request policy and also refuses Clio
+warming; its exact effect on provider automatic caches is API-specific.
+Existing `chat.prewarm: true` configurations without deployment evidence now
+skip the speculative request. Ordinary inference remains available.
+
+No paid warming or automatic sibling-worker warming is enabled. Native workers
+retain isolated/fork/splice context selection and share Pi serialization and
+accounting, but the worker's context guard and payload hooks must be included
+in any future headless warm composition. There is no main-to-worker cache
+transfer based on ancestry.
+
+### Validation status for this change
+
+Live validation on 2026-09-11 exercised mini's `ornith1.5-35b-moe` on
+llama.cpp (`b1-c841aee`) and dynamo's `qwen3.8-27b` on LM Studio, first directly
+and then through blade's LiteLLM 1.98.0. The selected models were allowed to
+wake/load for inference; no serving configuration or administrative API was
+changed. The same native models and thinking-off intent were retained.
+
+Ten repetitions per route used about 2,850 tokens of public synthetic context
+and a bounded output. All useful requests in the corrected engine run returned
+exactly `OK`. Median client TTFT was:
+
+| Route | New prefix | Repeated prefix | After a separate warm |
+| --- | ---: | ---: | ---: |
+| Mini native | 1,691 ms | 183 ms | 163 ms |
+| Dynamo native | 1,255 ms | 156 ms | 155 ms |
+| Mini through LiteLLM | 1,706 ms | 196 ms | 173 ms |
+| Dynamo through LiteLLM | 1,259 ms | 163 ms | 162 ms |
+
+Mini reported roughly 2,834 cached tokens directly and 2,837 through the
+gateway after warming. Dynamo's OpenAI-compatible responses did not expose a
+cache-read breakdown; their normalized zero must not be presented as measured
+cache misses. Its timing improvement is an observation, not a per-request
+cache-token measurement. Gateway response metadata identified the expected
+models/deployments with no reported fallback or retry.
+
+Including the warm itself, warm plus useful request took **10.6–12.4% more
+median elapsed time** than one first request. That fails the preregistered 5%
+maximum total-time regression. Automatic warming therefore remains off by
+default. This workload favors reuse from useful requests; the after-warm TTFT
+reduction alone is not a total-work improvement. An idle-time or foreground
+contention benefit requires its own controlled measurement before rollout.
+
+Four full Clio main-agent CLI runs also completed with no tool calls and
+matching native/gateway outputs per model: mini returned `OK.`, dynamo `OK`.
+The punctuation means mini did not meet a literal exact-`OK` instruction in
+those full-prompt smoke runs; it is not hidden by the transport success. The
+engine workload above enforced the exact output separately.
+
+Four custom-worker CLI runs then returned exactly `OK`, with zero tool calls
+and succeeded outcomes. Each emitted receipt matched its persisted receipt and
+passed Clio's integrity verifier against its persisted run envelope. The mini
+worker through LiteLLM reported 719 cache-read tokens in that verified receipt.
+These checks establish transport and accounting continuity; the synthetic
+worker's task quality was not independently graded.
+
+The first exploratory driver omitted the public capability update that
+production applies after model synthesis. That made dynamo through LiteLLM
+spend its output budget on thinking. Those samples were preserved and marked
+invalid for semantic comparisons; the reported rerun includes the existing
+public update and checks visible output. This was a driver error, not a newly
+found production thinking regression.
+
+Fixtures additionally cover OpenAI/Anthropic serializers, normalized usage,
+SDK pricing tiers, failed calls, selected-target refresh, warm hooks and
+lifecycle, and deployment invalidation. Isolated/fork/splice worker context
+contracts pass. vLLM live verification is explicitly outside this local pass;
+its scheduler and APC controls remain unverified and passive.
+
+Raw local results are in `.clio-coder/artifacts/cache-live-2026-09-11T14-17-51.153Z/`,
+with full CLI events under `.clio-coder/artifacts/cache-cli-2026-09-11T14-20-44.264Z/`.
+Worker events and receipt verification are under
+`.clio-coder/artifacts/cache-worker-2026-09-11T14-26-13.738Z/`.
+The original preregistration is preserved separately from the schema-correct
+`.clio-coder/validation.yaml`. These artifacts are not distributed with a release.
+The run does not establish replica affinity guarantees, eviction/TTL behavior,
+foreign-traffic fairness, paid-provider savings, or a complete deployment pin
+for every model binary/tokenizer. Those limits prevent a general performance
+claim or enabling automatic gateway/worker warming.

package/docs/guide/configuration-reference.md

@@ -1,8 +1,5 @@
 # Configuration reference
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Configuration reference visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/configuration_reference_blueprint.html).
-
 Every switch that changes what Clio Coder does, in one place: settings keys, environment variables, CLI flags, project files under `.clio-coder/`, recipe and prompt-fragment frontmatter, tool arguments the model can send, and model knowledge-base tags. The source of truth is `src/`; this page is the audited inventory of what current source reads and is maintained alongside the code. The narrative guide is [configuration-and-targets.md](configuration-and-targets.md); operator prose for each environment variable is in [environment-variables.md](environment-variables.md).
 
 Precedence, where several surfaces set the same value: a one-run CLI flag beats a session override (`/settings`, `/model`, `/thinking`), which beats `.clio-coder/settings.local.yaml`, which beats `.clio-coder/settings.yaml`, which beats the user `settings.yaml`, which beats the compiled default. Entries whose order differs say so in their precedence column.
@@ -25,7 +22,8 @@ Precedence, where several surfaces set the same value: a one-run CLI flag beats
 | `chat.retry.enabled` | `true` | Master switch for transient-provider retries in the interactive chat loop (boolean); dispatched workers use `fleet.retry.maxRetries` instead; applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `chat.retry.maxDelayMs` | `60000` | Ceiling in ms on the exponential backoff between chat-loop retries (integer >= 0); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `chat.retry.maxRetries` | `3` | Maximum retry attempts for one transient provider failure in the chat loop (integer >= 0); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `chat.retry.streamStallMs` | `180000` | Silence on an in-flight stream longer than this many ms is treated as a wedged backend and the turn is aborted and retried (integer >= 0, `0` disables the stall timer); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
+| `chat.retry.streamStallMs` | `180000` | Silence after a call's first token longer than this many ms is treated as a wedged backend and the turn is aborted and retried (integer >= 0, `0` disables the stall timer); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
+| `chat.retry.firstTokenStallMs` | `600000` | Silence allowed between sending a model call and its first token. It replaces `streamStallMs` for that window only, because a local server that slept reloads the model and prefills cold before it emits anything; the larger of the two values applies (integer >= 0, `0` never aborts a call that has not started streaming); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `chat.target` | `null` | Saved default chat target id (configured id or null); a dangling id normalizes to null and clears `chat.model`; seeds session routing at launch, so applies next session. | `run --target` > session routing (`/model`, `/thinking`, configured model-cycle actions, `/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `chat.thinkingLevel` | `low` | Saved default reasoning effort for the chat model: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, clamped to what the model supports at request time; applies next session. | `run --thinking` > session routing (`/model`, `/thinking`, configured model-cycle actions, `/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `context.compaction.auto` | `true` | Master switch for the pre-request compaction trigger when context pressure crosses `threshold` (boolean); manual `/context compact` still works when off; applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
@@ -60,7 +58,7 @@ Precedence, where several surfaces set the same value: a one-run CLI flag beats
 | `fleet.history.maxRuns` | `1000` | Retention cap on the durable dispatch run ledger (integer >= 1); applies next dispatch. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `fleet.limits.internalRunTimeoutMs` | `900000` | Wall-clock cap in ms for one internal generator dispatch such as the wiki documenter or the bootstrap scout (integer >= 1); applies next dispatch. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `fleet.limits.toolCallsPerRun` | `150` | Lifetime cap on admitted tool calls for one dispatched worker (integer >= 1); a recipe budget can only narrow it; read from effective settings at dispatch, so applies next dispatch. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `fleet.nodes` | `[]` | SSH-reachable worker nodes (the implicit `local` node is never listed); a node becomes dispatch-eligible only after the doctor fleet preflight passes; applies next dispatch. |  |
+| `fleet.nodes` | `[]` | SSH-reachable worker nodes (the implicit `local` node is never listed); a node becomes dispatch-eligible only after `clio-coder doctor --fix` records a passing fleet preflight for the project root (plain `doctor` probes and reports without recording); applies next dispatch. |  |
 | `fleet.nodes[].clioCoderEntry` | `clio-coder worker` | Remote worker-entry invocation run after `cd <projectRoot>`; also version-probed by the fleet preflight; defaults to `clio-coder worker` on the remote PATH. |  |
 | `fleet.nodes[].host` |  | SSH destination host (name or address); required. |  |
 | `fleet.nodes[].id` |  | Stable node id used in placement, receipts, and operator surfaces; required, `local` is reserved, duplicates are rejected. |  |
@@ -89,7 +87,7 @@ Precedence, where several surfaces set the same value: a one-run CLI flag beats
 | `integrations.externalAgents.defaults.connectTimeoutMs` | `30000` | Default ms an ACP agent has to answer `initialize` (integer >= 1, at most the max timer delay); never zero-disabled; applies next dispatch. |  |
 | `integrations.externalAgents.defaults.permissionTimeoutMs` | `120000` | Default ms an ACP permission request may wait for an operator (integer >= 1); applies next dispatch. |  |
 | `integrations.externalAgents.defaults.toolGovernance` | `clio-coder-policy` | Default governance for ACP agents without their own: `clio-coder-policy`, `agent-managed`, `deny-all` (legacy `clio-policy` is normalized with a warning); applies next dispatch. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `integrations.externalAgents.defaults.turnTimeoutMs` | `300000` | Default ms one ACP turn may take before it is cancelled (integer >= 1); applies next dispatch. |  |
+| `integrations.externalAgents.defaults.turnTimeoutMs` | `0` | Default ms one ACP turn may take before it is cancelled (integer >= 0; 0 disables); applies next dispatch. |  |
 | `integrations.externalAgents.entries` | `[]` | ACP delegation agents for `/delegate` and dispatch: list of stdio agent definitions with unique ids (`auto` reserved), each inheriting `defaults.*` where unset; applies next dispatch. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `integrations.externalAgents.entries[].args` | `[]` | Argument list for the ACP stdio command (list of strings, duplicates dropped); empty when absent. |  |
 | `integrations.externalAgents.entries[].command` |  | ACP stdio command spawned for the agent (newline-delimited JSON-RPC per ACP v1); required. |  |
@@ -102,7 +100,7 @@ Precedence, where several surfaces set the same value: a one-run CLI flag beats
 | `integrations.externalAgents.entries[].projectContext` | `none` | Project context sent to this agent as a dynamic message: `none` (default; repo conventions never leave the machine) or `bounded` (the bounded projection). |  |
 | `integrations.externalAgents.entries[].stallTimeoutMs` | `300000` | Event-inactivity stall window in ms: when no `session/update` arrives for this long the reconciler cancels the turn and finalizes the run as stalled; `<= 0` disables; 300000 when absent. |  |
 | `integrations.externalAgents.entries[].toolGovernance` |  | Who governs the agent's tool calls: `clio-coder-policy` (Clio's autonomy matrix), `agent-managed`, `deny-all`; absent inherits `defaults.toolGovernance`; `agent-managed` refuses `run --autonomy`. |  |
-| `integrations.externalAgents.entries[].turnTimeoutMs` |  | Per-agent ms one ACP turn may take before cancellation (integer >= 1); absent inherits `defaults.turnTimeoutMs`. |  |
+| `integrations.externalAgents.entries[].turnTimeoutMs` |  | Per-agent ms one ACP turn may take before cancellation (integer >= 0; 0 disables); absent inherits `defaults.turnTimeoutMs`. |  |
 | `integrations.git.commitAttribution` | `true` | Evidence-aware role trailers on commits created through Clio (boolean); applies immediately for subsequent commits. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `integrations.library.catalog` | `null` | Path of the private resource-library catalog (string or null); null means `<configDir>/library.yaml`; applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `integrations.library.confirmedRemote` | `null` | Remote URL written by `clio-coder library remote confirm <url>`; must equal `remote` before sync or push may run (string or null); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
@@ -171,6 +169,15 @@ Precedence, where several surfaces set the same value: a one-run CLI flag beats
 | `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[].cache.retention` | SDK default | Native Pi request cache policy: `none`, `short`, or `long`. Meaning depends on the selected API/model; this grants no management or paid-warming authority. | explicit call > target > Anthropic environment fallback > SDK default |
+| `targets[].cache.deployment.backend` | unset | Read-only binding to `llamacpp` or `vllm`; absence leaves warming ineligible. | target |
+| `targets[].cache.deployment.controlUrl` | unset | Explicit HTTP(S) discovery endpoint, without embedded credentials/query/fragment. No gateway credentials or administrative requests are sent here. | target |
+| `targets[].cache.deployment.model` | unset | Exact native model id, distinct from a gateway route alias. | target |
+| `targets[].cache.deployment.build` | unset | Expected worker build/version; a mismatch invalidates warm admission. Current llama warm protocol is verified against commit `c841aee`; other versions remain passive. | target |
+| `targets[].cache.deployment.gatewayDeploymentId` | unset | LiteLLM deployment id to compare against a single current `/v1/model/info` route. A match alone does not establish cache-control transport support. | target |
+| `targets[].cache.warm.maxInputTokens` | `8192` | Positive maximum estimated input tokens after engine context transforms; oversized warms are refused. This is an estimate, not a tokenizer or billing cap. | target |
+| `targets[].cache.warm.maxDurationMs` | `30000` | Positive client warm deadline, capped at 120000 ms. Client cancellation is not proof that backend computation stopped. | target |
+| `targets[].cache.warm.cooldownMs` | `60000` | Positive delay between completed warm requests; effective minimum 1000 ms. An identical prefix is suppressed for at least 60000 ms. | target |
 | `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. |  |
 | `targets[].pricing.input` |  | USD rate per input token unit used for cost accounting when set, taking precedence over catalog pricing (number >= 0); required together with `output`. |  |
@@ -202,6 +209,7 @@ Read from the process environment at boot unless the row says otherwise.
 | `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. |  |
 | `CLIO_CODER_ENDPOINT_SLOTS_TTL_MS` | `86400000` | Positive integer milliseconds a persisted endpoint slot count stays valid for an endpoint this process has not probed; older records are ignored and pruned. | env > built-in default (no settings key) |
+| `CLIO_CODER_ENTRY` | `unset` | Exported by the eval suite runner into a task runner's environment with the path of the Clio entry under evaluation (`src/domains/eval/suites/run.ts`). Clio itself never reads it. |  |
 | `CLIO_CODER_EVAL_RUNNER_STDOUT_FILE` | `unset` | Set by the eval suite runner to the path of the captured runner stdout JSONL for a task's measure step; read only by external graders (evals/behavioral-corpus-grader.mjs), never by src. |  |
 | `CLIO_CODER_FORCE_COMPACT` | `unset (disabled)` | Exactly `1` on the interactive process forces the pre-submit compaction to run on every turn while set, regardless of the context threshold. |  |
 | `CLIO_CODER_GIT_COMMITS_ENABLED` | `unset (in-process reads treat it as enabled; the hook requires exactly `1`)` | Set by Clio to `1`/`0` from `integrations.git.commitAttribution` for itself and child seams; the managed hook exits unless it is exactly `1`, while absent counts as enabled in process. | `integrations.git.commitAttribution` writes it; env is the transport, not an operator override |
@@ -237,9 +245,6 @@ Read from the process environment at boot unless the row says otherwise.
 | `CLIO_CODER_SKILL_MARKETPLACE_INDEX` | `unset` | Path to a skill-marketplace index file consulted after the catalog; an explicit indexPath option beats it and the built-in index path is the fallback. | explicit indexPath option > env > default index path |
 | `CLIO_CODER_STATE_DIR` | `platform default (`$XDG_STATE_HOME/clio-coder`, else `~/.local/state/clio-coder`)` | Absolute path for the state root; beats `CLIO_CODER_HOME/state` and the platform default, and the fleet-view pane child re-pins it from argv. | env > `CLIO_CODER_HOME/state` > `XDG_STATE_HOME` or platform default |
 | `CLIO_CODER_STATUS_STUCK_MS` | `180000` | Positive number of milliseconds of elapsed turn time after which the status watchdog reports the turn as stuck (tier 4). |  |
-| `CLIO_CODER_TEST_STAGE1_DELAY_MS` | `0` | Under `NODE_ENV=test` only, integer milliseconds (clamped to 0..5000) to sleep between the Stage 0 shell mount and Stage 1 hydration for PTY tests. |  |
-| `CLIO_CODER_TEST_STAGE1_FAIL` | `unset (disabled)` | Under `NODE_ENV=test` only, exactly `1` throws an injected Stage 1 hydration failure after the instant shell mounts. |  |
-| `CLIO_CODER_TEST_UPGRADE_NO_NETWORK` | `unset (disabled)` | Any non-empty value makes `clio-coder upgrade` skip the npm install step so upgrade tests run offline. |  |
 | `CLIO_CODER_TIMING` | `unset (disabled)` | Exactly `1` prints the startup timer report after the banner, but only on the bannered non-interactive boot (not the TUI, headless, or ACP paths). |  |
 | `CLIO_CODER_TRACE_BOOT` | `unset (disabled)` | Exactly `1` writes a `[clio-coder:boot] +<ms> <phase>` line to stderr for every boot phase marker, including startup-timer marks. |  |
 | `CLIO_CODER_TRACE_MAX_BYTES` | `134217728` | Integer of at least 1048576 bytes the SQLite trace mirror may occupy before the oldest terminal runs are pruned; smaller or invalid values fall back. | env > built-in default (no settings key) |
@@ -269,7 +274,6 @@ Read from the process environment at boot unless the row says otherwise.
 | `NO_COLOR` | `unset` | Any non-empty value drops every foreground and background SGR color from the theme; bold, dim, italic, and underline stay. |  |
 | `NODE_COMPILE_CACHE` | `unset (Clio uses `<cache>/v8-compile-cache` once the cache root exists)` | Presence (even empty) means the operator owns the V8 compile cache: Clio calls `enableCompileCache()` with no directory and never injects its own cache into workers. |  |
 | `NODE_DISABLE_COMPILE_CACHE` | `unset` | Presence disables Clio's compile cache for this process and stops the worker spawn from injecting one. |  |
-| `NODE_ENV` | `unset` | Exactly `test` unlocks the Stage 1 interleaving seams (`CLIO_CODER_TEST_STAGE1_DELAY_MS`, `CLIO_CODER_TEST_STAGE1_FAIL`); no other value matters. |  |
 | `NODE_OPTIONS` | `unset` | Scanned for `--trace-warnings`; when present, the trace store stops suppressing Node's `node:sqlite` ExperimentalWarning. |  |
 | `OLLAMA_NUM_PARALLEL` | `1` | Positive integer parallel slot count assumed for a local Ollama server during discovery; anything else counts as 1. |  |
 | `PATH` | `unset` | Searched for executables by interop CLI detection, toolchain resolution, the uninstall shadow check, and editor probing; the bash tool's login-env capture is discarded without it. |  |
@@ -426,7 +430,7 @@ Grouped by command. Global flags appear under `global`.
 
 | Flag | Controls |
 |---|---|
-| `--fix` | Repair structure (missing directories and template files, credential file permissions) instead of the read-only diagnosis. |
+| `--fix` | Repair structure (missing directories and template files, credential file permissions) and record fleet preflight results instead of the read-only diagnosis. |
 | `--help` | Print the command's usage and exit. |
 | `--json` | Emit JSON instead of the human-readable rendering. |
 | `-h` | Short form of --help. |
@@ -517,6 +521,7 @@ Grouped by command. Global flags appear under `global`.
 | `--acp` | Startup alias for the `acp` subcommand: rewrites the rest of the line onto `clio-coder acp`, so every trailing option is parsed by the ACP parser. |
 | `--all` | With `--help`, appends the `clio-coder dev` command list (components, evolve, share) to the top-level help; no effect otherwise. |
 | `--api-key` | Startup flag taking a literal key that overrides the stored credential for the target this invocation resolves; must precede the subcommand. |
+| `--autonomy` | Startup flag setting the interactive session's autonomy to `read-only`, `suggest`, `auto-edit`, or `full-auto` without modifying `settings.yaml`. Passing `--autonomy` before a subcommand is refused with exit 2 (`clio-coder run --autonomy` remains the headless form). |
 | `--continue` | Refused before the subcommand: exits 2 with the hint that sessions are resumed from inside the app by typing /resume; nothing is parsed from it. `run --continue` is a separate flag. |
 | `--help` | Print the top-level command list and exit 0 when given before any subcommand. |
 | `--no-context-files` | Startup flag that skips CLIO-CODER.md project-context injection for this invocation; must precede the subcommand (run rejects it with a position hint). |
@@ -569,6 +574,19 @@ Grouped by command. Global flags appear under `global`.
 | `--with-requirements` | For `library install`, also install the entry's unsatisfied requirements instead of refusing. |
 | `-h` | Short form of --help. |
 
+### `mcp`
+
+Operator commands are `clio-coder mcp list [--json]`, `clio-coder mcp trust <id> [--action-class read|execute|unknown] [--json]`, and `clio-coder mcp untrust <id> [--json]`. `--help`/`-h` prints help even with `--json`. Interactive `/mcp list`, `/mcp trust <id> [read|execute|unknown]`, and `/mcp untrust <id>` use the same outcomes. These commands inspect configuration or mutate trust without launching a server.
+
+| JSON response | Shape |
+| --- | --- |
+| list | `{servers: [...], diagnostics: [...], trustDiagnostics: [...]}`; servers include declaration and `trust: {status, actionClass, reason?}` |
+| trust | `{ok: true, record: {projectRoot, id, digest, actionClass, trustedAt}}` |
+| untrust | `{ok: true, removed: boolean}` |
+| mutation or usage error | `{ok: false, message: string}` with a one-line reason |
+
+Exit codes are 0 for success, 1 for operational failure, and 2 for invalid usage. List keeps its list response shape and exits 1 when config or trust diagnostics exist. CLI trust/untrust requires a declared project id; user declarations are trusted by authorship. Trust-file corruption is reported without overwriting it. See [the configuration contract](#local-stdio-mcp-configuration-and-trust).
+
 ### `memory`
 
 | Flag | Controls |
@@ -599,7 +617,10 @@ Grouped by command. Global flags appear under `global`.
 
 | Flag | Controls |
 |---|---|
+| `--force` | For `panes install`, overwrite an existing installation without prompting. |
 | `--help` | Print the command's usage and exit. |
+| `--json` | Emit JSON instead of the human-readable rendering. |
+| `-f` | Short form of --force. |
 | `-h` | Short form of --help. |
 
 ### `paths`
@@ -622,6 +643,7 @@ Grouped by command. Global flags appear under `global`.
 | `--dry-run` | Print the listing of what each selected root holds and change nothing. |
 | `--force` | Required for destructive execution; without it the command lists and refuses. |
 | `--help` | Print the command's usage and exit. |
+| `--json` | Emit JSON instead of the human-readable rendering. |
 | `--state` | Reset the state root only (every session transcript and its audit trail); the default level when no level flag is given. |
 | `-f` | Short form of --force. |
 | `-h` | Short form of --help. |
@@ -698,6 +720,15 @@ Grouped by command. Global flags appear under `global`.
 | `--thinking` | For `targets profile set`, the profile's thinking level: off, minimal, low, medium, high, xhigh, or max. |
 | `-h` | Short form of --help. |
 
+### `tasks`
+
+| Flag | Controls |
+|---|---|
+| `--expect` | For `tasks add`, repeatable repository-relative output file path expected by the task. |
+| `--help` | Print the command's usage and exit. |
+| `--verify` | For `tasks add`, repeatable verification check id (with optional `:timeoutMs` suffix) declared in `package.json` or `.clio-coder/verifiers.yaml`. |
+| `-h` | Short form of --help. |
+
 ### `tools`
 
 | Flag | Controls |
@@ -721,7 +752,6 @@ Grouped by command. Global flags appear under `global`.
 | `--limit` | For `trace runs`, integer 1 to 500 number of runs to list (also `--limit=N`). |
 | `--max-age-days` | For `trace prune`, integer 1 to 36500 retention age in days for this prune only (also `--max-age-days=N`). |
 | `--max-bytes` | For `trace prune`, integer size ceiling in bytes, at least 1048576, for this prune only (also `--max-bytes=N`). |
-| `--port` | For `trace ui`, TCP port for the localhost viewer, 0 to 65535 (also `--port=N`); 0 picks an ephemeral port. |
 | `-h` | Short form of --help. |
 
 ### `uninstall`
@@ -731,6 +761,9 @@ Grouped by command. Global flags appear under `global`.
 | `--dry-run` | Print what would be removed, including the per-project directories, and change nothing. |
 | `--force` | Required for destructive execution; without it the command lists and refuses. |
 | `--help` | Print the command's usage and exit. |
+| `--json` | Emit JSON instead of the human-readable rendering. |
+| `--keep-config` | Preserve the configuration root (`settings.yaml`, credentials). |
+| `--keep-data` | Preserve the data root (`memory`, evidence, vendored tools). |
 | `--remove-binary` | Also remove the launcher symlink when it points at this installation; a real file or a link elsewhere is kept and reported. |
 | `-f` | Short form of --force. |
 | `-h` | Short form of --help. |
@@ -742,6 +775,7 @@ Grouped by command. Global flags appear under `global`.
 | `--channel` | npm dist-tag to install: `latest`, `beta`, or `dev`; only the `--channel=<chan>` form is parsed; npm installs only. |
 | `--dry-run` | Print the planned npm install, migrations, and state refresh and change nothing. |
 | `--help` | Print the command's usage and exit. |
+| `--json` | Emit JSON instead of the human-readable rendering. |
 | `--post-install` | Internal marker the upgrade passes to its re-exec of the newly installed binary: skip the npm install and run migrations and doctor checks. |
 | `--skip-migrations` | Skip the data-dir migrations after the install step. |
 | `-h` | Short form of --help. |
@@ -760,6 +794,9 @@ Grouped by command. Global flags appear under `global`.
 
 | Flag | Controls |
 |---|---|
+| `--baseline` | For `verifiers add`/`edit`, repository-relative baseline JSON path for a perf-budget check. |
+| `--budget-ms` | For `verifiers add`/`edit`, wall-time bound in milliseconds for a perf-budget check. |
+| `--budget-relative` | For `verifiers add`/`edit`, fractional headroom over the bound for a perf-budget check. |
 | `--command` | For `verifiers add` (required) and `edit`, the check's argv as a JSON string array. |
 | `--cwd` | For `verifiers add`/`edit`, repository-relative working directory of the check. |
 | `--description` | For `verifiers add` (required) and `edit`, the check's description text. |
@@ -768,17 +805,54 @@ Grouped by command. Global flags appear under `global`.
 | `--help` | Print the verifiers usage and exit. |
 | `--id` | For `verifiers add`, the new check's id (required). |
 | `--json` | For `verifiers inspect`, the only accepted argument; emits the fixed machine-readable catalog projection. |
+| `--kind` | For `verifiers add`/`edit`, check kind: `command`, `numeric-compare`, or `perf-budget`. |
+| `--reference` | For `verifiers add`/`edit`, repository-relative reference JSON path for a numeric-compare check. |
 | `--rename` | For `verifiers author`, an `<old>=<new>` rename of a discovered check id; repeatable. |
 | `--tags` | For `verifiers add`/`edit`, comma-separated catalog tags. |
 | `--timeout-ms` | For `verifiers add`/`edit`, positive integer timeout in milliseconds. |
+| `--tolerance` | For `verifiers add`/`edit`, tolerance JSON object specifying numeric or perf-budget bounds. |
 | `--yes` | For mutating verifiers commands, confirm the write after the preview prints; without it nothing changes. |
 | `-h` | Short form of --help. |
 
+## Local stdio MCP configuration and trust
+
+Source: `src/domains/gateway/mcp/config.ts`, `trust.ts`, and `client.ts`. The optional user file is `<Clio config directory>/mcp.yaml`; the project file is `<workspace>/.clio-coder/mcp.yaml`. `clio-coder paths` locates the config directory. A user declaration shadows a project declaration of the same id with a diagnostic. Malformed files contribute no servers. This release supports local stdio only, with no remote transport or OAuth fields.
+
+```yaml
+version: 1
+servers:
+  - id: analysis
+    command: node
+    args: [tools/mcp-server.mjs]
+    cwd: .
+    env:
+      ANALYSIS_MODE: readonly
+    timeoutMs: 60000
+```
+
+| Field | Contract |
+| --- | --- |
+| `version`, `servers` | Required root fields; version 1, at most 32 server declarations per file. |
+| `servers[].id` | Required, at most 32 characters, matches `[a-z0-9][a-z0-9_-]*`; duplicate ids fail within a file. |
+| `servers[].command` | Required executable basename on PATH or absolute path, at most 512 bytes. Relative executable paths, shell command strings, and explicit shell executables are refused. |
+| `servers[].args` | Optional string array, default empty; at most 64 entries of 4096 bytes each. |
+| `servers[].cwd` | Optional, at most 512 bytes. Project cwd defaults to the workspace and must remain inside it, including symlinks. User cwd defaults to the config directory; it may be config-relative or absolute. |
+| `servers[].env` | Optional string map, default empty; at most 64 keys matching `[A-Z_][A-Z0-9_]*`, with values at most 4096 bytes. Adds to the safe environment allowlist. |
+| `servers[].timeoutMs` | Optional positive integer at most 900000; overrides request timeout. Default client request timeout is 60000 ms; initialize is bounded at 15000 ms. |
+
+The YAML file is capped at 256 KiB; aliases and unknown fields are rejected. NUL-containing command/argument/environment/cwd values are refused. Launch-time canonical cwd checks are admission checks, not ongoing filesystem isolation.
+
+User-scope declarations are trusted by authorship and get action class `unknown`. Project servers require `clio-coder mcp trust analysis` or `/mcp trust analysis`; an optional `--action-class read|execute|unknown` selects authority, with `unknown` as default. Trust is stored in user `<config>/mcp-trust.json`, version 1, mode 0600, with at most 256 records and 1 MiB. Each record binds canonical `projectRoot`, `id`, declaration `digest`, `actionClass`, and `trustedAt`. Editing command, arguments, cwd, environment, or timeout makes the record stale and requires review and re-trust. Trust does not come from a server annotation or a model-authored claim.
+
+Gateway discovery is lazy and session-cached. Untrusted or stale project declarations never spawn; failed or cancelled discovery is not silently restarted in that session. Trust changes should be used by a new session, since the running source resolved configuration once. Cancelling discovery closes its shared connection and fails its waiters. Session shutdown awaits client-owned teardown; the exit backstop signals only a still-owned process group.
+
+Transport bounds are 4 MiB per incoming JSON-RPC line, 4 MiB pending outbound bytes, 16 KiB stderr tail, 1 MiB normalized result text, and at most 500 tools or 100 pages per server discovery. Gateway result shaping bounds one MCP result to 16 KiB in model context, offloading larger results to disk artifacts with preview and reference. Request timeout or per-call abort can fail one call without closing a ready server; discovery cancellation closes the shared connection. Teardown uses TERM, a 3000 ms grace, KILL, and 2000 ms bounded confirmation, reporting incomplete cleanup. Launching an MCP server is not sandboxing; remote MCP/OAuth and general OS isolation are deferred.
+
 ## Project files
 
 Keys read from files under `.clio-coder/` in the repository.
 
-Project safety, hooks, and settings are ignored until the operator reviews them with `clio-coder config trust safety|hooks|settings` and approves the printed digest with `--hash`. Consent binds one canonical workspace and one surface's content and source location. Changes, local override additions, and safety-policy relocation require a new review. Startup names skipped files; `config inspect` shows effective safety provenance and trust. Settings and safety apply on restart; new hooks apply after extension reload, while changed or revoked published hooks stop before their next execution. `CLIO-CODER.md` remains project text and does not grant configuration authority.
+Project safety, hooks, and settings are ignored until the operator reviews them with `clio-coder config trust safety|hooks|settings` and approves the printed digest with `--hash`. Consent binds one canonical workspace and one surface's content and source location. Changes, local override additions, and safety-policy relocation require a new review. Startup names skipped files; `config inspect` shows effective safety provenance, trust, and names ignored project settings under the Settings header. Settings and safety apply on restart; new hooks apply after extension reload, while changed or revoked published hooks stop before their next execution. `CLIO-CODER.md` remains project text and does not grant configuration authority.
 
 ### `.clio-coder/agents`
 
@@ -972,11 +1046,43 @@ Arguments the model can send on `dispatch`, `bash`, `context`, and `verify`, gro
 | Argument | Class | Controls |
 |---|---|---|
 | `context.include_tree` | policy | scope=skills: list files under the skill base_dir. |
-| `context.limit` | policy | scope=docs: max sections (default 5, max 12). |
+| `context.limit` | policy | scope=recall discovery: max refs (default 8, max 12). |
 | `context.name` | task | scope=skills: skill name to load; omit to list. |
-| `context.query` | task | scope=docs: question or terms; omit to list the corpus. |
+| `context.query` | task | scope=recall discovery: path, tool, or ref terms; omit to list. |
 | `context.ref` | task | scope=recall: ref of the evicted item, as named in its marker. |
-| `context.scope` | policy | Context source. |
+| `context.scope` | policy | workspace, skills, or recall. |
+| `context.offset` | policy | Zero-based recall discovery offset; follow nextOffset. |
+
+### `gateway`
+
+| Argument | Class | Controls |
+| --- | --- | --- |
+| `gateway.op` | task | find, describe, or call. |
+| `gateway.query` | task | Case-insensitive find filter over name/description. |
+| `gateway.capability` | task | Name returned by find, required for describe/call. |
+| `gateway.args` | task | Capability arguments from its describe schema. |
+
+### `run_script`
+
+| Argument | Class | Controls |
+| --- | --- | --- |
+| `run_script.interpreter` | task | PATH name: python3, python, node, bash, sh, Rscript, julia, perl, ruby, octave. |
+| `run_script.script` | task | Regular script file inside the workspace; symlink escapes refused. |
+| `run_script.args` | task | Script argv, at most 64 entries, 4096 bytes each. |
+| `run_script.interpreter_args` | task | Pre-script argv with the same bounds; omitted defaults to Python -u or empty for other interpreters. |
+| `run_script.cwd` | task | Workspace-relative directory, default root. |
+| `run_script.timeout_ms` | policy | Positive integer, default 600000, clamped above 21600000. |
+| `run_script.inputs` | task | Up to 64 workspace-relative provenance references, not isolation. |
+| `run_script.outputs` | task | Up to 64 expected output references, observed after execution. |
+| `run_script.env` | task | Up to 32 uppercase/underscore keys, values at most 4096 bytes; manifest stores keys only. |
+
+### Gateway capability arguments
+
+`clio_docs` takes optional `query` and `limit` (default 5, max 12). `clio_library` takes `query`, `kind`, `ref`, `limit` (default 20, max 50), and zero-based `offset`. These replace context's docs/library scopes. `web_read` accepts `url`, `timeout_ms`, `max_bytes`, and `format`, without method, headers, or body. `web_fetch` retains the full HTTP surface.
+
+`data` requires `op: inspect|select|validate` and `path`, with optional `format: csv|tsv|json|jsonl`, `delimiter`, `header: auto|true|false`, `sample_rows` (10, max 1000), `max_rows` (100000, null for all), zero-based `offset`, `limit` (50, max 1000), `columns` (CSV names/indices), and RFC 6901 `pointer` (JSON). All are nested under `gateway.args`; the capability is read-only.
+
+`read.line_numbers` requests source line prefixes; tail numbering is refused above the 32 MiB line-count budget. For complete argument and result contracts, see [Tool usage](tool-usage.md).
 
 ### `dispatch`
 
@@ -1171,6 +1277,8 @@ Keys of the local-model knowledge base in `src/domains/providers/models/local-mo
 | `quirks.thinking.mechanism` |  | One of `effort-levels`, `budget-tokens`, `on-off`, `always-on`, `none`; it picks the thinking payload shape, reasoning class and level labels, overriding inference from `thinkingFormat`. |
 | `quirks.thinkingControl` |  | Free-text note on how a family's template gates thinking (for example a `<\|think\|>` system token); provenance only; nothing in src reads it. |
 
+The measured `mini/qwopus3.8-27b-dense` LiteLLM route family has a narrow catalog entry for its reported `low`, `medium`, and `xhigh` effort vocabulary. On the `mini/qwopus3.8-27b-dense-q6` deployment, Clio omitted effort and the upstream template rejected `high`, behavior consistent with an incompatible deployment default; the precise upstream cause was not inspected. Clio maps configured `high` or `max` to `xhigh` and explicitly forwards the resolved effort through LiteLLM. This entry comes from the 2026-09-16 server diagnostic and same-route validation; it does not assign capabilities to other Qwopus models by name similarity or change the selected model.
+
 ## Bounding constants
 
 Compiled-in limits (context budgets, retry counts, cache sizes, timeouts) are code-owned invariants, not configuration. They live beside the code that enforces them and change only through a source change with a changelog line.

package/docs/guide/environment-variables.md

@@ -1,8 +1,5 @@
 # Environment Variables
 
-> **Visual blueprint:** The source checkout includes the complete
-> [Environment Variables visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/environment_blueprint.html).
-
 This page inventories Clio-specific runtime variables and the ambient variables that materially change documented operator behavior. `settings.yaml` is the durable home for operator policy; environment variables support per-process overrides, directory layout, debugging, credentials, terminal integration, and internal plumbing. When prose and source disagree, prefer the cited read site.
 
 The `environment-variable-inventory` check in `scripts/check-hygiene.ts`, run by `pnpm run lint`, enforces coverage for Clio's `CLIO_*` variables and `NO_COLOR`. It intentionally does not treat every operating-system or provider convention as a Clio knob. Examples outside that enforced family include `PATH`, `HOME`, terminal capability variables, and provider API-key names selected dynamically by `src/engine/env-api-keys.ts`.
@@ -63,7 +60,7 @@ These names follow an upstream or operating-system convention. They are not subs
 | `SSH_CONNECTION`, `SSH_TTY`, `TMUX`, `STY` | Remote-session and terminal-multiplexer detection used by the adaptive stream-pacing policy (`src/interactive/stream-pacing-policy.ts`). |
 | `COLUMNS` | Fallback text width for non-TTY CLI output (`src/cli/text-layout.ts`). |
 | `TZ` | Local timestamp formatting and daily audit-log date boundaries (`src/interactive/format-time.ts`, `src/domains/safety/audit.ts`). |
-| `CI`, `NODE_ENV` | CI-sensitive presentation behavior and test/development-only seams. Neither grants tool authority. |
+| `CI` | CI-sensitive presentation behavior. It grants no tool authority. |
 
 ## Debug and trace toggles
 
@@ -105,6 +102,7 @@ Set by Clio for its own processes; not operator knobs.
 | `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`, 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_ENTRY` | Exported by the eval suite runner into a task runner's environment with the path of the Clio entry under evaluation (`src/domains/eval/suites/run.ts`). Clio itself never reads it. |
 | `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`). |
 | `CLIO_CODER_WORKER_PGID` | Process-group id the transport assigns a worker so its whole tree can be signalled (`src/domains/dispatch/transport.ts`, `src/worker/entry.ts`). |
@@ -116,10 +114,6 @@ Set by Clio for its own processes; not operator knobs.
 | Variable | Purpose |
 | --- | --- |
 | `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`). |
 
 Variables used only by external benchmark harnesses or install scripts are not