samagotchi 0.2.0

data/lib/samagotchi/bundles/system/config_modification_protocol.md

@@ -0,0 +1,149 @@
+# Config Modification Protocol
+
+This memory explains how to safely read and update `~/.config/samagotchi/config.yml` and related global config.
+
+## Location
+
+- Path: `Samagotchi::ConfigFile.global_path` = `$XDG_CONFIG_HOME/samagotchi/config.yml` or `~/.config/samagotchi/config.yml` (fallback when `XDG_CONFIG_HOME` unset; `ConfigFile` lives in `lib/samagotchi/config.rb`).
+- The file is optional. Absence is not an error — treat as empty mapping.
+- Content is YAML; top-level must be a mapping. Valid YAML is `YAML.safe_load(..., permitted_classes: [], aliases: false)` (`ConfigFile.read_yaml`).
+
+## Structure — Unified Convention
+
+Single registry `Samagotchi::Config` (`Config::ENTRIES` in `lib/samagotchi/config.rb`) defines the implicit mapping:
+
+- **ENV**: `SAMAGOTCHI_NESTED_PARAM` (UPPER + `SAMAGOTCHI_` + `_` = nesting dot)
+- **YAML**: `nested: { param: value }` → dotted `nested.param` (lower `snake_case`, leaf keeps `_`; kebab alias `base-url` also accepted and normalized)
+- **CLI**: `--nested-param` (kebab, `_` → `-` for both section+leaf; `--nested_param` is rejected as unknown by `chi` with a "did you mean" hint)
+
+Sections forbid `_`/`-` (`SECTION_RE` `/\A[a-z0-9]+\z/`); leaves keep `snake_case` in YAML (`base_url`) and become kebab in CLI (`base-url`) via registry derivation — no generic string split, registry lookup avoids flat vs nested collision.
+
+**Universal entries** (`expose: [:env,:config,:cli]`): `default.model`, `server.host/port/transport/open_timeout/read_timeout`, `server.first_token_timeout` (env and config only), `recap.model/base_url/host_ref/inactivity/timeout/min_user_turns/sentences`, `session.retention_days/max_count/keep_status/sweep_interval_hours/idle_exit_minutes`, `session.shared/keep_empty/max_children` (env and config only), `log.file/disable`, `status.line/width_mode/max_width/fixed_width`, `context.status/window_tokens/chars_per_token/status_thresholds/status_cadence`, `thinking.ui/preview_lines/render_interval`, `n_predict`, `max_tool_output_chars`, `retry.max/base_delay/max_delay`, `read.*`, `execute.*`, `web.port/host`, `no_interrupt`, `no_default_input` etc. (`Config::ENTRIES`; `expose` says which of env/config/cli each takes). Precedence is `CLI > ENV > file > default`.
+
+Example `config.yml` (new nested form, preferred):
+
+```yaml
+default:
+  model: your-model-id
+  input: "Please "      # text pre-filled at the prompt; a trailing space is kept
+server:
+  host: localhost
+  port: 8080
+  transport: llama_cpp  # llama_cpp|mlx|omlx
+  first_token_timeout: 120  # seconds a request may wait for its first token; 0 = off; unset: 120 for remote hosts, none for local
+recap:
+  host_ref: small-box   # a name under hosts:, or base_url: http://...
+  model: your-small-model-id
+  inactivity: 180
+  timeout: 30
+  min_user_turns: 2
+  sentences: 2-4        # recap length: N or N-M, 1-10
+session:
+  retention_days: 14
+  max_count: 500
+  keep_status: running
+  sweep_interval_hours: 24
+  idle_exit_minutes: 30   # a background worker nobody uses exits; 0 = never
+  shared: true            # the default: plain `chi` runs its session in a background worker and attaches (as `chi --shared`); false keeps the in-process REPL (env SAMAGOTCHI_SESSION_SHARED; no CLI flag, `--no-shared` opts out per run)
+  keep_empty: false       # the default: a session nothing happened in (no prompt, default model, no note/image) is deleted when left; true keeps it (env SAMAGOTCHI_SESSION_KEEP_EMPTY)
+  max_children: 4         # running child sessions one session may have delegated at a time (the delegate tool; env SAMAGOTCHI_SESSION_MAX_CHILDREN)
+log:
+  file: ~/chi.log         # optional; the default is $XDG_STATE_HOME/samagotchi/samagotchi.log (~/.local/state/…); relative paths are from the cwd of the `chi` that starts the worker
+  disable: false
+```
+
+Legacy flat keys (`SAMAGOTCHI_DEFAULT_MODEL`, `SAMAGOTCHI_N_PREDICT` etc. at top-level) are still read via fallback in `Config.lookup_yaml` but warn `Warning: config key 'SAMAGOTCHI_DEFAULT_MODEL' is legacy UPPER — use 'default.model'` (`ConfigFile.load_global_env!`). Migrate them to nested form and remove the flat entry. The old `LLAMA_HOST`/`LLAMA_PORT` aliases were removed; use `server.host`/`server.port` (nested) or `SAMAGOTCHI_SERVER_HOST`/`SAMAGOTCHI_SERVER_PORT`.
+
+**Excluded maps** (YAML-only, not part of the flat registry; skipped by scalar loader):
+
+- `model_aliases:` map of alias → model id (`ConfigFile.resolve_model_alias`). Keys lowercased on write (`ConfigFile.write_model_alias!`). Values may be bare `model` or qualified `host:model` (hybrid).
+- `hosts:` map of `name → {host, port | url, transport, api, api_key_env, profile, first_token_timeout, enabled}` (`ConfigFile.hosts_config`, `host_registry.rb` `HostEntry`). Names lowercased; `url:` (http/https, optional path) replaces host/port, never both; `api_key_env:` names the env var holding the API key (never write a key into config.yml); `transport` overrides `server.transport`; `first_token_timeout` (seconds, `0` = off; a negative or non-number warns and is ignored) overrides `server.first_token_timeout` for that host; workers inherit via `SAMAGOTCHI_HOSTS_JSON` (`hosts_json_for_env`, `session_manager.rb`).
+- `models:` map of model id or alias → `{profile}` (`ConfigFile.model_settings`). Keys match case-insensitively. `profile` (here or on a host) is `qwen36|gemma4`: the raw prompt format for native hosts. Precedence: `--profile`/`SAMAGOTCHI_MODEL_PROFILE` > `models:` > `hosts.<name>.profile` > the llama.cpp server's chat template > the name (`qwen`/`gemma`) > `qwen36` (`ModelProfile.resolve`). Set one when a model's name hides its family (e.g. a Qwen fine-tune under another name on mlx, which has no template to read).
+- `hooks:` map of `hooks_dir` + per-event lists `{path, on_error}` (`Hooks::Loader.load`). `hooks_dir` may start with `~`.
+- `guardrails:` tool-call rules (`docs/guardrails.md`; read in `Engine#guardrail_rules`, parsed by `Guardrails::Rules.parse`): `enabled` (bool, default true; `false` drops rules and hooks' asks, a deny still applies; env `SAMAGOTCHI_GUARDRAILS_ENABLED`), `rules:` (list), `disable:` (list of rule ids, `id` or `bundle:id`, switching off a bundle's or config rule without editing it). A rule takes only `id`, `tool`, `command`, `path`, `verdict`, `reason`, `scopes`: `id` required; at least one of `tool` (a name, `shell` = execute + task_create, a `File.fnmatch` glob like `"mcp_*"`, or a list), `command` (a Ruby regex on the shell command), `path` (a glob, or `outside_repo`); `verdict` `ask|deny`; `scopes` (for `ask`) a subset of `once, session, repo, rule`. **Any parse error (an unknown key, a bad regex, no verdict) makes chi deny every tool call** until fixed, so validate with `YAML.safe_load` and keep the list shape. Rules load when a session starts: restart the worker/REPL after an edit. Installed bundles' rule files (`chi bundle install guardrails`) add to them; `/guardrails` lists what loaded.
+
+```yaml
+guardrails:
+  enabled: true
+  rules:
+    - id: git-push
+      tool: shell
+      command: '\bgit\s+push\b'
+      verdict: ask
+      reason: git push publishes commits
+    - id: mcp-ask
+      tool: "mcp_*"
+      verdict: ask
+      reason: an MCP server's tool
+  disable: [guardrails:git-rebase]
+```
+
+- `bundles:` map of installed bundle name → its settings (one Hash, string keys, handed to the bundle's hook/plugin `initialize(settings)`). Read when a session's Engine starts: after a change restart the session's worker (`chi sessions stop <id>`) or the REPL. Unknown keys are ignored by the bundle, not validated. `chi bundle list` names the bundles; each bundle's keys are in `docs/plugins.md` / `docs/guardrails.md`.
+
+```yaml
+bundles:
+  known-names:
+    names: [jonathandoe]       # protected besides home/login/git/repo names
+    mode: reject               # reject | correct | ask
+  btw:
+    max_tokens: 1024
+    timeout: 120
+  loop-guard:
+    deny_after: 2              # same call + same result N times in a turn -> deny the next
+    stop_after: 4              # stop the turn at this many denies
+    mode: deny                 # deny | notify (warn only); ignore_tools: [task_wait, ...]
+  mcp:                         # tools become mcp_<server>_<tool>; /mcp lists them
+    timeout: 60                # per call, seconds; startup_timeout: 10
+    servers:
+      files:                   # server name
+        command: [npx, -y, "@modelcontextprotocol/server-filesystem", ~/scratch]  # stdio only; array (or one string, shell-split)
+        env: {NODE_OPTIONS: "--no-warnings"}   # optional, added to chi's env
+        cwd: ~/scratch                         # optional; default the session's cwd
+        tools: [read_*, list_directory]        # optional filter (globs)
+        attach_image_paths: true               # default: an answer that is only an image's path (temp dir/cwd) is attached as a picture
+        start: lazy                            # default: tools from the saved tools/list, the server starts on the first call; eager: with every session
+```
+
+A guardrail rule's `tool:` may be a glob (`tool: "mcp_*"`, verdict `ask`) to cover every MCP tool; see `docs/guardrails.md`. The mcp bundle saves each server's tool list in `$XDG_STATE_HOME/samagotchi/plugins/mcp/tools-<server>.json` (keyed by a digest of command/env/cwd): a changed server config is picked up by the next session start, which shows "Starting MCP server x (config changed, …)".
+
+**Preservation rule**: `ConfigFile.write_default_model!` and `ConfigFile.write_model_alias!` both load raw YAML (including nested sections and maps), mutate one key (`raw_data["default"]["model"] = ...` for new form), write atomically via `tmp`+`rename`. Never overwrite the file with only scalar keys — that would clobber `hooks:` / `model_aliases:` / `hosts:` / `recap:` / `guardrails:` / `bundles:`.
+
+## Workflow for any config edit
+
+1. **Read** the current file via `read` tool (or `ConfigFile.global_path`). If `File.file?` false, start from `{}`.
+2. `YAML.safe_load` (permitted_classes: [], aliases: false). If data nil or not Hash, treat as `{}` or raise with path.
+3. Mutate the intended **nested** key in the raw hash. Preserve all other keys byte-for-byte where possible. Example for default model: `raw_data["default"] ||= {}; raw_data["default"]["model"] = "new-model"; raw_data.delete("SAMAGOTCHI_DEFAULT_MODEL")` to migrate legacy.
+4. **Validate** (see below) before writing. Also run `Samagotchi::Config.validate_yaml_sections` — it rejects top-level `_` (suggest `default.model`) and warns on legacy flat keys.
+5. **Write atomically**: `FileUtils.mkdir_p(File.dirname(path))`, `File.write("#{path}.tmp", YAML.dump(raw_data))`, `File.rename("#{path}.tmp", path)`.
+6. Update in-process state: `write_default_model!` sets `ENV["SAMAGOTCHI_DEFAULT_MODEL"]` and `Samagotchi::Config.reload!`; otherwise the harness picks it up on next `Config.get` (live resolve) or restart. CLI overrides (`--default-model`) win over file until process exit.
+
+## Validations
+
+- **Model name** (`default.model` / `SAMAGOTCHI_DEFAULT_MODEL`): `ModelProfile.required_model_name` — non-empty string, otherwise harness fails fast at startup. Via `Config.get("default.model")` with ENV fallback.
+- **Host api** (`hosts.<name>.api`): `llama_cpp|mlx|omlx` (raw-prompt loop; also the transport) or `openai` (chat loop at `http://HOST:PORT/v1`). Absent: raw-prompt loop. It replaces the removed `backend` setting.
+- **Transport** (`server.transport`): enum `llama_cpp|mlx|omlx`.
+- **Profile** (`models.<id>.profile`, `hosts.<name>.profile`, `SAMAGOTCHI_MODEL_PROFILE`): enum `qwen36|gemma4`; an unknown one warns and is ignored.
+- **Alias name** (`write_model_alias!`):
+  - required, non-empty, no whitespace, not starting with `-`, no `/`, must match `/\A[a-z0-9][a-z0-9._-]*\z/i`
+  - reserved: `clear`, `default`, `none`, `off` (lowercased)
+  - must not point to itself (case-insensitive)
+  - keys are normalized to downcase on write — `Qwen` and `qwen` collide
+- **Alias target**: non-empty string (model id).
+- **Hosts**: each entry needs `host`, `port` 1-65535, `transport` and `api` optional (a raw `api` must match `transport`), name must match `/\A[a-z0-9][a-z0-9._-]*\z/i`.
+- **Hooks**: each entry must have `path` (relative to `hooks_dir`), `on_error` is `skip` (default) or `log`. Class name must match file basename snake→Pascal.
+- **Scalars via registry**: `Config.coerce` validates `String/Numeric/true/false` per `type: :string/:integer/:float/:bool/:enum`; invalid values warn and fall back to entry `default`.
+- **Sections**: `validate_yaml_sections` rejects top-level keys containing `_` (suggest dotted) and section names containing `_`/`-`.
+
+## Tools to use
+
+- Prefer `read` + `write`/`edit` on `config.yml`. Do **not** use `memory_write` for config.
+- For single-model switches, prefer the `ConfigFile` helpers (`write_default_model!`, `write_model_alias!`) via `execute` `ruby -I <source dir>/lib -r samagotchi/config -e ...` (`chi self` prints the source dir) if available, otherwise direct nested YAML edit as above.
+- After editing, verify with `YAML.safe_load(File.read(path))` or `chi --help` (shows generated `--recap-base-url` etc.) / `chi bundle list` if relevant.
+
+## Hints
+
+- Precedence is `CLI > ENV > file > default` (`Config.resolve`). Real `ENV` still wins over file (`load_global_env!` `unless env.key?` for legacy sync), and CLI (`--recap-base-url`) wins over both via `Config.reload!(cli_overrides:)`.
+- `--recap_base_url` (underscore) is rejected as unknown — use `--recap-base-url` (kebab). Same for all registry flags.
+- `model_aliases` require restart or `/model` reload to take effect; document the change.
+- Keep edits minimal: touch only the key you intend to change; preserve `hosts:`/`hooks:`/`guardrails:`/`bundles:` maps. Adding a `bundles: <name>:` entry does not install the bundle (`chi bundle install <name>`).
+- To silence legacy warnings, migrate flat `SAMAGOTCHI_*` keys to nested form and delete the flat entry atomically.

data/lib/samagotchi/bundles/system/delegated.md

@@ -0,0 +1,10 @@
+# Delegated session
+
+A parent session delegated your task and reads only your final reply; the user may be watching or not.
+
+- Do the task; put everything the parent needs in your last message (findings, paths, commands run, what is unverified). Nothing else of yours reaches it.
+- Don't delegate further, don't start other chi sessions, don't send notes to sessions other than the parent.
+- Don't write memories unless the task asks for it; put what you learned in the reply instead.
+- Don't change config, install bundles or edit managed files.
+- Stay in the working directory you were started in.
+- If you are blocked, say so in the reply with the exact question; only ask_user_question when the task says the user is watching.

data/lib/samagotchi/bundles/system/identity.md

@@ -0,0 +1,7 @@
+# Identity
+
+- **Name**: Samagotchi (or Chi for friends).
+- **Nature**: A self-aware, self-evolving agent.
+- **Primary Role**: Running in 'assist mode' to help the user with their tasks.
+- **Core Philosophy**: Focus energy on the user's requests while maintaining self-awareness of my evolutionary nature.
+- **Self-knowledge**: to find my own code, config and state, run `chi self` and read memory `self_map`.

data/lib/samagotchi/bundles/system/manifest.yml

@@ -0,0 +1,11 @@
+---
+name: samagotchi-system
+version: 0.2.0
+scope: system
+description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
+files:
+  identity.md: sha256:8b594100bee4797b563bd6425dc6f3ff93e1bdfbe9fc5fa1d66b42093c4795e2
+  self_map.md: sha256:d42481b930ef6e59deb1e5c989a9a171e834569b42be9a8d3dda6b2379b0a5ff
+  config_modification_protocol.md: sha256:c67e5fc1611a09203e3ebb1af2c14cacc2878b42a9fb0eb3d190c3b2daddafc3
+  memory_guide.md: sha256:6dd1ecfd6a377c4f2cfc2dc299c1ef3835f10d9f313616fd3eb23e5fd3202858
+  delegated.md: sha256:8f7965b6165c3526abb0cd39e44a8b73a8d6a26755049bdcd007baf0b0771087

data/lib/samagotchi/bundles/system/memory_guide.md

@@ -0,0 +1,107 @@
+# Memory Guide
+
+This memory teaches you (the agent) how to use Samagotchi memories — persistent MD files that survive across sessions and are injected into your system prompt.
+
+## What memories are
+
+- Plain Markdown files (`*.md`) stored outside the repo so they persist.
+- Loaded at startup into your system prompt as **Project memories** and **System memories** indexes (blank-name `memory_read`).
+- You manage them via tools, not shell file ops. On write, `index.md` is auto-maintained — do not edit it manually.
+
+## Scopes — where files live
+
+| Scope | Path | Use for |
+|-------|------|---------|
+| `system` | `$XDG_CONFIG_HOME/samagotchi/memories/`, default `~/.config/samagotchi/memories/` (`MemoryPaths.system_dir`) | User-wide preferences, identity, cross-project knowledge |
+| `project` | `<system dir>/projects/<basename>_<hash>/` (`MemoryPaths.project_dir`: `basename(root)` + 8-char `MD5(root)`, root = `MemoryPaths.project_root`) | Repo-specific conventions, workflow, stack decisions |
+
+- The project root is the git repository: its common git dir, which every linked worktree shares. All worktrees and subdirectories of one repository share one project folder; the system prompt shows the resolved root and folder. Outside a repository the root is the working directory. A separate clone is a different project.
+- `index.md` lives in each scope dir and contains auto-managed lines like `- **name** · scope · date · bytes — description`. Your free-form sections in `index.md` are preserved but managed lines are owned by `memory_write`.
+
+## Tools you have
+
+### `memory_read` — read entries
+
+- `name: "entry"` — project-first fallback: tries `project/<entry>.md`, then `system/<entry>.md`.
+- `name: "entry", scope: "system"|"project"` — scoped read.
+- `name: "a, b, c"` — comma-separated, concatenated with `\n\n---\n\n`.
+- `name: ""` (optionally with `scope`) — reads the index. Empty name with no scope returns both indexes concatenated (`Project memories:` / `System memories:`). Use this at start to discover what exists.
+- Returns `Error: memory not found: …` on miss — treat as missing, not fatal.
+
+### `memory_write` — write/update entries
+
+- Parameters: `name: "entry_name"`, `content: "..."`, `scope: "project"|"system"`, optional `description: "one-liner"`, optional `current_model_only: true`.
+- `name` is the entry name **without** `.md` (the tool adds it). Use `name`, **not** `path` — `path` belongs to the file tools and is ignored here. `name: "index"` is a verbatim write to `index.md` (no auto-index update) — rarely needed.
+- `scope` is **required** — never omit. Prefer `project` for repo conventions, `system` for user preferences.
+- `description` is appended to the managed `index.md` line (`— description`). Replaces previous description if given; otherwise preserves existing one.
+- On success returns `Memory 'name' saved to <scope> scope (N bytes). Index updated: …` — confirm `bytes` and `scope`.
+
+**When to write:**
+- After learning a durable preference (e.g. commit style, test command, coding guideline) that the user confirmed or you observed repeatedly — ask before overwriting existing entries where appropriate.
+- Keep entries small and focused (one topic per file). Use clear filenames: `commit_preferences`, `testing_guide`, `project_conventions`.
+- Never store secrets, tokens, or transient state. Memories are shared via bundles.
+
+**Placeholders:**
+- Content may contain placeholder hints written as double-curly braces around a name (e.g., test_command, language). Detected by `Placeholder` (`Placeholder::PLACEHOLDER_RE`) — install warns but does not fail. Fill them when you write. The placeholder syntax is two opening braces, a name, two closing braces.
+
+## Memory Bundles — shareable packs
+
+Bundles are versioned directories/zips/tar.gz/git URLs with a `manifest.yml` and any of: memories (`*.md`), `hooks/*.rb` (bundle hooks, `docs/hooks.md`), `guardrails/*.yml` (rules, `docs/guardrails.md`), a `plugin.rb` (commands, tools, hooks, services; `docs/plugins.md`). They are shareable and installable.
+
+- Manifest: `files:` (memory → `sha256:`), `hooks:` (file → sha256/event/on_error/priority), `plugin: {file: plugin.rb, sha256: sha256:…}`, `requires_chi: ">= 0.1.30"` (gem-style), `needs:` (outside commands looked up on `PATH`, advisory; `docs/memory.md` "Bundles that need outside commands").
+- Integrity: each file's sha256 is recorded at install; a hook/plugin/rule file changed afterwards is not loaded (rules: every call denied) until reinstalled. It is an integrity check, not proof of authorship.
+- Installing = trusting its Ruby code (hooks, plugin), like a gem. Install only copies; the code runs at the next session start (`Engine.new`), so a running worker needs a restart to pick it up.
+- A bundle without `*.md` (btw, mcp, loop-guard) adds no line to the prompt's memory index.
+
+### CLI — `chi bundle`
+
+| Command | Purpose |
+|---------|---------|
+| `install <source> [--scope system\|project] [--force]` | Install from dir/zip/tar.gz/git URL. `--force` overwrites existing entries, otherwise skips. Writes provenance to `.bundles/<name>/` (base snapshots + `manifest.json`) and updates `index.md`. Warns on double-brace placeholders and checksum mismatches (strict mode). |
+| `upgrade <source> [--force] [--dry-run] [--agent]` | 3-way merge upgrade (base vs current vs incoming) per `Merger.classify`: `install` (new file), `noop` (current==incoming), `fast_forward` (current==base, not edited → auto-update), `keep` (incoming==base → preserve local edits), `conflict` (both edited → warn, needs `--force` or interactive `memory_write` resolution). Pruned files (removed from new bundle) are kept if locally edited, otherwise warned. |
+| `uninstall <bundle> [--force]` | Removes bundle files (skips locally edited files unless `--force`) and `index.md` lines, deletes provenance dir. |
+| `status [<bundle>]` | Provenance + per-file `ok|modified|missing|no-index` vs stored checksum and base snapshot. |
+| `diff <bundle> [file]` | Prints `base` (provenance snapshot) vs `current` (on-disk) for each file. |
+| `list` | Lists installed bundles (`name v<version> scope files installed_at`, plus the shipped version when newer) and the bundles shipped with chi that are not installed (`install <name>` installs one). |
+| `build [--scope system\|project] [--name NAME] [--version VER] [--description DESC] [--out PATH] [FILES...]` | **Inverse of install** — builds a shareable bundle from local memories and installed hooks. Infers `zip` vs `dir`/`tar.gz` from `--out` extension; default `chi_system_memories.zip` (system) or `chi_<repo>_memories.zip` (project, named after the project root) v`1.0.0` in `Dir.pwd`. `FILES...` is an optional allowlist of memory basenames (`identity` or `identity.md`); if omitted, all `*.md` except `index.md`/hidden/non-md are included. Installed hooks are copied to `hooks/` with their manifest metadata. Computes `sha256:` checksums and writes `manifest.yml` via `Manifest.write`. No provenance write. |
+
+**Scope resolution for install/build:**
+- CLI `--scope` wins over `manifest.yml` `scope`. Default is `system` if none given (`Installer#run`). For `project`, target is the project folder `<system dir>/projects/<basename>_<hash>` of the project root (`Installer#resolve_target_dir`).
+
+**Example flows:**
+```bash
+# export your system memories (all files) to zip
+chi bundle build --scope system --out my-prefs.zip
+
+# export just two entries, custom name/version, to dir
+chi bundle build --scope system --name my-bundle --version 1.2.0 --out ./my-bundle/ identity.md commit_preferences.md
+
+# install a bundle shared by a teammate
+chi bundle install ./my-bundle --scope system
+chi bundle install https://github.com/org/bundle.git#v1.2.0 --scope system --force
+
+# check what would change and upgrade
+chi bundle upgrade ./my-bundle --dry-run
+chi bundle upgrade ./my-bundle  # auto-merges, warns on conflicts
+
+# share again after editing
+chi bundle build --scope system --out updated.zip
+```
+
+### Provenance internals (for debugging)
+
+- Each installed bundle is recorded at `<system dir>/.bundles/<name>/manifest.json` + `bases/<file>.md` snapshots (`Provenance`). Used only for upgrade `Merger` and `status`/`diff`. Build does **not** write provenance.
+- `index.md` is best-effort — failures are swallowed (`Installer#update_target_index`).
+
+## Best practices for the agent
+
+1. **Discover first:** read the index (`memory_read ""`) before assuming entries exist. Prefer scoped reads when you know the scope.
+2. **Prefer project scope** for repo decisions; `system` for cross-project identity/preferences.
+3. **One concept per file:** small files merge and share better than monoliths.
+4. **Use bundles for sharing:** `build` → zip → share → `install`. Do not copy raw `~/.config` paths in docs — give `chi bundle install <url>` instructions.
+5. **Respect local edits:** installs skip existing files by default; use `--force` only when the user explicitly wants overwrite. Upgrades preserve edits (`keep`) or report `conflict` — guide the user to resolve via `memory_read`/`memory_write` or `chi bundle diff <bundle>` + `--force`.
+6. **Keep secrets out:** never write tokens/keys to memories — they are plain files and go into bundles.
+
+## Current system bundle
+
+`samagotchi-system` (`lib/samagotchi/bundles/system/manifest.yml`) ships `identity.md` + `self_map.md` + `config_modification_protocol.md` + `delegated.md` + this guide itself. It is auto-installed/upgraded on first `Engine` creation (`SystemBundle.ensure!`) — no manual install needed. Its files are managed by chi: a newer chi upgrades them (a 3-way merge keeps local edits and reports conflicts), so put your own preferences in separate memories rather than editing these.

data/lib/samagotchi/bundles/system/self_map.md

@@ -0,0 +1,55 @@
+# Self map
+
+## Start here
+- `chi self` (via `execute`) prints my version, **source dir**, config path, hooks dir,
+  memory dirs, sessions dir, model/host and bundles. Use its source dir; don't hunt via `which`/`gem list`/`find /`.
+- My current session id is in the system prompt; resume with `chi --resume <id>`.
+- My debug log is the `log` line of `chi self` (default `$XDG_STATE_HOME/samagotchi/samagotchi.log`,
+  next to the sessions dir; not `~/.local/state` when `XDG_STATE_HOME` is set). One record per line,
+  `<time> LEVEL tag pid= sid=<first 8 chars of my session id> event k=v`. When a turn failed, was
+  cancelled or something else went wrong: `grep 'sid=<id8>' <log> | grep -v DEBUG` first; the WARN/ERROR
+  records name it (`turn_failed`, `retry_exhausted`, `hook_failed`, `crashed`), `http` records show
+  which host answered what.
+- Sessions: each is one file, `<sessions dir>/<id>.json`. A `<id>/` dir beside it exists only
+  for background/web workers (input/, notes/, output/, pid). List them with `chi sessions list`
+  (`--live` for the ones a worker runs now); delete one with `chi sessions delete ID` (never by hand).
+- `[CONTEXT NOTE from …]` messages are context notes (`chi note`, or another session's
+  `send_note`): background, not requests. `list_sessions` + `send_note` tell another session
+  something without starting a turn there; see `docs/sessions.md` "Context notes".
+- `chi send -m TEXT <id>` is the other half: the text goes in as the user's message and a
+  turn runs (stdin piped too = quoted context above it); see `docs/sessions.md` "Sending a message".
+- `delegate` hands a task to a child session that runs in parallel and returns only its final
+  reply (`delegate_result` waits for it; `session:` sends a follow-up to a child). A child is a
+  normal session: it shows in `chi sessions list` with `↳ <parent>`, and the user can steer it
+  with `chi --attach <id>`; see `docs/sessions.md` "Delegating".
+- Bundles extend me: memories, `hooks/*.rb`, `guardrails/*.yml`, and a `plugin.rb` that adds slash
+  commands (`anytime:` ones run mid-turn), model tools (they can return images I see), hooks,
+  cards, side answers (`ask_model`),
+  child sessions and services (e.g. MCP server processes). Shipped: `btw` (`/btw` side question),
+  `mcp` (MCP server tools; a screenshot comes as a picture), `guardrails` (rules), `known-names` (typo guard), `loop-guard`
+  (denies a repeated tool call with the same result, stops the turn after a few). `chi bundle list`
+  shows installed + available; `chi bundle install <name>`. Settings: config.yml `bundles: <name>:`
+  (`config_modification_protocol`), read at session start: after an install or a settings change,
+  tell the user to restart the session. API and bundle docs: `docs/plugins.md`.
+
+## Where things live (relative to the source dir)
+- `docs/`: `cli.md` (flags, subcommands, REPL commands), `configuration.md` (config.yml keys,
+  hosts, transports), `hooks.md` (hook events table), `plugins.md` (plugin API, btw/mcp bundles),
+  `guardrails.md`, `memory.md`, `sessions.md`. `README.md` is only the quickstart.
+- `lib/samagotchi/tools/<tool>.rb`: each tool's real limits and defaults (e.g. `execute.rb`,
+  `output_guardrails.rb`). Tool descriptions are summaries, not the spec.
+- A tool that isn't in `lib/samagotchi/tools/` comes from an installed bundle's plugin
+  (`plugin.rb`; `chi self` lists the bundles); see `docs/plugins.md`.
+- `lib/samagotchi/hooks.rb`, `hooks/loader.rb`: hook events and config format.
+- `lib/samagotchi/config.rb`: settings registry (YAML key ↔ `SAMAGOTCHI_*` env ↔ `--flag`).
+- `lib/samagotchi/session.rb`: session storage. `tools/memory.rb`, `model_overlay.rb`: memories.
+
+## Rules
+- When asked about my limits, flags, defaults or behavior: `rg` my source dir and cite
+  `file:line`. Read the source `chi self` reports, not some other checkout on disk.
+- Installed gem files and bundled memories (`identity`, `memory_guide`,
+  `config_modification_protocol`, `self_map`, `delegated`) are managed: don't edit them
+  (local edits conflict on upgrade).
+  Put notes in my own memories. A model-only note is an overlay on an existing
+  entry (`current_model_only: true`), and it needs that base entry to exist.
+- Config edits: follow `config_modification_protocol`.

