@iowarp/clio-coder 0.4.5 → 0.4.7

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

@@ -47,26 +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
-corepack enable pnpm
-pnpm install --frozen-lockfile
-pnpm 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`.
@@ -75,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
@@ -177,7 +271,7 @@ chat:
     favorites: []
     recentLimit: 12
   maxOutputTokens: 0
-  prewarm: true
+  prewarm: false
 
 fleet:
   default:
@@ -188,7 +282,7 @@ fleet:
   rosters: {}
   agentProfiles: {}
   nodes: []
-  concurrency: auto
+  concurrency: 1
 
 context:
   workingSet:
@@ -216,8 +310,8 @@ safety:
     enabled: false
 
 interface:
-  outputDetail: default
-  smoothStreaming: off
+  outputDetail: standard
+  smoothStreaming: auto
   mode: regular
   fullscreenScrollbar: auto
   terminalProgress: false
@@ -584,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,
@@ -617,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 |
@@ -643,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 |
@@ -695,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 |
@@ -779,11 +873,12 @@ 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
-`/agents connect` in the TUI opens the same flow.
+The full target wizard in Settings offers the same review after saving
+the first primary target; Quick Connect skips it. Also,
+`/interop` in the TUI opens the same flow.
 
 No code path writes `integrations.externalAgents.entries` without an operator
 decision, and `doctor --fix` is not such a path. An accepted proposal appends

package/docs/guide/configuration-reference.md

@@ -3,7 +3,7 @@
 > **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 the code read at the 0.4.2 cut and is maintained by hand with each release. 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).
+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.
 
@@ -16,18 +16,18 @@ Precedence, where several surfaces set the same value: a one-run CLI flag beats
 | Name | Default | Controls | Precedence |
 |---|---|---|---|
 | `chat.maxOutputTokens` | `0` | Global output-token budget requested on every chat turn (integer >= 0, `0` means per-model caps only); clamped to the model's max-output cap and remaining context window, with the product's 32,768-token ceiling used when the model cap is unknown; applies next turn. | session override (`/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `chat.model` | `null` | Saved default chat model id (string or null); null with a target set rebases to that target's `defaultModel` at validation; applies next session. | `run --model` > session routing (`/model`, `/thinking`, Alt+J/K, `/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `chat.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.model` | `null` | Saved default chat model id (string or null); null with a target set rebases to that target's `defaultModel` at validation; applies next session. | `run --model` > 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.modelPicker.cycleSet` | `[]` | Exact `target` or `target/model` refs configured model-cycle keys cycle through (refs with an empty target part are dropped); session-owned routing state, immediate this session, saved default next session. | session routing (configured model-cycle actions, `/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 |
 | `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.target` | `null` | Saved default chat target id (configured id or null); a dangling id normalizes to null and clears `chat.model`; seeds session routing at launch, so applies next session. | `run --target` > session routing (`/model`, `/thinking`, Alt+J/K, `/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
-| `chat.thinkingLevel` | `low` | Saved default reasoning effort for the chat model: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, clamped to what the model supports at request time; applies next session. | `run --thinking` > session routing (`/model`, `/thinking`, Alt+J/K, `/settings` apply-this-session) > `.clio-coder/settings.local.yaml` > `.clio-coder/settings.yaml` > user settings.yaml > default |
+| `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 |
 | `context.compaction.model` |  | Optional model pattern (prefer exact `target/model`) resolved when compaction runs. Must uniquely match an available HTTP chat model; invalid, ambiguous, unavailable, and worker-only selections fail explicitly. Absent means the current chat route summarizes. |  |
 | `context.compaction.systemPrompt` |  | Optional UTF-8 prompt file read on every compaction to replace the built-in system prompt. Relative paths use the current session workspace (`cwd`); absolute paths are supported. Must be a nonempty regular file of at most 65,536 bytes; read failures are explicit. `/context compact` focus instructions remain separate. |  |
@@ -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 |
@@ -221,7 +221,7 @@ 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_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_DISABLE_RETRIEVE_TOOLS` | off | Exactly `1` removes RETRIEVE tools from registries; `clio-coder eval skill` 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. | `eval skill --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 |
@@ -359,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. |
@@ -431,20 +436,29 @@ Grouped by command. Global flags appear under `global`.
 | Flag | Controls |
 |---|---|
 | `--allow-config-drift` | For `eval compare`, proceed when the two artifacts' configs differ and label the comparison as config drift allowed. |
+| `--allow-network` | For `eval skill`, keep the network tool plane available to the child runs instead of stripping it. |
 | `--baseline` | For `eval gate`, the baseline eval id the candidate is gated against (required). |
 | `--clio-coder-entry` | For `eval run`, path to the clio-coder CLI entry the runner executes; a relative path is pinned to the invoking directory. |
+| `--eval` | For `eval validate --package` and `eval run --package`, the named evaluation to run. |
 | `--format` | For `eval report`: `text`, `json`, `md`, `swe-jsonl`, or `junit`; for `eval compare`: `text`, `json`, `md`, or `junit`. |
 | `--help` | Print the command's usage and exit. |
-| `--json` | For `eval inventory`, the only accepted argument; emits the bounded machine-readable inventory. |
+| `--json` | Emit machine-readable JSON output for `eval inventory` or `eval skill`. |
 | `--metric` | For `eval compare`, the behavioral metric or metric family the comparison is scored on. |
 | `--model` | For `eval run`, wire model id that overrides the suite's model. |
 | `--out` | For `eval run`, path where the eval artifact is written. |
+| `--package` | For `eval validate` and `eval run`, package reference or path (`<path|kind:name>`). |
+| `--project` | For `eval validate --package` and `eval run --package`, target project scope. |
 | `--repeat` | For `eval run --task-file`, positive integer repetitions per v1 task. |
+| `--scenario` | For `eval skill`, the evals.md scenario id (or bare number) to run instead of every scenario. |
 | `--suite` | For `eval validate` and `eval run`, path to the Suite v2 YAML; run takes exactly one of `--suite` or `--task-file`. |
-| `--target` | For `eval run`, target id that overrides the suite's target. |
+| `--target` | For `eval run` and `eval skill`, target id overriding the default target. |
 | `--task-file` | For `eval run`, path to a compatibility v1 task file loaded as a suite. |
 | `--thresholds` | For `eval gate`, path to a thresholds file replacing the built-in gate thresholds. |
+| `--timeout` | For `eval skill`, positive integer seconds allowed per child run. |
 | `--trials` | For `eval run`, positive integer overriding the suite's `matrix.repeats` and requesting a fresh workspace per matrix item. |
+| `--trust-fixtures` | For `eval skill`, allow the fixture shell commands declared in evals.md to execute in the seed workspace. |
+| `--user` | For `eval validate --package` and `eval run --package`, target user scope. |
+| `--workspace` | For `eval skill`, existing checkout copied into the throwaway seed workspace; the source is never mutated. |
 | `-h` | Short form of --help. |
 
 ### `evidence`
@@ -543,12 +557,16 @@ Grouped by command. Global flags appear under `global`.
 
 | Flag | Controls |
 |---|---|
-| `--from` | For `library add`, a catalog directory or path to install from; the literal `catalog` selects the default catalog. |
+| `--all` | For `library skills`, list all discovered runtime skills including unmanaged local files. |
+| `--dry-run` | For `library install`, print the execution plan without writing changes. |
+| `--force` | For `library install`, `register`, and `update`, overwrite existing destination files or force operation. |
+| `--from` | For `library` commands, alternate index or catalog file/URL to read from. |
 | `--help` | Print the command's usage and exit. |
-| `--json` | Emit JSON for `library list`, `search`, and `add`. |
-| `--kind` | For `library list` and `library search`, restrict to one entry kind: `skill`, `agent`, `prompt`, or `fleet`. |
-| `--with-requirements` | For `library add`, also install the entry's unsatisfied requirements instead of refusing. |
-| `--yes` | For `library add`, confirm the install writes; without it the plan is printed and nothing is written. |
+| `--json` | Emit machine-readable JSON output. |
+| `--kind` | For `library list` and `library search`, restrict to one entry kind: `plugin`, `skill`, `agent`, `prompt`, or `fleet`. |
+| `--project` | Target project scope (`.clio-coder/`). |
+| `--user` | Target user scope (`<configDir>/`). |
+| `--with-requirements` | For `library install`, also install the entry's unsatisfied requirements instead of refusing. |
 | `-h` | Short form of --help. |
 
 ### `memory`
@@ -662,26 +680,6 @@ Grouped by command. Global flags appear under `global`.
 | `-f` | Short form of --force for `dev share import`. |
 | `-h` | Short form of --help. |
 
-### `skills`
-
-| Flag | Controls |
-|---|---|
-| `--all` | For `skills list`, include skills the model cannot load; for `skills update`, update every installed skill. |
-| `--allow-network` | For `skills eval`, keep the network tool plane available to the child runs instead of stripping it. |
-| `--category` | For `skills install`, install every marketplace skill in this catalog category instead of naming sources. |
-| `--force` | For `skills install`, `update`, and `sync`, overwrite an existing installed skill. |
-| `--help` | Print the command's usage and exit. |
-| `--json` | Emit JSON for `skills list`, `search`, `inspect`, `validate`, and `eval` (JSONL rows); the only accepted argument for `skills inventory`. |
-| `--name` | For `skills install`, install the single source under this skill name. |
-| `--project` | For `skills install`, choose the project skill root; mutually exclusive with `--user`. |
-| `--scenario` | For `skills eval`, the evals.md scenario id (or bare number) to run instead of every scenario. |
-| `--target` | For `skills eval`, target id used by the baseline, treatment, and judge runs instead of the default target. |
-| `--timeout` | For `skills eval`, positive integer seconds allowed per child run. |
-| `--trust-fixtures` | For `skills eval`, allow the fixture shell commands declared in evals.md to execute in the seed workspace. |
-| `--user` | For `skills install`, choose the user skill root; mutually exclusive with `--project`. |
-| `--workspace` | For `skills eval`, existing checkout copied into the throwaway seed workspace; the source is never mutated. |
-| `-h` | Short form of --help. |
-
 ### `targets`
 
 | Flag | Controls |
@@ -786,7 +784,7 @@ Project safety, hooks, and settings are ignored until the operator reviews them
 
 | Key | Controls | Precedence |
 |---|---|---|
-| `(recipe files)` | Project agent recipes (`<id>.md` with the recipe frontmatter schema); a project recipe must declare `audience: custom` and cannot override a shipped builtin. | For non-builtin ids: project `.clio-coder/agents/` > user agents > enabled-extension agents. Builtins remain protected; user recipes alone may customize a shipped base agent, never a shadow or internal agent. |
+| `(recipe files)` | Project agent recipes (`<id>.md` with the recipe frontmatter schema); a project recipe must declare `audience: custom` and cannot override a shipped builtin. | For non-builtin ids: project `.clio-coder/agents/` > user agents > enabled-plugin agents. Builtins remain protected; user recipes alone may customize a shipped base agent, never a shadow or internal agent. |
 
 ### `.clio-coder/fleets`
 

package/docs/guide/environment-variables.md

@@ -58,7 +58,7 @@ These names follow an upstream or operating-system convention. They are not subs
 | --- | --- |
 | Provider credential variables | `src/engine/env-api-keys.ts` maps the selected provider to its conventional key, including `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`, `GEMINI_API_KEY`, `AWS_*` Bedrock credentials, and Google Vertex application credentials. `clio-coder auth` remains the preferred managed credential path. |
 | `OLLAMA_NUM_PARALLEL` | Fallback concurrency advertised for an Ollama Native target when the runtime does not provide a stronger slot fact (`src/domains/providers/runtimes/local-native/ollama-native.ts`). |
-| `VISUAL`, `EDITOR` | External editor command, with `VISUAL` taking precedence (`src/interactive/external-editor.ts`). |
+| `VISUAL`, `EDITOR` | External editor command, with `VISUAL` taking precedence (`src/core/external-editor.ts`). |
 | `TERM`, `COLORTERM`, `TERM_PROGRAM`, `WT_SESSION` | Terminal capability, color-depth, keybinding, and desktop-notification adaptation. These variables describe the terminal rather than Clio policy. |
 | `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`). |
