samagotchi 0.131.0 → 0.133.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37f2a54062786637083ade10186ebb751a1cfd7a7996540defa03da018b29533
-  data.tar.gz: 6836e60f2a87358698adaf000592ac68af5ce8fe8f3c26799825fa26641d3f1a
+  metadata.gz: 8b85b6006a6570eb4145c39cf37ad004a56332b33240353c78d15529d532cd71
+  data.tar.gz: 6c194c4f62179e781a121e1e35eb9f8407795cb6e2b519ffa3ff917d0b6096eb
 SHA512:
-  metadata.gz: b908ad2c276d4dabb1c8bd64ad8435a2f9ab5408663243f8cd0f24e25ca2e4647cb356228a7a37027c1c5f2895936c4df8424af5203d8c121b5403577e2a2456
-  data.tar.gz: a3c96161fc7cb55e200367417e1dac93442845e0a868ad02d58ecca15a504af6824c419e8188252c9100daf405892be203e75fd6d7baaca1406c20186a4ff6f4
+  metadata.gz: 777ad65e1223ba4f99058f5ecdd3d89621af1b1f2f61ff02b21a0760607a92d18d179f9da49dae7c257a07ac107fdcfadd2c0bcf14c8555a25a1570f07c8729e
+  data.tar.gz: e5115ba552ca82ac8a1f6d79f917d50d970bcd7202866a3ac30a15a89541ea94b61ef0a2ff61f0594f996c2a874aa01e7fe1cb3c4cf1551357f017417416c217

data/CHANGELOG.md

@@ -7,10 +7,95 @@ and commands may change between minor versions. How releases are made:
 [docs/releasing.md](docs/releasing.md).
 ## [Unreleased]
 
