samagotchi 0.131.0 → 0.132.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37f2a54062786637083ade10186ebb751a1cfd7a7996540defa03da018b29533
-  data.tar.gz: 6836e60f2a87358698adaf000592ac68af5ce8fe8f3c26799825fa26641d3f1a
+  metadata.gz: ebe264e1dbd5adc620889aa40d66fd458519c64f038a3a3e5de06ee6a6da46e7
+  data.tar.gz: 3c72148287422c9821c25bc3979c71890fb4abad81af3829650aef3c13549a3f
 SHA512:
-  metadata.gz: b908ad2c276d4dabb1c8bd64ad8435a2f9ab5408663243f8cd0f24e25ca2e4647cb356228a7a37027c1c5f2895936c4df8424af5203d8c121b5403577e2a2456
-  data.tar.gz: a3c96161fc7cb55e200367417e1dac93442845e0a868ad02d58ecca15a504af6824c419e8188252c9100daf405892be203e75fd6d7baaca1406c20186a4ff6f4
+  metadata.gz: f8ffaf8ca17c125a38af6a30432d8b14a66ea97df8201686acedca8dde11869845b0e2a6abe0f9ece18db4e5848f9340b2ef73910371977fafe9889d430eebad
+  data.tar.gz: e556232bbad1093cff1779510162a179b1284cc90bd8cc54d8082e2a4dab5e96f98bb6ebae5ef99ab82610a1bd33880c830cfae8b1076d1e6ca841c406ae45b3

data/CHANGELOG.md

@@ -7,10 +7,55 @@ and commands may change between minor versions. How releases are made:
 [docs/releasing.md](docs/releasing.md).
 ## [Unreleased]
 
