samagotchi 0.142.0 → 0.144.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a85be5a5307b395bec2801e6ef026217134a6012989388a24dde0068bbc411cf
-  data.tar.gz: a9619ea7ae5b97ce7fa11929468c04f617ec948566a8aeba19d70ffcc0e48bd6
+  metadata.gz: 9e6a9b3aacbab7f8ce2c03c1bf67ba3b37ba647db975b340b6e146ee544de0d4
+  data.tar.gz: 65346bf0d90d4355f7d47e7760d952624cd13b02f2e324ec834649c4a2e12e1d
 SHA512:
-  metadata.gz: 29f21b2213ec66f61cb410ad7f68bedcf76e05f46249f28f56952f83797eb11bd50069484096c2d8f3d5745293446b2c8fc0977f41a709828cfe59beb349cff7
-  data.tar.gz: 63fb61ada67c933d764ec1c5f6a3e692bfd24faee0af91d666ccb32f6b60f17a3ee06494a3713531659229cfeb1d378d2ac38db3709801fefd7dd6e5a5e6e5a5
+  metadata.gz: 536a9cc745170f15f8b52806bc91fa53fc5faa5e0864aa783d8508142ece75626f589fc62974a0883df922671a1543f02cd5c0c8e16d094fd8e8fb3ce94bdd56
+  data.tar.gz: '06086d99f2b967fff766b9b29dbaae5792450276ef655f3822c58d6d1c844f84cb77737c99ef0b1eeec0ea80316533900d491624450379f9b2100b8f01d39584'

data/CHANGELOG.md

@@ -7,6 +7,109 @@ and commands may change between minor versions. How releases are made:
 [docs/releasing.md](docs/releasing.md).
 ## [Unreleased]
 
