@iowarp/clio-coder 0.4.4 → 0.4.6

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

@@ -47,25 +47,120 @@ configured remote before synchronization can run. See
 
 ## First-run flow
 
-From a source checkout:
+After [installing Clio](installation-and-lifecycle.md), run `clio-coder configure`
+from the repository you want to work on. The launcher has three choices:
 
-```bash
-git clone https://github.com/iowarp/clio-coder.git
-cd clio-coder
-npm ci
-npm run install:local
-hash -r
-clio-coder --version
+```text
+❯ Quick Connect    endpoint → model → ready
+  Settings         all configuration options
+  Diagnostics      check an existing installation
 ```
 
-Then start from the repository you want Clio to work on:
+Choose **Quick Connect**:
+
+1. Enter your endpoint URL. Examples: `localhost:1234` for LM Studio,
+   `localhost:11434` for Ollama, or the URL supplied by your API provider.
+2. Enter an API key if requested. Native local servers that work without a key
+   skip this step. Other APIs offer a key field even when their model list is
+   public, because chat may still require authentication; leave it blank only
+   for a keyless server.
+3. Choose a model if the endpoint offers several. Type to filter the list,
+   use arrows to move, and Enter to select. A single model is selected for you.
+4. Review the endpoint and model, then choose **Connect**. Run `clio-coder` to
+   start coding. Starting `clio-coder` itself without a target opens this same
+   launcher and continues into chat after setup succeeds.
+
+Quick Connect detects LM Studio, Ollama, and LiteLLM where their discovery APIs
+are available; other servers use the OpenAI- or Anthropic-compatible protocol.
+It checks live model discovery, without sending a generation request. An
+unreachable endpoint or empty model list stays in setup with a useful error.
+Use **Settings → Targets & Auth → Add a target** for browser sign-in,
+subscriptions, AWS credentials, explicit runtime selection, or a server that
+needs a manually entered model id.
+
+A first connection powers both chat and dispatched workers. Connecting again
+changes chat; existing fleet and background assignments, target capabilities,
+and preferences remain in place. A saved matching endpoint reuses its credential.
+New endpoints never inherit an unrelated provider key. Pasted keys are masked
+and saved locally only when you choose **Connect**.
+
+Escape goes back one step, including from the review screen. Ctrl+U clears a
+text field or model filter; Ctrl+C quits. In ordinary menus, `q` also quits;
+in the model filter it is text. Cancelling leaves the connection draft unsaved.
+Leaving first setup without a chat target exits 130. Use
+`clio-coder configure --quick` to open this path directly.
+
+## Recommended defaults
+
+Quick Connect uses the shipped defaults, with no separate preset to maintain.
+These aim to make one coding session useful on a laptop or a shared endpoint:
+
+| Area | Default and purpose |
+| --- | --- |
+| Connection | One endpoint and model for chat and the fleet default on first setup. No separate model assignments to learn. |
+| Autonomy | `auto-edit`: workspace edits are allowed; unrecognized commands need approval. The safety policy still applies. |
+| Parallel work | One worker at a time, so a single local model or shared endpoint is not flooded by default. Explicit `auto` still allows four workers. |
+| Worker permissions | Deny worker tool requests that need approval (`deny`), returning a structured denial so the worker can continue. This works across native and external runtimes. Interactive operator escalation is available for mediated runtimes in Settings. |
+| Cost | $5 tracked session budget. This depends on reported usage and known pricing; it is not a provider billing cap. |
+| Thinking | Low for chat, off for workers; actual support depends on the chosen model. |
+| Model limits | Runtime/model discovery supplies limits where available. `chat.maxOutputTokens: 0` uses the resolved model limit. Unknown models still use Clio's fallback limits; set a capability override in Settings if the server cannot advertise its actual capacity. |
+| Long sessions | Automatic compaction at 80% context pressure, with working-set management enabled. Compaction uses the chat model. |
+| Bounded work | Up to 3 chat retries, 2 worker retries, 60 chat tool calls per turn, 150 tool calls per worker run, and a 15-minute internal worker timeout. |
+| Background activity | Prompt prewarm is off. Memory stays rules-only without a separate memory route. No automatic peer setup or library sync. |
+| Terminal | Regular terminal mode, smooth streaming on automatic TTY detection, no panes or desktop notifications. |
+| Extensions and trust | No configured external peers or runtime plugins; project resource imports are untrusted by default. |
+
+Newly initialized settings contain these values. Existing explicit values are
+preserved; omitted keys inherit the current shipped defaults. For this release,
+the changed defaults are worker concurrency `1`, prewarm `false`, and smooth
+streaming `auto`. See the
+[full settings reference](configuration-reference.md) for every key.
+
+## Advanced settings
+
+Choose **Settings**, or run `clio-coder configure --settings`, to open the full
+configuration menu:
+
+- **Targets & Auth**: add, edit, rename, or remove a target; choose chat, fleet,
+  and background-memory defaults. Add and Edit share the full target wizard.
+  Adding a target preserves existing defaults. Editing preserves its other
+  capabilities, gateway settings, and role-specific model overrides. Rename
+  updates the target name and its references together.
+- **Models & Thinking**, **Chat Defaults**, **Fleet**, **Permissions & Autonomy**,
+  **Panes & Layout**, and **Skills & Extensions** cover common settings.
+- **Diagnostics** shows paths, runs the read-only doctor, and displays saved YAML.
+- **All Settings** opens a validated editor for every settings key, including
+  fleet profiles, routing, memory, compaction, plugins, hooks, and keybindings.
+
+Escape returns to the parent menu, which remembers the selected row. Each
+accepted setting is saved immediately; leaving another field does not undo
+previously accepted settings. Clear a model override or list by deleting its
+prefilled text before accepting it. The full target wizard instead saves at
+**Save target** after review. Pasted keys wait for Save; browser sign-in stores
+credentials when sign-in succeeds. Optional delegation review follows Save.
+
+Open a section directly, or open the full editor:
 
 ```bash
