samagotchi 0.2.0 → 0.3.0

data/docs/configuration.md

@@ -2,26 +2,37 @@
 
 ## 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
 
 # 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 +69,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 +135,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 +154,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 +170,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
 ```
@@ -205,9 +243,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 +255,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 +269,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 +312,62 @@ 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.
+
 ## 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:
+
+- `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.
 
-- `SAMAGOTCHI_SERVER_OPEN_TIMEOUT` (default: `10`) connection timeout in seconds.
-- `SAMAGOTCHI_SERVER_READ_TIMEOUT` (default: `600`) response read timeout in seconds.
+```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 +395,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
@@ -335,9 +423,24 @@ Transient network failures are retried automatically with exponential backoff.
 
 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:
 
@@ -467,7 +570,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 +592,87 @@ 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). |
+| `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". |
+| `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

@@ -27,6 +27,12 @@ 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.
 
 ## Install

data/docs/hooks.md

@@ -50,7 +50,7 @@ The plugin class must respond to `#call(event)` — duck-typed, no base class re
 |-------|--------------|---------------|
 | `:session_start` | First turn of the session | `{ type: :session_start, session_id: "..." }` |
 | `:before_turn` | Before each turn starts | `{ type: :before_turn, session_id: "...", prompt: "..." (nil on a continue), messages: [...] (the history before this turn) }` |
-| `:after_turn` | After a turn completed or was cancelled (not after one that failed) | `{ type: :after_turn, status: "completed" \| "canceled", messages: [...] (the conversation the turn stored; a cancelled or empty turn ends it with a `kind: turn_note` system message, and a context line is `kind: context`, see [sessions.md](sessions.md#notes-a-turn-leaves-for-the-model)) }` |
+| `:after_turn` | After a turn completed or was cancelled (not after one that failed) | `{ type: :after_turn, status: "completed" \| "canceled", present: (see [Presenting the answer](#presenting-the-answer-display-only)), messages: [...] (the conversation the turn stored; a cancelled or empty turn ends it with a `kind: turn_note` system message, and a context line is `kind: context`, see [sessions.md](sessions.md#notes-a-turn-leaves-for-the-model)) }` |
 | `:before_generation` | Before each LLM API call (both loops) | `{ type: :before_generation, iteration: N }` |
 | `:after_generation` | After LLM returns (both loops) | `{ type: :after_generation, iteration: N, response: "...", messages: [...] (the conversation as sent) }` |
 | `:before_tool_call` | Before tool dispatch (and before `tool_call_started`) | `{ type: :before_tool_call, iteration: N, call: {...}, params: "...", guardrail: Verdict, context: {...}, targets: {...}, blocked: false, block_reason: nil }` |
@@ -59,7 +59,7 @@ The plugin class must respond to `#call(event)` — duck-typed, no base class re
 
 Every event also carries the hook runtime (next section): `hook:` (the label
 of the hook about to run) and the callables `notify:`, `ask_user:`,
-`stop_turn:`.
+`stop_turn:`, `steer:`.
 
 `messages:` is a **read-only copy**: a frozen array of copied message hashes
 (`{role:, content:, …}`). A hook that mutates it, or its strings, gets
@@ -69,8 +69,8 @@ cheap).
 ## What a hook can do: the runtime
 
 Besides reading (and, on `:before_tool_call`, voting on) its event, a hook
-can talk to the user through three callables the registry puts on every
-event:
+can talk to the user, and to the running turn, through four callables the
+registry puts on every event:
 
 ```ruby
 class Watchful
@@ -94,6 +94,14 @@ class Watchful
       # that call, and the rest of the batch is denied; from :after_turn or
       # :session_end it does nothing (false).
       event[:stop_turn].call("too many iterations without progress") if event[:iteration] > 20
+    when :after_tool_call
+      # Put text into the running turn, as the user's steering does: at the
+      # loop's next boundary it joins the conversation as its own user
+      # message, and every UI shows a nudge line ("<bundle> nudged: …").
+      # True when queued; false with no turn, and from :after_turn or
+      # :session_end. A steer that arrives after the model's final answer is
+      # dropped (logged), not merged: it never keeps a finished turn going.
+      event[:steer].call("Say briefly what you have found so far.") if event[:iteration] == 30
     end
   end
 end
@@ -103,11 +111,55 @@ end
 known-names)` for a bundle hook, `audit.rb (config)` for a config hook,
 `turn hook` for one registered at runtime.
 