+## [0.144.0] - 2026-11-02
+
+### Changed
+
+- `chi update`'s re-check of the bundles chi doesn't ship warns about a reference to chi's internals only when this chi
+  no longer has it: the constant doesn't resolve, or the method the name gives isn't there. The row reads
+  `warn boundary plugin.rb: Samagotchi::OldInternal::Thing is gone from this chi, so this bundle may fail`; a name that
+  still works (`Samagotchi::Log`) gets no row, so the table stops repeating warnings about bundles that load fine.
+  `chi bundle check` (the author's own run) stays strict.
+- The web's session bar on a phone no longer swipes: id, status, model and ⚙ stay on the row, and ⋯ opens a bottom sheet with the
+  rest (toolkit, working set, participants, chain links, delegates, the telemetry, Continue, Archive, Stop, Delete). A dot on ⋯ says
+  when something there needs a look. See [docs/cli.md](docs/cli.md#the-session-bar-on-a-phone).
+- chi web uses much less CPU during a turn: about a fifth of a core less on a Mac Studio while a question waits or the model
+  is silent, and less while text streams. The stage's dot and running tick are now a slow opacity blink instead of a pulsing
+  ring, the spinners turn in small steps, and while a question or an approval blocks the turn they stand still, so movement
+  means chi is working. An in-turn card like check-in's keeps its dot blinking, as that turn goes on.
+
+### Fixed
+
+- An event with bytes JSON can't take (a plugin's card, say) no longer ends every stream that reaches it: it goes out scrubbed.
+- A waiting approval on the web page opens at its question and command, on a phone and on a desktop, when it arrives and when the page
+  loads on it. A card too tall for the stage showed its options with what it asks scrolled out of sight; the options are now a scroll
+  down the stage's one scroll.
+- `chi update` tells you a `chi web` started with `--port` runs old code; it only looked on `web.port`.
+- `chi self` finds a `chi web` started with `--port`; it said `not running on port N` for `web.port`.
+- `/guardrails` in chi web or an attached terminal shows all of its listing: a command's reply was cut at 4 KB, so with the core
+  bundle's rules System 1's section never showed and the text stopped mid-word. A reply now goes up to 64 KB, and a longer one ends
+  with a line saying it was cut.
+- A `!` command that prints bytes that aren't valid UTF-8 no longer breaks the session's page and attached terminals: its output
+  stopped every stream that reached it, on each reconnect. The bad bytes show as `?`, as they do in the saved conversation.
+- `/guardrails` no longer shows `System 1 (on):` when the settings mean nothing can be judged: it reads
+  `System 1 (on, but nothing is judged: system_one.host is not set):`, and likewise for a host that isn't in `hosts:`,
+  isn't `api: openai` or names no model.
+- A `bundles:` entry in config.yml for a bundle that isn't installed (or a key it doesn't take) warns once, not in every new session,
+  respawn and delegate; a changed finding warns again, as does one fixed and then back.
+- An answer with a line that opens and closes backticks itself (```` ```foo``` first ````) no longer loses every link after it: the source-links
+  and github-pr bundles and the web's file refs read it as inline code, not as a code block left open.
+- A session whose cost-cap, work-cap or check-in saved nothing no longer leaves an empty folder under `plugins/<bundle>/sessions/`.
+  `ctx.session_dir(create: false)` is the path with no folder made, for a bundle that only reads. `chi update` gets them
+  (cost-cap 0.2.5, work-cap 0.1.5, check-in 0.3.3).
+- A Stop that arrives on an empty reply ends the turn cancelled. It used to end
+  as "no answer: the model returned nothing".
+
+Update with `chi update` (the core profile 0.4.3): check-in 0.3.3, cost-cap 0.2.5 and work-cap 0.1.5 (these three need this chi), github-pr 0.6.2 and source-links 0.6.2.
+
+## [0.143.0] - 2026-11-01
+
+### Added
+
+- `chi update` checks the bundles chi doesn't ship, such as one from GitHub, against the new chi, and adds a row for each warning or error: a `requires_chi` it fails, a plugin or
+  hook that no longer loads, a `ctx` call the API lacks, a reference to chi's internals. It never changes them, and these rows don't fail the update (`--json`: a new `level` field). `--no-bundles` skips
+  it, and `--dry-run` with a newer gem to install says `not checked`, as only that chi could answer. See [docs/cli.md](docs/cli.md#updating).
+- `chi bundle check` warns (`api`) on a `ctx.*` or `chi.*` call, or a keyword, that this chi's API lacks, at its line:
+  `ctx.settingz`, `ctx.sessions.nope`, `ctx.card(titel:)`. It reads the plugin's source, so a path no test runs counts too.
+- `ctx.session_dir`: a session's own folder for a bundle, created on use, removed with the session, so a bundle no longer
+  builds that path itself. cost-cap, work-cap and check-in now keep their state there (`state.json`); a running session's
+  file moves in by itself. `chi update` gets them (cost-cap 0.2.4, work-cap 0.1.4, check-in 0.3.1).
+- A manifest may list `settings:`, the keys config.yml's `bundles: <name>:` takes, with `session_settings:`' types. A key it rules out warns
+  when a session starts, in every UI, and so does a `bundles:` name no installed bundle has. Only a warning: the session goes on.
+  The shipped bundles with settings list theirs (`chi update`).
+- A plugin's `chi.on` handler that raises now tells you, once per event in a worker, in the TUI and the web
+  (`plugins> plugin.rb (bundle x) before_turn hook failed (…)`). Before, only the log knew. The hook is still skipped, and the log
+  still has each failure.
+- A bundle's `hooks/*.rb` file that raises now tells you the same way, once per hook in a worker, whatever its `on_error` —
+  including the default `skip`, which logged nothing at all. A guard bundle that broke (`chi-nah`, say) used to fail quietly;
+  now `plugins> guard.rb (bundle chi-nah) before_tool_call hook failed (…)` says so. `on_error` still decides logging and
+  the deny; the notice is only added, and config.yml's own hooks are unchanged.
+
+### Changed
+
+- With System 1 on the model's own local server, its asks now run during your turn as on any other host: toolkit suggestions (audit, the
+  deferred switch and the worker's warm-up, all skipped there before), context candidates (held to the turn's end before) and bundles' judgments (skipped before).
+  Measured on Splash, they don't push out the session's cached prompt. Each costs the running generation about 0.15 s.
+
+### Removed
+
+- `shared_host:` on `chi.judgment`, the `:shared_host` reason, and `shared_host_busy` in the bundle test kit: a bundle still passing `shared_host:` fails to load, with an
+  `ArgumentError`. check-in 0.3.1 no longer passes it, so run `chi update`.
+
+### Fixed
+
+- `chi sessions delete` now also drops the session's lines from `context_candidates.jsonl` (its `judged` lines keep 200
+  characters of its prompts), as it already purges that session's System 1 runs.
+- A reply that is only a tool call the host could not read is now caught when the block has nothing inside it
+  (`<function=task_list></function>`, `<tool_call>{"name":"x"}</tool_call>`), and its close must be the tag that opened it.
+- A Stop that arrives on a reply that is only a tool call the host could not read ends the turn cancelled. It used to fail
+  it with "the reply came back as a ... block the host could not read, twice in a row".
+- With `update.auto: install`, "chi updated to X" counts the sessions the old chi web restarted (it said 0 of them), and a run
+  chi web is restarted in the middle of still tries the sessions it had left.
+- With `update.auto: install`, an error in one step (a full disk, a hiccup reading the sessions) no longer stops automatic updates until
+  chi web restarts: the step is tried again 5 minutes later.
+- With `update.auto: install` and `update.restart: idle`, sessions that were busy or recently used at the update really are tried again for
+  a day, as documented. They used to stay on the old chi once chi web had restarted. The extra tries respect the idle rule, and the page only hears of one that restarts a session.
+- A hung `chi update` run by chi web (the **Update** button, `update.auto: install`) is stopped after 30 minutes and reported as failed. It used to answer "update running" to every later update until chi web restarted.
+- Web: a hash that names no session (`#/`, or none) while one is open now leaves it, as the **+** button does. It used to change
+  only the URL: the page kept showing that session, and Send went into it.
+- `chi bundle check`'s `requires-chi-floor` knows the calls and keywords it was missing: `ctx.context.propose`, `candidates`, `withdraw` and
+  `left_behind`, `ctx.review?`, `ctx.continues`, `ctx.context.attach(movable:)` and others, so a bundle using them with a lower `requires_chi` is told.
+- `/context attach` and `/context decline`, typed in or from audit or off mode, no longer show a "closed" card when no offer card was open.
+- Web: on a phone, a Revise stub's "superseded by vN" stays readable, so two stubs that open with the same line can be told apart.
+
+Update with `chi update` (the core profile 0.4.2): check-in 0.3.1, cost-cap 0.2.4 and work-cap 0.1.4 keep their state in `ctx.session_dir`, and check-in no longer passes `shared_host:` (the older check-in 0.3.0 fails to load on this chi until it is updated). btw, agents-md, claude-peer, codex-peer, coordinator, github-pr, known-names, loop-guard, mcp, ruby, skills, slow-commands and source-links only list their settings or have small fixes.
+
 ## [0.142.0] - 2026-11-01
 
 ### Added
