samagotchi 0.141.0 → 0.143.0

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
@@ -117,6 +117,7 @@ end
 
 `bundle.tool_call` runs guarded hooks; `bundle.tool` calls a registered tool. `bundle.steers`, `cards`, `stops` and
 `questions` record effects; `bundle.answer` / `model_answers` provide `ask_user` / `ask_model` answers.
+`bundle.judgments` answers `ctx.judge` and records its asks and runs (each judgment is on in the kit, off in chi until the user sets it);
 `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
@@ -132,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