+A steer is saved in the session as `{role: "user", kind: "steer", source:
+"<bundle>", content: "…"}`; the model reads only its text, as a user turn.
+Its `source` is the hook's bundle (a config or turn hook's label otherwise).
+
 Timing: a notice from `:after_turn` or `:session_end` shows after the turn's
 end line. A question from `:before_tool_call` shows **before** the tool
 line (the gate runs first), so its text should name the call. The notices
 are also logged (`turn` tag, `hook_notice`).
 
+## Presenting the answer (display only)
+
+`:after_turn` carries one more callable, `present:`. It changes how the
+turn's answer is **shown**, never what the model said: the block gets the
+current display text (the answer's content until a hook changed it) and
+returns the new one.
+
+```ruby
+class Shout
+  def call(event)
+    return unless event[:type] == :after_turn
+
+    event[:present].call { |text| text.gsub(/\bTODO\b/, "**TODO**") }
+  end
+end
+```
+
+- The result is kept as `display` on the answer's model message in the
+  session file. The model never sees it: the prompts and chat requests take
+  the fields they send, and the copies of the conversation given to hooks
+  (`messages:`), plugins (`ctx.messages`) and the recap leave it out.
+- Calls chain in hook order (bundle hooks by priority, then config hooks,
+  then turn hooks): each block gets what the one before returned. The call
+  returns the display text after it.
+- A block that raises, returns something other than a String, or returns
+  more than 200 000 characters leaves the display as it was (logged as
+  `present_rejected` with the hook's label).
+- It works on the stored conversation's last message only when that is the
+  model's answer: after a cancelled, failed or empty turn there is none, and
+  the call returns nil without running the block.
+- **The web** renders `display` instead of the answer (markdown, sanitised
+  like every answer: raw HTML is escaped, only http(s)/mailto links are
+  kept), on a live turn and after a reload. Its copy button copies the
+  display text. The page learns about it from an `answer_display` event
+  that comes after `turn_completed` (the hooks run after the turn ended).
+- **Terminals** (the REPL, the attached TUI) have printed the answer by then
+  and do not change it; use `event[:notify]` for something they should show.
+
+A plugin gets the same from `chi.on(:after_turn) { |event, ctx| event[:present].call { … } }`.
+
 ## Settings
 
 A hook class whose `initialize` takes an argument gets its settings: **one
@@ -299,7 +351,7 @@ Notes:
 - Ordering: bundle hooks fire by `(priority, bundle_name, hook_name)` (lower priority first), then plain `config.yml` hooks in registration order.
 - Settings: a hook class with `initialize(settings = {})` gets the bundle's section of `config.yml` `bundles:` (see [Settings](#settings)).
 - A bundle can also ship a `plugin.rb` whose `chi.on(event)` blocks are bundle hooks too, next to commands and tools; see [Plugins](plugins.md).
-- Shipped bundles: `chi bundle install guardrails` (rules, see [Guardrails](guardrails.md#the-guardrails-bundle)) and `chi bundle install known-names` (a hook, see [Guardrails](guardrails.md#the-known-names-bundle)), `chi bundle install btw` (a plugin: `/btw`, see [Plugins](plugins.md#the-btw-bundle)), `chi bundle install mcp` (a plugin: tools from MCP servers, see [Plugins](plugins.md#the-mcp-bundle)) and `chi bundle install loop-guard` (a plugin: breaks tool-call loops, see [Plugins](plugins.md#the-loop-guard-bundle)).
+- Shipped bundles: `chi bundle install guardrails` (rules, see [Guardrails](guardrails.md#the-guardrails-bundle)) and `chi bundle install known-names` (a hook, see [Guardrails](guardrails.md#the-known-names-bundle)), `chi bundle install source-links` (a hook: announces source refs, see [The source-links bundle](#the-source-links-bundle)), `chi bundle install btw` (a plugin: `/btw`, see [Plugins](plugins.md#the-btw-bundle)), `chi bundle install mcp` (a plugin: tools from MCP servers, see [Plugins](plugins.md#the-mcp-bundle)) `chi bundle install loop-guard` (a plugin: breaks tool-call loops, see [Plugins](plugins.md#the-loop-guard-bundle)) and `chi bundle install check-in` (a plugin: checks on a long turn, see [Plugins](plugins.md#the-check-in-bundle)).
 - Installing a bundle executes its hook code at `Engine` startup. Only install bundles you trust, as you would a gem. Hooks are **not** executed at install time (copy-only); they are `module_eval`'d at `Engine.new` inside per-bundle `Samagotchi::Bundles::<name>` namespaces (no top-level `require` collisions). Keep hook files side-effect-free at load time; do work in `#call` — top-level side effects (require, IO, `at_exit`, global assignment) run once per `Engine.new` (class redefinition is idempotent).
 
 Lifecycle:
@@ -307,3 +359,72 @@ Lifecycle:
 - `chi bundle install <source>` copies `hooks/*.rb` to `~/.config/samagotchi/memories/.bundles/<name>/hooks/` and persists metadata + `trust_level` + `source_commit` (git HEAD) to provenance.
 - `Engine.new` loads `config.yml` hooks first, then bundle hooks via `Provenance.each_installed_holding_hooks` → `Hooks::BundleLoader.load`. Bundle hooks are process-scoped (they survive the per-turn `clear_hooks`; only plain hooks are cleared). Experimental bundles emit a one-line startup warning.
 - `chi bundle status`, `diff`, `uninstall`, `build` are hook-aware (counts, metadata, removal).
+
+## The source-links bundle
+
+```sh
+chi bundle install source-links
+```
+
+installs one `after_turn` hook and a short memory. When the model's answer
+mentions a known source ref — a JIRA ticket, a GitHub issue, an internal
+wiki page — the web links it in the answer (below), and every UI shows one
+line right after the message:
+
+```
+sources: JIRA JIRA-123 → https://myjira.com/browse/JIRA-123, JIRA JIRA-10 → https://myjira.com/browse/JIRA-10
+```
+
+The note is **not part of the conversation**: it is an event shown to the
+user, never stored in the session file. A UI replays it while the session's
+worker lives (a page reload keeps it; a stopped worker loses it). Only the
+model's final answer is scanned (the last `role: "model"` message), and only
+the first 20 000 characters of it. A ref that is already a link is skipped —
+inside a bare URL (`https://x.com/JIRA-123`), in a markdown link's target, or
+in a markdown link's label when the target names the same ref
+(`[JIRA-123](https://x.com/JIRA-123)`) — while `see https://x.com JIRA-123`
+and `[fix for JIRA-123](https://github.com/o/r/pull/9)` still link. A ref
+glued to URL punctuation (`/browse/JIRA-1`, `?key=JIRA-1`, `JIRA-1/foo`) is
+skipped too; `Ticket:JIRA-5` and `#JIRA-123` are ordinary plain text and do
+link. Refs are deduped within the turn (case-insensitively) and listed in
+first-occurrence order, whatever order the sources are configured in. With no
+sources configured the hook is a silent no-op.
+
+```yaml
+bundles:
+  source-links:
+    sources:
+      - name: JIRA
+        prefix: JIRA              # simple form: \bJIRA-(\d+)\b
+        base_url: https://myjira.com/browse/
+      - name: GitHub
+        pattern: '\bGH-(\d+)\b'   # full form: a regex
+        url: 'https://github.com/org/repo/issues/{match}'
+        case_insensitive: false   # optional, default false
+    max: 10                       # optional: refs per line, default 10
+    note: false                   # optional: no sources line, default true
+```
+
+**In the web** the refs are also links in the answer itself: each
+occurrence becomes `[JIRA-123](https://myjira.com/browse/JIRA-123)` through
+[`event[:present]`](#presenting-the-answer-display-only), so the model's
+text stays as it was, and the links survive a reload and a stopped worker
+(they are the answer's `display` in the session file). The same skip rules
+apply, and a ref in code (a `` `span` `` or a fenced block) or anywhere in a
+markdown link is left as it is; past the first 20 000 characters the answer
+is unchanged. The terminals see only the line; `note: false` drops it and
+keeps the web links.
+
+The `prefix:` form compiles to `\b<prefix>-(\d+)\b` and the URL is
+`base_url` + the full ref text (`JIRA-123`). The `pattern:` form takes a
+regex; `{match}` in `url` is replaced with the first capture group (or the
+full match when the pattern has none). `case_insensitive: true` adds the
+`/i` flag. Past `max` refs the line ends with `… +N more`.
+
+Each regex is compiled with a per-regex timeout (0.5 s, per match attempt),
+so a catastrophic pattern is abandoned instead of hanging the turn: that
+source is skipped whole (its partial matches are discarded) with a warning,
+and the others still report. An entry with neither `prefix:` nor `pattern:`,
+or a pattern that does not compile, is skipped with a warning at load. The
+hook is `on_error: log`: a bug in it warns and the turn is unaffected. As with
+every bundle hook, a running worker picks it up after its next start.