+## [0.132.0] - 2026-10-29
+
+### Added
+
+- `chi home`, `chi home set [--ruby PATH]`, `chi home doctor`: the chi home, the one Ruby and gem path every chi
+  launch boots (`~/.config/samagotchi/home.json`). The first `chi bootstrap` or `chi update` records it once (the
+  desktop helper's Ruby when it has samagotchi, else chi's own); see docs/configuration.md (The chi home). A
+  write or edit of home.json asks, as config.yml does (rule `chi-home`, the user's alone).
+- Bundles: model-notes 0.2.0 ships `model_notes_tone` (`models: *`): every model answers first, in plain words, without
+  preambles or closing offers. Off with `chi --mute model_notes_tone`; your own note of that name wins.
+- Plugins: `chi.prompt_section(name) { |ctx| … }` adds a bundle's text to the system prompt's stable part (after the
+  toolkit's prompt, before the memory indexes), and `chi.prompt_changed!` builds the prompt again at the next turn.
+  A section that fails keeps its last good text; `/stats` names the sections (`prompt sections:`).
+- Plugins: a command can ask before a change that restarts the prompt cache, as `/thinking` does:
+  `ctx.cache_confirm(line, changed:)` gives a confirm for a person at a web tab or a TUI once the session has a
+  model reply, and the command returns `[text, confirm]` (the TUI prefills the `--yes` line, the web shows Apply).
+- Plugins: `ctx.model_names` lists the names chi looks the session's model up under (alias, target, ref, bare id),
+  so a bundle can match a per-model map the way config.yml's `models:` settings are matched.
+
+### Changed
+
+- With a chi home, every session worker (whoever starts or wakes it), chi web's restart and Update, `chi update`
+  and `chi bootstrap`'s commonmarker install run on it: the home's Ruby with its gem path set inside Ruby, never in
+  an env, so session tools keep the spawner's GEM_HOME/GEM_PATH. `chi update` from another Ruby runs the home's
+  (`updating the chi home (<ruby>)`) and installs into its gems; a worker whose home can't load chi logs one
+  `boot_failed` line instead of a silent spawn timeout. Without a home every launch is as before.
+- Desktop helper: `chi desktop install` and `upgrade` make it boot the chi home when there is one, and its launch
+  file no longer carries `RUBYLIB`, nor `GEM_HOME`/`GEM_PATH` when it boots the home (they reached every command its
+  sessions ran). `chi update` drops `RUBYLIB` from an existing one, and `GEM_HOME`/`GEM_PATH` once it boots the home.
+- `/model` asks before switching to another model once the session has a model reply, from a web tab or a TUI (the
+  new model has no cache of the conversation): the reply names the size it rereads and the line that applies it,
+  flags and all (`/model qwen --default --yes`); `--yes` (or `-y`) applies at once, and a typo is an error before any
+  question. `chi send`, delegates and `chi --model` on an attached or resumed session apply at once.
+- `/llm-context` asks the same way before the two changes that break the prompt cache now: `forget` turned on or off,
+  and a layer with applied stubs turned off (`/llm-context reset --yes` applies too). Turning `stale` on, the apply
+  rule and the budget don't ask; the web's `llm ctx` chip and `chi --llm-context` on an attached or resumed session
+  apply at once.
+
+Update with `chi update`, then restart `chi web` and the session workers (`chi sessions restart`): a new TUI's
+`--model X` on a worker from before this release switches it to the model "X --yes".
+
 ## [0.131.0] - 2026-10-29
 
 ### Changed
 
+- Web: the start page's composer row stays one row at any width: a long model name ellipsizes instead of pushing
+  Start to a second row.
+- Web: the start page's model button shows a short name (`openrouter · deepseek-v4.1-flash`: no org prefix, the tag
+  kept, the host only when it isn't the default); its tooltip and label keep the full name.
 - Cache: confirmations for prompt-cache changes estimate the reread size when known and warn that Anthropic drops
   preserved thinking after a full-prefix change.
 
@@ -4992,7 +5037,8 @@ 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.131.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.132.0...HEAD
+[0.132.0]: https://github.com/dm1try/samagotchi/compare/v0.131.0...v0.132.0
 [0.131.0]: https://github.com/dm1try/samagotchi/compare/v0.130.1...v0.131.0
 [0.130.1]: https://github.com/dm1try/samagotchi/compare/v0.130.0...v0.130.1
 [0.130.0]: https://github.com/dm1try/samagotchi/compare/v0.129.0...v0.130.0

data/bin/chi

@@ -82,7 +82,9 @@ SUBCOMMANDS = {
   # audit suggestions for which toolkit fits a session's first prompt
   "toolkit" => ["samagotchi/toolkit_report_command", "ToolkitReportCommand"],
   # other machines' chi web, for chi --remote NAME (add, ls, rm)
-  "remote" => ["samagotchi/remote_command", "RemoteCommand"]
+  "remote" => ["samagotchi/remote_command", "RemoteCommand"],
+  # the chi home: the Ruby every chi launch boots (set, doctor)
+  "home" => ["samagotchi/home_command", "HomeCommand"]
 }.freeze
 # chi --remote NAME <command> (or CHI_REMOTE=NAME): the session commands
 # against another machine's chi web; what runs here only is refused (exit 2).

data/docs/architecture.md

@@ -133,6 +133,36 @@ terminal renders the events it gets over the Bridge.
 - In REPL mode `TerminalUI` builds the `Engine` in process (`-p` and `--non-interactive` too);
   otherwise the session's `Worker` (`lib/samagotchi/worker.rb`, spawned by `SessionManager`) builds it.
 
+## How chi launches itself
+
+chi starts chi in several places, and each must land on the same install whoever starts it (a terminal on another
+Ruby, chi web, the macOS helper under launchd). The **chi home** (`ChiHome`, `chi_home.rb`; recorded in
+`$XDG_CONFIG_HOME/samagotchi/home.json` by `chi home set`, or once by `chi bootstrap` / `chi update`:
+[configuration.md](configuration.md#the-chi-home)) names that install: a Ruby and its gem path.
+
+**One mechanism.** `ChiHome::Record#boot_argv(run:)` is `[home ruby, "-e", "Gem.paths = {'GEM_HOME' => …,
+'GEM_PATH' => …}; <run>"]`: the gem path goes into the boot string, never into an environment, so the tools a worker
+runs keep the spawner's GEM_HOME/GEM_PATH (or none), and a stray one in the spawner's env can't move chi off the
+home. `ChiHome::CHI_BOOT` (`gem 'samagotchi', '>= 0.a'; load Gem.bin_path('samagotchi', 'chi')`) plus `"--"` and
+the arguments runs the home's newest `chi`. Each site asks `ChiHome.current` at launch time; it is nil (and the site
+keeps its own argv, as before the home) without home.json, for one that isn't its shape (warned once), when the
+home's Ruby is gone, when no `samagotchi-*.gemspec` is under its gem path, and from a source checkout.
+
+| Site | With a home | Without |
+|---|---|---|
+| `SessionManager.worker_command`: every worker (attach, `chi send`, chi web, delegate and Verify-fresh children, `resume_session`, `:restart`) | the home's ruby, `Gem.paths`, `>= 0.a` with the fallback pin (`ChiHome.fallback_version`: the spawner's version when the home has it, else the home's newest; a home older than the spawner is warned once); a chi that still can't load writes one `boot_failed` line to `SAMAGOTCHI_LOG_FILE` and exits 1 | `RbConfig.ruby -e` with `>= 0.a` (a checkout: `-I lib`) |
+| `Web::Server.reexec_command` (chi web's restart) | `CHI_BOOT -- web …`; the `:no_wrapper` refusal never applies; a home whose newest chi is older than this one is passed over (logged `restart_home_older`) | `[RbConfig.ruby, wrapper, …]` (`$PROGRAM_NAME` in a checkout) |
+| `Web::App#update_argv` (the **Update** button's child) | `CHI_BOOT -- update --to V --no-desktop --json` | `[RbConfig.ruby, wrapper, update, …]` |
+| `UpdateCommand` | on another Ruby than the home (`Record#running_here?`): exec `CHI_BOOT -- update …` once (`SAMAGOTCHI_UPDATE_IN_HOME=1`: an older home chi ignores it); the install (`GemUpdate`) runs `ChiHome.gem_bin` with `ChiHome.install_env` (the home's GEM_HOME/GEM_PATH for that child, `mise`'s dir on PATH); the hand-over execs `CHI_BOOT -- update --no-gem --gem-from …` | this Ruby's `gem`, the wrapper |
+| `BootstrapCommand` (commonmarker) | `ChiHome.gem_bin` + `install_env`; installed? = in the home's specifications | this Ruby's `gem` |
+| `Desktop::MacOS#launch_config` | argv `CHI_BOOT + ["--"]`; `launch_ok?` / `launch_problem` check only absolute argv entries | `[ruby, wrapper or bin/chi]` |
+| `InstalledVersions`, `Web::UpdateCheck` | the home's specification dirs and gem dir | the running process's |
+
+Unchanged: `ContextProviders`' `{ruby}` (`RbConfig.ruby`: the home's ruby inside a home worker), `chi bundle
+try/test/check` (`-I LIB_DIR`), hooks (in-process). The worker's boot string, `run_session_loop(id, state_dir:)` and
+`SAMAGOTCHI_BOOT_FALLBACK` stay the cross-version contract (`spec/worker_contract_spec.rb`): the home only adds the
+prelude in front. An older chi that wakes a session doesn't read home.json and starts its worker as before.
+
 ## Session retention & ordering
 
 - **Files:** `~/.local/state/samagotchi/sessions/<uuid>.json` + `<uuid>/input|output|owner.lock|bridge.json` (XDG-aware), and the `<uuid>/stopped` and `<uuid>/archived` marker files.
@@ -227,7 +257,8 @@ The system prompt (`SystemPrompt#build`, assembled in `#system_prompt_with_index
 base prompt, then the toolkit's "Not loaded in this session" line (only when the toolkit
 leaves tools out), rg guidance, the identity, the model notes, the preloaded memories,
 AGENTS.md (root → cwd), the appended files (`--append-system-prompt`), the toolkit's
-kit prompt (a kit's `prompt:` text, only when it has one), the memory
+kit prompt (a kit's `prompt:` text, only when it has one), the plugins' prompt
+sections (`chi.prompt_section`, only when a plugin gives text), the memory
 indexes, and last **the model** (`Model: this session runs on <ref> (host …; model key …)` and a line telling
 the model to answer "which model are you" from it, not from training), the working
 directory and the session id and log (Gemma's native tool declarations still follow).

data/docs/cli.md

@@ -35,6 +35,7 @@
 - `chi models [--format text|json] [--timeout S] [TEXT]` — list the models every configured host offers, as the names `--model` takes (see [Listing the models](#listing-the-models))
 - `chi self` — print version, source dir (checkout or installed gem), config/memory/session paths, model/host and bundles. Run by a session's `execute`, the `model` row (and host, loop, profile, thinking, served model) is **that session's** model, labelled `(this session <id8>; default …)`; elsewhere it is the default, `(default)`. `model key` is the memory overlay key (`<name>.<key>.md`), and `model notes` the model notes a prompt of that model loads (`model_notes_deepseek (system, 612 chars)`, `none`; inside a session its `--mute` list is left out). `chi self --model` prints only the model a new session starts on, an alias resolved to its target (the desktop helper's hint)
 - `chi update [--dry-run] [--to VERSION] [--json] [--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 home`, `chi home set [--ruby PATH]`, `chi home doctor` — the chi home: the one Ruby (and its gem path) every chi launch boots, whoever launches it. `chi home` shows it (its Ruby, the newest chi in it, gem home and path, `mise`, when and by which chi it was set, and the chi you ran when that is another one; exit 1 with the problem when it can't boot chi), `set` records this chi's Ruby and gem path (or `--ruby PATH`'s own; it must have samagotchi), `doctor` checks it (for now: its Ruby is there and has samagotchi; exit 1 says what to do). This machine only (see [The chi home](configuration.md#the-chi-home))
 - `chi bundle install|upgrade|uninstall|status|diff|list|build|trash|new|test|check` — 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; `core` and `dev` are profiles that install a set of them (see [Bundle profiles](memory.md#bundle-profiles-core-and-dev),  [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)). `trash` lists and empties the bundle trash (moved files from uninstalls/upgrades). A usage error (an unknown subcommand or flag, a missing argument, a bad `build --scope`) exits 2, as for the other subcommands. Plain `chi` and `chi web` exit 1 on an unknown flag, a flag missing its value or a stray argument. `new`, `test` and `check` are for writing one: see [Writing a bundle](#writing-a-bundle-new-test-check)
 
 - `chi guardrails replay [--dry-run] [--threshold T] [--model M]` — seed System 1's record from the approvals this machine's sessions already answered: each ask is judged by the configured model and written to `guardrails/judgments.jsonl` with the answer the user gave, then a per-rule table prints (asks, allowed, denied, would-be auto-allows, false allows, asks with no judgment). A parent agent's answer is not the user's: only its deny is replayed, and only where the parent could have allowed. `--dry-run` judges without writing, `--threshold` overrides `guardrails.system_one.threshold` for the table, `--model` the configured model for this run. Exit 2 when `guardrails.system_one.mode` is off or no `host` is set; a usage error exits 2 (see [System 1](guardrails.md#system-1-experimental))
@@ -257,11 +258,22 @@ done
   [configuration](configuration.md#all-settings)). If the gem can't be updated
   in place, the notice gives the blocker and its command instead.
 
+- **The chi home.** With a [chi home](configuration.md#the-chi-home), a `chi
+  update` started on another Ruby first says `updating the chi home (<ruby>)`
+  and runs the home's chi update instead (the version check, `--to` and the
+  rows are the home's); chi web's **Update** runs the home's too. Without
+  one, the first `chi update` (not `--dry-run`, not under Bundler, and only
+  once its own checks passed) records one: of the desktop helper's Ruby and
+  the Ruby it runs on, the one with the newer chi, and says `chi home set to
+  <ruby> (chi home set to change)`.
 - **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; a chi
-  installed under another Ruby is a separate install it doesn't touch). Then it
-  hands over to the new chi, which does the rest and prints the table. Old
+  of the chi home's Ruby, into the home's gems (`GEM_HOME`/`GEM_PATH` set to
+  the home's for that one command, and `mise`'s folder on its PATH when the
+  home names one, for mise's reshim plugin); without a home, the Ruby chi runs
+  on (the real one, not a mise/rbenv/asdf shim; a chi installed under another
+  Ruby is a separate install it doesn't touch). 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 load
   files from them, so a `gem cleanup` while they run breaks them (a
   `LoadError`, missing web assets); restart them first. A chi web, an
@@ -293,7 +305,9 @@ done
   sources changed; otherwise only its launch file is refreshed (a newer chi or
   other terminal settings). It keeps the Ruby, chi and PATH the helper runs (a
   PATH is filled in only when the file has none): `chi desktop install --force`
-  and `chi desktop upgrade` bake this shell's. A helper whose Ruby or chi is gone
+  and `chi desktop upgrade` bake this shell's (the chi home's boot, when there
+  is one). A refresh drops `RUBYLIB` from the launch file, and `GEM_HOME`/`GEM_PATH`
+  once it boots the chi home. A helper whose Ruby or chi is gone
   is reported as failed, naming `chi desktop install --force`. See
   [Desktop helper](desktop.md).
 - **Running processes** are reported, never stopped. A live worker keeps its
@@ -689,11 +703,14 @@ saved with the session and applies from the next turn's start; the reply says
 what it costs: `forget` on or off re-reads the whole prompt once, `stale` turned
 on stages the reads already superseded as one batch under the apply rule, and a
 layer turned off sends its stubs whole again (turning it back on brings them
-back). `/llm-context` alone answers mid-turn too; a change sent while a turn runs
+back). Once the session has a model reply, the two that break the cache now
+(`forget` on or off, a layer with applied stubs turned off) ask first and name
+the `--yes` line that applies them; `/llm-context reset --yes` works too.
+`/llm-context` alone answers mid-turn too; a change sent while a turn runs
 waits for the turn's end (see *Typing during a turn*). `/stats` shows
 the same values on its `llm context:` line. The web's info bar shows them as the
 `llm ctx` chip (`llm ctx stale,forget · session`), whose popover sets them
-through `/llm-context`. See "LLM context: a session's own strategy" in
+through `/llm-context … --yes` (its form says what a change costs). See "LLM context: a session's own strategy" in
 [configuration.md](configuration.md).
 
 `/working-set` lists the session's working set as the model has it (see [The
@@ -801,9 +818,9 @@ mid-turn too, and the lists, cards, top bar and tab show it in place of the firs
 message; a continue's next link keeps it. In the web, `✎` next to the session's
 title (its strip card, or the top bar) does it. See [Session titles](sessions.md#session-titles).
 
-A `/thinking`, `/reasoning-history` or `/toolkit` change that restarts the prompt cache
+A `/model`, `/llm-context`, `/thinking`, `/reasoning-history` or `/toolkit` change that restarts the prompt cache
 asks first: the reply says what it costs, changes nothing, and names the line
-that applies it (`/thinking low --yes`). `--yes` (or `-y`) applies it at once.
+that applies it (`/thinking low --yes`, `/model qwen --default --yes`). `--yes` (or `-y`) applies it at once.
 The terminal puts that line in the next input (Enter applies it); the web's
 reply has an Apply button. `chi send ID "/thinking low"`,
 `chi -p "/thinking low" --non-interactive` and lines piped into the REPL apply
@@ -1596,6 +1613,10 @@ In interactive assist mode, you can switch the request model without restarting:
 - `/model <name> --alias <alias>`: create alias for current effective model (alias value may be bare or `host:model`).
 - `/model`: show the effective model (and default when diverged: `runtime model: <effective> (default: <default>, profile=<name>, <source>)`, e.g. `profile=qwen36, server (chat_template)`). When the session's prompt carries model notes the line ends with `; notes: model_notes_deepseek (system, 612 chars)`; a switch's `runtime model set to …` names the new model's ([Memory](memory.md#model-notes)).
 - `/model clear` (or `default`/`none`/`off`): clear the session override, reverting to the configured default.
+- Once the session has a model reply, a switch to another model asks first from a web tab or a TUI (the new model
+  has no cache of the conversation): the reply names the line with `--yes` that applies it, flags and all
+  (`/model qwen --alias q --yes`); `--yes` (or `-y`) applies at once. A typo (an unknown host, a bad alias) is an
+  error before any question. See "Changes that restart the prompt cache" in [configuration.md](configuration.md).
 - `/guardrails`: the guardrail rules (by source), what failed to load, your stored approvals, and System 1's
   recent auto-allows; `/guardrails revoke N` removes approval N and `/guardrails wrong [N]` flags an auto-allow
   this session should have been asked about (see [Guardrails](guardrails.md)).

data/docs/configuration.md

@@ -833,10 +833,14 @@ models:
 
 ## Changes that restart the prompt cache
 
-`/thinking`, `/reasoning-history` and `/toolkit` ask before a change that makes the server read the conversation again:
-Gemma's thinking switch, a remote chat host's thinking fields ("Thinking"), a change to or from `all` once an earlier
-reply has thinking ("Reasoning history"), and any change to the declared tools, which start every request
-("Toolkits"). They ask only when what the next turn runs under really changes and the session has a model reply.
+`/model`, `/llm-context`, `/thinking`, `/reasoning-history` and `/toolkit` ask before a change that makes the server
+read the conversation again: a switch to another model (a plain name, `--default`, `--alias N`, `clear`; the new model
+has no cache of the conversation), `forget` turned on or off and a layer with applied stubs turned off ("LLM context:
+a session's own strategy"), Gemma's thinking switch, a remote chat host's thinking fields ("Thinking"), a change to or
+from `all` once an earlier reply has thinking ("Reasoning history"), and any change to the declared tools, which start
+every request ("Toolkits"). They ask only when what the next turn runs under really changes (`/model` naming the model
+it already runs, by its resolved ref, doesn't ask) and the session has a model reply. A `/model` name is checked
+first: an unknown host or a bad alias is an error at once, not a question.
 
 - The reply says what it costs and changes nothing yet. When known, it estimates the reread size: the whole
   conversation for full-prefix changes, or from the first changed reply for reasoning history. On `api: anthropic`,
@@ -849,8 +853,9 @@ reply has thinking ("Reasoning history"), and any change to the declared tools,
   the button is gone after a reload.
 - Only a person at a web tab or a chi TUI is asked. `chi send ID "/thinking low"`,
   `chi -p "/thinking low" --non-interactive`, lines piped into the REPL, a delegate, a plugin and a card's action
-  apply directly, since nobody would see the question; so do the start flags (`chi --thinking` on a resumed or
-  attached session sends `/thinking LEVEL --yes`). A plain `chi -p` opens the REPL, which asks.
+  apply directly, since nobody would see the question; so do the start flags (`chi --thinking`, `--model` and
+  `--llm-context` on a resumed or attached session send `/thinking LEVEL --yes`, `/model NAME --yes` and
+  `/llm-context … --yes`). A plain `chi -p` opens the REPL, which asks.
 
 ## Llama HTTP Timeouts
 
@@ -1347,6 +1352,51 @@ The helper reads these from its launch file: after editing them run
 (`$TMUX_TMPDIR/tmux-<uid>`, else `/tmp/tmux-<uid>`) are resolved then and
 frozen in it. See [Desktop helper](desktop.md#agents-in-kitty-and-tmux).
 
+## The chi home
+
+With several Rubies on one machine (mise, rbenv, chruby; a project that pins its own), whichever Ruby started chi
+used to decide which chi ran: a terminal in a project on Ruby 3.4 woke its session's worker on that Ruby's chi (an
+older one, or none), chi web's restart could fall off onto another install, and the macOS helper ran the Ruby of the
+shell it was installed from. The **chi home** is the one Ruby, and its gem path, every chi launch boots, whoever
+launches it. It is recorded in `~/.config/samagotchi/home.json` (`$XDG_CONFIG_HOME` is honoured):
+
+```json
+{
+  "ruby": "/Users/me/.local/share/mise/installs/ruby/4.0.7/bin/ruby",
+  "gem_home": "/Users/me/.local/share/mise/installs/ruby/4.0.7/lib/ruby/gems/4.0.0",
+  "gem_path": "/Users/me/.gem/ruby/4.0.0:/Users/me/.local/share/mise/installs/ruby/4.0.7/lib/ruby/gems/4.0.0",
+  "mise": "/opt/homebrew/bin/mise",
+  "set_at": "2026-10-29T21:00:00Z",
+  "set_by_version": "0.132.0"
+}
+```
+
+- **Setting it.** `chi home set` records the Ruby your `chi` runs on and its gem path (a chruby shell's
+  `GEM_HOME`/`GEM_PATH` are part of it: that is where its chi lives); `chi home set --ruby PATH` records another
+  Ruby with its own gem dirs. Either needs samagotchi installed there (`gem install samagotchi` with that Ruby
+  first). Without a home.json, the first `chi bootstrap` or `chi update` records one, once (from an installed chi,
+  never under `bundle exec`): of the desktop helper's Ruby (when its newest chi is at least the one running) and the
+  Ruby chi runs on, the one with the newer chi. Nothing else ever overwrites it.
+  `chi home` shows it; `chi home doctor` checks it (see [CLI](cli.md#commands)).
+- **What follows it.** Every session worker (whoever starts or wakes it: a terminal, `chi send`, chi web, a
+  delegating session, a restart), chi web's restart and its **Update** button, `chi update` (from another Ruby it
+  runs the home's `chi update`, and installs into the home's gems with the home's `gem`), `chi bootstrap`'s
+  commonmarker install, chi web's "installed; restart" notice and the macOS helper after its next `chi desktop
+  install` or `upgrade`. The boot sets the home's gem path inside Ruby (`Gem.paths`), never in an environment
+  variable: the commands a session runs (`execute`, tasks, `!cmd`, MCP servers) keep the GEM_HOME/GEM_PATH of whoever
+  started the worker, or none. How: [How chi launches itself](architecture.md#how-chi-launches-itself).
+- **No home, or one that can't boot chi** (its Ruby gone after a Ruby upgrade, samagotchi uninstalled there, a
+  home.json that isn't JSON): each launch uses the Ruby that starts it, as without a home, and the log says why once
+  per process (`home_unusable`, `home_invalid`). After a Ruby upgrade: `gem install samagotchi` with the new Ruby,
+  then `chi home set` from it. A source checkout (`bin/chi`, `bundle exec`) never uses the home: a worktree's
+  `bin/chi` starts its own code.
+- **A home with an older chi than the one launching**: workers still boot the home (the log says so once,
+  `home_older_than_spawner`), but chi web's restart runs the newest chi it knows outside the home instead
+  (`restart_home_older`): its flags may be ones the older chi doesn't know.
+- **A home that still fails at boot** (a broken install): the worker writes one `boot_failed` line to the debug log
+  (`log.file`) and exits, rather than leave the spawner waiting.
+- Each machine has its own home (a remote's is that machine's).
+
 ## Project specific description
 
 If an AGENTS.md file is present in the project root, samagotchi injects its
@@ -1641,6 +1691,12 @@ its own). The first target is a long session such as a day-long coordinator, whe
   and their results stay in the history.
 - **Switching a layer off:** its stubs go out whole again from the next request (a cache break from the first). The
   session keeps the originals and the edits, so turning the layer back on brings the same stubs back.
+- **Asks first:** once the session has a model reply, `/llm-context` from a web tab or a TUI asks before the two that
+  break the cache now: `forget` on or off, and a layer with applied stubs turned off (the reply names the
+  `/llm-context … --yes` line; "Changes that restart the prompt cache"). Turning `stale` on, the apply rule and the
+  budget don't ask: they only decide when a batch goes in, and each batch's break comes as designed (`next_request`
+  with staged edits pending moves a break the old rule makes by the end of the next turn anyway). The chip's Set and
+  `--llm-context` on an attached or resumed session send `--yes`.
 - **Where to see it:** `/llm-context` (each value and where it came from: `the session`, `models: <key>`,
   `hosts entry '<name>'`, `llm_context.*`), `/stats` (`llm context:`), the turn log (an `llm_context` record per
   turn that runs a layer or whose session set its strategy) and the web's chip. A woken worker's status line counts

data/docs/desktop.md

@@ -257,7 +257,9 @@ don't break it. From a checkout it runs **that** checkout's `bin/chi`; installin
 warning, because the helper stops working once that worktree is removed. After switching between a checkout and a
 gem install, run `chi desktop upgrade` from the one you now use.
 
-The helper runs the Ruby and chi of **the shell you installed from**, and only `chi desktop install --force` and
+With a [chi home](configuration.md#the-chi-home), `chi desktop install` and `upgrade` make the helper boot the home
+(its Ruby, the newest chi in its gems) whatever shell you run them from. Without one, the helper runs the Ruby and
+chi of **the shell you installed from**, and only `chi desktop install --force` and
 `chi desktop upgrade` change that: they pick the Ruby and chi of the shell you run them in. `chi update` never
 repoints it, so running it from a project with another Ruby (or an older chi) leaves the helper where it was. If
 the Ruby or chi the helper runs is gone (a Ruby upgrade, a removed worktree), `chi update` fails the helper's row
@@ -286,12 +288,19 @@ says the same.
 Apps started by macOS get a bare environment: no shell rc files, so no rbenv/chruby/mise/asdf and none of your
 exports. So `install` writes `~/Library/Application Support/Chi Helper/launch.json` with:
 
-- the absolute path of the Ruby running chi and of chi itself (the gem's wrapper, or a checkout's `bin/chi`), as of
-  the last `chi desktop install` or `upgrade` (`chi update` keeps them);
+- what to run, as of the last `chi desktop install` or `upgrade` (`chi update` keeps it): with a
+  [chi home](configuration.md#the-chi-home), the home's boot, `["<home ruby>", "-e", "Gem.paths = {…}; gem
+  'samagotchi', '>= 0.a'; load Gem.bin_path('samagotchi', 'chi')", "--"]` (the helper appends its own arguments
+  after `--`); without one, the absolute path of the Ruby running chi and of chi itself (the gem's wrapper, or a
+  checkout's `bin/chi`). The helper and `chi update` check only the absolute paths in it;
 - `LANG=en_US.UTF-8`;
-- only these variables, and only when they are set: `XDG_CONFIG_HOME`, `XDG_STATE_HOME`, `GEM_HOME`, `GEM_PATH`,
-  `RUBYLIB` (a relative `XDG_*` dir made absolute from the install's current folder: the helper starts in `/`).
-  No tokens and no `SAMAGOTCHI_*` settings go in;
+- only these variables, and only when they are set: `XDG_CONFIG_HOME`, `XDG_STATE_HOME` (a relative one made
+  absolute from the install's current folder: the helper starts in `/`). No tokens and no `SAMAGOTCHI_*` settings
+  go in, and never `RUBYLIB`. `GEM_HOME` and `GEM_PATH` go in only without a chi home (a `[ruby, chi]` launch,
+  whose chi may be found only through them, as under chruby): the home's boot sets its gem path itself, and they
+  would reach every command the helper's sessions run (a project's `bundle exec` on the wrong gems). A launch file
+  from an older chi loses `RUBYLIB` at the next `chi update`, and `GEM_HOME`/`GEM_PATH` once it boots the chi home
+  (`chi desktop upgrade` moves it to the home);
 - `PATH`: the shell's PATH when the file is written, with only absolute folders, in order, each once. The helper's
   chi, the sessions it starts and their `execute` commands can find the tools your terminal finds (mise, Homebrew,
   `codex`, `node`);

data/docs/guardrails.md

@@ -4,7 +4,7 @@ Every tool call the model makes passes one check before it runs, in both
 loops (native and chat hosts). The verdict is **allow**, **ask** or
 **deny**; the strictest vote wins, and a deny can't be undone by a later
 voter. Of two asks the first one names the rule, except a rule only the
-user may allow (`chi-config`, `chi-hooks`, `shell-touches-chi`,
+user may allow (`chi-config`, `chi-home`, `chi-hooks`, `shell-touches-chi`,
 `chi-context-cmd`, `chi-broadcast`): it takes over, and only the scopes both asks offer
 are offered.
 
@@ -215,7 +215,7 @@ rules off: `guardrails: {disable: [write-outside-repo, git-outside-repo]}`.
 
 Whatever the setting, a parent can't allow a call on chi's own files: a
 `write`, `edit` or `execute` on the config dir (config.yml, installed bundles'
-rules), the hooks dir or the approval store, by its rule (`chi-config`,
+rules), the hooks dir or the approval store, by its rule (`chi-config`, `chi-home`,
 `chi-hooks`, `shell-touches-chi`), its paths or its command. "Allow once" on a
 config.yml rewrite would allow everything from then on, so those questions are
 the user's alone (`user_only`): `chi answer` and the worker refuse the allow
@@ -280,7 +280,7 @@ Built in, for `write`, `edit` and `memory_write` (symlinks resolved; see
 - deny: the approval store's dir, installed bundles (`memories/.bundles/`),
   and [attached context](context.md) sources (`<state dir>/context/`: a
   source's command runs later, outside the gate; `chi context` changes them);
-- ask (once or for the session): `config.yml` and the plain hooks dir.
+- ask (once or for the session): `config.yml`, `home.json` (the [chi home](configuration.md#the-chi-home): the Ruby every chi launch boots) and the plain hooks dir.
 
 `execute` can still reach them; the guardrails bundle asks about shell
 commands that name them.

data/docs/internals/anthropic.md

@@ -133,8 +133,9 @@ append-only within a process, so what changes the prefix is:
 1. **A system-prompt rebuild** (`SystemPrompt#build` is cached per process and key; `SystemPrompt#reset!` drops it):
    a new process (`--resume`, a respawn after `session.idle_exit_minutes`, a crash) after a memory index line, an
    AGENTS.md, an appended file, a model note or a bundle memory changed; `/model` (the tail's `Model:` line, its
-   overlays and notes); `/thinking` (another key); a toolkit or profile change; a plugin's `tools_changed!`; the
-   session's first participant joining or last leaving (the tail's participants line, participants.md).
+   overlays and notes); `/thinking` (another key); a toolkit or profile change; a plugin's `tools_changed!` or
+   `prompt_changed!` (its prompt section's text, plugins.md); the session's first participant joining or last
+   leaving (the tail's participants line, participants.md).
 2. **A tool set change**: the same triggers, plus MCP lines that differ on a respawn.
 3. **History edits by design**: the `llm_context` `stale`/`forget` stubs, and the image cut moving a batch.
 

data/docs/internals/engine.md

@@ -832,10 +832,10 @@ answer is stripped from prefill + response, so the reasoning never lands in it).
    persistent.
 5. **A stable system prompt for the cache.** `SystemPrompt#build` caches the prompt per Engine, keyed by
    `[chat, thinking, layers]` (chat/native, the thinking level, the turn's LLM context layers), and is reset
-   only on a model switch, a tools change, a profile change or a toolkit change (`Engine#apply_toolkit!`). The
-   stable part (base prompt, the toolkit's not-loaded line, rg guidance, identity, model notes, preloaded memories,
-   AGENTS.md, appended files, the toolkit's kit prompt, memory indexes) comes before the volatile tail (model,
-   working directory, session).
+   only on a model switch, a tools change, a plugin's `prompt_changed!` (`Engine#prompt_changed!`), a profile
+   change or a toolkit change (`Engine#apply_toolkit!`). The stable part (base prompt, the toolkit's not-loaded line,
+   rg guidance, identity, model notes, preloaded memories, AGENTS.md, appended files, the toolkit's kit prompt, the
+   plugins' prompt sections, memory indexes) comes before the volatile tail (model, working directory, session).
    prompt-caching.md covers this in detail.
 
 ## Key files

data/docs/internals/prompt-caching.md

@@ -40,6 +40,7 @@ right-hand column happens.
 │   AGENTS.md (root → cwd)                                                 │  (picked up by a new
 │   appended files (append_system_prompt:, --append-system-prompt)         │  process or a rebuild)
 │   kit prompt (per toolkit: its kit's prompt: text, only when it has one) │
+│   plugin prompt sections (chi.prompt_section, by (bundle, name))         │  chi.prompt_changed!
 │   project + system memory indexes                                        │
 │                ◄── remote Claude / Messages: cache_control breakpoint #1 │
 ├──────────────────────────────────────────────────────────────────────────┤
@@ -65,8 +66,8 @@ right-hand column happens.
 - The system prompt is built **once per key** and kept (`SystemPrompt#build`, keyed by `[chat, thinking, layers]`:
   the loop, the thinking level, the turn's LLM context layers; a `/thinking` change builds under another key). All
   of them are dropped only on `@prompt_builder.reset!`: a model switch (`Engine#switch_model!`), a plugin's
-  `tools_changed!`, a profile change, or a toolkit change (`Engine#apply_toolkit!`). A per-turn rebuild would break
-  everything below it.
+  `tools_changed!` or `prompt_changed!` (`Engine#prompt_changed!`), a profile change, or a toolkit change
+  (`Engine#apply_toolkit!`). A per-turn rebuild would break everything below it.
 - The tools layer is shared **per toolkit** (configuration.md, "Toolkits"): sessions on the same toolkit share it,
   and a chain's links keep theirs. A session's toolkit is saved when it is created and never resolved again from
   config. A change (`/toolkit`, `ctx.use_toolkit`) is applied only at a turn's start (`Engine#apply_toolkit!`,
@@ -88,6 +89,15 @@ right-hand column happens.
   sessions on the kit share it; a memory write (the indexes after it) doesn't move it. It is part of the
   `Toolkit::Resolved` the Registry holds, so a switch that changes only the text is a toolkit change
   (`apply_toolkit!` → `reset!`). `full` and kits without one send the bytes they sent before.
+- A plugin's prompt sections (`chi.prompt_section`, `Plugin::PromptSections`) sit after the kit prompt and before
+  the memory indexes (`SystemPrompt#plugin_prompt_section`), sorted by (bundle, name), each
+  `From <bundle> (<name>):\n<text>`; with none (every block nil) the bytes are what they were before. A block runs
+  only inside a build, never per request, so its text changes the prompt only at a rebuild: `/model` (a block
+  reading `ctx.model` re-resolves for free) or the plugin's `chi.prompt_changed!`, which its command calls only
+  after asking (`ctx.cache_confirm`, rule 6); a running turn keeps the prompt it started with (`turn_messages` puts
+  it in the turn's messages once). A block that raises, returns a non-String or text over 2000 characters keeps
+  the section's last good text for the session: a skip on a transient error would break the cache twice (and on
+  Claude 5.x cost the preserved thinking each time).
 - find_tools' description is a function of the toolkit and the source groups **at load**: `ToolIndex#declare`
   snapshots source group names and description lines (name, summary, callable count). `ToolIndex#refresh!` (from
   `ToolkitBinding#apply!`) filters that snapshot by the new toolkit and rebuilds the `chi` line from the built-ins
@@ -221,7 +231,9 @@ is prefilled once. The native and the chat loop use the same plan.
 3. **Deterministic order.** Tools, memory lists and anything else that's rendered from a hash or a set needs a
    fixed sort. Plugin tools are sorted by (bundle, name) whatever order their plugins finished starting in
    (R5a).
-4. **Don't rebuild the system prompt per turn.** Rebuild only when its content really changed (`reset!`).
+4. **Don't rebuild the system prompt per turn.** Rebuild only when its content really changed (`reset!`). A
+   plugin's prompt section is the same text for the same inputs, and its `chi.prompt_changed!` is called only when
+   its text changed.
 5. **Measure.** Every generation logs `prompt=`, `cached=` and, where the provider reports it, `cache_write=`
    on its `generation_completed` log line. `/stats` shows "cached N (P%)" and "cache writes". A change that
    drops `cached=` on the second fresh session is a regression. Update the prompt snapshot fixtures with
@@ -230,13 +242,21 @@ is prefilled once. The native and the chat loop use the same plan.
    the conversation again asks a person at a web tab or a TUI first (`CacheConfirm`: the reply carries the
    `--yes` line, `SessionCommands::Result#confirm` and the `command_ran` event's `confirm`). Each setting has a
    classifier: `Thinking.cache_cost` (`:full` for Gemma, `:provider` for a remote chat host, `:tail` otherwise) and
-   `ReasoningHistory.cache_cost` (`:history` for a change to or from `all` once an earlier reply has thinking).
+   `ReasoningHistory.cache_cost` (`:history` for a change to or from `all` once an earlier reply has thinking),
+   `/model` (`SessionCommands#model_ask`: `:full` for any other resolved ref, `Engine#model_switch_ref` checking
+   the name first, so a typo errors instead of asking; every switching branch, `--default`, `--alias`, `clear`), and `LLMContextCommand#cache_cost` (`:full` for forget
+   on or off, `:history` for a layer with applied stubs turned off; stale on, the apply rule and the budget only
+   decide when a batch's break comes, so they don't ask).
    `CacheConfirm.needed?` asks only for `:full`, `:provider` and `:history`, when the effective level changes and
    the session has a model reply. The confirmation estimates the reread size from the latest known context count:
    the whole conversation for `:full` / `:provider`, or up to the first changed reply for `:history`; it omits the
    estimate when no count is known. On `api: anthropic`, a `:full` / `:provider` change also warns that preserved
-   thinking in replies is dropped from then on. A new setting with a cost (a `/model` across templates,
-   `/llm-context` turning forget on) adds its classifier and goes through the same step.
+   thinking in replies is dropped from then on. A new setting with a cost adds its classifier and goes through
+   the same step. A launch flag (`chi --model`, `--llm-context`, `--thinking` on an attached or resumed session,
+   `LLMContextOverride.command_line`) and a chip whose form states the cost (`level_chip.js`, `llm_context_chip.js`)
+   send their line with `--yes`: typing the flag, or the Set, is the choice. A plugin command asks
+   through `ctx.cache_confirm(line, changed:)` (cost `:full`: its prompt section is in the stable part), with the
+   sender's flag `SessionCommands#run` gives it (`CacheConfirm.asking`), and returns `[text, confirm]`.
 7. **No wall-clock time rendered at wire time.** A history entry's `at` (`MessageTime::KEY`, when it happened) is
    display-only: no wire format reads it, and a guard spec checks that `ChatLoop#wire_messages` and
    `Prompt.format_with_images` give the same bytes with and without it (`spec/message_time_history_spec.rb`). A

data/docs/memory.md

@@ -164,9 +164,23 @@ Working habits for this model:
   longest run without an edit and the Continues and steers each needed; run a
   note on and muted for the same kind of task. See
   [testing.md](testing.md) ("The model notes report").
+- **A note for every model**: `models: *` matches any id, so one note sets a
+  house style for all of them. The model-notes bundle ships one,
+  `model_notes_tone`:
+
+  ```markdown
+  models: *
+  How to write answers:
+  - Answer first, in plain words. Skip preambles, restating the question and closing offers. Use a list only for steps or several parallel items.
+  ```
+
+  It stacks with a family's note. Off for one session: `chi --mute
+  model_notes_tone` (at launch); everywhere: `chi memory rm model_notes_tone
+  --scope system`, or keep your own text under that name (yours wins).
 - **Shipped notes: the model-notes bundle.** `chi bundle install model-notes`
-  (or the `dev` profile) installs reviewed notes into the system scope; for
-  now `model_notes_deepseek` (`models: *deepseek-v4*`). Each note's provenance
+  (or the `dev` profile) installs reviewed notes into the system scope:
+  `model_notes_deepseek` (`models: *deepseek-v4*`) and `model_notes_tone`
+  (`models: *`, concise answers for every model). Each note's provenance
   and evidence is in the bundle's `notes/README.md`, and its spec pins which
   model ids load which note ([Plugins](plugins.md#the-model-notes-bundle)).
   - **Your own note of the same name wins.** The install skips a