samagotchi 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 950fbee37d2110efad37f8d3f8981144f49af9a2ccf75649d5953b1fe7773260
-  data.tar.gz: aaad7adb0e9aa3c81b601df48fde4ebab965862ed954454c8b79e2de841f0789
+  metadata.gz: 63f5d3415cd7f3cfe7f2811ab19bcabca4eafe62e349fd9d0d28fcd157c38340
+  data.tar.gz: a2fea7402c8a1cba19e795320c134e12a5cf58b026934cc954c4ecd80e6d765c
 SHA512:
-  metadata.gz: 1b4d092f263192c242dead3ae0c556758a38af2f01285dc590362d698696a31d38801c70e64ff85daa33067ceda92be7687915024d1e81802bd0a2c365cc292d
-  data.tar.gz: 7a06a4d47dea9168e40b0ae0ba7bc6cbfe1b377ba9ac29a998d19f0ee17a766de3186786894deea8b6765a78e21b14e3e7ece8238ab401354c43a5eba4d1815b
+  metadata.gz: b8c4eb982683f47f10b9f77af3bc0b32518b8707860fcb796377870bb838ba13d326ece7b2e28f675097507478ec3723206ecd654fe8720e8653bf9a234f6930
+  data.tar.gz: fd059521495cca9d033924c818c8b35da945e6354b7806acdf65af7f275e51f9b20f5b228ff00dd81c2f16d73abd8de881d505b7eb3620e0a70792e28f4d7965

data/CHANGELOG.md

