samagotchi 0.2.0 → 0.4.0

data/docs/configuration.md

@@ -2,26 +2,38 @@
 
 ## Global Config File
 
-Chi can preload a global config file and expose those entries as environment
-variables before the app boots.
+Chi reads its settings from three places; the first that sets a value wins:
+
+1. a CLI flag (`--server-port 8081`),
+2. an environment variable (`SAMAGOTCHI_SERVER_PORT=8081`),
+3. the global config file (`server: {port: 8081}`),
+
+then the built-in default. [All settings](#all-settings) lists them.
+
+`chi bootstrap HOST[:PORT]` writes a first config for a model server, or adds
+it to this file as a `hosts:` entry (see [First setup](cli.md#first-setup)).
 
 Default path:
 
 - `$XDG_CONFIG_HOME/samagotchi/config.yml`
 - Fallback when `XDG_CONFIG_HOME` is unset: `~/.config/samagotchi/config.yml`
 
-Example:
+Example (every section is optional except `default.model`; README.md has a
+minimal one):
 
 ```yaml
-SAMAGOTCHI_DEFAULT_MODEL: Qwen3-14B-Instruct
-server:
+default:
+  model: Qwen3-14B-Instruct
+server:                 # the model server when there is no hosts: map below
   host: 192.0.2.10
   port: 8081
-SAMAGOTCHI_THINKING_UI: spinner
+thinking:
+  ui: spinner
+  level: default        # off | low | medium | high | default; see "Thinking"
 
 # Multi-host (optional): aggregated /models and per-model routing.
-# Bare SAMAGOTCHI_DEFAULT_MODEL uses the default host; host:model pins to a host.
-# Transport per host overrides SAMAGOTCHI_SERVER_TRANSPORT; api: openai makes a
+# A bare default.model uses the default host; host:model pins to a host.
+# transport: on a host overrides server.transport; api: openai makes a
 # host use the OpenAI chat API instead of chi's raw prompt.
 hosts:
   main:
@@ -58,36 +70,61 @@ session:
   # keep_empty: false       # true keeps sessions nothing happened in (default: deleted when left)
   # max_children: 4         # running sessions one session may have delegated at a time (the delegate tool)
 
-# Baseline memories preloaded into the system prompt (same shape as --memory).
+# Baseline memories preloaded into the system prompt (same shape as --memory);
+# name entries you have, or chi warns at each start.
 # CLI --memory entries are appended after these, deduped.
 memories:
-  - system/user_preferences
-  - project/feature-env-template
+  # - system/user_preferences
+  # - project/feature-env-template
 ```
 
 Behavior:
 
 - The file is optional.
-- Top level is a YAML mapping of scalar env overrides plus nested sections.
-- Real environment variables still win over config-file values.
+- Top level is a YAML mapping of sections (`default:`, `server:`, `recap:`, …)
+  and the maps described below. Keys are lower `snake_case`, one level per
+  dot: `server.read_timeout` is `server: {read_timeout: 600}`.
+- A key chi doesn't read warns at start, with the closest known key:
+  `config: unknown key 'default.modle' (did you mean 'default.model'?)`.
+  Names you choose under the maps below (host names, model ids) don't warn.
+- Environment variables and CLI flags win over config-file values.
 - Workers inherit hosts via `SAMAGOTCHI_HOSTS_JSON` propagated through `SessionManager.spawn_options`.
 
 This lets you run `chi` without repeating common defaults such as model
 and llama host/port on every invocation.
 
-Note: The global config file supports both flat scalar entries (for env vars)
-and nested sections like `hosts:`, `recap:`, `hooks:`, `guardrails:` (see
-[Guardrails](guardrails.md)), `bundles:` (a bundle's settings for its hooks,
-see [Hooks: Settings](hooks.md#settings)), `model_aliases:`,
-`memories:`. Scalar entries are loaded as environment
-variables; non-scalar sections are skipped by the env-loader and parsed by
-their respective subsystems (e.g. the hooks system, `HostRegistry`). The
-`memories:` list is the persistent baseline for preloaded memory entries —
+Besides the settings sections, the file holds maps that are read by their
+own subsystems: `hosts:` (below), `models:` (see "Prompt profile" and
+"Images"), `model_aliases:`, `hooks:` (see [Hooks](hooks.md)),
+`guardrails:` (see [Guardrails](guardrails.md)), `bundles:` (a bundle's
+settings for its hooks, see [Hooks: Settings](hooks.md#settings)) and
+`memories:`. Their entry names (host names, model ids, aliases) are yours to
+choose. The `memories:` list is the persistent baseline for preloaded memory entries —
 the same name shape as `--memory` (bare name or `scope/name`), merged under
 any per-run `--memory` values (config baseline first, deduped). A per-run
 `--mute NAME` removes an entry from the merged list for that session (see
 "Muting a memory" in cli.md).
 
+### Environment variables
+
+Every setting has an environment variable: `SAMAGOTCHI_` plus its dotted
+name in upper case, with `_` for each dot. `default.model` is
+`SAMAGOTCHI_DEFAULT_MODEL`, `server.read_timeout` is
+`SAMAGOTCHI_SERVER_READ_TIMEOUT`. Use them to override the file for one run or
+one shell (`SAMAGOTCHI_LOG_LEVEL=debug chi`); keep lasting choices in the file.
+Most settings also have a CLI flag: the dotted name in kebab case
+(`--server-read-timeout 900`); `chi --help` lists them.
+
+### Legacy flat keys
+
+Older configs used the environment names as top-level keys
+(`SAMAGOTCHI_DEFAULT_MODEL: my-model`). They are still read, but every run
+warns (`config key 'SAMAGOTCHI_DEFAULT_MODEL' is legacy UPPER — use
+'default.model'`). When a file has both, the nested key wins and the warning
+names both (`both 'SAMAGOTCHI_DEFAULT_MODEL' and 'default.model' are set;
+using 'default.model', remove the flat key`). Move each to its nested form (`default: {model: my-model}`) and delete
+the flat line. `/model --default` already writes the nested form.
+
 ## Model Server Transport
 
 Chi talks to a model server over HTTP and supports three transports:
@@ -99,11 +136,13 @@ Chi talks to a model server over HTTP and supports three transports:
   continuous batching + tiered SSD KV cache) using the same `/v1/completions`
   and `/v1/models` endpoints as `mlx`.
 
-Select the transport with `SAMAGOTCHI_SERVER_TRANSPORT` (`llama_cpp`, `mlx`, or
-`omlx`). `SAMAGOTCHI_SERVER_HOST`/`SAMAGOTCHI_SERVER_PORT` are reused for all three —
+> **mlx and oMLX** are not verified with recent chi versions; llama.cpp and
+> OpenAI-compatible hosts (`api: openai`) are the tested paths.
+
+Select the transport with `server.transport` (`llama_cpp`, `mlx`, or `omlx`;
+env `SAMAGOTCHI_SERVER_TRANSPORT`). `server.host`/`server.port` are reused for all three —
 only the request/response shape differs. oMLX's default server port is `8000` (not
-`8080`), so point `SAMAGOTCHI_SERVER_PORT` at it, e.g. `SAMAGOTCHI_SERVER_PORT=8000`.
-With `hosts:` each entry may set `transport: llama_cpp|mlx|omlx` to override the
+`8080`), so point `server.port` at it. With `hosts:` each entry may set `transport: llama_cpp|mlx|omlx` to override the
 global transport per host (`lib/samagotchi/host_registry.rb`).
 
 Each host may also set `api:`, which says how chi talks to it:
@@ -116,11 +155,11 @@ Without `api:` a host uses the raw-prompt loop, as before. The loop follows the
 model's host, so `/model other-host:model` can move a session between the two.
 Workers started by plain `chi`, `chi web` or `--attach` get the same hosts, `api:` included.
 
-Example for mlx-lm:
+Example for mlx-lm (not verified with recent chi versions, like oMLX below):
 
 ```yaml
-SAMAGOTCHI_SERVER_TRANSPORT: mlx
 server:
+  transport: mlx
   host: 127.0.0.1
   port: 8080
 ```
@@ -132,8 +171,8 @@ mlx_lm.server --model mlx-community/Qwen3-14B-Instruct-4bit
 Example for oMLX:
 
 ```yaml
-SAMAGOTCHI_SERVER_TRANSPORT: omlx
 server:
+  transport: omlx
   host: 192.0.2.10
   port: 8000
 ```
@@ -176,6 +215,20 @@ hosts:
 
 `chi self` shows the variable and whether it is set (`api key  FIREWORKS_API_KEY (set)`).
 
+Every host with `api_key_env:` sends `Authorization: Bearer <key>` on each request,
+chat or raw-prompt alike, so a llama.cpp started with `--api-key` works as a native
+host too (`chi bootstrap --key-env VAR` writes such an entry). An unset variable
+fails the turn before any request (`set VAR`); a 401/403 names the variable to
+check, or, on a host without `api_key_env:`, suggests adding it:
+
+```yaml
+hosts:
+  box:
+    host: 192.0.2.20
+    port: 8080
+    api_key_env: BOX_LLAMA_KEY
+```
+
 For models on that host, chi uses the chat loop (its own OpenAI chat adapter): it
 takes the OpenAI base (`url:`, else `http://HOST:PORT/v1`) and streams messages plus
 function schemas from `/v1/chat/completions`; the model's reasoning (`reasoning_content`)
@@ -205,9 +258,9 @@ oMLX's known tool-call limitation (a stream filter that strips markup) only
 affects its `/v1/chat/completions` endpoint, not the `/v1/completions` endpoint
 chi uses, so raw `[[…]]`/`<|tool_call>` markers stream through untouched.
 
-`SAMAGOTCHI_DEFAULT_MODEL` (config default) and `/model` (runtime effective) pick the model; the status line and `/model`
+`default.model` (config default) and `/model` (runtime effective) pick the model; the status line and `/model`
 output always render the runtime effective model (showing default when diverged). Which prompt format it gets is the
-prompt profile (see "Prompt profile" below). How the selector reaches the request differs by transport:
+prompt profile (see "Prompt profile" below). How the selector reaches the request differs by transport (mlx and oMLX: not verified with recent chi versions):
 
 - **mlx** (`mlx_lm.server`): the `model` field is omitted entirely — the server
   uses whatever was loaded via its own `--model` CLI flag.
@@ -217,7 +270,7 @@ prompt profile (see "Prompt profile" below). How the selector reaches the reques
   (case-insensitive) first, then substring, then passed through unchanged. That
   resolved id is usually prefixed (e.g. `mlx-community--gemma-3-4b-it-4bit`), so a
   short selector such as `gemma-3-4b-it-4bit` is what you set in
-  `SAMAGOTCHI_DEFAULT_MODEL`. An unknown selector passes through raw and oMLX 404s,
+  `default.model`. An unknown selector passes through raw and oMLX 404s,
   listing its available models; if `/v1/models` is unreachable, samagotchi falls
   back to the raw selector and lets the server decide (its own 400/404). Either
   error fails the turn with the server's message (see "Server errors" below). Runtime
@@ -231,8 +284,8 @@ syntax, thought tags and stop sequences. That is the prompt profile, `qwen36` or
 worse output: a ChatML model under `gemma4` never hits a stop sequence, generates until its limit and then runs the
 tool calls it made up on the way. The first of these that says something wins:
 
-1. `--profile NAME` (or `--model-profile NAME`), then `SAMAGOTCHI_MODEL_PROFILE`: for every model in the process,
-   including one picked later with `/model`.
+1. `--profile NAME` (or `--model-profile NAME`), then `SAMAGOTCHI_MODEL_PROFILE` (`model.profile` has no config-file
+   form): for every model in the process, including one picked later with `/model`.
 2. `models:` in `config.yml`, keyed by model id or alias (case-insensitive; the name as typed, alias-resolved or
    without its host prefix):
 
@@ -274,13 +327,127 @@ Workers get `hosts:` (with `profile:`) through `SAMAGOTCHI_HOSTS_JSON` and read
 `--profile` reaches the worker a chi starts, but a worker that another process wakes later (`chi web`, `--attach`
 after an idle exit) gets that process's environment, so put a lasting choice in config.
 
+## Sampling
+
+chi asks chat hosts (`api: openai`) for greedy decoding (`temperature: 0.0`) and sends native hosts no sampling
+fields, so their server's defaults apply (llama.cpp: temperature 0.8). `sampling:` on a `hosts:` entry or a `models:`
+entry sets request fields for the model's turns:
+
+```yaml
+hosts:
+  work:
+    url: https://llm.example.com/v1
+    api: openai
+    api_key_env: WORK_API_KEY
+    sampling: { temperature: 0.6, presence_penalty: 1.5 }
+models:
+  qwen3.6-35b-a3b:
+    sampling: { temperature: 0.6, top_p: 0.95, repeat_penalty: 1.1 }
+```
+
+- The fields go into the request as written; chi doesn't check the names, since providers differ (`repeat_penalty`,
+  `min_p`, `dry_multiplier` are llama.cpp's; `presence_penalty` is OpenAI-style). A provider that refuses one fails
+  the turn with its error (`host work rejected the request: HTTP 400: …`; one server answered a `presence_penalty`
+  with "the requested logits or output transformation is not supported"): remove the last field you added from that
+  host's or model's `sampling:`, or set it to `null` in the model's entry. A nested map passes through too, e.g.
+  `chat_template_kwargs: { enable_thinking: false }`.
+- A `models:` entry's fields win over its host's, field by field (the host can set a penalty and the model move only
+  the temperature). The entry is found the way `profile:` is (the name as typed, alias-resolved or without its host
+  prefix).
+- `temperature: null` (or `~`) sends no temperature, so the provider's default applies (vLLM takes it from the
+  model's `generation_config.json`).
+- Fields chi sets itself are refused with a warning: `model`, `messages`, `prompt`, `stream`, `stream_options`,
+  `tools`, `tool_choice`, `stop`, `n_predict`, `max_tokens`, `n`, `parallel_tool_calls`, `response_format`,
+  `cache_prompt`. A `sampling:` that isn't a map warns and is skipped.
+- Greedy decoding can make a heavily quantized thinking model loop in its reasoning ("Let me write the reply…"
+  for minutes) or end with an empty answer. Qwen's own advice for its thinking models is `temperature: 0.6,
+  top_p: 0.95` (not greedy), with `presence_penalty` between 0 and 2 against endless repetition.
+- The idle recap and side questions keep their own short, deterministic settings.
+
+`/model` shows what applies (`sampling: temperature=0.6 presence_penalty=1.5 (hosts.work)`), and each request's
+`stream` line in the debug log carries a `sampling=` field with what was sent. The fields are read every turn, so a
+`/model` switch takes the new model's. A worker gets `hosts:` (with `sampling:`) when it starts, through
+`SAMAGOTCHI_HOSTS_JSON`, and reads `models:` from the config file each turn: after changing a host's `sampling:`,
+stop the session's worker (`chi sessions stop`) for it to take effect.
+
+## Thinking
+
+How much a model thinks before it answers. One level, `off`, `low`, `medium`, `high` or `default`, set per model,
+per host or for everything:
+
+```yaml
+thinking:
+  level: default          # every model without its own level
+hosts:
+  openrouter:
+    url: https://openrouter.ai/api/v1
+    api: openai
+    api_key_env: OPENROUTER_API_KEY
+    thinking: low
+models:
+  qwen3.6-35b-a3b:
+    thinking: off         # unquoted off works (YAML reads it as false)
+```
+
+- `default` sends nothing: the provider's or the chat template's own default, which is chi's behaviour without the
+  setting. For some hybrid models that default is *no* thinking (DeepSeek V3.1 on OpenRouter); `medium` turns it on.
+  `on` isn't a level.
+- Order, first set wins: `--thinking LEVEL` or `SAMAGOTCHI_THINKING_LEVEL`, then the `models:` entry (found the way
+  `profile:` is), then the `hosts:` entry, then `thinking.level` in the file, then `default`. Anything else than a
+  level warns once and counts as unset.
+- The flag reaches the sessions that start with it; a session already running keeps its level. `models:` levels
+  and `thinking.level` in the file are read every turn; a host's `thinking:` reaches a worker when it starts, as
+  its `sampling:` does (`chi sessions stop` to change it).
+- `/model` shows the level and where it came from (`thinking: off (models: qwen3.6-35b-a3b)`), `chi self` too.
+- The idle recap and plugins' side questions always ask with thinking off, whatever the level.
+
+What each backend gets:
+
+| Backend | `off` | `low` / `medium` / `high` |
+|---|---|---|
+| native (`/completion`), `qwen36` | an empty thought after the assistant cue, and no turn preamble | no knob: thinking stays as the model has it, one notice |
+| native, `gemma4` | no `<\|think\|>` token at the start of the system prompt | no knob, one notice |
+| chat host (`api: openai`) | `chat_template_kwargs: {enable_thinking: false}` and `reasoning_effort: "none"` | `reasoning_effort: <level>` |
+
+On chat hosts: llama.cpp honours both off switches but ignores the effort; Splash takes `reasoning_effort` (off only
+through `none`) and scales with it; OpenRouter translates `reasoning_effort` per model (some can't turn thinking off:
+Qwen3-30B-A3B thinks anyway, gpt-oss refuses).
+
+When the model thinks although the level is `off`, chi says so once per session and host
+(`thinking> warning: off wasn't honoured by … (N chars of thinking)`) and logs `thinking_not_honoured` each time.
+When a host answers the thinking fields with an HTTP 400 about reasoning (gpt-oss: "Reasoning is mandatory"), chi
+sends the request again without them, leaves them out for that model from then on, and says so once.
+
+The fields go under the `sampling:` map ("Sampling"): a `sampling:` key wins over the level's, and
+`chat_template_kwargs` merges per sub-key. A `null` there drops a field the level would send, at any depth, for a
+host that refuses one of them:
+
+```yaml
+hosts:
+  strict:
+    url: https://llm.example.com/v1
+    api: openai
+    thinking: off
+    sampling: { reasoning_effort: null }   # sends only enable_thinking: false
+```
+
+A different level changes a native model's system prompt (Gemma's token, Qwen's turn preamble), so the next turn
+reads the whole context again once; on a chat host only the end of the prompt changes.
+
 ## Llama HTTP Timeouts
 
 Long-running llama.cpp completions can exceed Ruby's default HTTP read timeout.
-Configure these environment variables to avoid premature request failures:
+Raise these to avoid premature request failures:
 
-- `SAMAGOTCHI_SERVER_OPEN_TIMEOUT` (default: `10`) connection timeout in seconds.
-- `SAMAGOTCHI_SERVER_READ_TIMEOUT` (default: `600`) response read timeout in seconds.
+- `server.open_timeout` (default: `10`, env `SAMAGOTCHI_SERVER_OPEN_TIMEOUT`) connection timeout in seconds.
+- `server.read_timeout` (default: `600`, env `SAMAGOTCHI_SERVER_READ_TIMEOUT`) response read timeout in seconds.
+  Either timeout at `0` (or anything not a positive number) is its default, on every host.
+
+```yaml
+server:
+  open_timeout: 10
+  read_timeout: 900
+```
 
 A streamed answer also has a **first-token limit**: the seconds it may take to show its first text, reasoning or
 tool call. A remote provider can keep a queued request open for minutes with SSE keep-alive comments
@@ -308,9 +475,10 @@ prompt caches hit and every turn is answered by the same model. Servers that don
 
 To explicitly route requests to a named model in llama.cpp, set:
 
-- `SAMAGOTCHI_DEFAULT_MODEL` (required): model name/id sent as the `model` field on `/completion` requests.
+- `default.model` (required; env `SAMAGOTCHI_DEFAULT_MODEL`, `--model` per run): model name/id sent as the `model`
+  field on `/completion` requests.
 
-When `SAMAGOTCHI_DEFAULT_MODEL` is unset or blank, Samagotchi fails fast with a clear startup/configuration error.
+When `default.model` is unset or blank, Samagotchi fails fast with a clear startup/configuration error.
 
 With several `hosts:`, an unqualified model name goes to the host whose `/models`
 list has it (after `/models` ran), by exact id first, then by substring. A
@@ -321,23 +489,55 @@ the running server (llama.cpp's `/props`), else the window the host's model list
 gives (`context_length`, `context_window`, `max_model_len` or llama.cpp's
 `meta.n_ctx`), else `context.window_tokens`.
 
+A `:` in a model name is often part of the id (`qwen3:8b`, `mistral:7b`,
+`unsloth/Qwen3-8B-GGUF:Q4_K_M`), so the part before the first `:` picks a host
+only when it is a configured host's name. An unknown prefix is refused with an
+error naming it and the configured hosts (with a "did you mean" for a near
+miss) when either
+- the rest is an `org/model` id (`nosuch:anthropic/claude-sonnet-4`), or
+- the prefix is a hosted provider's name: `openrouter`, `openai`, `anthropic`,
+  `google`, `gemini`, `groq`, `xai`, `together` or `fireworks`
+  (`openai:gpt-4o` with no `openai` host).
+
+The check applies wherever the model comes in: `--model`, `default.model`, an
+alias, `/model`, `chi send --new --model`, the web's new-session model and a
+delegate's model. Any other unknown prefix (`nosuch:x`) is sent to the default
+host as the model id.
+
 ## Llama Network Retry Behavior
 
 Transient network failures are retried automatically with exponential backoff.
 
 - Default retries: `5` (up to `6` total attempts including the first call).
 - Default backoff: `0.5s`, `1s`, `2s`, `4s`, `8s`.
-- Retry scope: transient network errors (timeouts, refused/reset connections, EOF/socket reachability failures),
+- Retry scope: transient network errors (timeouts, reset connections, EOF/socket reachability failures),
   HTTP 429 and HTTP 500/502/503/504/529. A `Retry-After` header replaces the backoff delay; one longer than
   60s is not waited out and the error is reported instead.
+- A refused connection (nothing listening) is not retried: the turn fails at once with `can't reach host <name> at
+  <address> (connection refused) — is the server running?`.
 - A stream that has already produced output is never retried (the retry would repeat it); it fails the turn.
 - Cancellation (`Ctrl-C`) is never retried.
 
 Configuration:
 
-- `SAMAGOTCHI_RETRY_MAX` (default `5`): number of retries after the first failed attempt.
-- `SAMAGOTCHI_RETRY_BASE_DELAY` (default `0.5`): backoff base delay in seconds.
-- `SAMAGOTCHI_RETRY_MAX_DELAY` (default `8.0`): cap for backoff delay in seconds.
+- `retry.max` (default `5`, env `SAMAGOTCHI_RETRY_MAX`): number of retries after the first failed attempt.
+- `retry.base_delay` (default `0.5`, env `SAMAGOTCHI_RETRY_BASE_DELAY`): backoff base delay in seconds.
+- `retry.max_delay` (default `8.0`, env `SAMAGOTCHI_RETRY_MAX_DELAY`): cap for backoff delay in seconds.
+
+```yaml
+retry:
+  max: 5
+  base_delay: 0.5
+  max_delay: 8.0
+```
+
+`retry.empty_answer` is a different thing: the request worked, but the model's answer had no visible text and no
+tool calls (thinking only, or nothing; a thinking loop cut by the provider's output cap looks like this). chi then
+asks again in the same turn with a hidden note ("your last reply had no visible answer…"), at `temperature: 0.6`
+unless `sampling:` sets one; the REPL prints `↻ empty answer, asking again (1/1)` and the web shows it as a row of
+the step. `retry.empty_answer` (default `1`, at most `3`, env `SAMAGOTCHI_RETRY_EMPTY_ANSWER`, no CLI flag) is how
+many times per turn; `0` ends the turn at the empty answer as before. An answer cut because the context is full
+(90 % or more) is not retried. When the retries run out the turn ends with "(the model returned an empty answer)".
 
 Assist-mode UX:
 
@@ -352,7 +552,7 @@ message (before, a failed llama.cpp `/completion` ended the turn as
 
 | Kind | When | Retried |
 |---|---|---|
-| connection | refused, reset, timed out, dropped mid-stream | yes (network retry), not mid-stream |
+| connection | reset, timed out, dropped mid-stream; refused | yes (network retry), not mid-stream; refused: no |
 | rate limited | HTTP 429 | yes, honouring `Retry-After` |
 | server | HTTP 5xx, llama.cpp's mid-stream `error:` event | 500/502/503/504/529 only |
 | auth | HTTP 401/403 | no |
@@ -467,7 +667,7 @@ Whether a model can see images is found out before a turn with images is sent:
 - a native llama.cpp host: `/props` must report `modalities.vision` (the server
   runs with `--mmproj`) and a media marker, and the prompt profile must know the
   chat template's image wrapping (qwen36 does; gemma4 not yet);
-- mlx and oMLX hosts: no;
+- mlx and oMLX hosts: no (not verified with recent chi versions);
 - an OpenAI-API host: a local llama.cpp's `/props`, else the host's model list
   (OpenRouter's `architecture.input_modalities`); when it doesn't say, the image
   is sent and a refusal is reported.
@@ -489,6 +689,92 @@ modalities check: without a media marker the prompt can't carry an image.
 If an AGENT.md file is present in the project root, samagotchi injects its
 contents into the system prompt under a "Project specific description:" section.
 
-To skip loading AGENT.md, set:
-
-`SAMAGOTCHI_SKIP_AGENT_MD=true`
+To skip loading AGENT.md, set `skip_agent_md: true` at the top level of
+`config.yml` (env `SAMAGOTCHI_SKIP_AGENT_MD=true`).
+
+## All settings
+
+Every setting below takes the three forms described in
+[Environment variables](#environment-variables): a nested key in
+`config.yml`, `SAMAGOTCHI_<DOTTED_NAME>` in the environment and, where the CLI
+column says so, a `--kebab-name` flag. The maps (`hosts:`, `models:`,
+`model_aliases:`, `hooks:`, `guardrails:` rules, `bundles:`, `memories:`) are
+described in their own sections.
+
+| Setting | Default | CLI | What it does |
+|---|---|---|---|
+| `default.model` | (required) | `--model` | The model a new session starts with; `host:model` pins a host. |
+| `default.input` | none | | Text pre-filled at the first prompt (a trailing space is kept); `--no-default-input` skips it. See [CLI](cli.md). |
+| `default.n_predict` | server's | yes | Most tokens one generation may produce (native hosts). |
+| `model.profile` | none | `--profile` | Prompt profile for every model (`qwen36`, `gemma4`); env and CLI only. See "Prompt profile". |
+| `server.transport` | `llama_cpp` | yes | `llama_cpp`, `mlx` or `omlx`; see "Model Server Transport". |
+| `server.host` | `localhost` | yes | The model server when there is no `hosts:` map. |
+| `server.port` | `8080` | yes | Its port. |
+| `server.open_timeout` | `10` | yes | Connection timeout, seconds. |
+| `server.read_timeout` | `600` | yes | Read timeout, seconds. |
+| `server.first_token_timeout` | 120 remote, off local | | Seconds to the first token; `0` = off. `hosts.<name>.first_token_timeout` wins. |
+| `recap.enabled` | on | | `false` (or `recap: false`) turns the idle recap off. |
+| `recap.model` | session's | yes | Model that writes the recap. |
+| `recap.host_ref` | session's | yes | A `hosts:` name to ask (`host:` is accepted too). |
+| `recap.base_url` | none | yes | An OpenAI API base to ask instead (`http://h:8081/v1`). |
+| `recap.inactivity` | `180` | yes | Idle seconds before a recap. |
+| `recap.timeout` | `30` | yes | Seconds a recap request may take. |
+| `recap.min_user_turns` | `2` | yes | Prompts a session needs before it gets a recap. |
+| `recap.sentences` | `2-4` | yes | Recap length, `N` or `N-M` (1–10). |
+| `session.shared` | `true` | | Plain `chi` runs its session in a worker and attaches; `--no-shared` per run. |
+| `session.idle_exit_minutes` | `30` | yes | An unused worker exits after this; `0` = never. |
+| `session.keep_empty` | `false` | | Keep sessions nothing happened in. |
+| `session.max_children` | `4` | | Running delegated sessions one session may have. |
+| `session.retention_days` | `14` | yes | Delete sessions not updated for N days; `0` = forever. See [Sessions](sessions.md). |
+| `session.max_count` | `500` | yes | Keep the newest N; `0` = uncapped. |
+| `session.keep_status` | `running` | yes | Comma list of statuses never pruned. |
+| `session.sweep_interval_hours` | `24` | yes | How often the retention sweep runs. |
+| `image.max_side` | `1568` | | See "Images". |
+| `image.max_bytes` | `3750000` | | See "Images". |
+| `image.max_per_request` | `20` | | See "Images". |
+| `guardrails.enabled` | `true` | | See [Guardrails](guardrails.md). |
+| `log.file` | state dir | yes | See "Debug Log File". |
+| `log.disable` | `false` | yes | No file logging. |
+| `log.level` | `info` | yes | `debug`, `info`, `warn`, `error`. |
+| `status.line` | `on` | yes | The REPL status line, `on` or `off`. |
+| `status.width_mode` | `terminal_cap` | yes | `terminal_cap` (terminal width up to `max_width`) or `fixed`. |
+| `status.max_width` | `160` | yes | Cap for `terminal_cap`. |
+| `status.fixed_width` | `120` | yes | Width for `fixed`. |
+| `context.status` | `true` | yes | Context-usage telemetry for the model. See [context telemetry](internals/context-telemetry.md). |
+| `context.window_tokens` | server's, else 256000 | yes | Context window when the server doesn't report one. |
+| `context.chars_per_token` | `4.0` | yes | Estimate ratio when the server reports no usage. |
+| `context.status_thresholds` | `20,40,60,80` | yes | Percentages that trigger a status. |
+| `context.status_cadence` | `0` | yes | Also every N rounds; `0` = thresholds only. |
+| `thinking.ui` | `spinner` | yes | `spinner` or `off`. |
+| `thinking.render_interval` | `0.08` | yes | Seconds between thinking redraws. |
+| `thinking.turn_preamble` | `true` | yes | Ask a `qwen36` model to open its thinking with a short `TURN:` line (the step label). |
+| `thinking.level` | `default` | `--thinking` | `off`, `low`, `medium`, `high` or `default` for every model; the flag and env outrank the `models:`/`hosts:` entries, the file's value doesn't. See "Thinking". |
+| `models.<key>.thinking`, `hosts.<name>.thinking` | none | | A model's or host's level. See "Thinking". |
+| `max_tool_output_chars` | `10000` | yes | Tool output kept in the conversation; a top-level key (see below). |
+| `retry.max` | `5` | yes | See "Llama Network Retry Behavior". |
+| `retry.base_delay` | `0.5` | yes | |
+| `retry.max_delay` | `8.0` | yes | |
+| `retry.empty_answer` | `1` | | Times a turn asks again after an empty answer (at most 3, `0` = off). See "Llama Network Retry Behavior". |
+| `update.gem` | `true` | | `false`: `chi update` never installs a newer gem (`--no-gem` for one run). See [CLI: Updating](cli.md#updating). |
+| `update.bundles` | `true` | | `false`: `chi update` leaves the shipped bundles to `chi bundle upgrade` (`--no-bundles`). |
+| `update.desktop` | `true` | | `false`: `chi update` leaves the desktop helper alone (`--no-desktop`). |
+| `read.truncate_at_bytes` | `65536` | yes | A `read` result larger than this is cut to a preview. |
+| `read.preview_bytes` | `12288` | yes | Size of that preview. |
+| `read.hard_max_bytes` | `2097152` | yes | Largest file `read` opens. |
+| `read.telemetry_threshold_pct` | `80` | yes | A `read` result that alone fills this % of the context window carries a token estimate. |
+| `execute.truncate_at_bytes` | `65536` | yes | The same for `execute` output. |
+| `execute.preview_bytes` | `12288` | yes | |
+| `execute.telemetry_threshold_pct` | `80` | yes | |
+| `web.port` | `4567` | `--port` | `chi web`'s port. See [CLI](cli.md). |
+| `web.host` | `127.0.0.1` | yes | `127.0.0.1`, `::1` or `localhost`. |
+| `web.markdown` | `false` | yes | Render answers as Markdown in `chi web`. |
+| `web.turn_view` | `true` | yes | One block per turn; `false` = the row of bubbles. |
+| `web.annotate_presets` | `Agreed\|Could you please elaborate?` | yes | Quick replies next to Annotate in `chi web`, `\|`-separated (a YAML list works too); `""` in the file or on the CLI leaves only Annotate (an empty env value means the default). See [CLI](cli.md#web-annotate-presets). |
+| `history.file` | state dir | | Prompt history path. |
+| `no_interrupt` | `false` | `--no-interrupt` | Raise the tool-call limit of a turn to 1000; a top-level key. |
+| `no_default_input` | `false` | `--no-default-input` | Don't pre-fill `default.input`; a top-level key. |
+| `skip_agent_md` | `false` | | Don't load AGENT.md; a top-level key (see below). |
+
+`max_tool_output_chars`, `skip_agent_md`, `no_interrupt` and
+`no_default_input` have no section: in `config.yml` they are top-level keys as
+written (`max_tool_output_chars: 20000`).

data/docs/desktop.md

@@ -1,6 +1,7 @@
 # Desktop helper (macOS)
 
-`chi desktop` installs **Chi Helper**, a small native app. It sends text you selected in any app to a chi session,
+`chi desktop` installs **Chi Helper**, a small native app. It sends text you selected in any app (or a screenshot,
+an image: see [Images](#images)) to a chi session,
 either with a question as [your message](sessions.md#sending-a-message) (a turn runs, and the answer shows in the
 attached terminal or web page), or as a [context note](sessions.md#context-notes) (the model sees it on its next
 turn, and no turn starts).
@@ -27,8 +28,40 @@ it's still live; if there's only one live session, that one is (a recent one nev
 session starts its worker; a note to one waits for its next start, and the panel shows chi's line saying so. After a
 send the panel shows chi's line and closes. On an error it stays open and shows the error.
 
+The first row, **New session in <folder>** (⌘0), starts a session with the message instead: `chi send --new --dir
+<folder>`, so it shows in `chi web` at once (see [Starting a session](sessions.md#starting-a-session)). The folder is
+that of the most recently updated live session, else of the newest recent one, else your home folder. It is ticked
+alone (ticking it clears the sessions and the reverse) and is preselected when no session is live. ⌘⏎ on it beeps: a
+note needs a session. After the send the panel shows `started <id>…` for 3 s.
+
 A session open in a `chi --no-shared` REPL isn't listed: it takes no notes or messages.
 
+## Images
+
+The panel also sends images, as attachments of the message (`chi send --image`, see
+[Sending a message](sessions.md#sending-a-message)):
+
+- **A screenshot:** ⌃⇧⌘4 (a region to the clipboard), then ⌃⌥⌘N. The panel shows it as a thumbnail, named
+  `clipboard.png`; the context box stays empty.
+- **Finder:** right-click image files → Services → **Send to chi** (the same Service as for text, so its shortcut
+  works here too), or ⌘C on them and ⌃⌥⌘N. Up to 20 at once.
+- **Other apps:** a picture selected in Preview, Safari's Copy Image, anything that puts image data on the clipboard.
+- **Drop** image files or the floating screenshot thumbnail (⇧⌘4 to a file) anywhere on the open panel: they are
+  added to the ones there.
+
+When the clipboard holds both text and a picture (cells copied in Numbers or Excel), the text wins, as before. The
+thumbnails sit under the message line, 48 px high, the file name as a tooltip; hover one for its ✕.
+
+- A message is required with images: the line says "Say something about the image…", and ⏎ does nothing until
+  there is text (the context box counts).
+- Notes are text only: ⌘⏎ with images beeps and says "Notes are text only: ⏎ sends the image as a message".
+- The session's model must see images. A text-only one fails the turn in the session (the attached terminal or the
+  web shows why); the panel has already said it was sent.
+- A session busy with a turn runs the image message as its next turn: the line says `(runs after the current turn)`.
+- Clipboard and dropped image data goes to temp files under `$TMPDIR/chi-helper`, deleted after the send or when
+  the panel closes; files from Finder are sent as they are, never touched. A send with images may take up to 30 s
+  (converting, a worker starting) before the panel gives up.
+
 ## Install
 
 ```sh
@@ -47,16 +80,22 @@ don't break it. From a checkout it runs **that** checkout's `bin/chi`; installin
 warning, because the helper stops working once that worktree is removed. After switching between a checkout and a
 gem install, run `chi desktop upgrade` from the one you now use.
 
+`chi update` keeps it current: it rebuilds and restarts the helper only when its Swift sources changed since the
+build (`launch.json` records their digest) or the Ruby it runs moved. A new chi that left the sources alone only
+rewrites `launch.json`, which the app reads at each send, so the app keeps its older version number and that's fine.
+
 ## Commands
 
 | Command | Does |
 |---|---|
 | `chi desktop install [--force] [--login]` | builds, installs and starts it; `--force` replaces an existing copy |
-| `chi desktop upgrade` | rebuilds it for this chi and restarts it, keeping the login setting |
+| `chi desktop upgrade` | rebuilds it for this chi and restarts it, keeping the login setting (always; `chi update` does it only when needed) |
 | `chi desktop uninstall` | quits it and removes the app, its login item, launch file and settings |
 | `chi desktop status` | version against chi's, how it runs chi, state dirs, Service, hotkey, process, login item |
 
-`chi self` has a `desktop` line: `0.1.x (matches)`, `0.1.w (chi is 0.1.x: chi desktop upgrade)` or `not installed`.
+`chi self` has a `desktop` line: `0.1.x (matches)`, `0.1.w (up to date for chi 0.1.x)` (an older build whose sources
+haven't changed), `0.1.w (chi is 0.1.x: chi update)` (a rebuild is due) or `not installed`. `chi desktop status`
+says the same.
 
 ## How it runs chi
 
@@ -86,7 +125,7 @@ Each call is stopped after 10 s. A stopped `chi note` says the note may be partl
 ## Troubleshooting
 
 - **"chi not found at …, run `chi desktop upgrade`"**: the Ruby or checkout in `launch.json` moved (a Ruby upgrade,
-  a removed worktree). Run `chi desktop upgrade` from the chi you use now.
+  a removed worktree). Run `chi desktop upgrade` (or `chi update`) from the chi you use now.
 - **No "Send to chi" in the Services menu:** check `chi desktop status` (service). Try
   `/System/Library/CoreServices/pbs -update`, start the app again, or log out and back in. It must be ticked in
   System Settings → Keyboard → Keyboard Shortcuts… → Services → Text.
@@ -94,4 +133,6 @@ Each call is stopped after 10 s. A stopped `chi note` says the note may be partl
   restarts or you log out: macOS caches Services.
 - **⌃⌥⌘N does nothing:** `status` says whether another app holds it. macOS doesn't report clashes with its own
   shortcuts.
+- **"Send to chi" missing on images in Finder or Preview** after an upgrade: the Services cache still has the old
+  (text-only) entry; `/System/Library/CoreServices/pbs -update`, restart the helper, or log out and back in.
 - **"No live sessions":** start one with `chi` in a terminal; `chi sessions list --live --scope=all` shows the same list.

data/docs/guardrails.md

@@ -38,6 +38,17 @@ once it closes. On a short terminal the list shrinks (the hint row, then the `in
 lines, then the header go, then the options fold onto fewer rows). Once answered, one
 line stays in the scrollback: `! execute: git push origin main → Allow once`.
 
+An `edit` or `write` also shows the change it would make, computed without
+touching the file: a `change: +3 −1` line in the question (`new file, 12 lines`;
+`would fail: old text not found in …` when the edit can't apply), and the
+unified diff itself. The web card shows the diff under the path (20 lines,
+then "show all"); the terminals print it above the question, green and red,
+40 lines at most (the rest is on the web). Binary files and files over 1 MB
+say so instead of a diff. After the call runs, its row shows what really
+changed: `diff +3 −1` under the row on the web (closed, it survives a
+reload) and ` +3 −1` at the end of the terminal's tool line. The model never
+sees these diffs.
+
 Who answers:
 
 - REPL (`chi --no-shared`, `-p` without `--non-interactive`): at the `? ` prompt.