+## [0.133.0] - 2026-10-30
+
+### Added
+
+- Sessions follow their project: a session's worker reads its folder's `mise env` once at start, and `execute`,
+  tasks, `!cmd`, MCP servers and context sources run in it, getting the project's Ruby (and node, …) whoever started
+  the worker (`session.project_env: mise`, the default; `off` skips mise). chi's own process keeps its
+  env (its keys, proxies and config never come from a project). The starter's GEM_HOME/GEM_PATH are dropped when the
+  Ruby changes. `chi` inside those tools stays the chi home's (a `chi` script in `$XDG_STATE_HOME/samagotchi/bin`). A
+  mise.toml edit needs `chi sessions restart`; a `mise env` that fails (an untrusted mise.toml) changes nothing and
+  logs one `project_env` warning. A session started from a tool for another folder never gets this one's env.
+  `chi self` shows `home` and `project env`. See docs/sessions.md (Project env).
+- Pair turns: their `execute` runs without the project env; a command that runs `mise` or `direnv`, and a write to
+  mise's config (the owner's next worker start runs it), ask the owner; `.envrc` and mise's local files are secrets,
+  as `.env` is.
+- Bundles: mcp 0.7.3 starts its servers in the session's project env.
+- `chi home doctor` checks what should follow the chi home, one row each with `ok`/`warn`/`fail` and the command to
+  run: the chi you ran, the desktop helper's launch file (`chi desktop upgrade`), sessions saved by a newer chi than
+  the home's, the tools' `chi` script, a Gemfile.lock in this project that bundles samagotchi, mise, and the last
+  worker's `project_env` warning in this folder (e.g. `mise trust`). See docs/configuration.md (Checking it).
+- A chi run at a terminal on another Ruby than the chi home's says so in one dim line, at most once a day
+  (`chi X on <ruby>; the chi home is <ruby> (chi Y) (chi home doctor)`).
+- Web start page: a 🧰 beside ⚙ picks the new session's toolkit. **Auto** (the default, nothing sent) leaves the
+  first message to `toolkit.suggest.mode: on`'s suggestion when one can come, else `toolkit.default`; a picked kit is
+  sent (no suggestion then) and shows as a `tools: lean` chip (a dot on a phone). The list holds the built-in and
+  config kits a new session can start on; `GET /api/models` lists them as `toolkits`. A kit Start refuses is said in
+  the list. See docs/configuration.md (Toolkits).
+
+### Changed
+
+- Web start page: thinking, LLM context and review files move into one ⚙ panel beside the model picker (a bottom
+  sheet on a phone): each a row of segments that applies at once, the first one the picked model's own
+  (`default (high)`), the context's apply rule and budget under **Apply and budget ▸**, and **Review files…** as a
+  view of its own. Only what is set shows on the row, as accent chips (`think high`, `ctx stale`,
+  `review: README.md`) that open the panel; on a phone ⚙ carries a dot instead. Still for the next new session
+  only. See docs/configuration.md (A new web chat).
+
+Update with `chi update` (mcp 0.7.3), then restart `chi web` and the session workers (`chi sessions restart`). If
+you use the desktop helper, run `chi desktop upgrade` once; `chi home doctor` says what else to do.
+
+## [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 +5077,9 @@ 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.133.0...HEAD
+[0.133.0]: https://github.com/dm1try/samagotchi/compare/v0.132.0...v0.133.0
+[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

@@ -8,6 +8,14 @@ $LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
 require "samagotchi/utf8_default"
 Samagotchi::Utf8Default.apply!
 
+# A chi a session's tool runs: back to that worker's own env before anything
+# reads config (its API keys and proxies, not the project's mise env), and
+# the workers it starts never take the project's (docs/sessions.md, Project env).
+if ENV.key?("SAMAGOTCHI_PROJECT_ENV_ORIG")
+  require "samagotchi/project_env"
+  Samagotchi::ProjectEnv.take_orig!
+end
+
 require "samagotchi/config"
 
 begin
@@ -27,6 +35,14 @@ if ENV.key?("SAMAGOTCHI_WEB_RESTARTED") || ENV.key?("SAMAGOTCHI_WEB_ADOPT_PIDS")
   web_restarted = Samagotchi::Web::Server.take_restart_env!
 end
 
+# A person's chi at a terminal on another Ruby than the chi home's: one dim
+# line a day saying so (HomeNotice: never in a worker's tools, a script or
+# machine output).
+unless web_restarted
+  require "samagotchi/home_notice"
+  Samagotchi::HomeNotice.show
+end
+
 # `chi self`: print version, source dir, config/memory/session paths, model and
 # bundles (read-only, offline) — lets the agent find its own code and state.
 if ARGV[0] == "self"
@@ -82,7 +98,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,63 @@ 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; it runs under the
+project env below, so a `mise env` that sets GEM_HOME reaches it), `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.
+
+**The tools a worker runs** follow the project, not the boot, and only they do: a spawned worker
+(`WORKER_PROCESS_ENV`; never an in-process loop) calls `ProjectEnv.compute` in `run_session_loop`, after the owner
+lock and before `Worker.new`, and installs the result (`ProjectEnv.install!`; a frozen `ProjectEnv::Overlay`,
+`{key => value or nil}`). Its ENV is never written: chi's own process (LLM calls, `HostKeys`, Net::HTTP proxies,
+Config, Paths, hooks, plugins) keeps the spawner's env. The overlay is the session folder's `mise env -C DIR --json`
+(mise's `__MISE_*`/`MISE_SHELL` unset; the spawner's GEM_HOME/GEM_PATH unset when the first `ruby` on PATH changes,
+unless mise sets them; never `HOME`, `XDG_*`, `SAMAGOTCHI_*`, `CHI_REMOTE`, `RACK_ENV`, `CI`), `ChiShim`'s dir
+(`$XDG_STATE_HOME/samagotchi/bin`, only a `chi` that execs `Record#boot_argv(run: CHI_BOOT)`) first on PATH when there
+is a home, `SAMAGOTCHI_PROJECT_ENV` (`mise:<ruby>` or `none:<reason>`, for `chi self`) and
+`SAMAGOTCHI_PROJECT_ENV_ORIG` (the worker's own value of each key it changes). It is merged into: `execute` and
+`task_create` for the owner's turns (`Builtins.project_env`, less `TaskRuntime::SANITIZED_ENV_KEYS`; never a
+participant's turn), `!cmd` (`SessionCommands#shell`), context sources (`ContextFetch`) and MCP servers (the mcp
+bundle's `server_env`). A worker started from the worker inherits its clean ENV. A `chi` a tool runs (through the shim or not, a fresh
+process with the tools' env) takes the worker's values back from the record in `bin/chi`, before anything reads
+config (`ProjectEnv.take_orig!`): its own API keys and proxies, and the env of any worker it starts, are the
+worker's (`ChildEnv` still drops the record and marker for a child). `restore_env` never returns a reserved key and
+returns `DYLD_*`/`LD_*`/`RUBYOPT`/`RUBYLIB`/`RUBYGEMS_*`/`BUNDLE*` only as unsets. Hooks run in-process, with the
+worker's env. Specs never reach a real mise: `SAMAGOTCHI_MISE_CLI` (only that path when set) points at a missing
+file. User side: [sessions.md](sessions.md#project-env).
+
+**Checking it.** `chi home doctor` (`HomeDoctor`) reads home.json and what should follow it, each condition's text
+from its owner: `ChiHome.problem`, `HomeNotice.mismatch` (also the once-a-day notice `bin/chi` prints at a TTY on
+another Ruby), `Desktop::MacOS#launch_problem` / `#home_problem`, `ChiShim.problem`, `ProjectEnv::NO_MISE` and
+`ProjectEnv.last_warning` (the newest `project_env` / `project_env_applied` record for the folder, from the debug
+log's last 4 MB). Rows: [configuration.md](configuration.md#checking-it-chi-home-doctor).
+
 ## 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 +284,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 and what should follow it, one row each with `ok`, `warn` or `fail` and what to run (exit 1 on a `fail`; see [Checking it](configuration.md#checking-it-chi-home-doctor)). At a terminal, a chi on another Ruby than the home's says so in one dim line a day. 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

@@ -70,6 +70,7 @@ model_aliases:
 session:
   shared: true
   # idle_exit_minutes: 30   # an unused worker exits after this (0 = never)
+  # project_env: mise      # a worker's tools get its folder's `mise env` (off: the starter's env)
   # keep_empty: false       # true keeps sessions nothing happened in (default: deleted when left)
   # max_children: 4         # running sessions one session may have delegated at a time (the delegate tool)
   # delegate_reports: wake  # a child's reply reaches its parent by itself: wake (an idle parent runs a turn), queue, off
@@ -171,7 +172,7 @@ or `chi web` restart.
 | `hooks`, `bundles` | Worker start | Hooks, plugins and their bundle settings load with the engine. |
 | `recap.*` | Worker start | The engine builds its recap job at start, and again when it binds a session with its own `recap.enabled` or `recap.sentences` (`--set`, see "Per-session settings") and when `/recap on\|off\|default` changes the session's own value. |
 | `session.shared` | Next `chi` invocation | It selects attached-worker or in-process mode for that invocation. |
-| `session.idle_exit_minutes`, `session.keep_empty`, `session.max_children`, `session.delegate_reports`, `session.task_wakes`, `session.max_wakes` | Worker start or next matching lifecycle decision | Existing workers keep their idle-exit timer; the other values are read for the next corresponding decision. |
+| `session.idle_exit_minutes`, `session.project_env`, `session.keep_empty`, `session.max_children`, `session.delegate_reports`, `session.task_wakes`, `session.max_wakes` | Worker start or next matching lifecycle decision | Existing workers keep their idle-exit timer and project env; the other values are read for the next corresponding decision. |
 | `session.retention_*`, `session.max_count`, `session.keep_status`, `session.sweep_interval_hours` | Next retention sweep | `chi web` sweeps on its configured schedule and on `GET /api/sessions`; `chi sessions prune` uses the values for that invocation. The sweep interval is checked on the next hub tick. |
 | `web.*` except `web.participants.*` | `chi web` start | Restart `chi web` to change its bind address, port or page settings. |
 | `log.*` | Process start | Each process holds its configured log sink and level after first use; restart that process. |
@@ -655,7 +656,7 @@ models:
     came from);
   - `chi --thinking LEVEL` on a run that starts or resumes a session (the REPL, `-p`, `--resume`, an attached one);
   - `chi send --new --thinking LEVEL`;
-  - the web's `think` chip, in the session bar and on the start page (`POST /api/sessions` takes `"thinking": "low"`;
+  - the web's `think` chip in the session bar, and the start page's ⚙ panel (`POST /api/sessions` takes `"thinking": "low"`;
     anything that isn't a level answers `400 invalid_thinking`).
 - `chi web --thinking LEVEL` is the default for the sessions its workers run, below a session's own. A session started
   with only the env (`SAMAGOTCHI_THINKING_LEVEL=low chi send --new …`) loses the level when a worker without that env
@@ -833,10 +834,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 +854,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 +1353,76 @@ 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) follow the session's project (its
+  `mise env`, [Project env](sessions.md#project-env)), and their `chi` is the home's. 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).
+
+### Checking it: chi home doctor
+
+`chi home doctor` prints one row per check, `ok`, `warn` or `fail`, each with what to run; it exits 1 when a row
+fails (a launch can't boot what it should), 0 otherwise. Run it in a project folder to check that project too.
+
+| Row | When | What to run |
+|---|---|---|
+| the home | `fail`: its Ruby is gone (a Ruby upgrade) or has no samagotchi | `gem install samagotchi` with the new Ruby, then `chi home set` from it |
+| this chi | `warn`: the chi you ran is another Ruby's, or another version, than the home's (`ok` for a source checkout, which starts its own code) | `chi home set` to make this one the home, or run the home's |
+| the desktop helper | `fail`: its launch file's Ruby or chi is gone; `warn`: it runs `[ruby, chi]` (installed before the home), boots the home as it was before a `chi home set`, or sets `GEM_HOME`/`GEM_PATH` | `chi desktop install --force` / `chi desktop upgrade` |
+| sessions | `warn`: sessions last saved by a newer chi than the home's (their workers run without what it added) | `chi update` |
+| the tools' `chi` | `warn`: `$XDG_STATE_HOME/samagotchi/bin/chi` boots another chi than the home | the next worker start rewrites it (`chi sessions restart ID` for a running session) |
+| this project's Gemfile.lock | `warn`: the nearest Gemfile.lock up to the git root bundles samagotchi (`bundle exec chi` isn't supported) | `bundle remove samagotchi` there; run chi itself |
+| mise | `ok` with the mise found; without one, `warn` when `session.project_env: mise` is set explicitly (`ok` for the default) | install mise, or `session.project_env: off` |
+| the last worker here | `warn`: the newest worker record for this folder in the debug log is a `project_env` warning (an untrusted mise.toml, a timeout) | `mise trust` there (or fix what it says), then `chi sessions restart ID` |
+
+The rows after the home's first one need a home that can boot chi; the last three are checked with or without one.
+
+**The notice.** An installed chi run by a person at a terminal (stdin and stderr TTYs) on another Ruby, or another
+version, than the home's prints one dim line on stderr, at most once a day: `chi 0.131.0 on /x/bin/ruby; the chi home
+is /y/bin/ruby (chi 0.132.0) (chi home doctor)`. Never inside a session's tools, for `--json`, `--format json`,
+`--non-interactive`, `--version`, `--help`, `chi home`, `chi update` or `chi self`, from a source checkout, or in a
+test run (`SAMAGOTCHI_ENV`, `RACK_ENV`, `CI`). The day is stamped in `$XDG_STATE_HOME/samagotchi/home_noticed`.
+
 ## Project specific description
 
 If an AGENTS.md file is present in the project root, samagotchi injects its
@@ -1498,6 +1574,18 @@ toolkit:
   `full`. A continue and a fork keep the toolkit name. `/toolkit` shows and changes it. The kit's tools, prompt
   text and group selectors are part of its definition, not the session file: edits reach a saved name at its next
   worker start.
+- **A new web chat: 🧰.** The start page's 🧰 (beside ⚙; a bottom sheet on a phone) picks the new session's toolkit.
+  **Auto**, checked by default, sends nothing: the session is on `toolkit.default` with `toolkit_origin: default`, so
+  with `toolkit.suggest.mode: on` its first message may switch it to a suggested kit. Auto is listed only when that
+  can happen as far as chi web can tell (on mode, a `guardrails.system_one.host`, two described config kits); bundle
+  and memory kits can add candidates it doesn't see. A kit picked is sent as `POST /api/sessions`'s `toolkit` and
+  saved as `chosen`: no suggestion, the default kit included (its row says `default`); without Auto, the default's
+  row is the one checked and sends nothing. The list holds the built-ins and config kits a new session can start
+  on: not `review`, `child` or a kit named `undecided`, not a kit whose `groups:` refuses a new session, and not one
+  that doesn't resolve in chi web (a base that is a bundle kit); bundle and memory kits load in the worker, so pick
+  them with `/toolkit`. The configured default is always listed. A pick closes the list and shows a `tools: lean`
+  chip on the row (a dot on 🧰 on a phone); it is for that create only, never remembered. A review session is
+  always `chosen`: with review files set the list says it starts on the default unless you pick a kit.
 - **Left out: reachable or removed.** A built-in missing from a kit's base list (`lean` has no `delegate`; a
   `kits:` entry on `base: lean` or `child` inherits that) is left out softly: it is **reachable**. `find_tools` searches it as group `chi` (`chi/delegate`, with its inputSchema) beside
   the MCP servers' tools, and `call_tool(tool: "chi/delegate", args: {…})` runs it as `delegate` itself, through the
@@ -1617,14 +1705,18 @@ its own). The first target is a long session such as a day-long coordinator, whe
 - **Set it** at start with `chi --llm-context stale,forget --llm-context-apply turn_end --llm-context-budget 64k`
   (the same flags on `chi send --new`), in the session with `/llm-context strategy … apply … budget …`
   (docs/cli.md, "Session commands"), or from the web's `llm ctx` chip in the info bar.
-- **A new web chat:** the start page's `llm ctx` chip, beside the model picker, shows the picked model's values
-  and follows a model pick. Its form (titled "new session") sets a choice for that one chat: the chip reads
-  `llm ctx stale · new session` in the accent colour, and the create sends it as `POST /api/sessions`'s
-  `llm_context` (`{"strategy": "stale,forget", "apply": "turn_end", "budget": "64k"}`, each a word as
-  `/llm-context` takes it, `default` for unset; anything else answers `400 invalid_llm_context` and starts
-  nothing), so the session file holds it before the first turn runs. It is not remembered: it resets after a
-  create, on a reload and when you open a session (a failed create keeps it), and an untouched chip sends nothing
-  (the model's values apply, as without the chip).
+- **A new web chat:** the start page's ⚙ panel (beside the model picker; a bottom sheet on a phone) holds the new
+  session's rarely used settings, each a row of segments that applies at once: **Thinking** and **Context** (the
+  strategy; **Apply and budget ▸** opens the other two fields, with their own Set), the first segment following the
+  picked model (`default (high)`), and **Review files…** (docs/sessions.md, Review sessions). A row the picked model
+  has no values for is hidden. What is set shows on the row as an accent chip (`think high`, `ctx stale`,
+  `review: README.md`) that opens the panel; on a phone ⚙ carries a dot and its label names them. The create sends
+  the context choice as `POST /api/sessions`'s `llm_context` (`{"strategy": "stale,forget", "apply": "turn_end",
+  "budget": "64k"}`, each a word as `/llm-context` takes it, `default` for unset; anything else answers
+  `400 invalid_llm_context` and starts nothing), so the session file holds it before the first turn runs. Nothing
+  is remembered: the choices reset after a create, on a reload and when you open a session (a failed create keeps
+  them); a choice made before picking a model without that row stays (its chip says it is sent anyway), and nothing
+  set sends nothing (the model's values apply).
 - **Values:** `none` and a budget of `off` are values the session sets on purpose (they win over the model's);
   `default` (or `/llm-context reset` for all three) unsets one, back to following the model. A budget is 4k to
   10M tokens (`4000`–`10000000`, or `4k`–`10000k`). The layers are kept in chi's order (`stale`, then `forget`).
@@ -1641,6 +1733,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
@@ -1986,6 +2084,7 @@ column says so, a `--kebab-name` flag. The maps (`hosts:`, `models:`,
 | `broadcast.threshold` | `0.5` | | The P(yes) a recipient needs, when the triage host gives logprobs; a plain yes or no is 1 or 0. |
 | `session.shared` | `true` | | Plain `chi` runs its session in a worker and attaches; `--no-shared` per run. |
 | `session.idle_exit_minutes` | `30` | yes | An unused worker exits after this; `0` = never. |
+| `session.project_env` | `mise` | | The commands a session's worker runs follow its project: `mise` runs them in the session folder's `mise env`, read once at worker start (`chi sessions restart` picks up a mise.toml edit); `off` doesn't ask mise: the tools keep the env of whoever started the worker (with a chi home, the home's `chi` still goes first on their PATH). See [Project env](sessions.md#project-env). |
 | `session.keep_empty` | `false` | | Keep sessions nothing happened in. |
 | `session.max_children` | `4` | | Running delegated sessions one session may have. |
 | `session.delegate_reports` | `wake` | | When a delegate child ends a turn, its reply reaches the parent: `wake` runs an idle parent's turn for it, `queue` waits for the parent's next turn, `off` leaves it to `delegate_result`. |

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,20 @@ 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). `chi home doctor` flags a helper that isn't on the home: a
+  `[ruby, chi]` argv, a boot of the home as it was before a `chi home set`, or `GEM_HOME`/`GEM_PATH` in its env;
 - `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`);