@@ -8,6 +8,87 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-09-30
+
+### Added
+
+- `chi update`: brings an installed chi up to date in one command: the gem
+  from rubygems, then the system bundle, the shipped bundles you installed and
+  the desktop helper (rebuilt only when its sources changed), shown in one
+  table. Your edits to bundle files are kept and reported, running workers and
+  an old `chi web` are only reported, `--dry-run` shows the plan, and
+  `--no-gem` / `--no-bundles` / `--no-desktop` (or `update.*` in config.yml)
+  skip parts. The first start of a new chi version says in one line when
+  something can be updated.
+- A thinking level per model, host or run: `thinking: off | low | medium |
+  high | default` (`models.<key>.thinking`, `hosts.<name>.thinking`,
+  `thinking.level`, `--thinking LEVEL`). Chat hosts get the matching request
+  fields; native Qwen and Gemma turn thinking off. chi says once when a level
+  can't work on a host, and a host that refuses the thinking fields (gpt-oss
+  on OpenRouter) is asked again without them. `/model` and `chi self` show
+  the level.
+- Edit previews: an edit/write approval shows the diff it would make, in the
+  web card and in the terminal, and every edit/write row gets a
+  "diff +3 −1" that opens to the change (live, after a reload and on a join).
+- `chi send --image PATH` (repeatable, up to 20): images go with the message
+  as attachments, the same as the web composer's chips; converted and
+  downscaled once, then copied into each session. Works with `--new` (the
+  session starts idle, then gets the message with its images) and `--wait`.
+  A missing file or a non-image stops the send before anything goes out.
+- The desktop helper takes images: a clipboard screenshot, image files from
+  Finder's Send to chi, other apps' image data, or a drop on the panel; they
+  show as thumbnails and go with the message.
+- source-links 0.3.0: `#12` links to the current project's repo (from its git
+  remote) and `owner/repo#12` to that repo; `url:` templates take `{1}`,
+  `{name}`, `{repo}` and `{host}`, with `remote:` and `remote_host:` per
+  source, and the note lists each link once.
+- The web shows when the provider is asked again after an error ("↻ retrying
+  (503) in 3 s, 1/2") or a turn waits for a plugin's setup.
+
+### Changed
+
+- A model named with a host that isn't configured (`nosuch:org/model`, or a
+  provider's name like `openrouter:x`) is an error that names the host and
+  lists the configured ones, in the CLI, `chi send --new`, the web and
+  `/model`, instead of going to the default host.
+- The terminal no longer rewrites `#word` into a memory reference: "PR #1"
+  and "#ff0000" reach the model as typed (Tab still completes `#name`).
+- A question you dismiss reaches the model as dismissed, not as a tool
+  error, so it keeps asking when it should.
+- `/quit` works in the REPL like `/exit`, and the web answers it too;
+  `/stats` and `/recap` take trailing words in both terminals.
+- A delegated session gets reworded rules: the answer first, then evidence,
+  then what's unverified; follow-up messages arrive as new turns.
+
+### Fixed
+
+- A llama.cpp server started with `--api-key` works: the key in
+  `api_key_env` is sent on every request (it got 401). A 401/403 from any host
+  now says which variable to check or to set `api_key_env`.
+- A bundle upgrade that keeps your edited file no longer disables the
+  bundle's plugin, and the system bundle stops warning about the same edit on
+  every start.
+- One bundle with a broken manifest.json no longer stops the hooks of the
+  bundles after it from loading.
+- A long-running worker picks up edited guardrail rules.
+- `write` without content fails instead of emptying the file.
+- Per-model `vision:` follows a model alias, like `profile:` and `sampling:`.
+- A timeout of 0 in config means the default on llama.cpp hosts too (it was a
+  0-second timeout).
+- A reminder turn drops a pending continue offer, so a later "no" can't roll
+  the reminder back.
+- More than 8 options in `ask_user_question` is always an error (one path
+  silently used the first 8).
+- A memory read with a comma list counts each name in the REPL and the web.
+- `/archive` or `/quit` typed during a REPL turn no longer goes to the model
+  as text; `EXIT --DELETE` works in any case in an attached terminal.
+- `chi bundle status` finds index lines again (it said "no-index" for every
+  file).
+
+Update with `chi update` (new in this version: from 0.3.0, run
+`gem install samagotchi` once, then `chi update`). Bundle moved:
+source-links 0.3.0.
+
 ## [0.3.0] - 2026-09-29
 
 ### Added
@@ -153,6 +234,7 @@ and long-lived sessions.
 - A macOS desktop helper (`chi desktop install`): a "Send to chi" Service and a
   hotkey panel that send selected text or the clipboard to your sessions.
 
-[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/dm1try/samagotchi/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/dm1try/samagotchi/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/dm1try/samagotchi/releases/tag/v0.2.0

data/README.md

@@ -32,6 +32,22 @@ bin/chi self
 `bin/chi` runs the checkout; `bundle exec rake gem:install` installs it as a
 local gem, which puts `chi` on your PATH.
 
+### Updating
+
+```sh
+chi update --dry-run    # what would change
+chi update              # the gem, then the bundles and the desktop helper
+```
+
+`chi update` installs the newest samagotchi from rubygems.org (old versions
+stay installed: running sessions still use them), then brings the rest up to
+the new version: the system bundle, the bundles chi ships that you installed,
+and the macOS helper (rebuilt only when its sources changed). Memory files you
+edited are kept, and the table says which. Running sessions move to the new
+chi when their worker idles out (30 min) or on `chi sessions stop ID`; a
+running `chi web` needs a restart. From a checkout, `git pull` instead. See
+[CLI: Updating](docs/cli.md#updating).
+
 ## Set up
 
 Point chi at your model server; it works out the rest and writes

data/bin/chi

@@ -257,6 +257,12 @@ if ARGV[0] == "bootstrap"
   exit Samagotchi::BootstrapCommand.new(ARGV[1..] || []).run
 end
 
+# `chi update`: bring an installed chi up to date, before OptionParser (its own flags)
+if ARGV[0] == "update"
+  require "samagotchi/update_command"
+  exit Samagotchi::UpdateCommand.new(ARGV[1..] || []).run
+end
+
 # `chi desktop`: the native "Send to chi" helper, before OptionParser (its own flags)
 if ARGV[0] == "desktop"
   require "samagotchi/desktop_command"
@@ -372,7 +378,7 @@ if ARGV[0] == "bundle"
     lines << ""
     lines << "Your task: resolve each conflict by editing the file in place using the memory_write tool."
     lines << "Use memory_read to inspect current content if needed. The correct scope for memory_write is the bundle's scope."
-    lines << "When all conflicts are resolved, type /exit to finish. If you abort, the upgrade will not be applied."
+    lines << "When all conflicts are resolved, type /exit to finish. If you stop early, the files stay as they are (the rest of the upgrade is already applied)."
     lines.join("\n")
   end
 
@@ -529,7 +535,7 @@ if ARGV[0] == "bundle"
           ans = begin; $stdin.gets; rescue => _e; nil; end
           launch = ans && ans.strip.downcase.start_with?("y")
         else
-          puts "Non-interactive terminal — aborting. Re-run with --force to overwrite or --agent in a TTY."
+          puts "Non-interactive terminal: kept your edits in the file(s) above; the rest is upgraded. Re-run with --force to take the bundle's version, or --agent in a TTY to merge."
           exit 2
         end
         if launch
@@ -537,37 +543,15 @@ if ARGV[0] == "bundle"
           puts "Launching interactive session for conflict resolution… (/exit when done)"
           require "samagotchi/terminal_ui"
           Samagotchi::TerminalUI.new(prompt: prompt).run
-          # After session, re-check if conflicts resolved by re-reading current files vs incoming
-          # Simple heuristic: if user edited files, current != base now but we assume resolved if file exists
-          # Re-run upgrade without conflicts? User already edited in place, so we need to write provenance now
-          # Update provenance to reflect resolved state
-          if manifest
-            # Re-collect provenance files from target dir for this bundle
-            prov_files = {}
-            target_scope = scope || provenance.read[:scope]&.to_s || "system"
-            target_dir = Samagotchi::MemoryBundle::Installer.new(source: expanded_source, name: bundle_name, scope: target_scope).send(:resolve_target_dir, target_scope)
-            # Actually reuse provenance write with current target files for bundle keys
-            bundle_files = installer.conflicts.keys + installer.results.select { |_, r| %w[installed updated].include?(r[:status]) }.keys
-            # Fallback: collect all md that exist and were in installer results
-            all_keys = installer.results.keys
-            all_keys.each do |k|
-              p = File.join(target_dir, k)
-              prov_files[k] = p if File.exist?(p)
-            end
-            if prov_files.any?
-              Samagotchi::MemoryBundle::Provenance.new(name: bundle_name).write(
-                files: prov_files,
-                scope: target_scope,
-                version: manifest.version,
-                source_path: expanded_source
-              )
-              puts "Provenance updated after interactive resolution."
-            end
-          end
+          # The installer already recorded the upgrade (conflicted files
+          # kept their old base); the resolved files now start from the
+          # bundle's version.
+          Samagotchi::MemoryBundle::Provenance.new(name: bundle_name).resolve_conflicts(installer.conflicts)
+          puts "Provenance updated after interactive resolution."
           puts "Upgrade resolved interactively."
           exit 0
         else
-          puts "Upgrade aborted due to conflicts. Resolve manually or re-run with --force."
+          puts "Kept your edits in the file(s) above; the rest is upgraded. chi bundle diff #{bundle_name} FILE shows the base; re-run with --force to take the bundle's version."
           exit 2
         end
       end
@@ -637,6 +621,7 @@ if ARGV[0] == "bundle"
       puts "Target: #{st[:target_dir]}"
       st[:files].each do |k, info|
         mods = []
+        mods << "conflict (kept your edits over v#{st[:provenance][:version]}: chi bundle diff #{name} #{k})" if info[:conflict]
         mods << "modified" if info[:modified]
         mods << "missing" if info[:missing]
         mods << "no-index" unless info[:index_present]
@@ -806,6 +791,7 @@ if ARGV[0] == "bundle"
         line += "  (shipped v#{b.upgrade.version}: chi bundle upgrade #{b.upgrade.source})" if b.upgrade
         puts line
       end
+      puts "  (or all at once: chi update)" if installed.any?(&:upgrade)
     end
     unless available.empty?
       puts ""
@@ -930,7 +916,7 @@ ARGV.each do |arg|
   base = arg.split("=", 2).first
   # If dashed version is a known flag (registry or hardcoded), reject underscore variant
   dashed = base.tr("_", "-")
-  known = %w[--prompt --resume --attach --shared --no-shared --model --memory --mute --no-interrupt --non-interactive --verbose --no-default-input --port --open] + Samagotchi::Config.cli_entries.map(&:cli_flag)
+  known = %w[--prompt --resume --attach --shared --no-shared --model --thinking --memory --mute --no-interrupt --non-interactive --verbose --no-default-input --port --open] + Samagotchi::Config.cli_entries.map(&:cli_flag)
   if known.include?(dashed) || known.include?(base)
     warn "Unknown option: #{arg} (did you mean #{dashed}?)"
     exit 1
@@ -949,6 +935,7 @@ parser = OptionParser.new do |opts|
            chi bundle <install|upgrade|uninstall|status|diff|list|build>
            chi desktop <install|upgrade|uninstall|status>   macOS "Send to chi" helper
            chi self                         version, paths, model and bundles
+           chi update [--dry-run]           update this chi, its bundles and the desktop helper
     (each subcommand takes --help)
 
   BANNER
@@ -959,6 +946,8 @@ parser = OptionParser.new do |opts|
   opts.on("--model NAME", "Model selector (runtime only, overrides --resume) [alias for --default-model]") { |m| options[:model] = m; cli_overrides["default.model"] = m }
   opts.on("--profile NAME", Samagotchi::ModelProfile::NAMES,
           "Prompt profile for every model in this run (#{Samagotchi::ModelProfile::NAMES.join('|')}) [alias for --model-profile]") { |p| cli_overrides["model.profile"] = p }
+  opts.on("--thinking LEVEL", Samagotchi::Thinking::LEVELS.map(&:to_s), "How much the model thinks this run: off|low|medium|high|default (outranks config.yml; " \
+                              "sessions already running keep theirs) [env SAMAGOTCHI_THINKING_LEVEL]") { |l| cli_overrides["thinking.level"] = l }
   opts.on("--memory NAME", "Preload a memory entry into the system prompt (repeatable; a comma list too)") { |m| (options[:memories] ||= []) << m }
   opts.on("--mute NAME", "Hide a memory from this session: not in the prompt, refused by memory_read (repeatable; a comma list too)") { |m| (options[:muted] ||= []) << m }
   opts.on("--no-interrupt", "Raise the tool call limit to 1000 iterations (useful for long tasks)") { options[:no_interrupt] = true; cli_overrides["no_interrupt"] = true }
@@ -1074,7 +1063,18 @@ when "web"
   end
 end
 
+# The first interactive start of a new installed chi says what `chi update` would update.
+chi_update_hint = lambda do
+  require "samagotchi/installed_gem"
+  require "samagotchi/update_hint"
+  if Samagotchi::UpdateHint.wanted?(prompt: options[:prompt], non_interactive: options[:non_interactive],
+                                    tty: $stdin.tty? && $stdout.tty?, installed: Samagotchi::InstalledGem.spec)
+    Samagotchi::UpdateHint.show
+  end
+end
+
 if options[:web]
+  chi_update_hint.call
   require "samagotchi/web/server"
   port = options[:web_port] || Samagotchi::Config.get("web.port") || 4567
   # legacy env fallback
@@ -1143,6 +1143,7 @@ if options[:memories] || options[:muted]
   end
 end
 
+chi_update_hint.call
 require "samagotchi/launch_mode"
 launch, launch_note = if scratch
                         [:repl, nil]

data/docs/cli.md

@@ -16,9 +16,10 @@
 - `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 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 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) and [the check-in bundle](plugins.md#the-check-in-bundle))
 
 ### First setup
@@ -57,6 +58,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, 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 +131,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). |
@@ -279,7 +340,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 +351,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 +366,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
@@ -375,7 +442,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.
+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).
 
 ```sh
 chi web --no-web-turn-view   # the classic chat view; --web-turn-view is the default
@@ -582,7 +652,9 @@ During assist-mode thinking (while the spinner is active), you can cancel an in-
 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.
+- 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

@@ -29,6 +29,7 @@ server:                 # the model server when there is no hosts: map below
   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.
@@ -214,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`)
@@ -355,6 +370,70 @@ 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; 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 |
@@ -651,11 +748,16 @@ described in their own sections.
 | `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. |