@@ -1011,7 +1114,7 @@ Update with `chi update` (the system bundle 0.118.0), then restart `chi web`.
 - `/exit` in an attached terminal **asks what to do with what still runs** when only things you can stop keep the
   worker up (reminders, a watched background task, a delegate with a live worker): keep running in the background,
   stop them and exit, or go back. Anything else that holds the worker (a running turn, queued prompts, another UI)
-  still refuses as before, and a delegate never holds the idle exit. See [cli.md](docs/cli.md#attached-terminal).
+  still refuses as before, and a delegate never holds the idle exit. See [cli.md](docs/cli.md#sharing-a-session).
 - The web's `stop session` asks the same first: a sheet (a bottom sheet on a phone) counts what still runs and offers
   **Stop all**, **Stop session only** (the stop as it was: background tasks and delegates keep running) or
   **Cancel**; with nothing to stop it is one tap as before. See [Sessions](docs/sessions.md).
@@ -1650,7 +1753,7 @@ Update with `chi update`.
   and active minutes across turns, the bound a session whose step-limit Continue keeps being answered otherwise
   lacks. At a cap the turn pauses on Continue / Stop, the question naming the session's totals; `/workcap` shows or
   sets it, `chi send --new --set work-cap.tool_calls=400` caps a child. Inert until a cap is set. See
-  [docs/plugins.md](docs/plugins.md#the-work-cap-bundle).
+  [docs/bundles.md](docs/bundles.md#the-work-cap-bundle).
 
 ### Fixed
 
@@ -1786,7 +1889,7 @@ Update with `chi update` (the system bundle 0.95.0), then restart `chi web`.
 - The `model-notes` bundle (0.1.0, in the `dev` profile, now 0.7.0): reviewed model notes, for now
   `model_notes_deepseek` for DeepSeek V4 / V4.1 (`models: *deepseek-v4*`). A same-name note you already have is
   skipped and keeps loading; to take the bundle's, remove yours and install again. See
-  [docs/plugins.md](docs/plugins.md#the-model-notes-bundle).
+  [docs/bundles.md](docs/bundles.md#the-model-notes-bundle).
 
 ### Changed
 
@@ -3610,7 +3713,7 @@ Update with `chi update` (mcp 0.6.1).
   instructions. Guardrail rules on `mcp_<server>_<tool>` names still match (`mcp_call` acts as that tool), and the
   question names `<server>: <tool>`; approvals stored under the old names don't carry over. Hooks and loop-guard's
   `ignore_tools` see `mcp_call`. `/mcp` lists the tools as `<server>/<tool>` and says what every request carries.
-  Needs chi 0.37.0. See [docs/plugins.md](docs/plugins.md#the-mcp-bundle).
+  Needs chi 0.37.0. See [docs/bundles.md](docs/bundles.md#the-mcp-bundle).
 
 ### Fixed
 
@@ -3662,7 +3765,7 @@ Update with `chi update` (mcp 0.5.1).
   rebuild (the split, your decisions, its verdicts, follow-ups), its status in the index description, and resumes
   from it in a new session after checking git and the session list; `/coordinate resume` picks up an open handoff.
   When the work is done it marks the handoff DONE and asks whether to remove it. See
-  [docs/plugins.md](docs/plugins.md#the-coordinator-bundle).
+  [docs/bundles.md](docs/bundles.md#the-coordinator-bundle).
 - The guardrails bundle (0.8.0) asks before every memory removal (`memory-remove`, once at a time). Guardrail rules
   take `memory: remove`.
 - In the web, a file reference in an answer (`lib/foo.rb:28`, `lib/foo.rb:28-34`, in inline code too) links to that
@@ -3671,7 +3774,7 @@ Update with `chi update` (mcp 0.5.1).
   at the PR's head. Display only; `bundles: github-pr: line_links: false` turns it off (github-pr 0.2.0; run
   `chi update`). See [docs/context.md](docs/context.md#line-links).
 - `/mcp` shows roughly how many tokens each MCP server's tool definitions take in every request, and the total
-  (mcp 0.5.0; run `chi update`). See [docs/plugins.md](docs/plugins.md#the-mcp-bundle).
+  (mcp 0.5.0; run `chi update`). See [docs/bundles.md](docs/bundles.md#the-mcp-bundle).
 
 ### Fixed
 
@@ -5423,7 +5526,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.142.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.144.0...HEAD
+[0.144.0]: https://github.com/dm1try/samagotchi/compare/v0.143.0...v0.144.0
+[0.143.0]: https://github.com/dm1try/samagotchi/compare/v0.142.0...v0.143.0
 [0.142.0]: https://github.com/dm1try/samagotchi/compare/v0.141.0...v0.142.0
 [0.141.0]: https://github.com/dm1try/samagotchi/compare/v0.140.0...v0.141.0
 [0.140.0]: https://github.com/dm1try/samagotchi/compare/v0.139.1...v0.140.0

data/README.md

@@ -218,6 +218,7 @@ once, for the session, for the repo, or for the whole rule in the repo.
 - [Guardrails](docs/guardrails.md): allow / ask / deny for tool calls, rules, approvals
 - [Hooks](docs/hooks.md): plugin hooks and bundle hooks
 - [Plugins](docs/plugins.md): bundle plugins (commands, tools, hooks)
+- [Bundles](docs/bundles.md): what each shipped bundle does (btw, mcp, cost-cap, claude-peer, skills…), its commands and settings
 - [Writing a bundle](docs/bundle-authoring.md): `chi bundle new`, `test`, `check`, `try`, `install --dev`
 - [Testing](docs/testing.md): specs, affected specs, lint, worktrees
 - [Architecture](docs/architecture.md): Engine, TerminalUI, bridge, web

data/docs/architecture.md

@@ -365,7 +365,8 @@ The owner's update routes publish progress and results as `chi_update` events wi
 `version` and may include a progress line. The hub retains the latest event for a reconnecting
 tab's snapshot. `POST /api/update` decides itself whether this install can take a gem
 (`UpdateCheck.blocked_reason`: a checkout, Bundler, an unwritable gem dir → 409 `update_blocked`), so
-it holds with `update.notify: off`; a child that prints no rows fails with its own last line, and a
+it holds with `update.notify: off`; a child that prints no rows fails with its own last line, a child still running after
+30 minutes (`UpdateOps::UPDATE_TIMEOUT`; it has a process group of its own) is stopped with what it started and fails the same way, and a
 done install refreshes the hub's installed version (`SessionHub#refresh_installed`) before its `done`.
 Worker restarts target every worker older than the version installed now (refreshed the same way)
 and publish per-session results. Only one of an install, a worker restart pass and a web restart runs
@@ -385,17 +386,23 @@ and installs it through `UpdateOps#install(wait: true, auto: true)` when the ins
 runs, no hub summary has `status: running` or a `pending_question`, and the version isn't in `auto_failed` or
 already in the `auto` record (one automatic try per version). Its frames carry `auto: true` (the page: "Automatic
 chi update in progress", "(automatic)" in the sheet's title). Its record is `update_check.json`'s `auto`:
-`{version, from, at, kept, phase: installed|workers|web|done|failed, workers: {restarted, left}, detail, pushed}`.
+`{version, from, at, kept, phase: installed|workers|web|retrying|done|failed, workers: {restarted, left}, detail, pushed}`,
+in Ruby the value object `Web::AutoUpdateRecord`, which owns that shape (`from_h`, `to_store`).
 With `update.restart: never` the run ends at the install (`chi_notice` `installed`). With `idle` it goes on
-(`phase` `installed` → `workers` → `web` → `done`): `UpdateOps#restart_workers(select:)` over the stale workers whose
+(`phase` `installed` → `workers` → `web` → `retrying` → `done`): `UpdateOps#restart_workers(select:)` over the stale workers whose
 summary is idle with no question and `updated_at` at least 10 minutes old (`QUIET`; the others are `skipped` rows;
-the worker's own atomic refusal still applies), the left ones retried each step for 24 h (`RETRY_FOR`); then, with no
+the worker's own atomic refusal still applies); then, with no
 turn running, `Server.restart_preflight` (the restart's command with `--version`, 20 s, killed on a timeout; it must
 print a chi at least the release) and, if it passes, the record's `phase: web` is written **before**
 `UpdateOps#restart_web`. A failed preflight, or a refused restart, publishes `restart_failed` and ends the run
 (`failed`). `AutoUpdate#stop` waits `STOP_WAIT` (25 s, longer than the preflight's timeout) for its thread, and a
 preflight that ends after a stop leads to nothing (no `web`, no exec): the next start takes the run up again. The restarted chi web's AutoUpdate (first step after 5 s) finds `phase: web`, checks it runs the
-release, counts the workers once more and publishes `updated`, then `done`. Results reach the phone as `chi_notice`
+release, counts the workers once more and publishes `updated`, then `done`, or `retrying` while workers are left. Those are
+retried each step until none is left or 24 h (`RETRY_FOR`) have passed since the install, under the same filter, and from
+whichever chi web is up (`workers` before the restart, `retrying` after it, and a restart mid-retry reads it from the
+record). The time is checked before each pass, so a run always ends. A later pass is `quiet:`: no `chi_update` frames (each
+is a sticky toast) unless a worker restarts, and no further `chi_notice`. `retrying` isn't an open phase for the install
+gate: a newer release installs under its usual gate, and its record replaces this one, its own passes taking the workers over. A step that raises is logged (`auto_update_failed`) and taken again at the next poll; each one saves the record before it publishes, so the owner hears it once. Results reach the phone as `chi_notice`
 hub events (`SessionHub#publish_notice`), see [internals/web-push.md](internals/web-push.md).
 
 The page's scope is in its URL, and the server picks the default: `?dir=<folder>` is that folder's
@@ -602,7 +609,7 @@ A map of the parts the overview above doesn't name (paths under `lib/samagotchi/
 | Bundle authoring | `bundle_command.rb` (`BundleCommand`), `bundle_command/{scaffold,check,test_run}.rb`, `bundle_command/try/{run,sandbox,trace}.rb`, `testing.rb` + `testing/` (the test kit) | `chi bundle new`, `check`, `test` and `try`, and the kit a bundle's tests load it with ([bundle-authoring.md](bundle-authoring.md), [internals/bundles.md](internals/bundles.md)). |
 | Session config (`--set`) | `session_config.rb` (`SessionConfig`, `SessionConfig::Settings`) | A session's own settings as one value (`Session#settings`, `SessionSetup#settings`): `core`, the `--set KEY=VALUE` values of the core keys marked `session: true` (`Config::Entry`), typed by `Config.coerce!` and read first through `Config.get(key, session:)` (`RecapSetup`; `Engine#session=` rebuilds the recap job, `IdleScheduler#replace_job`), file key `config_settings`; `bundles`, the `--set BUNDLE.KEY=VALUE` values, checked against the manifest's `session_settings:`, laid over `bundles: <name>:` in `ctx.settings` ([plugins.md](plugins.md)), file key `bundle_settings`. `SessionConfig.clash` refuses a bundle setting named like a core one (install, `chi bundle check`). See [configuration.md](configuration.md#per-session-settings). |
 | Plugin API | `plugin/api.rb` (`Plugin::Api`), `plugin/tool_spec.rb` (`Plugin::ToolSpec`: a checked tool declaration, how it is registered), `plugin/loader.rb`, `plugin/context.rb` (`ctx`), `plugin/http.rb` + `plugin/http_transport.rb` (`ctx.http`), `plugin/card.rb` (`Plugin::Card`) | What a bundle's plugin registers: tools, commands, annotation actions, hooks, services, toolkits, peer sources; what its handlers get as `ctx` ([plugins.md](plugins.md)). |
-| Peer bundles' base | `plugin/peer.rb` (`Plugin::Peer`) | What claude-peer and codex-peer share (the send tool, the command, the cards, payloads); each bundle's subclass sets its strings and transport ([plugins.md](plugins.md#the-claude-peer-bundle)). |
+| Peer bundles' base | `plugin/peer.rb` (`Plugin::Peer`) | What claude-peer and codex-peer share (the send tool, the command, the cards, payloads); each bundle's subclass sets its strings and transport ([bundles.md](bundles.md#the-claude-peer-bundle)). |
 | Shipped bundles | `bundles/` (`mcp`, `github-pr`, `loop-guard`, `skills`, `source-links`, …) | Bundles that ship with chi. |
 | Hooks | `hooks/registry.rb` (`Hooks::Registry`), `hooks/loader.rb`, `hook_routes.rb` (`HookRoutes`), `event_routes.rb` (`EventRoutes`) | Hook registration and dispatch; what a hook or plugin does beyond reading its event (notice, question, stop, steer) routed to the UIs (cards and notices through one set of routes) ([hooks.md](hooks.md)). |
 | Guardrails | `guardrails.rb`, `guardrails/shell_lex.rb`, `guardrails/data_readers.rb`, `guardrails/rules.rb`, `guardrails/protected_paths.rb`, `guardrails/parent_policy.rb` + `guardrails/parent_approvals.rb`, `guardrail_wiring.rb` | The gate before every tool call: shell lexing (and the commands that only read a heredoc as data), YAML rules, the core checks on chi's own files, approvals, what a parent agent may answer (`guardrails.parent_answers`) ([guardrails.md](guardrails.md)). |

data/docs/bundle-authoring.md

@@ -2,7 +2,7 @@
 
 Read this first when someone asks for new chi functionality "as a bundle". It is the short path: the loop, the
 files, what a hook sees, how to test, and what goes wrong. The full references are in this same `docs/` folder:
-[plugins.md](plugins.md) (the `chi.*` API and `ctx`) and [hooks.md](hooks.md) (every event's fields).
+[plugins.md](plugins.md) (the API), [hooks.md](hooks.md) (event fields), [bundles.md](bundles.md) (shipped bundles).
 
 ## The loop
 
@@ -59,8 +59,8 @@ plugin:
 `plugin.rb` defines `class Plugin` with `register(chi)`; `initialize(settings)` (optional) gets config.yml
 `bundles: my-bundle:` as a Hash with string keys, once, when the plugin loads. A value a session may set
 (`chi --set my-bundle.KEY=V`, listed in the manifest's `session_settings:`, typed with `{KEY: number}` so a
-value of another type is refused) is read from `ctx.settings` at call
-time. `chi bundle check --set KEY=VALUE` gives the sandboxed load a setting.
+value of another type is refused) is read from `ctx.settings` at call time. List what config.yml may set in `settings:`
+(`[greeting]`, or `{greeting: string}`): a typo there then warns. `chi bundle check --set KEY=VALUE` gives the sandboxed load a setting.
 
 ## What a hook sees
 
@@ -89,7 +89,7 @@ Match on `result:`, not `output:`. An execute's result is its `stdout:` and `std
 empty), then `exit: N` (`exit: 0 (no output)` when both were empty); a non-zero exit makes `status:` `"error"`.
 Act through `ctx`: `ctx.notify(text, level: :warn)`, `ctx.steer(text)` (a line the model reads before its next
 step), `ctx.card(…)`, `ctx.stop_turn(reason)`, `ctx.ask_user(…)`, `ctx.data_dir` (the bundle's state folder),
-`ctx.cwd`, `ctx.log`. In a test, each recorded notice, steer or stop names its hook as `"plugin.rb (bundle
+`ctx.session_dir` (this session's, removed with it), `ctx.cwd`, `ctx.log`. In a test, each recorded notice, steer or stop names its hook as `"plugin.rb (bundle
 my-bundle)"`, the plugin's label (a `hooks/x.rb` file's is `"x.rb (bundle my-bundle)"`).
 
 ## Testing it
@@ -121,7 +121,7 @@ end
 `bundle.http.stub` stubs `ctx.http`; `bundle.question_asked(text, question:)` fires `:question_asked` and returns
 the refs; `sandbox.config`, `sandbox.fake_executable` and `bundle.install` cover setup.
 The full list is in [plugins.md, Testing a bundle](plugins.md#testing-a-bundle-experimental). The kit is
-experimental (it may change before chi 1.0). If a test needs a fake of chi's own (a stub of a `Samagotchi::`
+experimental (it may change before chi 1.0). A failing matcher that meets `ENV` prints `#<the process ENV, contents not shown>`, not your keys. If a test needs a fake of chi's own (a stub of a `Samagotchi::`
 class, a hand-built `ctx`), that is a gap in the kit: say so to the user rather than reaching into chi.
 
 ## Pitfalls
@@ -133,14 +133,14 @@ class, a hand-built `ctx`), that is a gap in the kit: say so to the user rather
   newer than the floor (`ctx.http` needs 0.80.0, `ctx.cost` 0.83.0, `ctx.usage` 0.100.0, `ctx.sessions.children` 0.34.0). A keyword added
   later counts too (`ctx.ask_model(model:)` 0.80.0, `ctx.sessions.send(delivery:)` 0.64.0, `chi.toolkit(prompt:)`
   0.72.0, `chi.toolkit(groups:)` 0.121.0), when the call is written on `ctx` / `chi` itself (not through a variable).
+- **A typo in an API call.** `check` warns (`api`) on a call or keyword this chi lacks, on any path; for a newer chi on purpose, guard it with `ctx.respond_to?(:name)`.
 - **trust_level.** Leave it out. `reviewed` / `trusted` are for someone who reviewed the bundle, not its author.
 - **Restart.** A session loads bundles when it starts: after an install or a settings change, the user starts a
   new session (or `chi sessions restart ID`).
 - **chi's internals.** A bundle may use `chi.*`, `ctx` and the names
   [plugins.md, Stable for bundles](plugins.md#stable-for-bundles) lists; any other `Samagotchi::` name may change
   in any release (`check` warns: `boundary`).
-- **Load errors.** A plugin that raises at load is skipped and the session goes on: `check` shows the error at its
-  `plugin.rb:LINE`.
+- **Load errors.** A plugin that raises at load is skipped and the session goes on: `check` shows the error at its `plugin.rb:LINE`.
 
 ## Verifying it live