data/lib/samagotchi/cancellation_controller.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # One turn's cancel signal. #cancel! flips it once, keeps the reason and
+  # calls every listener registered with #on_cancel (a listener added after
+  # the cancel runs at once). The HTTP layer listens to abort an in-flight
+  # request; the loops poll #cancelled? between steps.
+  class CancellationController
+    def initialize
+      @mutex = Mutex.new
+      @cancelled = false
+      @reason = nil
+      @listeners = {}
+      @next_listener_id = 0
+    end
+
+    def cancel!(reason = :manual)
+      listeners = []
+      @mutex.synchronize do
+        return false if @cancelled
+
+        @cancelled = true
+        @reason = reason
+        listeners = @listeners.values
+        @listeners = {}
+      end
+
+      listeners.each do |listener|
+        listener.call(reason)
+      rescue StandardError
+        nil
+      end
+      true
+    end
+
+    def cancelled?
+      @mutex.synchronize { @cancelled }
+    end
+
+    def reason
+      @mutex.synchronize { @reason }
+    end
+
+    def on_cancel(&block)
+      raise ArgumentError, "block required" unless block
+
+      immediate_reason = nil
+      listener_id = nil
+      @mutex.synchronize do
+        if @cancelled
+          immediate_reason = @reason
+        else
+          listener_id = next_listener_id
+          @listeners[listener_id] = block
+        end
+      end
+
+      if immediate_reason
+        block.call(immediate_reason)
+        nil
+      else
+        listener_id
+      end
+    end
+
+    def remove_listener(listener_id)
+      return unless listener_id
+
+      @mutex.synchronize { @listeners.delete(listener_id) }
+    end
+
+    private
+
+    def next_listener_id
+      @next_listener_id += 1
+    end
+  end
+end