@@ -89,7 +89,7 @@ These two take a path, not `1`. Setting either to `1` writes a file named `1` in
 Example:
 
 ```bash
-CLIO_CODER_RENDER_TRACE=/tmp/clio-render.jsonl clio-coder
+CLIO_CODER_RENDER_TRACE=/tmp/clio-coder-render.jsonl clio-coder
 ```
 
 ## Internal plumbing

package/docs/guide/exit-codes-and-output.md

@@ -18,7 +18,7 @@ Clio Coder follows a deterministic exit code taxonomy across all commands:
 | **`0`** | **Success** | Successful command execution, clean run settlement, `--version`, `--help` invocation, or missing trace database notice without an explicit `--db` flag. |
 | **`1`** | **Operational Failure** | Execution error, model target unreachable, doctor diagnosis with unresolved issues, explicit `--db` path not found, or evaluation rubric failure (`fail` or `error` verdict). |
 | **`2`** | **Syntax / Usage Error** | Unknown subcommand, invalid flag, missing required positional arguments, global flag placed after subcommand, or data mutation SQL keyword passed to `clio-coder trace sql`. |
-| **`3`** | **Unmeasured / Harness State** | Specific to `clio-coder skills eval`: rubric could not be evaluated due to unparseable judge output, timeout, or evidence archive write failure (distinct from a failure/regression). |
+| **`3`** | **Unmeasured / Harness State** | Specific to `clio-coder eval skill` (formerly `clio-coder skills eval`): rubric could not be evaluated due to unparseable judge output, timeout, or evidence archive write failure (distinct from a failure/regression). Package eval commands (`clio-coder eval run --package`) and suite evaluations return 1 on failure. |
 
 ---