samagotchi 0.3.0 → 0.5.0

data/docs/cli.md

@@ -12,14 +12,16 @@
 - `chi --attach <session-id>` — attach the terminal to a session's worker (e.g. one started from the Web UI), waking one if it has exited
 - A session id can be shortened to any unique prefix (like git): `chi --attach 2ea8`. `--resume`, `--attach`, `sessions stop`, `sessions archive` and `sessions delete` take one; an ambiguous prefix lists the sessions it matches.
 - `chi web [--port 4567] [--open] [--scope=all]` — start the Web UI (single localhost port session control plane) on this git project's sessions (`--scope=all`, or a folder in no repo: every session); if a chi web already runs on the port, print (with `--open`, open) its page for this folder and exit. Something else on the port (an older chi web too) exits 1 with "port N is in use"
+- `chi web --web-host lan` — the Web UI on your home network too, for your phone: a link with an access token and its QR code (see [chi web on your phone](#chi-web-on-your-phone)); `chi web --new-token` replaces the token
 - `chi web --web-markdown` — opt in to sanitized Markdown rendering for completed assistant messages
-- `chi web --no-web-turn-view` — show turns as the classic row of bubbles instead of the default turn view (each turn as one block of steps, the running one at the bottom); `?view=turn|chat` on the page URL overrides it (see [Web turn view](#web-turn-view))
+- `chi web --web-view stage|chat` — draw turns with the stage view (the running turn pinned above the composer) or as the classic row of bubbles instead of the default turn view (each turn as one block of steps, the running one at the bottom); `?view=turn|stage|chat` on the page URL overrides it (see [Web views](#web-views))
 - `chi sessions list|stop|archive|unarchive|delete|prune|clean` — manage persisted sessions; `list` shows this git project's, `list --scope=all` every one, a delegated session with `↳ <parent>`, `list --archived` the archived ones too (see [Sessions](sessions.md))
 - `chi note [--source NAME] [-m TEXT] (ID|PREFIX)... | --all` — add a context note (TEXT or stdin) to sessions: background the model sees on its next turn; it starts no turn (see [Sessions: Context notes](sessions.md#context-notes))
-- `chi send [-m TEXT] (ID|PREFIX)...` — send a message to sessions as if typed there: a turn starts (or a running one picks it up); piped stdin goes above `-m` as quoted context (see [Sessions: Sending a message](sessions.md#sending-a-message)); `--new` starts a session with it instead, and `--wait` prints the answer (`--wait ID` with no message waits for the next reply without sending; see [Starting a session](sessions.md#starting-a-session))
+- `chi send [-m TEXT] [--image PATH]... (ID|PREFIX)...` — send a message to sessions as if typed there: a turn starts (or a running one picks it up); piped stdin goes above `-m` as quoted context, and `--image` attaches images (see [Sessions: Sending a message](sessions.md#sending-a-message)); `--new` starts a session with it instead, and `--wait` prints the answer (`--wait ID` with no message waits for the next reply without sending; see [Starting a session](sessions.md#starting-a-session))
 - `chi desktop install|upgrade|uninstall|status` — the macOS "Send to chi" helper: a Service and a ⌃⌥⌘N hotkey that send text to live sessions as context notes (see [Desktop helper](desktop.md))
 - `chi self` — print version, source dir (checkout or installed gem), config/memory/session paths, model/host and bundles
-- `chi bundle install|upgrade|uninstall|status|diff|list|build` — manage memory bundles (see [Bundle hooks](hooks.md#bundle-hooks-unified-workflow-bundle)); `list` shows the installed ones and the ones shipped with chi, which `install <name>` installs (see [Guardrails](guardrails.md), [Plugins](plugins.md#the-btw-bundle), [the mcp bundle](plugins.md#the-mcp-bundle) [the loop-guard bundle](plugins.md#the-loop-guard-bundle) and [the check-in bundle](plugins.md#the-check-in-bundle))
+- `chi update [--dry-run] [--no-gem] [--no-bundles] [--no-desktop]` — update an installed chi: the gem, the system bundle, the shipped bundles you installed and the desktop helper, in one table (see [Updating](#updating))
+- `chi bundle install|upgrade|uninstall|status|diff|list|build` — manage memory bundles (see [Bundle hooks](hooks.md#bundle-hooks-unified-workflow-bundle)); `list` shows the installed ones and the ones shipped with chi, which `install <name>` installs (see [Guardrails](guardrails.md), [Plugins](plugins.md#the-btw-bundle), [the mcp bundle](plugins.md#the-mcp-bundle) [the loop-guard bundle](plugins.md#the-loop-guard-bundle), [the check-in bundle](plugins.md#the-check-in-bundle) and [the skills bundle](plugins.md#the-skills-bundle))
 
 ### First setup
 
@@ -57,6 +59,65 @@ chi bootstrap                            # try localhost 8080, 11434, 1234, 8000
   or with anchors gets the lines printed to paste instead. `--dry-run` shows
   what it would write.
 
+### Updating
+
+`chi update` brings an installed chi up to date and prints one table:
+
+```
+component      from   to     status
+chi (gem)      0.2.0  0.3.0  updated
+system bundle  0.2.0  0.3.0  updated (kept your edits in identity.md: chi bundle diff samagotchi-system identity.md)
+btw            0.1.1         up to date
+known-names    0.1.0  0.1.1  updated
+infra_tools    1.0.0         skipped (not from chi)
+Chi Helper     0.2.0         up to date (launch file refreshed)
+workers                      2 live on 0.2.0: they move to 0.3.0 at idle exit (30 min) or chi sessions stop 2ea8c1f0 91b0d2aa
+Also shipped, not installed: check-in, skills, source-links (chi bundle install NAME)
+done
+```
+
+- **The gem.** It asks rubygems.org for the newest samagotchi (5 s timeout)
+  and, when that's newer, runs `gem install samagotchi` with the gem command
+  of the Ruby chi runs on (the real one, not a mise/rbenv/asdf shim). Then it
+  hands over to the new chi, which does the rest and prints the table. Old
+  versions stay installed: running workers and an old `chi web` still use
+  them (so don't `gem cleanup` while they run). Offline, the row says
+  "couldn't check" and the rest still runs; a failed install fails the row
+  and the rest runs on the current version. Under Bundler (`bundle exec`)
+  the row says `bundle update samagotchi` instead.
+- **The system bundle** normally updated itself when the new chi started;
+  the row says what it did.
+- **Shipped bundles**: each one you installed from chi (`chi bundle install
+  NAME`) is upgraded when chi ships a newer version. Memory files get the
+  3-way merge of `chi bundle upgrade`: an unedited file is updated, an edited
+  one that the new version also changes is kept, and the row says so (`chi
+  bundle diff NAME FILE` shows it; `chi bundle upgrade NAME --force` takes the
+  bundle's). Hooks, rules and the plugin are replaced; an edited one didn't
+  load anyway (its sha no longer matched) and the row says it was replaced.
+  A bundle of the same name from elsewhere (a zip, git) is skipped ("not from
+  chi"), a newer installed one is left, one whose new version needs a newer
+  chi is skipped, and bundles you didn't install stay uninstalled.
+- **The desktop helper** (macOS) is rebuilt and restarted only when its Swift
+  sources changed (or the Ruby it runs moved); otherwise only its launch file
+  is refreshed. See [Desktop helper](desktop.md).
+- **Running processes** are reported, never stopped: live workers on another
+  version, and a `chi web` on `web.port` running an older chi (sessions it
+  starts run that version too: restart it).
+
+`--dry-run` shows the table with "would update" and changes nothing. It is
+this version's view: bundles that only a newer gem ships newer show up once
+that gem is installed (the real run installs it first and hands over).
+`--no-gem`, `--no-bundles` and `--no-desktop` leave a part alone for one run;
+`update.gem`, `update.bundles` and `update.desktop: false` in config.yml turn
+one off for good. It exits 0 when nothing failed (kept edits and skips are
+fine), 1 when a part failed, 2 on a usage error. A second run changes nothing
+and ends with "everything is up to date".
+
+From a checkout it refuses (`git pull`, or `chi bundle upgrade NAME` for one
+bundle). After a gem update, the first interactive start of the new version
+(`chi`, `chi web`; not `-p` or `--non-interactive`) says in one line when
+bundles or the helper can be updated.
+
 ## Flags
 
 Samagotchi exposes one flag that feeds a prompt (`-p`, `--prompt`) and one that
@@ -71,6 +132,7 @@ controls exit behavior (`--non-interactive`); `--resume` composes with both.
 | `--no-shared` | Run the plain in-process REPL for this run. |
 | `--attach SESSION_ID` | Attach to a session's worker, waking one if it has exited. |
 | `--model NAME` | Use this model for the run (overrides the configured default and a resumed session's model). |
+| `--thinking LEVEL` | How much the model thinks this run: `off`, `low`, `medium`, `high` or `default` (env `SAMAGOTCHI_THINKING_LEVEL`), over the config's levels. A session already running keeps its own. See "Thinking" in configuration.md. |
 | `--profile NAME` | Prompt profile (`qwen36` or `gemma4`) for every model in this run, over config and the server's template (same as `--model-profile`, env `SAMAGOTCHI_MODEL_PROFILE`). See "Prompt profile" in configuration.md. |
 | `--memory NAME` | Preload a memory entry into the system prompt (repeatable; a comma list too). Merged under the config.yml `memories:` baseline. Works attached: the list is stored on the session, so its worker builds the same prompt on every respawn. |
 | `--mute NAME` | Hide a memory from this session (repeatable; a comma list too): its index line is not in the prompt, `memory_read` refuses it, the identity auto-load skips it, and it is dropped from the preloads (config baseline or `--memory`). A name matches in both scopes (`gh-helper`, `project/gh-helper` and `gh-helper.md` all hide `gh-helper`). Nothing on disk changes. See [Muting a memory](#muting-a-memory). |
@@ -87,8 +149,8 @@ flag also works as `--kebab-case VALUE`, e.g. `--server-host`, `--server-port`,
 `api: openai` in config.yml is driven through the OpenAI chat API (streamed; a remote
 provider via `url:` and `api_key_env:`); every other host gets chi's own raw-prompt loop. `/model` and `--model host:model` switch hosts, and
 the loop with them. See [Configuration](configuration.md) (`hosts:` and `api:`).
-`--backend`, `SAMAGOTCHI_BACKEND` and a `backend:` key were removed; chi says so if
-it sees one.
+`--backend`, `SAMAGOTCHI_BACKEND` and a `backend:` key were removed (`backend:` warns
+as an unknown key).
 
 ### Entrypoint scenarios
 
@@ -279,7 +341,7 @@ REPL alike:
   typed comes back once it closes. The choices then go, and one line stays:
   `? Pick a fruit → Banana`.
 - Ctrl-C cancels the turn and keeps what you typed.
-- In the plain REPL, Ctrl-D on an empty prompt (or `exit`, `/exit`) mid-turn
+- In the plain REPL, Ctrl-D on an empty prompt (or `exit`, `/exit`, `/quit`) mid-turn
   exits once the turn ends: `(exits after this turn; Ctrl-C cancels it)`
   (`/exit --delete` deletes the session then too). In an
   attached terminal it detaches at once and the turn goes on in the worker
@@ -290,7 +352,7 @@ turns.
 
 ### Images
 
-A model that can see images gets them three ways:
+A model that can see images gets them these ways:
 
 - **`@path` in a prompt** (REPL, attached terminal, `-p`): `what's wrong in
   @shot.png?`, `@~/Desktop/a.jpg`, `@"my shot.png"`. Each `@` token that names an
@@ -305,6 +367,12 @@ A model that can see images gets them three ways:
 - **The Web UI**: paste or drop images into the composer. Each shows as a chip
   (× removes it) and is sent with the message; an image alone is sent as
   `[image: name]`. Messages show thumbnails; a click opens one full size.
+- **`chi send --image PATH`** (repeatable, up to 20) with a message, from a
+  script or another terminal: `chi send --image shot.png -m "why is this red?"
+  3fa2`. The attached terminal and the web show it like an image typed there.
+- **The desktop panel** (macOS, [Desktop](desktop.md#images)): a screenshot on
+  the clipboard, an image selected in Finder, or one dropped on the panel goes
+  as an attachment with the message.
 
 Images are downscaled to a 1568 px long side (with `sips` on macOS or
 ImageMagick; without either, a larger image is refused with a hint) and stored
@@ -350,16 +418,54 @@ touch screen), and so does each code block of a rendered answer. An answer
 copies its Markdown source, not the rendered text; a code block copies just
 its code; a prompt copies the text as you typed it.
 
-### Web turn view
+### Web views
+
+`web.view` picks how the page draws a turn: `turn` (the default, below),
+`stage` (the running turn pinned above the composer, below) or `chat` (the
+classic row of bubbles: one thinking block, one activity panel and one
+answer bubble per generation).
+
+```sh
+chi web --web-view stage     # or chat; turn is the default
+```
+
+The setting also supports `SAMAGOTCHI_WEB_VIEW=stage` or the global config:
+
+```yaml
+web:
+  view: stage
+```
+
+`?view=turn`, `?view=stage` or `?view=chat` on the page URL picks the view
+for that page load, whatever the config says; the parameter is dropped
+when you switch between the project and all-sessions views. The terminal
+UIs are not affected.
 
-The turn view, the default, shows a turn as *one block* where the work
-happens (the classic chat view renders a turn with tool calls as a row of
-bubbles: one thinking block, one activity panel and one answer bubble per
-generation; `web.turn_view: false` brings it back). The running
+**The stage view** pins the running turn above the composer, in its own
+card, so it stays on screen without scrolling: a status row (what it is
+doing, the step, the elapsed time), your prompt on one line, the newest
+narration sentence (else the newest thinking one, in italics; click it for
+the step's reasoning), the running tool with what it does, and the last
+three calls. A card that needs you (a question, an approval, check-in)
+sits in the stage too. The chip under it, `N steps · M tool calls` with one
+tick per call, opens the turn view's block in place (newest step first
+while it runs; a tick opens its step). `▾` folds the stage to its status
+row, remembered in this browser. When the turn ends the answer shows in
+the stage, and the whole turn moves up into the history once you are not
+using the stage (the pointer over it, a touch or scroll in the last 4 s,
+keyboard focus or a selection keep it) for 1.5 s; sending the next message
+moves it at once. The history is never scrolled while a turn runs, and only
+follows the hand-off if you were at its end. The `/` command list opens
+over the stage's lower edge.
+
+**The turn view** shows a turn as *one block* where the work
+happens. The running
 generation is the live part at the bottom (its thinking, its narration, its
 tool rows), the earlier ones stack above it collapsed to one line each
-(their narration's first line, else `working with <tools>`, and a call
-count), expandable for inspection. The live thinking is one line: the
+(their narration's first line, else their first call's title such as
+`edit lib/a.rb`, and a call count), expandable for inspection. A tool row
+says what the call did: a file's path relative to the session's folder, a
+command without its leading `cd … &&` (the full parameters on hover). The live thinking is one line: the
 newest complete sentence, changing at most once per 1.5 s. Click it for the
 full text; a peek is per step (the next step's thinking starts closed
 again). When a step ends its thinking closes to a plain `thinking` line
@@ -375,23 +481,10 @@ from the saved messages (each step's thinking, narration, tool parameters
 and output, the output capped at 2000 characters) and the timing records
 (status and duration per row). On an `api: openai` host the model's
 reasoning is saved with each step for this (never sent back to the model);
-steps saved before that have none, so they show no thinking.
-
-```sh
-chi web --no-web-turn-view   # the classic chat view; --web-turn-view is the default
-```
-
-The setting also supports `SAMAGOTCHI_WEB_TURN_VIEW=false` or the global config:
-
-```yaml
-web:
-  turn_view: false
-```
-
-`?view=chat` on the page URL forces the classic chat view for that page load
-and `?view=turn` the turn view, whatever the config says; the parameter is dropped
-when you switch between the project and all-sessions views. The terminal
-UIs are not affected.
+steps saved before that have none, so they show no thinking. An `edit` or
+`write` row has a closed `diff +3 −1` under it that opens to the change it
+made (up to 120 lines or 8 KB), live and after a reload (see
+[Guardrails](guardrails.md#ask) for the diff an approval shows first).
 
 ### Web annotate presets
 
@@ -419,6 +512,51 @@ web:
 there means the default, not "none": use `""` in the file or on the command
 line. A `chi web` that already runs keeps its list; restart it.
 
+### chi web on your phone
+
+`chi web` listens on 127.0.0.1 only. `--web-host lan` (or `web.host: lan`
+in config.yml) also opens it on this machine's private IPv4 address, for a
+phone on the same Wi-Fi:
+
+```sh
+chi web --web-host lan
+```
+
+```
+Chi Web on http://127.0.0.1:4567/?dir=/Users/me/projects/app (public: …)
+LAN: http://192.168.1.55:4567/?token=…   ← anyone with this link can run commands as you
+Plain http: the link and your traffic can be read by anyone on this Wi-Fi.
+<the link's QR code>
+```
+
+Scan the QR code with the phone's camera. The page trades the token in the
+link for a cookie (kept 400 days) and drops it from the address, so a
+bookmark or a home-screen icon keeps working across restarts. A home-screen
+web app on iOS has cookies of its own: if it opens on "needs chi web's
+access token", paste the token there (the part of the link after
+`token=`), or open the link once in it.
+
+- Every request from another machine needs the token (the cookie, or
+  `Authorization: Bearer <token>` for curl); this Mac (127.0.0.1) needs none.
+  Without it the page says how to get in and the API answers 401.
+- The token lives in `$XDG_STATE_HOME/samagotchi/web-token` (0600).
+  `chi web --new-token` replaces it: a running chi web takes the new one at
+  once, and every phone has to scan the new QR code.
+- A second `chi web` prints the LAN link and QR code again. A plain
+  `chi web --web-host lan` while a chi web without LAN access runs asks you
+  to stop that one first. `chi self` says whether chi web runs on the LAN.
+- `lan` picks the first private address (10.x, 172.16–31.x, 192.168.x) on an
+  interface that is up, not a VPN tunnel, bridge, VM or container, and names
+  the others; `web.host: 10.0.0.3` picks one yourself. An address outside
+  those ranges (a Tailscale 100.x one, a public one) works, with a warning.
+  After the address changes (a new Wi-Fi), restart chi web. IPv6 isn't
+  offered.
+- It is plain http: the token and everything you do travel unencrypted on
+  the Wi-Fi. Use it on your home network, never on a shared one (a café, an
+  office guest network), and run `chi web --new-token` if a link leaks.
+- On http the browser has no notifications: the bell is hidden on the phone,
+  and the tab title still counts what needs you.
+
 ## Runtime Model Switch (Assist Mode)
 
 In interactive assist mode, you can switch the request model without restarting:
@@ -506,38 +644,23 @@ Behavior details:
 
 ## Status Line
 
-Assist mode can render a compact generalized status line that can include mode,
-context estimate, and active memory hints.
-
-Behavior:
-
-- A static status line is printed before the next `>` prompt in assist mode.
-- During spinner rendering, status details are rendered in the spinner block.
-- When llama.cpp streaming payload includes usage fields, status prefers server-derived token telemetry (`p`, `c`, `t`) and context percent.
-- If server usage fields are absent, status falls back to the `:context_status` estimate telemetry.
-- When a memory is loaded between tool rounds, the spinner line includes a `loaded: <memory>` notification immediately after the spinner frame.
-- After responses, memory details are shown via the same unified `status>` line.
-- The legacy standalone `memories>` summary line is no longer emitted.
-- With `--mute`, the sticky and idle rows add `muted: <names>` after `mem:` (the
-  spinner row doesn't). Attached, `mem:` shows the used memories and the
-  session's `--memory` list before the first turn records them.
-
-Configuration:
-
-- `SAMAGOTCHI_STATUS_LINE` (default `on`): set to `off`, `false`, or `0` to disable status-line rendering.
-- `SAMAGOTCHI_STATUS_WIDTH_MODE` (default `terminal_cap`): one of `terminal_cap`, `fixed`.
-- `SAMAGOTCHI_STATUS_MAX_WIDTH` (default `160`): maximum width used by `terminal_cap`.
-- `SAMAGOTCHI_STATUS_FIXED_WIDTH` (default `120`): fixed width used by `fixed` mode.
+The REPL and attached mode show one status row under the prompt, drawn when what it says
+changes:
 
-Width mode behavior:
-
-- `terminal_cap`: use `min(terminal_columns, SAMAGOTCHI_STATUS_MAX_WIDTH)`, single-line with `+N` overflow indicator.
-- `fixed`: use `SAMAGOTCHI_STATUS_FIXED_WIDTH`, single-line with `+N` overflow indicator.
-
-Notes:
+```
+status> model=Qwen3.6-35B | ↳ 3f2a1c9e | ctx=12.3% (under20) | mem: notes, cli_usage | muted: gh-helper
+```
 
-- Spinner rendering remains app-managed to keep cursor cleanup deterministic.
-- Raw terminal auto-wrap is intentionally avoided in the spinner region.
+- `model=`: the model in use, `(default: …)` beside it when it isn't the config's default, and
+  `model=<served> (served; asked <name>)` when the server said it served another model.
+- `↳ <id>`: the session that delegated this one.
+- `ctx=`: the kernel's context estimate and its bucket, updated during a turn (on hosts that
+  report none, `api: openai`, at the turn's end).
+- `mem:`: the memories the session read, with its `--memory` list; `muted:` its `--mute` list.
+  Up to 8 names each, then `+N`.
+- The row is cut to the terminal's width. Without a live region (output or input not a terminal,
+  `TERM=dumb`) it prints as a line when it changes.
+- `SAMAGOTCHI_STATUS_LINE` / `status.line` (default `on`): `off`, `false` or `0` hides it.
 
 ## Tool Tally
 
@@ -552,37 +675,48 @@ It lists the top 3 tools by count (ties go to the tool used first), the failed c
 (a call a guardrail or an approval blocked counts as a call, not as failed) and the last
 call with its parameters, cut to the terminal width. It starts over with each turn.
 
-- Attached mode: the second row of the activity slot, shown while the slot is (the
+- The REPL and attached mode: the second row of the activity slot, shown while the slot is (the
   model generating or a tool running). Joining a turn mid-way seeds it from the turn so far.
-- The REPL (`--no-shared`): a row under the spinner row. The spinner stops while tools
-  run (the `tool>` lines show them), so the tally shows while the model generates
-  between tool rounds; the spinner block is one row taller from then on.
 - The web: the activity panel's summary reads `activity · 12 tool calls (2 failed) · execute ×7 · …`
   (without `last:`: the rows show it).
 
-## Thinking Spinner Sentence
+## Activity Row
+
+While a turn runs, one row above the prompt says what it is doing, the spinner frame first
+(the REPL and attached mode alike):
 
-While the model generates, the spinner row shows the newest complete sentence of its thinking
-(`model> thinking · <sentence> |` in the REPL, `| thinking · <sentence>` in attached mode), or of its
-answer (`writing ·`), like the web's thinking ticker: the same sentence rules (a list number such as
-`118.` is no sentence end; a newline is one), and the row changes at most once every 1.5 s so it
-doesn't flicker. A long sentence is cut with `…`; a Qwen `TURN:` prefix and inline markdown are left
-out. Before the first sentence the row reads `thinking...`. With `TERM=dumb` there is no spinner row.
+- `| thinking…` while the model starts, then `| thinking · <sentence>`: the newest complete
+  sentence of its thinking, or of its answer (`writing ·`), like the web's thinking ticker: the
+  same sentence rules (a list number such as `118.` is no sentence end; a newline is one), and the
+  row changes at most once every 1.5 s so it doesn't flicker. A long sentence is cut with `…`; a
+  Qwen `TURN:` prefix and inline markdown are left out.
+- `| waiting for the first token… 5s` after 2 s with nothing streamed.
+- `| running execute…` while a tool runs (its `tool>` line prints when it ends).
+- `| retrying (1/4 in 0.5s): Errno::ECONNREFUSED` while a network error is retried.
+- `| mcp: starting servers…` while a plugin's slow setup (an init task) runs, between turns too;
+  `mcp> ✓ …` prints when it is done.
 
-- When a memory entry is loaded during thinking, the spinner line also shows a compact inline preview
-  of that tool call (for example `tool: memory_read(name=...)`) for live visibility before end-of-turn
-  tool logs; the sentence gets the room left.
+The spinner turns with time, so a turn that gets no chunks still looks alive. Without a live
+region (output or input not a terminal, `TERM=dumb`) there is no activity row; the turn's lines
+still print as they end.
 
 ## Thinking-Phase Cancellation
 
-During assist-mode thinking (while the spinner is active), you can cancel an in-flight model request without exiting the process:
+While a turn runs, you can cancel it without exiting the process:
 
 - Press `Ctrl-C` to cancel the active request.
 
 Behavior notes:
 
 - Cancellation returns control to the prompt immediately; what you typed there stays.
-- Partial model output from the canceled request is not committed as a completed model turn.
+- The turn ends with one line, `✕ turn canceled (Ctrl-C) · 3.1s`, and for a prompt turn a dim
+  `partial progress kept; !rollback restores the pre-turn state` under it (a canceled continue is back where it
+  started). A failed turn ends with `✕ turn failed: <summary> · 2.0s` and a dim `prompt restored for retry`. The
+  REPL and attached mode say the same; the web says `✕ canceled (Ctrl-C)` (`stopped` for its Stop button,
+  `by a hook` for a hook's).
+- Visible text the canceled request had streamed stays in the conversation, marked `[interrupted]`, so the next
+  message (or a continue) picks up from the half-finished reply; the canceled request's thinking and any unfinished
+  tool call are dropped.
 
 ## Iteration Limit Behavior
 

data/docs/configuration.md

@@ -28,7 +28,7 @@ server:                 # the model server when there is no hosts: map below
   host: 192.0.2.10
   port: 8081
 thinking:
-  ui: spinner
+  level: default        # off | low | medium | high | default; see "Thinking"
 
 # Multi-host (optional): aggregated /models and per-model routing.
 # A bare default.model uses the default host; host:model pins to a host.
@@ -87,6 +87,11 @@ Behavior:
   `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.
+- An edit to the file needs no restart of `chi web`: a new session's worker
+  reads the file when it starts, and a running chi takes a changed value the
+  next time it reads that setting (a worker keeps `hosts:` and what it set up
+  at its start until it is stopped). A worker gets the CLI flags of the chi
+  that started it through its environment.
 - Workers inherit hosts via `SAMAGOTCHI_HOSTS_JSON` propagated through `SessionManager.spawn_options`.
 
 This lets you run `chi` without repeating common defaults such as model
@@ -114,15 +119,9 @@ 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.
+An environment name used as a top-level key (`SAMAGOTCHI_DEFAULT_MODEL: my-model`,
+the old flat form) is not read: it warns as an unknown key with the nested one
+to use (`did you mean 'default.model'?`).
 
 ## Model Server Transport
 
@@ -214,6 +213,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`)
@@ -355,6 +368,72 @@ models:
 `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 (when its `/props` says
+`chat_template_caps.supports_reasoning_effort: false`, chi says so once per session and host, from the `/props`
+answer the turn already fetched for the window); 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.
@@ -362,6 +441,7 @@ 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.
+  Either timeout at `0` (or anything not a positive number) is its default, on every host.
 
 ```yaml
 server:
@@ -409,15 +489,32 @@ 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.
 
@@ -455,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 |
@@ -630,7 +727,7 @@ described in their own sections.
 | `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.keep_status` | none | yes | Comma list of statuses never pruned (a session a worker or `chi` has open is never pruned anyway). |
 | `session.sweep_interval_hours` | `24` | yes | How often the retention sweep runs. |
 | `image.max_side` | `1568` | | See "Images". |
 | `image.max_bytes` | `3750000` | | See "Images". |
@@ -639,23 +736,23 @@ described in their own sections.
 | `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`. |
+| `status.line` | `on` | yes | The status row under the prompt (the REPL's and attached mode's), `on` or `off`. |
 | `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. |
@@ -664,9 +761,9 @@ described in their own sections.
 | `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.host` | `127.0.0.1` | yes | `127.0.0.1`, `::1` or `localhost`; `lan` (this machine's private IPv4 address) or one of its IPv4 addresses also opens `chi web` to the network, with an access token (`chi web --new-token` replaces it). Anything else binds `127.0.0.1` with a warning. See [CLI: chi web on your phone](cli.md#chi-web-on-your-phone). |
 | `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.view` | `turn` | yes | How `chi web` draws a turn: `turn` (one block per turn), `stage` (the running turn pinned above the composer) or `chat` (the row of bubbles). See [CLI](cli.md#web-views). |
 | `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. |