-cd /path/to/your/repo
-clio-coder doctor --fix
-clio-coder configure --list
+clio-coder configure --section targets
+clio-coder configure --section models
+clio-coder configure --edit
 ```
 
+The editor uses `VISUAL`, then `EDITOR`, then an available `nano` or `vi`. It edits
+a temporary draft, validates it against the same schema Clio uses at startup,
+and asks you to save, return to the editor, or discard. Invalid YAML or settings
+never replace the saved file. A save keeps the previous file at
+`settings.yaml.bak` and refuses to overwrite concurrent changes. `--edit` also
+works when malformed settings prevent the regular menu from loading.
+
+These commands edit user settings. Approved project settings and session
+choices can override them; use `clio-coder config inspect` to see the active
+sources. Without a terminal, `--section` prints its values and exits; `--json`
+and `--list` inspect settings and runtimes without initializing an installation.
+Dumb terminals retain the numbered prompt fallback; Quick Connect requires a
+regular interactive terminal. Use explicit flags for unattended target setup.
+
 Start one local runtime and register exactly one target first. Clio integrates with popular local inference engines:
 - **[LM Studio](https://lmstudio.ai):** A desktop application to run LLMs locally. Target runtime ID: `lmstudio`.
 - **[Ollama](https://ollama.com):** A lightweight, extensible framework for building and running LLMs locally. Target runtime ID: `ollama-native`.
@@ -74,8 +169,8 @@ Start one local runtime and register exactly one target first. Clio integrates w
 - **[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
+The full target wizard completes a valid orchestrator before it offers any
+worker-only colleague. Quick Connect skips this optional review. 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
@@ -176,7 +271,7 @@ chat:
     favorites: []
     recentLimit: 12
   maxOutputTokens: 0
-  prewarm: true
+  prewarm: false
 
 fleet:
   default:
@@ -187,7 +282,7 @@ fleet:
   rosters: {}
   agentProfiles: {}
   nodes: []
-  concurrency: auto
+  concurrency: 1
 
 context:
   workingSet:
@@ -215,8 +310,8 @@ safety:
     enabled: false
 
 interface:
-  outputDetail: default
-  smoothStreaming: off
+  outputDetail: standard
+  smoothStreaming: auto
   mode: regular
   fullscreenScrollbar: auto
   terminalProgress: false
@@ -583,7 +678,7 @@ each as a stable deep link:
 | `targets` | Runtime connections, advertised models, auth metadata, and capability overrides |
 | `context` | Working set, compaction, and proactive memory |
 | `safety` | Autonomy, cost/tool/read limits, and the optional review watchdog |
-| `interface` | Output detail, terminal behavior, notifications, keybindings, and experimental pane settings |
+| `interface` | Output style, terminal behavior, notifications, keybindings, and experimental pane settings |
 | `integrations` | Project-resource trust, external agents, runtime plugins, resource library, and Git attribution |
 
 The Center groups rows with task-oriented labels such as Orchestrator, Targets,
@@ -616,7 +711,7 @@ This is the version-2 durable schema shipped in `DEFAULT_SETTINGS`. Validation i
 | `chat.modelPicker.favorites` | `[]` | list of target/model references | immediately |
 | `chat.modelPicker.recentLimit` | `12` | integer ≥ 1 | immediately |
 | `chat.maxOutputTokens` | `0` | integer ≥ 0; `0` uses the model cap or the 32,768-token fallback when unknown | next turn |
-| `chat.prewarm` | `true` | boolean | next turn |
+| `chat.prewarm` | `false` | boolean | next turn |
 | `chat.retry.enabled` | `true` | boolean | next turn |
 | `chat.retry.maxRetries` | `3` | integer ≥ 0 | next turn |
 | `chat.retry.baseDelayMs` | `2000` | integer ≥ 0 | next turn |
@@ -642,7 +737,7 @@ This is the version-2 durable schema shipped in `DEFAULT_SETTINGS`. Validation i
 | `fleet.permissions.mode` | `deny` | `deny`, `fail`, `escalate` | next dispatch |
 | `fleet.permissions.escalation.timeoutMs` | `120000` | integer ≥ 1 | next dispatch |
 | `fleet.permissions.escalation.fallback` | `deny` | `deny` or `fail` | next dispatch |
-| `fleet.concurrency` | `auto` | `auto` or integer ≥ 1 | restart |
+| `fleet.concurrency` | `1` | `auto` or integer ≥ 1 | restart |
 | `fleet.retry.maxRetries` | `2` | integer ≥ 0 | next dispatch |
 | `fleet.retry.routeCooldownMs` | `15000` | integer ≥ 0 | next dispatch |
 | `fleet.limits.toolCallsPerRun` | `150` | integer ≥ 1 | next dispatch |
@@ -694,10 +789,10 @@ The safety-limit leaves have no one-process `CLIO_CODER_*` overrides in the curr
 | Key | Default | Validation | When it applies |
 | --- | --- | --- | --- |
 | `interface.terminalProgress` | `false` | boolean | next turn |
-| `interface.outputDetail` | `default` | `minimal`, `default`, `verbose` | next turn |
+| `interface.outputDetail` | `standard` | `compact`, `standard`, `detailed` | immediately |
 | `interface.mode` | `regular` | `regular` or `fullscreen` | restart |
 | `interface.fullscreenScrollbar` | `auto` | `hidden`, `auto`, `always` | restart |
-| `interface.smoothStreaming` | `off` | `off`, `auto`, `on` | immediately |
+| `interface.smoothStreaming` | `auto` | `off`, `auto`, `on` | immediately |
 | `interface.desktopNotifications` | `false` | boolean | next turn |
 | `interface.panes.enabled` | `off` | `auto`, `embedded`, `off` | restart |
 | `interface.panes.notifications` | `failures` | `failures`, `all`, `off` | immediately |
@@ -778,10 +873,11 @@ Review and connect detected agents with:
 clio-coder configure --interop
 ```
 
-On a terminal this walks the pending proposals one at a time, showing the exact
-YAML entry before it asks, and writes only what you answer yes to. Without a
+On a terminal this shows one list of pending proposals with their launch
+commands. Space selects peers and Enter confirms the selection. Without a
 TTY it prints the proposals and exits 0 with `settings.yaml` byte-identical.
-The interactive `clio-coder configure` wizard ends with the same review, and
+The full target wizard in Settings offers the same review after saving
+the first primary target; Quick Connect skips it. Also,
 `/agents connect` in the TUI opens the same flow.
 
 No code path writes `integrations.externalAgents.entries` without an operator
@@ -1141,3 +1237,7 @@ clio-coder auth status <target-or-runtime>
 ```
 
 When opening issues, include the Clio version, Node version, target id/runtime, model id, whether the live model listing succeeds (or the target probe result), and a redacted receipt or command transcript.
+
+## 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.

package/docs/guide/configuration-reference.md

@@ -20,7 +20,7 @@ Precedence, where several surfaces set the same value: a one-run CLI flag beats
 | `chat.modelPicker.cycleSet` | `[]` | Exact `target` or `target/model` refs Alt+J/Alt+K cycle through (refs with an empty target part are dropped); session-owned routing state, immediate this session, saved default next session. | session routing (Alt+J/K, `/settings`) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `chat.modelPicker.favorites` | `[]` | Exact `target/model` refs pinned in the focused model picker; refs naming an unconfigured target are dropped at validation; applies immediately. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `chat.modelPicker.recentLimit` | `12` | How many recently selected `target/model` refs `recent-models.json` keeps (integer >= 1); applies immediately. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `chat.prewarm` | `true` | Whether the known prompt prefix is sent to a `local-native` server at session start, after resume, and after compaction to fill its prefix cache (boolean; no effect on other tiers, workers, headless); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
+| `chat.prewarm` | `false` | Whether the known prompt prefix is sent to a `local-native` server at session start, after resume, and after compaction to fill its prefix cache (boolean; no effect on other tiers, workers, headless); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `chat.retry.baseDelayMs` | `2000` | First backoff delay in ms for chat-loop retries, doubled per attempt up to `maxDelayMs` (integer >= 0); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `chat.retry.enabled` | `true` | Master switch for transient-provider retries in the interactive chat loop (boolean); dispatched workers use `fleet.retry.maxRetries` instead; applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `chat.retry.maxDelayMs` | `60000` | Ceiling in ms on the exponential backoff between chat-loop retries (integer >= 0); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
@@ -52,7 +52,7 @@ Precedence, where several surfaces set the same value: a one-run CLI flag beats
 | `fleet.adaptiveRouting.roles` | `[]` | Execution roles (`researcher`, `verifier`, `reviewer`, `judge`) for which measured joint routing may change execution; unlisted roles only record a shadow recommendation; applies next dispatch. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `fleet.agentProfiles` | `{}` | Map of native agent id to a `fleet.profiles` name so that agent's dispatches use that route (`auto` is reserved; ACP agents cannot be bound); applies next dispatch. | `run --target` > `run --agent-profile` > session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `fleet.agentProfiles.<key>` |  | One binding: the key is the native agent id, the value the `fleet.profiles` name used when that agent is dispatched without an explicit profile; applies next dispatch. |  |
-| `fleet.concurrency` | `auto` | Maximum concurrently running local workers: `auto` currently resolves to the compiled default of 4, or set an integer >= 1; applies at restart. |  |
+| `fleet.concurrency` | `1` | Maximum concurrently running local workers: `auto` currently resolves to the compiled default of 4, or set an integer >= 1; applies at restart. |  |
 | `fleet.default.model` | `null` | Saved default model id for workers (string or null; null rebases to the target's `defaultModel`); applies next session. | `run --model` > selected `fleet.profiles` route model > session routing (`/settings`) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `fleet.default.target` | `null` | Saved default target id for dispatched workers and `/run` (configured id or null; dangling ids become null); seeds session routing, so applies next session. | `run --target` > `run --agent-profile`/`--agent-runtime` > `fleet.agentProfiles` binding to a `fleet.profiles` route > session routing (`/settings`) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `fleet.default.thinkingLevel` | `off` | Saved default thinking level for workers (`off` through `max`); applies next session. | `run --thinking` > selected `fleet.profiles` route thinkingLevel > session routing (`/settings`) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
@@ -115,7 +115,7 @@ Precedence, where several surfaces set the same value: a one-run CLI flag beats
 | `interface.keybindings` | `{}` | Map of binding id (`clio-coder.*`; legacy `clio.*` ids are renamed) to a key string or list of key strings; invalid bindings are reported at boot; applies immediately. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `interface.keybindings.<key>` |  | One rebinding: the key is a binding id such as `clio-coder.notifications.dismiss`, the value a key string or a list of alternatives; applies immediately. |  |
 | `interface.mode` | `regular` | Renderer: `regular` keeps scrollback, `fullscreen` uses the alternate screen with a sticky layout; applies at restart. |  |
-| `interface.outputDetail` | `default` | Transcript detail level: `minimal`, `default`, `verbose`; applies next turn. | session override (`/output`, `/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
+| `interface.outputDetail` | `standard` | Output style: `compact`, `standard`, `detailed`; applies immediately. Legacy `minimal`/`default`/`verbose` values are accepted. | session override (Alt+O, `/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `interface.panes.enabled` | `off` | Pane-host rung: `auto` detects a guest pane host, `embedded` asks Clio to own a session (behaves as `auto` until implemented), `off` skips detection; applies at restart. | `--no-panes` / `--with-panes` (`--with-panes` keeps a saved `embedded`, otherwise `auto`) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `interface.panes.files.enabled` | `false` | Whether the files pane (yazi) may open (boolean); applies on the next files-pane open. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `interface.panes.files.followCwd` | `true` | Whether the files pane follows the conversation's working directory (boolean); applies on the next files-pane open. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
@@ -125,7 +125,7 @@ Precedence, where several surfaces set the same value: a one-run CLI flag beats
 | `interface.panes.layout` | `off` | Docks composed at interactive boot in guest mode: `off` opens nothing, `workers` opens the workers dock, `cockpit` opens workers and files; applies at restart. |  |
 | `interface.panes.notifications` | `failures` | Which terminal run states raise a pane-host toast: `failures`, `all`, `off`; applies immediately. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `interface.panes.workers.ratio` | `0.34` | Share of terminal width the workers dock takes (number 0.05 through 0.5); applies at restart. |  |
-| `interface.smoothStreaming` | `off` | Presentation-only pacing of streamed assistant text and thinking: `off`, `auto` (TTY heuristics), `on`; applies immediately. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
+| `interface.smoothStreaming` | `auto` | Presentation-only pacing of streamed assistant text and thinking: `off`, `auto` (TTY heuristics), `on`; applies immediately. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `interface.terminalProgress` | `false` | Whether terminal progress (OSC progress) is emitted while a turn runs (boolean); applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `safety.autonomy` | `auto-edit` | Baseline autonomy for tool admission: `read-only`, `suggest`, `auto-edit`, `full-auto`; applies immediately (an ACP session's own autonomy wins inside that session). | `run --autonomy` (stored as the session override `safety.autonomy`) > session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
 | `safety.limits.chatToolCallsPerTurn` | `60` | Soft per-turn tool-call budget for the chat agent (integer >= 1); crossing it blocks further calls with a stop-and-summarize directive, the hard ceiling sits 15 above; applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
@@ -191,6 +191,7 @@ Read from the process environment at boot unless the row says otherwise.
 | `APPDATA` | `~\AppData\Roaming` | Windows-only base directory for the config and data roots (`%APPDATA%\clio-coder\config`, `%APPDATA%\clio-coder\data`); ignored on other platforms. |  |
 | `CI` | `unset` | Any non-empty value marks a CI run and makes smooth-streaming `auto` fall back to the immediate coalescer instead of paced animation; explicit `on` is unaffected. |  |
 | `CLIO_CODER_ALLOW_EXTERNAL_FULL_ACCESS` | `unset (disabled)` | Exactly `1` lets a `full-auto` dispatch to the claude-code or antigravity-code subprocess runtime pass their dangerous skip-permissions flag; any other value keeps the bypass closed. |  |
+| `CLIO_CODER_ANTHROPIC_CACHE_RETENTION` | `unset` | Read per native Anthropic provider call: `none`, `short`, or `long` cache retention. Long TTL requires model compatibility; unset preserves SDK defaults. | explicit call option > env > SDK default |
 | `CLIO_CODER_BIN_DIR` | `~/.local/bin` | Directory holding the `clio-coder` launcher symlink that uninstall removes and the install script creates; a path, defaulting to `~/.local/bin`. |  |
 | `CLIO_CODER_BUS_TRACE` | `unset (disabled)` | Exactly `1` subscribes a tracer to the shutdown, session-end, and domain lifecycle bus channels and writes one `[clio-coder:bus]` line per event to stderr. |  |
 | `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 |
@@ -220,7 +221,10 @@ Read from the process environment at boot unless the row says otherwise.
 | `CLIO_CODER_LMSTUDIO_CORESIDENT_CONTEXT` | `131072` | Positive integer ceiling on the context length requested when loading an LM Studio model next to another resident model; `off`, `0`, or `false` disables the clamp. |  |
 | `CLIO_CODER_MEMORY_TRACE` | `unset (disabled)` | File path for a JSONL trace of proactive task-memory step envelopes including up to 8000 chars of model text per step; off when unset or empty. |  |
 | `CLIO_CODER_MODEL_CATALOG_DIRS` | `unset` | PATH-delimited list of extra model-catalog overlay directories, applied after the user and project overlays with the highest precedence. |  |
-| `CLIO_CODER_NO_NETWORK_TOOLS` | `unset (disabled)` | Exactly `1` removes the network (RETRIEVE) tools from every registry built in the process; `clio-coder skills-eval` sets it for hermetic arms and `--allow-network` deletes it. | `skills-eval --allow-network` clears it for child arms; otherwise env only |
+| `CLIO_CODER_DISABLE_RETRIEVE_TOOLS` | off | Exactly `1` removes RETRIEVE tools from registries; `clio-coder skills-eval` sets it for child arms. Bash, hooks, external CLIs, and provider networking remain available; OS isolation is required for hermetic runs. Legacy `CLIO_CODER_NO_NETWORK_TOOLS=1` remains accepted. | `skills-eval --allow-network` clears both spellings for child arms |
+| `CLIO_CODER_NO_NETWORK_TOOLS` | off | Legacy alias of `CLIO_CODER_DISABLE_RETRIEVE_TOOLS`; disables retrieval tools only, with no shell network isolation. | env only |
+| `CLIO_CODER_PROVIDER_DUMP_PATH` | `unset` | Read per native provider call: absolute path for private JSONL request-body and terminal-response diagnostics. Parent must exist; the file must be operator-owned, regular, mode `0600`, and not a symlink. Known credentials are redacted; prompt and tool content remain. | env only |
+| `CLIO_CODER_WEB_FETCH_ALLOW_PRIVATE_NETWORK` | off | Exactly `1` allows web_fetch to reach private and local services. This operator process opt-in is not accepted from model arguments or project settings. | env only |
 | `CLIO_CODER_PACKAGE_ROOT` | `auto-detected` | Path used as the package root for bundled assets and docs instead of walking up to package.json; the docs engine re-reads it live, other callers cache the first answer. |  |
 | `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. |  |
@@ -338,8 +342,10 @@ Grouped by command. Global flags appear under `global`.
 
 | Flag | Controls |
 |---|---|
+| `--hash` | For `config trust safety\|hooks\|settings`, approve the exact full SHA-256 digest returned by a prior review; a changed review is refused. |
 | `--help` | Print the command's usage and exit. |
-| `--json` | For `config inspect`, emit the customization graph as JSON. |
+| `--json` | For `config inspect`, emit the customization graph; for `config trust safety\|hooks\|settings`, emit a read-only source and trust preview. |
+| `--revoke` | For `config trust safety\|hooks\|settings`, withdraw this workspace's approval for that configuration surface. |
 | `-h` | Short form of --help. |
 
 ### `configure`
@@ -353,6 +359,11 @@ Grouped by command. Global flags appear under `global`.
 | `--api-key-env` | Name of the environment variable read for the target's API key at call time, instead of storing a literal. |
 | `--background-model` | Model id to use when this target is set as the proactive task-memory (background) target. |
 | `--context-window` | Capability override: positive integer context window in tokens recorded on the target instead of the probed or catalog value. |
+| `--quick` | Open Quick Connect directly: endpoint, key if needed, model, and Connect. Requires a terminal. |
+| `--settings` | Open the full settings menu directly. |
+| `--edit` | Open all user settings in VISUAL/EDITOR as a draft; validate and confirm before saving, retain settings.yaml.bak, and allow repair of malformed YAML. Requires a terminal. |
+| `--json` | Print effective user settings as JSON without initializing the installation. |
+| `--section` | Open targets, models, chat, fleet, permissions, panes, skills, diagnostics, or advanced (All Settings); without a terminal, print the section values and exit. |
 | `--fleet-model` | Model id stored as the fleet default model when this target becomes the fleet default target (mutually exclusive with `--agent-profile`). |
 | `--force` | Save a model outside the runtime catalog, or one the target does not advertise, without refusing. |
 | `--gateway` | Mark the registered target as a gateway. |
@@ -774,6 +785,7 @@ Grouped by command. Global flags appear under `global`.
 
 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.
 
 ### `.clio-coder/agents`
 
@@ -855,7 +867,7 @@ Keys read from files under `.clio-coder/` in the repository.
 | `commands[].requireConfirmation` | `true` parks the command for operator approval even at an autonomy level that would otherwise run it. |  |
 | `commands[].shellOperators` | `allow` admits pipes, redirects, and chaining in the command line; `deny` refuses them. |  |
 | `commands[].timeoutMs` | Wall-clock cap for the command; overrides the bash call's own `timeout_ms`. |  |
-| `disableDefaultPathPolicy` | `true` drops the built-in path policy (protected dotfiles, secrets, build outputs) so only the file's own path lists apply. |  |
+| `disableDefaultPathPolicy` | In an approved safety policy, `true` drops project-default path rules. Operator credentials, settings, skills, trust records, and host authority paths remain protected. |  |
 | `noDeletePaths` | Globs tools may read and write but never delete. |  |
 | `noWritePaths` | Globs tools may read and delete but never write. |  |
 | `readOnlyPaths` | Globs tools may read but never write or delete. |  |
@@ -929,6 +941,7 @@ Keys the recipe loader reads from `.clio-coder/agents/<id>.md` and the builtin r
 | `projectContextTier` |  | Enum `none \| bounded`; `bounded` injects the capped project name/conventions/invariants projection as a dynamic message and `none` skips the CLIO-CODER.md read. |
 | `resultContract` |  | Required object naming the typed result shape the worker must return; the terminal output is validated and repaired against it. |
 | `resultContract.kind` |  | One of twelve recipe-declarable report kinds (`scout-report`, `mutation-report`, `delegation-plan`, ...) or `architect-plan`; `council-ballot` may only arrive as a coordinator override. |
+| `resultContract.maxSummaryBytes` | 16384 | Optional integer between 1 and 32768 allowed only for `mutation-report`; sets the inline summary byte allowance before model dispatch. |
 | `resultContract.path` |  | Workspace-relative plan file path required only by `architect-plan` and refused for any other kind; absolute or `..` paths are rejected. |
 | `skills` |  | Array of unique skill names bound to files at registry load; they inject knowledge into the prompt, require the `context` tool, and never widen tool authority. |
 | `tags` |  | Array of unique lowercase routing hints shown in the catalog and matched against task signals when ranking candidate agents. |
@@ -1021,6 +1034,7 @@ Arguments the model can send on `dispatch`, `bash`, `context`, and `verify`, gro
 | `dispatch.model` | policy | Default model override. |
 | `dispatch.node` | policy | Default fleet node pin (omit for automatic placement). |
 | `dispatch.persona` | task | Default persona for the batch, max 8000 chars. |
+| `dispatch.result_summary_max_bytes` | policy | Sets the inline summary byte allowance for `mutation-report` contracts (1 to 32768, default 16384). Inherited by mutating tasks; ignored by non-mutation steps. |
 | `dispatch.review` | policy | Reviewer gate for one task: a read-only reviewer verdicts pass, revise, or fail, and revise re-runs the builder with the findings. |
 | `dispatch.review.max_cycles` | policy | Review/revise cycles before an operator decision (default 2, max 4). |
 | `dispatch.review.model` | policy | Model for the reviewer. |
@@ -1048,6 +1062,7 @@ Arguments the model can send on `dispatch`, `bash`, `context`, and `verify`, gro
 | `dispatch.tasks[].intent` | policy | Per-task intent (`$defs.intent`); it must fit inside the batch `intent`. |
 | `dispatch.tasks[].model` | policy | Per-task model override. |
 | `dispatch.tasks[].node` | policy | Fleet node pin: local or a fleet.nodes id. |
+| `dispatch.tasks[].result_summary_max_bytes` | policy | Per-task summary allowance override for `mutation-report` contracts (1 to 32768). Fails validation on non-mutation steps. |
 | `dispatch.tasks[].target` | policy | Per-task target id override. |
 | `dispatch.tasks[].task` | task | The assignment, with expected output and constraints. |
 | `dispatch.tasks[].worktree` | policy | Run this writer in an isolated git worktree. |

package/docs/guide/environment-variables.md

@@ -5,7 +5,7 @@
 
 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 `npm 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`.
+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`.
 
 ## Behavior knobs without a settings key
 
@@ -14,6 +14,8 @@ The `environment-variable-inventory` check in `scripts/check-hygiene.ts`, run by
 | `NO_COLOR` | unset | Set to any non-empty value to drop every foreground and background color. Bold, dim, italic, and underline stay, because they are what is left to read the interface by (`src/interactive/theme/tokens.ts`). |
 | `CLIO_CODER_RIGOR` | repo-derived | Finish-contract evidence bar, `normal` or `high`, layered over the repo-derived default (`src/domains/safety/rigor.ts`). |
 | `CLIO_CODER_ALLOW_EXTERNAL_FULL_ACCESS` | off | `1` lets full-auto pass through to external CLI runtimes with their own full access (`src/engine/claude/subprocess-runtime.ts`, `src/engine/antigravity/subprocess-runtime.ts`). |
+| `CLIO_CODER_ANTHROPIC_CACHE_RETENTION` | unset | Native engine requests using `anthropic-messages` accept `none`, `short`, or `long`. Long requests ask for a one-hour cache TTL when the model's compatibility metadata supports it. An explicit per-call preference wins; unset preserves SDK defaults, and other APIs are unchanged (`src/engine/provider-diagnostics.ts`). |
+| `CLIO_CODER_PROVIDER_DUMP_PATH` | unset | Absolute path for opt-in native-provider JSONL diagnostics. One record per completed call contains payloads after caller callbacks and the terminal response. The parent directory must exist; the file must be operator-owned, regular, mode `0600`, and not a symlink. New files use that mode. Auth options and headers are omitted, known provider credentials are redacted, and prompt/message/tool content is retained. Keep this diagnostic private and delete it when finished. Ledger events are unchanged; external CLI transports are not captured (`src/engine/provider-diagnostics.ts`). |
 | `CLIO_CODER_FORCE_COMPACT` | off | `1` forces compaction before every interactive turn for as long as it is set (`src/interactive/chat-loop.ts`). |
 | `CLIO_CODER_LEGACY_MASK` | off | `1` temporarily restores the destructive stale-observation mask before summary compaction; remove it after compatibility diagnosis. |
 | `CLIO_CODER_STATUS_STUCK_MS` | 180000 | Stuck-turn watchdog threshold (`src/interactive/status/watchdog.ts`). |
@@ -28,7 +30,9 @@ The `environment-variable-inventory` check in `scripts/check-hygiene.ts`, run by
 | `CLIO_CODER_SKILL_MARKETPLACE_INDEX` | unset | Skill-marketplace index path override (`src/domains/resources/skills/marketplace.ts`). |
 | `CLIO_CODER_MODEL_CATALOG_DIRS` | unset | Extra model-catalog directories (`src/domains/providers/knowledge-base-path.ts`). |
 | `CLIO_CODER_ENDPOINT_SLOTS_TTL_MS` | 86400000 | How long a persisted endpoint slot count answers for an endpoint nothing has probed in this process. A record past the bound is ignored and pruned rather than allowed to over-admit (`src/domains/providers/endpoint-slots-store.ts`). |
-| `CLIO_CODER_NO_NETWORK_TOOLS` | off | `1` strips network tools from every registry in the process; the skills-eval harness sets it for hermetic arms; `--allow-network` clears it (`src/tools/network-policy.ts`). |
+| `CLIO_CODER_DISABLE_RETRIEVE_TOOLS` | off | `1` strips RETRIEVE tools from registries. Bash, hooks, external CLIs, and provider networking remain available; hermetic runs require OS isolation. Legacy `CLIO_CODER_NO_NETWORK_TOOLS=1` is accepted; `skills-eval --allow-network` clears both spellings. |
+| `CLIO_CODER_NO_NETWORK_TOOLS` | off | Legacy alias of `CLIO_CODER_DISABLE_RETRIEVE_TOOLS`; disables retrieval tools only, with no shell network isolation. |
+| `CLIO_CODER_WEB_FETCH_ALLOW_PRIVATE_NETWORK` | off | `1` permits web_fetch to reach private and local services; operator process setting only, never a tool argument or project setting (`src/tools/network-policy.ts`). |
 | `CLIO_CODER_REDUCE_MOTION` | off | `1` makes smooth-streaming `auto` use the immediate coalescer. Explicit `on` remains an operator request, while stdout backpressure still pauses frame production. |
 | `CLIO_CODER_SCREEN_READER` | off | `1` makes smooth-streaming `auto` use the immediate coalescer so a screen reader receives the existing low-motion update behavior. |
 | `CLIO_CODER_INSTANT_SHELL` | on | `0` disables the single-owner Stage 0 interactive shell for immediate rollback. Unset or `1` mounts one terminal/editor owner before service hydration; ACP, headless, ordinary non-TTY, and subcommand paths never mount it. An explicit `CLIO_CODER_INTERACTIVE=1` keeps its force-interactive non-TTY behavior. |

package/docs/guide/fleet-dispatch.md

@@ -841,12 +841,7 @@ hard block.
   and a one-line receipt footer showing the outcome glyph, token count, duration,
   and contract status (such as `└ ✓ ok · 8.4k tok · 18s · contract unmeasured`),
   with the failure reason printed on the rail above the footer when a run fails.
-- Runs the model itself asked for through the dispatch tool (identified by
-  parentToolCallId) render as folded `◆` cards under the spawning tool segment;
-  operator-typed runs are `◇` and open. The fold chord uses the `clio-coder.tool.expand`
-  keybinding (`Alt+O`), which toggles the newest foldable item of either kind
-  (tool call or worker block). `Ctrl+Alt+O` or `Alt+Shift+O` toggles every tool
-  call and worker block at once.
+- Model-launched workers use `◆`; operator-launched workers use `◇`. Both follow the current Output style: Compact identity/outcome, Standard short summary, Detailed bounded activity and a larger summary. `Alt+O` cycles styles for the session. `/view transcript` and `/view dispatch:<runId>` expose full available details. Execution success and validation quality remain separate facts.
 - Sharing: nothing a worker produced enters the main model's context unless
   `--share` was passed or the operator runs `/share [runId]`. What enters is a
   bounded note of the shape `[worker result] <agent> · run <id> · <outcome> · shared by the operator`
@@ -962,3 +957,15 @@ the contract explicitly with `clio-coder fleet run <name>` and retain its
 receipts. The [fleet demo runbook](../process/fleet-demo-runbook.md) provides a bounded
 end-to-end scenario, including reviewer gates and verification commands. Live
 fleet execution is not hidden inside deterministic CI.
+
+## Bounded result delivery
+
+Documenter and Coder use a structured report (`mutation-report`). Explicit recipe selections remain in force. For a read-only explanation, its `summary` carries the requested explanation and citations, with `mutatedPaths` empty. The inline `summary` allows up to 16,384 UTF-8 bytes by default, configurable up to a ceiling of 32,768 UTF-8 bytes via recipe `maxSummaryBytes` or dispatch `result_summary_max_bytes`. In batch dispatches, a top-level `result_summary_max_bytes` default is inherited by mutating tasks and safely ignored by non-mutation steps; setting an explicit per-task `result_summary_max_bytes` on a non-mutation step fails validation before model dispatch. Authored `commitMessage` and `architect-plan` authorship remain bounded at 1,000 UTF-8 bytes. Coder and Documenter explanations have no global 15-line limit. If worker output exceeds the sealed output bound, capture fails explicitly naming the bound rather than reporting an ambiguous JSON syntax error. If the requested answer cannot fit within the summary allowance or cannot be grounded, the summary must state the specific limitation. A longer artifact requires authorization to write it; a shortened answer or validation log does not satisfy an unmet length requirement.
+
+Documenter exposes no arbitrary shell commands; it relies on declared verifier checks or grounded source reads. In validation reporting, unexecuted checks must never be recorded as failures (`passed: false` applies only to checks that actually ran and failed). Unexecuted checks or execution limitations belong in the `summary` deliverable as stated limitations.
+
+The Scout recipe instructs the model to return structured findings with source paths and exact lines checked against live reads. A search hit alone does not establish a citation. On repair, unsupported findings should be removed rather than moved to convenient range endpoints. Inline delivery and schema conformance do not establish semantic citation accuracy.
+
+Ordinary dispatcher, council, and wiki planning time and tool estimates are advisory during execution rather than automatic aborts. Enforced bounds are explicit caller deadlines (`timeout_ms`), operator cancellation, contract output bounds, and capacity rules. The fleet tool-call cap limits tool use. The `fleet.limits.internalRunTimeoutMs` setting bounds internal CLI dispatch; it does not impose a wall-clock deadline on ordinary TUI dispatch workers.
+
+A pipeline stops before admitting a dependent when a completed step reports failed quality. Execution success, result conformance, and deliverable quality remain separate facts. An independent recovery has its own receipt and does not replace the failed pipeline result. When delivery is missing or incomplete, report the terminal result and limitation; a successful process exit alone does not establish the requested deliverable.

package/docs/guide/glossary.md

@@ -90,7 +90,7 @@ This document defines the 50 core architectural concepts and terminology used th
 - **Owning Type**: `WorkerShareFacts` in `src/interactive/worker-share.ts`.
 
 ### 21. Fold
-- **Definition**: Collapsing an expanded tool call or worker block down to a single-line summary row. Toggled for the newest foldable item with `Alt+O` or for all items with `Ctrl+Alt+O` / `Alt+Shift+O`.
+- **Definition**: Presenting an action as a short summary in the current Output style. `Alt+O` cycles Compact, Standard, and Detailed. Use `/view transcript` for full available details.
 - **Owning Type**: `WorkerEntryRenderOptions` in `src/interactive/renderers/worker-entry.ts`.
 
 ### 22. Interop

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

@@ -3,7 +3,40 @@
 > **Visual blueprint:** The source checkout includes the complete
 > [Installation and Lifecycle Operations visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/lifecycle_blueprint.html).
 
-Clio Coder is designed to be self-contained and platform-compliant. This document outlines the default directory paths, file purposes, permission levels, and lifecycle commands (`install`, `reset`, `upgrade`, and `uninstall`). Clio Coder installs from npm as `@iowarp/clio-coder` (`npm install -g @iowarp/clio-coder`, published since v0.3.0) or from a source checkout with a deterministic local symlink; the CLI classifies both install kinds and `clio-coder upgrade` handles each.
+Clio Coder installs from the npm registry as `@iowarp/clio-coder` using npm,
+pnpm, or Bun, or from a source checkout using the pinned pnpm workflow. The
+[README installation guide](../../README.md#install) covers global installs,
+cached runners (npm exec/npx, pnpm dlx, bunx, and Yarn dlx), release tarballs,
+and manager-specific update and removal commands. All routes require Node.js
+`>=22.19.0`, including installations managed by Bun.
+
+Repository development uses pnpm 10.34.5 and `pnpm-lock.yaml`. Registry
+consumers install the built package and do not need the repository toolchain.
+This guide describes the default directories, file purposes, permissions, and
+lifecycle operations.
+
+### Start, change settings, or recover
+
+| Task | Command | Result |
+| --- | --- | --- |
+| Set up a new installation | `clio-coder configure` | Quick Connect: endpoint, key if needed, model, Connect; then start `clio-coder`. |
+| Change a connection | `clio-coder configure --section targets` | Add or edit endpoints, credentials, and models; choose role defaults. |
+| Change any setting or repair YAML | `clio-coder configure --edit` | Edit a draft, validate, and save with a backup. |
+| Diagnose the installation | `clio-coder doctor` | Read-only diagnosis. `clio-coder doctor --fix` repairs structure and permissions. |
+| Finish a package-manager update | `clio-coder upgrade --post-install` | Apply local migrations and installation checks. |
+| Start configuration over | `clio-coder reset --config` | Reset settings, preserve credentials and history, then run `clio-coder configure`. |
+| Emulate a fresh user | `clio-coder reset --all` | Remove all four user roots, recreate defaults, then run `clio-coder configure`. |
+| Remove user state | `clio-coder uninstall` | Remove the selected user roots; remove the package with the manager that installed it. |
+
+Reset and uninstall preview their scope and ask for confirmation. Use
+`--dry-run` to inspect without changing anything. A bare `reset` clears session
+state, so use `--config` when your intent is to start model setup over. Project
+`.clio-coder/` directories survive these user-level operations.
+
+The source installer prepares the launcher and directory structure, then points
+you to `clio-coder configure`. It does not ask you to configure delegation peers
+before your primary model is set up. Upgrading preserves settings and
+credentials; reinstalling the package alone does not reset them.
 
 ### Optional dependency: the Claude Agent SDK
 
@@ -11,6 +44,8 @@ Clio Coder is designed to be self-contained and platform-compliant. This documen
 
 ```bash
 npm install -g @iowarp/clio-coder --omit=optional
+# Or: pnpm add -g @iowarp/clio-coder --no-optional
+# Or: bun add -g @iowarp/clio-coder --omit=optional
 ```
 
 Measured on Linux x64 with a production install (`--omit=dev`): 387MB across 118 packages with the SDK, 143MB across 109 packages without it. That is 244MB and nine packages saved, a 63% smaller tree, and what remains is fully open-licensed.
@@ -119,7 +154,7 @@ Use the local source installer from the cloned repository:
 ```bash
 git clone https://github.com/iowarp/clio-coder.git
 cd clio-coder
-npm run install:local
+pnpm run install:local
 hash -r
 clio-coder --version
 ```
@@ -127,8 +162,8 @@ clio-coder --version
 `scripts/install-local.sh` is idempotent and auditable:
 
 - verifies `node` satisfies `package.json` `engines.node`;
-- runs `npm ci` unless `node_modules` satisfies the lockfile or `--skip-deps` is passed;
-- runs `npm run build` unless `--no-build` is passed;
+- runs `pnpm install --frozen-lockfile` to sync dependencies with the workspace lockfile unless `--skip-deps` is passed;
+- runs `pnpm run build` unless `--no-build` is passed;
 - verifies `dist/cli/index.js` exists and is executable;
 - creates `${CLIO_CODER_BIN_DIR:-$HOME/.local/bin}` and links `clio-coder` there;
 - warns if that bin dir is not on `PATH`, and warns when another `clio-coder`
@@ -195,11 +230,25 @@ Refreshes state metadata and applies pending lifecycle migrations, which may upd
 ```bash
 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
-(migration check, `install.json` refresh) and prints the real update steps,
-`git pull`, `npm run install:local`, `hash -r`. The npm reinstall path applies
-only to a genuinely npm-installed binary.
+On a source checkout, the command applies pending migrations, refreshes
+`install.json`, and prints the source update steps (`git pull`,
+`pnpm run install:local`, `hash -r`). An npm global installation can be
+reinstalled through npm when a newer version or pending work requires it.
+
+For pnpm, Bun, Yarn, repository-local, and cached installations, first update
+with the package manager that owns that installation, then run:
+
+```bash
+clio-coder upgrade --post-install
+clio-coder doctor
+```
+
+`--post-install` applies local migration and metadata checks without querying
+the registry or reinstalling a package. Its `--dry-run` previews only those
+local operations. Automatic package replacement without this flag currently
+assumes npm for packaged installations; use the owning manager's removal
+command as well. Package removal preserves Clio's user configuration and
+sessions; the uninstall operation below deliberately removes those roots.
 
 #### Current migration contract
 
@@ -270,7 +319,7 @@ Key lifecycle and operational updates in v0.3.7:
 - Fullscreen TUI mode (`interface.mode`, `interface.fullscreenScrollbar`) is
   available through `/settings interface` and requires a restart. Adaptive
   presentation pacing is the live `interface.smoothStreaming` setting; it
-  defaults to `off`, with conservative `auto` and explicit `on` available from
+  defaults to conservative `auto`, with `off` and explicit `on` available from
   the same area.
 - Interactive launch paints a measured Stage 0 shell on the same terminal and editor that Stage 1 hydrates. Typing, queued submits, resize, and Ctrl+C remain live during hydration; set `CLIO_CODER_INSTANT_SHELL=0` for the legacy fully hydrated first-frame path.
 - Turn settlement is enforced on `/new`, `/resume`, `/tree`, and `/fork` to cleanly commit in-flight streams before session writer replacement (#114).
@@ -382,18 +431,20 @@ 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:
+
+The interactive launcher starts with **Quick Connect**, followed by **Settings**
+and **Diagnostics**. Quick Connect asks for an endpoint URL, a key when needed,
+and a model when several are available. Review and **Connect**; the recommended
+defaults handle the rest. An unconfigured interactive `clio-coder` opens this
+same launcher and continues into chat after a successful setup.
 
 ```bash
-clio-coder configure [--section <name>] [--json] [--interop] [--list] [--all]
+clio-coder configure
+clio-coder configure --quick
+clio-coder configure --settings
 ```
 
-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:
+**Settings** contains the nine advanced sections:
 
 1. **Targets & Auth**: manage providers, endpoints, credentials, and models.
 2. **Models & Thinking**: default models, thinking levels, model favorites, cycle set.
@@ -403,14 +454,22 @@ runtime sections:
 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.
+9. **All Settings**: validated file editor for the complete settings schema.
 
 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`).
+and provides arrow-key navigation with Escape to go back and `q` to quit. The
+parent menu remembers your selected row. Dumb terminals use numbered menus
+with `b` for Back and `q` to quit.
 
 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.
+The `--json` flag emits user settings with defaults in formatted JSON for scripting.
+`--edit` opens a temporary settings draft in `VISUAL`/`EDITOR`, validates it before
+saving, and keeps the previous file as `settings.yaml.bak`. It can repair a file
+that is too malformed to open the regular menu. See the
+[configuration guide](configuration-and-targets.md#first-run-flow) for the complete
+new-user, add-target, edit-target, and cancellation paths.
 
 ---