samagotchi 0.3.0 → 0.5.0

data/docs/desktop.md

@@ -1,6 +1,7 @@
 # Desktop helper (macOS)
 
-`chi desktop` installs **Chi Helper**, a small native app. It sends text you selected in any app to a chi session,
+`chi desktop` installs **Chi Helper**, a small native app. It sends text you selected in any app (or a screenshot,
+an image: see [Images](#images)) to a chi session,
 either with a question as [your message](sessions.md#sending-a-message) (a turn runs, and the answer shows in the
 attached terminal or web page), or as a [context note](sessions.md#context-notes) (the model sees it on its next
 turn, and no turn starts).
@@ -35,6 +36,32 @@ note needs a session. After the send the panel shows `started <id>…` for 3 s.
 
 A session open in a `chi --no-shared` REPL isn't listed: it takes no notes or messages.
 
+## Images
+
+The panel also sends images, as attachments of the message (`chi send --image`, see
+[Sending a message](sessions.md#sending-a-message)):
+
+- **A screenshot:** ⌃⇧⌘4 (a region to the clipboard), then ⌃⌥⌘N. The panel shows it as a thumbnail, named
+  `clipboard.png`; the context box stays empty.
+- **Finder:** right-click image files → Services → **Send to chi** (the same Service as for text, so its shortcut
+  works here too), or ⌘C on them and ⌃⌥⌘N. Up to 20 at once.
+- **Other apps:** a picture selected in Preview, Safari's Copy Image, anything that puts image data on the clipboard.
+- **Drop** image files or the floating screenshot thumbnail (⇧⌘4 to a file) anywhere on the open panel: they are
+  added to the ones there.
+
+When the clipboard holds both text and a picture (cells copied in Numbers or Excel), the text wins, as before. The
+thumbnails sit under the message line, 48 px high, the file name as a tooltip; hover one for its ✕.
+
+- A message is required with images: the line says "Say something about the image…", and ⏎ does nothing until
+  there is text (the context box counts).
+- Notes are text only: ⌘⏎ with images beeps and says "Notes are text only: ⏎ sends the image as a message".
+- The session's model must see images. A text-only one fails the turn in the session (the attached terminal or the
+  web shows why); the panel has already said it was sent.
+- A session busy with a turn runs the image message as its next turn: the line says `(runs after the current turn)`.
+- Clipboard and dropped image data goes to temp files under `$TMPDIR/chi-helper`, deleted after the send or when
+  the panel closes; files from Finder are sent as they are, never touched. A send with images may take up to 30 s
+  (converting, a worker starting) before the panel gives up.
+
 ## Install
 
 ```sh
@@ -53,16 +80,22 @@ 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.
 
+`chi update` keeps it current: it rebuilds and restarts the helper only when its Swift sources changed since the
+build (`launch.json` records their digest) or the Ruby it runs moved. A new chi that left the sources alone only
+rewrites `launch.json`, which the app reads at each send, so the app keeps its older version number and that's fine.
+
 ## Commands
 
 | Command | Does |
 |---|---|
 | `chi desktop install [--force] [--login]` | builds, installs and starts it; `--force` replaces an existing copy |
-| `chi desktop upgrade` | rebuilds it for this chi and restarts it, keeping the login setting |
+| `chi desktop upgrade` | rebuilds it for this chi and restarts it, keeping the login setting (always; `chi update` does it only when needed) |
 | `chi desktop uninstall` | quits it and removes the app, its login item, launch file and settings |
 | `chi desktop status` | version against chi's, how it runs chi, state dirs, Service, hotkey, process, login item |
 
-`chi self` has a `desktop` line: `0.1.x (matches)`, `0.1.w (chi is 0.1.x: chi desktop upgrade)` or `not installed`.
+`chi self` has a `desktop` line: `0.1.x (matches)`, `0.1.w (up to date for chi 0.1.x)` (an older build whose sources
+haven't changed), `0.1.w (chi is 0.1.x: chi update)` (a rebuild is due) or `not installed`. `chi desktop status`
+says the same.
 
 ## How it runs chi
 
@@ -92,7 +125,7 @@ Each call is stopped after 10 s. A stopped `chi note` says the note may be partl
 ## Troubleshooting
 
 - **"chi not found at …, run `chi desktop upgrade`"**: the Ruby or checkout in `launch.json` moved (a Ruby upgrade,
-  a removed worktree). Run `chi desktop upgrade` from the chi you use now.
+  a removed worktree). Run `chi desktop upgrade` (or `chi update`) from the chi you use now.
 - **No "Send to chi" in the Services menu:** check `chi desktop status` (service). Try
   `/System/Library/CoreServices/pbs -update`, start the app again, or log out and back in. It must be ticked in
   System Settings → Keyboard → Keyboard Shortcuts… → Services → Text.
@@ -100,4 +133,6 @@ Each call is stopped after 10 s. A stopped `chi note` says the note may be partl
   restarts or you log out: macOS caches Services.
 - **⌃⌥⌘N does nothing:** `status` says whether another app holds it. macOS doesn't report clashes with its own
   shortcuts.
+- **"Send to chi" missing on images in Finder or Preview** after an upgrade: the Services cache still has the old
+  (text-only) entry; `/System/Library/CoreServices/pbs -update`, restart the helper, or log out and back in.
 - **"No live sessions":** start one with `chi` in a terminal; `chi sessions list --live --scope=all` shows the same list.

data/docs/guardrails.md

@@ -38,6 +38,17 @@ once it closes. On a short terminal the list shrinks (the hint row, then the `in
 lines, then the header go, then the options fold onto fewer rows). Once answered, one
 line stays in the scrollback: `! execute: git push origin main → Allow once`.
 
+An `edit` or `write` also shows the change it would make, computed without
+touching the file: a `change: +3 −1` line in the question (`new file, 12 lines`;
+`would fail: old text not found in …` when the edit can't apply), and the
+unified diff itself. The web card shows the diff under the path (20 lines,
+then "show all"); the terminals print it above the question, green and red,
+40 lines at most (the rest is on the web). Binary files and files over 1 MB
+say so instead of a diff. After the call runs, its row shows what really
+changed: `diff +3 −1` under the row on the web (closed, it survives a
+reload) and ` +3 −1` at the end of the terminal's tool line. The model never
+sees these diffs.
+
 Who answers:
 
 - REPL (`chi --no-shared`, `-p` without `--non-interactive`): at the `? ` prompt.

data/docs/hooks.md

@@ -351,7 +351,7 @@ Notes:
 - Ordering: bundle hooks fire by `(priority, bundle_name, hook_name)` (lower priority first), then plain `config.yml` hooks in registration order.
 - Settings: a hook class with `initialize(settings = {})` gets the bundle's section of `config.yml` `bundles:` (see [Settings](#settings)).
 - A bundle can also ship a `plugin.rb` whose `chi.on(event)` blocks are bundle hooks too, next to commands and tools; see [Plugins](plugins.md).
-- Shipped bundles: `chi bundle install guardrails` (rules, see [Guardrails](guardrails.md#the-guardrails-bundle)) and `chi bundle install known-names` (a hook, see [Guardrails](guardrails.md#the-known-names-bundle)), `chi bundle install source-links` (a hook: announces source refs, see [The source-links bundle](#the-source-links-bundle)), `chi bundle install btw` (a plugin: `/btw`, see [Plugins](plugins.md#the-btw-bundle)), `chi bundle install mcp` (a plugin: tools from MCP servers, see [Plugins](plugins.md#the-mcp-bundle)) `chi bundle install loop-guard` (a plugin: breaks tool-call loops, see [Plugins](plugins.md#the-loop-guard-bundle)) and `chi bundle install check-in` (a plugin: checks on a long turn, see [Plugins](plugins.md#the-check-in-bundle)).
+- Shipped bundles: `chi bundle install guardrails` (rules, see [Guardrails](guardrails.md#the-guardrails-bundle)) and `chi bundle install known-names` (a hook, see [Guardrails](guardrails.md#the-known-names-bundle)), `chi bundle install source-links` (a hook: announces source refs, see [The source-links bundle](#the-source-links-bundle)), `chi bundle install btw` (a plugin: `/btw`, see [Plugins](plugins.md#the-btw-bundle)), `chi bundle install mcp` (a plugin: tools from MCP servers, see [Plugins](plugins.md#the-mcp-bundle)) `chi bundle install loop-guard` (a plugin: breaks tool-call loops, see [Plugins](plugins.md#the-loop-guard-bundle)), `chi bundle install check-in` (a plugin: checks on a long turn, see [Plugins](plugins.md#the-check-in-bundle)) and `chi bundle install skills` (a plugin: `/skill`, versions of skills, see [Plugins](plugins.md#the-skills-bundle)).
 - Installing a bundle executes its hook code at `Engine` startup. Only install bundles you trust, as you would a gem. Hooks are **not** executed at install time (copy-only); they are `module_eval`'d at `Engine.new` inside per-bundle `Samagotchi::Bundles::<name>` namespaces (no top-level `require` collisions). Keep hook files side-effect-free at load time; do work in `#call` — top-level side effects (require, IO, `at_exit`, global assignment) run once per `Engine.new` (class redefinition is idempotent).
 
 Lifecycle:
@@ -386,9 +386,11 @@ in a markdown link's label when the target names the same ref
 and `[fix for JIRA-123](https://github.com/o/r/pull/9)` still link. A ref
 glued to URL punctuation (`/browse/JIRA-1`, `?key=JIRA-1`, `JIRA-1/foo`) is
 skipped too; `Ticket:JIRA-5` and `#JIRA-123` are ordinary plain text and do
-link. Refs are deduped within the turn (case-insensitively) and listed in
-first-occurrence order, whatever order the sources are configured in. With no
-sources configured the hook is a silent no-op.
+link. The line names each URL once (compared case-insensitively: `#12` and
+`dm1try/samagotchi#12` may be one issue, and with `case_insensitive: true`
+`JIRA-1` and `jira-1` are one ticket), in first-occurrence order, whatever
+order the sources are configured in. With no sources configured the hook is a
+silent no-op.
 
 ```yaml
 bundles:
@@ -417,9 +419,8 @@ keeps the web links.
 
 The `prefix:` form compiles to `\b<prefix>-(\d+)\b` and the URL is
 `base_url` + the full ref text (`JIRA-123`). The `pattern:` form takes a
-regex; `{match}` in `url` is replaced with the first capture group (or the
-full match when the pattern has none). `case_insensitive: true` adds the
-`/i` flag. Past `max` refs the line ends with `… +N more`.
+regex and a `url:` template with placeholders (below). `case_insensitive:
+true` adds the `/i` flag. Past `max` refs the line ends with `… +N more`.
 
 Each regex is compiled with a per-regex timeout (0.5 s, per match attempt),
 so a catastrophic pattern is abandoned instead of hanging the turn: that
@@ -428,3 +429,84 @@ and the others still report. An entry with neither `prefix:` nor `pattern:`,
 or a pattern that does not compile, is skipped with a warning at load. The
 hook is `on_error: log`: a bug in it warns and the turn is unaffected. As with
 every bundle hook, a running worker picks it up after its next start.
+
+### Placeholders, and the project's own repo
+
+A `url:` template (the `pattern:` form only; `base_url:` is always
+`base_url` + the ref) can use:
+
+| placeholder | value | when it can't be filled |
+|---|---|---|
+| `{match}` | the first capture group, else the whole ref | never: it falls back to the ref |
+| `{1}` … `{9}` | a numbered capture group | the group didn't take part: the ref is **not linked** |
+| `{name}` | a named capture group `(?<name>…)` | the group didn't take part: **not linked** |
+| `{repo}`, `{host}` | the named group `repo` / `host` when the pattern has one and it took part; else the project's git remote | neither: **not linked** |
+
+A ref with a placeholder that can't be filled is left out of both the line
+and the answer: no URL is built with a hole in it (another source on the same
+ref can still link it). A `{word}` or `{N}` that is none of the above (not a
+group of the pattern, or `{7}` in a two-group pattern) stays as literal text,
+with one warning when the source is loaded. Every value is percent-encoded
+(everything outside `A-Za-z0-9-._~`, `/` included), except that `{repo}`
+keeps its `/` between segments (GitLab's `group/sub/proj`); a `{repo}` with an
+empty, `.` or `..` segment counts as unfilled.
+
+So one source links both `#12` in this project and a cross-repo ref:
+
+```yaml
+bundles:
+  source-links:
+    sources:
+      - name: GitHub
+        # `#12` → this project's repo; `owner/repo#12` → that repo
+        pattern: '(?<![\w/&])(?:(?<repo>[A-Za-z0-9][\w-]*/[\w.-]*\w))?#(?<num>\d+)\b'
+        url: 'https://github.com/{repo}/issues/{num}'
+        remote_host: github.com
+```
+
+```
+sources: GitHub #12 → https://github.com/dm1try/samagotchi/issues/12, GitHub rails/rails#5 → https://github.com/rails/rails/issues/5
+```
+
+GitHub redirects `/issues/N` to `/pull/N` and back, so one URL covers issues
+and pull requests. The lookbehind keeps `&#123;`, `x/#1` and a partial
+`b/c#1` inside `a/b/c#1` out; code and URLs are skipped as always. `PR #12`
+links, `PR#12` doesn't (a `#` right after a letter). The pattern is loose on
+purpose: a bare `#\d+` also matches "step #2", and `and/or#5` or `TCP/IP#3`
+read as qualified refs. A stricter variant wants `PR #`, `issue #` or a
+qualified ref:
+
+```yaml
+        pattern: '(?<![\w/&])(?:(?<repo>[A-Za-z0-9][\w-]*/[\w.-]*\w)#|\b(?:PR|[Ii]ssue) #)(?<num>\d+)\b'
+```
+
+**Where `{repo}` and `{host}` come from.** Without a named group that took
+part, they come from `git remote get-url <remote>` run in the session's
+working directory (the worker's; the in-process REPL's is the terminal's
+current directory). `remote:` picks the remote, default `origin` — a fork
+sets `remote: upstream`. Git applies `insteadOf` rewrites and includes, and a
+worktree reports its main repo's remote. The URL forms understood are
+`https://`, `http://`, `ssh://`, `git://` (credentials and port dropped) and
+scp-like `[user@]host:owner/repo`; the repo is the path without a trailing
+`.git` or `/`. A local path, `file://`, no git, no repo or no such remote
+leaves the ref unlinked, silently (a debug log line only). Git is asked only
+when a hit needs it — a JIRA source or a qualified ref never runs it — and
+the answer, even "none", is remembered for the worker's life: a remote
+changed mid-session counts after the worker's next start.
+
+`remote_host:` (a host or a list, compared case-insensitively) applies the
+remote-derived links only when the remote's host is one of them, so a
+`https://github.com/{repo}/…` template never points a GitLab project's `#12`
+at github.com. A qualified ref is linked whatever the local remote is. An SSH
+alias (`git@github-work:o/r.git` from a multi-account `~/.ssh/config`) or an
+`insteadOf` mirror reports its own host; list it too:
+`remote_host: [github.com, github-work]`.
+
+Two Ruby regex notes. With named groups in a pattern, a plain `(…)` doesn't
+capture and gets no number, so `{1}` is the first *named* group, and so is
+`{match}` (in the example above `{match}` is the repo part): use either named
+or numbered groups in one pattern, and named placeholders with named groups.
+And a pattern with a `host` (or `repo`) group lets the model's text choose the
+link's domain (or repo): the escaping rules out URL injection, but the choice
+of the target is the model's.
+

data/docs/memory.md

@@ -34,6 +34,46 @@ names of a comma list are read). Its file and index line are untouched.
 These startup index reads are harness-injected context assembly and are not
 rendered as `tool>` activity lines.
 
+## Skills
+
+A **skill** is a memory named `skill_<name>` that holds the steps of a
+repeatable task you and chi did together: a release, a deploy, a data fix.
+chi is told about skills by the system bundle (`identity.md`, every turn, and
+`memory_guide.md`), so this works without installing anything:
+
+- **Saving.** Say "let's memorize this" or "save this as a skill" after the
+  task, and chi writes the skill with `memory_write` (project scope; system
+  when you ask, or when it isn't about this project) and shows it. On a vague
+  one ("I like how we did that") it may ask first.
+- **Following.** The skill's index line (the `description:` of its
+  `memory_write`, "Release a new version of this repo: …") is in every
+  prompt, so next time chi reads the skill and follows it.
+- **Updating.** When a step turned out different (a renamed script, an extra
+  step), chi fixes the skill in the same turn: those steps changed, the rest
+  kept, a dated Changelog line added. No confirmation.
+
+A skill is plain Markdown, no frontmatter:
+
+```markdown
+# Skill: release
+
+## Steps
+1. Run `scripts/verify.sh`; stop if it fails.
+2. …
+## Gotchas
+- …
+## Changelog
+- 2026-09-29 created
+- 2026-09-30 step 1: check.sh was renamed to verify.sh
+```
+
+It is a memory like any other: `memory_read`, `chi --mute skill_release`,
+`chi bundle build` share it. The optional `skills` bundle (`chi bundle install
+skills`, [docs/plugins.md](plugins.md#the-skills-bundle)) adds `/skill save`,
+`/skill list`, `/skill show`, `/skill diff`, keeps older versions with a
+one-line diff after each update, and nudges a model that skips a failing
+step instead of fixing the skill.
+
 ## Bundles that need outside commands
 
 A bundle's memory can rely on a command chi doesn't ship, such as a GitHub

data/docs/plugins.md

@@ -814,6 +814,56 @@ with a line and carry on unchanged.
 | `/checkin mode ask` / `nudge` / `notify` | the mode |
 | `/checkin nudge` / `later` / `stop` | the card's actions, also by hand |
 
+## The skills bundle
+
+`chi bundle install skills` installs the bundle shipped with chi
+(`lib/samagotchi/bundles/skills/plugin.rb`): one anytime command, `chi.on`
+hooks, `ctx.sessions.send`, `ctx.notify` and `event[:steer]`. It has no memory
+file; skills themselves work without it ([docs/memory.md](memory.md#skills)).
+
+| | |
+|---|---|
+| `/skill save [name] [--system]` | sends this session a request to save what was just done as `skill_<name>` (chi picks a name when none is given), project scope unless `--system`. The request holds the skill's shape, so the result is the same with a model that never read the memory guide. It runs as a turn; sent while a turn runs, it joins that turn at its next step (the request says to finish the task first). An existing skill is updated. In a `--no-shared` REPL, which takes no messages, the command shows the request to send yourself |
+| `/skill list` | the `skill_*` memories of both scopes, with the date and description from the index |
+| `/skill show <name>` | one skill as saved (project first, as `memory_read` looks) |
+| `/skill diff <name> [N]` | the skill now against its N-th newest older version (default 1: before the last change), unified |
+
+**History.** Before `memory_write`, `write` or `edit` changes a
+`skill_<name>.md` in a memories folder, the file as it was is kept under
+`$XDG_STATE_HOME/samagotchi/plugins/skills/history/<scope>/<name>/` (`system`,
+or `project-<project folder>`), the newest `history_keep`. It is state, not a
+memory: `chi bundle build` and a synced `~/.config` never see it. After the
+call a line says what happened:
+
+```
+skills> skill release saved (project, 14 lines)
+skills> skill release updated (+2 −1): 1. Run `scripts/verify.sh`; stop if it fails. · /skill diff release
+```
+
+The line is the file on disk changing, whatever the tool answered; a denied
+write shows nothing.
+
+**The nudge** (`nudge: true`). Some models, finding a skill's step broken,
+skip it and go on without fixing the skill. In a turn that read a skill
+(`memory_read` of a `skill_*` name, or `read` of its file), the first failing
+tool call after it (an `execute` that exited non-zero, a tool error) steers
+the model once: *"A step of skill release failed. Find out why before skipping
+it; if the skill is out of date, fix it now: memory_write the whole skill,
+its title and every section as they were, that step fixed, a Changelog line
+added."* If the turn ends with a failed step and the
+skill not rewritten, one line says so: `skill release was followed, a step
+failed, the skill wasn't updated`. A failure unrelated to the skill (a test
+meant to fail) can set it off too: once per turn, and only after a skill was
+read.
+
+```yaml
+# config.yml
+bundles:
+  skills:
+    history_keep: 20   # older versions kept per skill
+    nudge: true        # steer once when a followed skill's step fails
+```
+
 ## Shutdown
 
 When the REPL exits, or a session's worker exits (an idle exit, `/exit`, a

data/docs/releasing.md

@@ -12,16 +12,16 @@ can run the whole release; the user approves the notes before the tag and the
   and `lib/samagotchi/bundles/system/manifest.yml` are bumped together (a spec
   and `rake release:check` enforce it). The system bundle upgrades itself when
   chi starts.
-- **Every other shipped bundle** (btw, guardrails, known-names, loop-guard,
-  mcp) has its own semver in its `manifest.yml` and, when it needs a newer chi,
-  a `requires_chi:` line. They never upgrade by themselves: users run
-  `chi bundle upgrade NAME`. So:
+- **Every other shipped bundle** (btw, check-in, guardrails, known-names,
+  loop-guard, mcp, skills, source-links) has its own semver in its
+  `manifest.yml` and, when it needs a newer chi, a `requires_chi:` line. They never upgrade by themselves: users run
+  `chi update` (all of them, with the gem) or `chi bundle upgrade NAME`. So:
   - a change to a bundle's files bumps that bundle's `version:`
     (`rake bundles:check` fails otherwise, once there's a tag to compare with);
   - a bundle that uses something new in chi raises its `requires_chi` in the
     same change; `release:bump` never touches `requires_chi`;
-  - the release notes list the `chi bundle upgrade NAME` steps for every
-    bundle whose version moved.
+  - the release notes say "run `chi update`" and name the bundles whose
+    version moved (what changed in each), not per-bundle upgrade steps.
 - Pre-1.0: config and commands may change in a minor version (0.2 → 0.3); a
   patch version (0.2.0 → 0.2.1) is fixes only.
 
@@ -58,9 +58,9 @@ The agent does each step and stops where the user has to say yes.
 1. **Start from main, up to date and green.** `git checkout main && git pull`;
    CI on main is green.
 2. **Draft the notes.** `bundle exec rake release:draft_changelog`, then edit
-   `## [Unreleased]` in CHANGELOG.md into short user-facing lines. Add the
-   `chi bundle upgrade NAME` steps for bundles whose version moved since the
-   last tag (`git diff vPREV -- lib/samagotchi/bundles/*/manifest.yml`).
+   `## [Unreleased]` in CHANGELOG.md into short user-facing lines. End with
+   "Update with `chi update`", naming the bundles whose version moved since
+   the last tag (`git diff vPREV -- lib/samagotchi/bundles/*/manifest.yml`).
    Pick the version: fixes only → patch, anything else → minor.
 3. **The user approves the notes and the version.** Show them the section.
 4. **Bump.** `bundle exec rake "release:bump[X.Y.Z]"`, review `git diff`.
@@ -130,9 +130,12 @@ next patch version.
 The suite runs the same on Linux CI as on macOS, with no CI-only skips. A few
 things differ there, and a new spec that trips on them fails only on CI:
 
-- `CI` set marks every new session a test run, and `--all`, `list_sessions`
-  and friends leave test runs out. A spec that lists sessions makes them with
-  `test_run: false`.
+- `CI` set marks every new session a test run, and `list_sessions` and
+  friends leave test runs out. A spec that lists sessions makes them with
+  `test_run: false`. `chi sessions list --live`/`--cwd`/`--format` and
+  `chi note --all` show test runs when they run as one (`CI` set counts): a
+  spec checking that they are hidden unsets `CI` or stubs
+  `Session.test_session_env?`.
 - The gems live under `vendor/bundle`: a child `ruby` started with a bare env
   (`unsetenv_others: true`) needs `GEM_HOME`/`GEM_PATH` to find nokogiri.
 - Ruby 3.3's zlib raises `Zlib::BufError` when a thread interrupt lands in a

data/docs/sessions.md

@@ -56,7 +56,22 @@ chi sessions clean --dry-run --days 7            # test sessions older than 7 da
 
 **Projects:** a session belongs to the git project it was started in: the repository, whichever worktree or subfolder of it (the same project root memories use). `chi sessions list` (with `--live` and `--format` too) and `chi web` show the current folder's project; `--scope=all` shows every session, and so does a folder in no repo (`~`). `--cwd PATH` is a folder filter instead of the project. The project is stored with the session (`project_root` in its JSON, `project` in `--format json`), so a session keeps it after its worktree is deleted; sessions older than that are placed by their folder, and one whose folder is gone shows in `--scope=all` only. Retention, `--resume`/`--attach ID`, `chi send`/`chi note ID` and `chi note --all` (every live session) are not scoped. The agent's `list_sessions` lists its own project's sessions; `cwd: "/"` lists every one.
 
-`--live`, `--cwd` and `--format` make `list` a picker for scripts (`SessionManager.session_summaries`): `--live` keeps the sessions a worker runs now (the owner lock, not the saved status; a session open in a plain REPL is left out), `--cwd PATH` those in PATH or below, and test runs are left out. `--live` shows 10 unless `--limit` says otherwise; filters apply before the limit. `--format json` prints `[{id, short_id, desc, cwd, project, updated_at, live, busy, owner, recap, parent_id, archived, scratch, ctx_pct}]` (`owner`: `"worker"`, `"tui"` for a plain REPL, which takes no notes or messages, or null; `recap`: the first sentence of the session's recap, or null), `--format tsv` one `id<TAB>desc` line per session, where `desc` is `<folder> · <last prompt>` cut to 60 characters (the text form of `--live`/`--cwd` shows `<folder> · <recap>` when there is one; tsv and json keep `desc`).
+`--live`, `--cwd` and `--format` make `list` a picker for scripts (`SessionManager.session_summaries`): `--live` keeps the sessions a worker runs now (the owner lock, not the saved status; a session open in a plain REPL is left out), `--cwd PATH` those in PATH or below, and test runs are left out unless the list is itself run as one (`SAMAGOTCHI_ENV=test`, `RACK_ENV=test` or `CI` set: then they show, marked `[test]`; `chi note --all` likewise). `--live` shows 10 unless `--limit` says otherwise; filters apply before the limit. `--format json` prints `[{id, short_id, desc, cwd, project, updated_at, live, busy, owner, recap, parent_id, archived, scratch, ctx_pct}]` (`owner`: `"worker"`, `"tui"` for a plain REPL, which takes no notes or messages, or null; `recap`: the first sentence of the session's recap, or null), `--format tsv` one `id<TAB>desc` line per session, where `desc` is `<folder> · <last prompt>` cut to 60 characters (the text form of `--live`/`--cwd` shows `<folder> · <recap>` when there is one; tsv and json keep `desc`).
+
+**Ordering:**
+
+- `Session.list` / `SessionManager.list_sessions` / `GET /api/sessions?sort=&order=&limit=&offset=` default to `updated_at desc` (newest activity first). Also supports `created_at`, `asc`. `X-Total-Count` header when paginated.
+- Web UI (`chi web`): the page's scope is in its URL. Started in a git repo, `chi web` opens `/?dir=<that folder>`: that project's sessions, and new chats start in that folder; the header chip says `<project> · all`, and `all` opens the same place without `?dir` (every session; a new chat there starts in the server's own folder, shown on the start page, and cards name their folder; `← <project>` goes back to the project view it came from, or to the server's own project). One server serves every project: a second `chi web` (from another repo) finds it through `GET /api/info` and prints (with `--open`, opens) its page for its own folder instead of starting another. The 3 latest sessions sit above the chat; "All sessions" (or `/`) opens every session at `#/sessions`, with a search over preview, id and status (Esc or Back returns). The open session is in the URL (`#/s/<id>`), so a reload or a copied link opens it again; the chi logo top left goes back to the empty start for a new chat. The message box grows with its text; drag its top edge to keep it taller (double-click resets). The info bar copies `chi --attach <id>` for a terminal. The start page's model picker (bottom left of the composer, the chosen name `▾`) chooses the model a new chat starts on; it opens a search list over the conversation (↓ or a click; downward when the start page leaves no room above): an empty search shows the last 5 picks (Recent) and then each host's model ids A–Z under the host, the default host first; typed words must each match the host or the id (a substring, else for 3+ characters the letters in order, so `deepseek4.1 fla` finds `openrouter · deepseek/deepseek-v4.1-flash`), ⏎ picks, Esc/Tab close, a pick puts the focus in the message box: `GET /api/models` lists the hosts' models as chi spells them (`{default, models: [{name, host, id}], warning?}`; bare for the default host, `host:model` for the others, from the same cached lists as `/models`, a bounded wait, a host that is down noted in `warning`), and `POST /api/sessions` takes `model` (blank means the default). The start page's first message goes as later ones do: `POST /api/sessions` with `idle: true` and `preview` (the message, which names the session until its turn is saved), then `POST /api/sessions/:id/turn`, so a failed first turn puts its prompt back in the composer too; a first command line (`/model …`) still starts the session as its `prompt`. The browser remembers the last choice; a running session's model is in the info bar and changes only with `/model`.
+- Web notifications: when a session needs you while the tab is hidden or behind another window (a question or a guardrail approval, a plugin card with buttons during a turn such as check-in's, a failed turn, a turn done after 10 s or more; a delegated session only for its questions, a canceled turn never), the page title counts it, `(N) Chi`, until you come back to the tab. The bell at the right of the top bar also turns on OS notifications ("needs an answer", "needs approval", "needs you", "turn failed", "done in 42 s", under the session's first message; a click opens the session): its first click asks the browser for the permission, and the choice is kept per browser. Any session of the page's scope counts, not only the open one. What was already so when the page loaded never counts, and several chi tabs show one notification per event. A chi tab in front tells the others (a `BroadcastChannel`), so while you look at one, the ones behind neither notify nor count what it shows; coming back to a tab clears those events in the other tabs' titles too. The hub's `session` frames carry what this needs: `pending_question` (`{id, kind}`, kind `question` or `approval`), `pending_card` (`{id, bundle}`: the running turn's card with actions, from `pending_card.json` that the worker keeps in the session's folder while one is open; a card without actions, such as loop-guard's, never counts) and `last_turn` (`{outcome, ended_at, seconds, origin}`, saved in the session's JSON as the engine ends each turn).
+- The web frontend is a zero-build ES-module stack in `lib/samagotchi/web/public/`: `data.js` (retrieval, typed SSE `openStream` for a session and `openEvents` for the session list), `sessions_list.js` (the list as a pure reducer over `GET /api/events`: a snapshot replaces it, an upsert keeps a known card in place, a removal drops it), `notify.js` (which of those events needs the user, for the notifications), `app.js` (presentation/state; a session with no live stream gets one when its `session` event says `bridge_up`, after one re-read: `event_seq` starts over in each worker, so a dropped stream is never resumed with its old cursor), `format.js` (pure formatters such as `previewOf`). Unit-tested via `npm test` (`node --test spec/web/public/*.test.js`).
+- Selecting a session in the web UI is read-only: `GET /api/sessions/:id` never spawns a worker (it reads a live worker's snapshot when one runs, else the session file). A prompt (`POST /turn`) or a command (`POST /command`) wakes the worker, and `/stream` briefly waits for a freshly-spawned bridge before answering. A caught-up SSE reconnect holds the stream open; `reset` markers are only sent for reconnects behind the ring window, or with a cursor from another worker (event ids are `<event_seq>-<epoch>`, one epoch per worker).
+
+**Test-session hygiene:**
+
+- New sessions set `test_run:true` when `SAMAGOTCHI_ENV=test` or `RACK_ENV=test` or `CI` is set (explicit flag, `metadata_version` 2). Old sessions without the flag load as `test_run:false`.
+- Test runs are tagged and obey the same retention. `chi sessions clean` deletes every test session whatever its age (`--days N`: only those older than N days); a live worker or a `keep_status` status still keeps one. `chi sessions prune --test-only` applies the usual age and count rules to test sessions only.
+- A `chi scratch` session (`"scratch": true`) is deleted when its REPL ends; one a killed process left behind is deleted by the next sweep, `prune` or `clean`, whatever its age or status, once nobody owns it. `list` shows it as `[scratch]` (every text form; `scratch: true` in `--format json`); `chi web` never shows one. See [CLI: Scratch sessions](cli.md#scratch-sessions).
+- For ad-hoc manual QA use `SAMAGOTCHI_ENV=test XDG_STATE_HOME=/tmp/chi-test-$USER chi ...` to isolate from real state; the flag also marks sessions that `chi web` or an attached `chi` spawn (their workers inherit the environment), so `clean` finds them if they land in the real state.
 
 ## Context notes
 
@@ -120,8 +135,9 @@ cancel during its thinking, it said it had never been asked.
 `chi send` is the other half of `chi note`: the text goes in as your message, the same as typing it in the attached terminal or the web composer, so a turn runs.
 
 ```sh
-chi send [-m TEXT] (ID|PREFIX)...
+chi send [-m TEXT] [--image PATH]... (ID|PREFIX)...
 chi send -m "is this the same bug?" 3fa2           # a message
+chi send --image shot.png -m "why is this red?" 3fa2  # with an image
 pbpaste | chi send -m "is this the same bug?" 3fa2  # the clipboard quoted above the message
 pbpaste | chi send 3fa2                             # the clipboard is the message
 ```
@@ -130,7 +146,8 @@ pbpaste | chi send 3fa2                             # the clipboard is the messa
 - It goes through the same path as the web composer (`SessionManager.deliver_turn`): the worker's Bridge when it is up, so every attached UI shows it as your message (client id `cli:send`, shown like any user message); the input file when the worker is on its way out. During a running turn it is merged into that turn at the next step, like a message typed then.
 - A session with no worker gets one started (like `--attach` or the web composer). A session open in a plain REPL (`--no-shared`) refuses it. Only sessions on this machine: Bridges listen on 127.0.0.1.
 - Fire and forget: it returns once the message is queued and never prints the answer; that shows in whatever is attached. A guardrail "ask" waits for a UI to answer it, so with nothing attached the turn stalls there until one attaches (`chi --attach ID`).
-- One line per session: `sent`, `sent (the running turn picks it up)`, `sent (started its worker)`, `refused: …` or `failed: …`. Exit 0 when all were sent, 1 when any was refused, failed or not found, 2 for a usage error. There is no `--all`.
+- `--image PATH` (repeatable, up to 20) sends images with the message, as the web composer's chips do. Each file is read once before anything is sent (bmp, tiff and heic converted to png, large ones downscaled, as for `@path`); a missing file or one that isn't an image is a usage error (exit 2) and nothing is sent. Each session gets its own copy in `<session>/images/`. Text is still required (`-m` or stdin; context alone counts), also with `--wait`. The session's model must see images: one known not to (the host's model list says text-only, `vision: false` in `models:` or `hosts:`, a native llama.cpp without a vision model) is refused before anything is sent, with the reason (`<id>  refused: gemma can't take images (…); send text only or switch the model (/model)`); the other sessions of the same send still get it, and the exit is 1. With `--new` nothing is started. When chi can't tell (a native host whose `/props` doesn't answer, a list that doesn't say), the message is sent as before and a text-only model fails the turn in the session. A running turn doesn't take images mid-turn: the message runs as the next turn, and the line says `(runs after the current turn)`. With `--new` the session starts idle with the message as its preview, then the message goes in as its first turn once its worker is up (`<id>  started with 1 image`); if the worker doesn't come up in 5 s the session is kept, with its id on the `failed:` line.
+- One line per session: `sent`, `sent with 2 images`, `sent (the running turn picks it up)`, `sent (started its worker)`, `refused: …` or `failed: …`. Exit 0 when all were sent, 1 when any was refused, failed or not found, 2 for a usage error. There is no `--all`.
 
 The Automator action above works for messages too: swap its last line for `pbpaste | "$chi" send -m "what do you make of this?" $(print -r -- "$picked" | cut -f1)`.
 
@@ -164,18 +181,3 @@ The `delegate` tool hands a task to a **child session**: an ordinary chi session
 - Every child starts with the shipped `delegated` system memory preloaded (`preloaded_memory_names: ["system/delegated"]`; `--mute delegated` would hide it): put everything in the final reply, don't delegate further, don't write memories or change config, stay in the folder. Its system prompt also says `Delegated by session <parent id>`. The parent's own `--mute` list does not carry over.
 - Limits: a child cannot `delegate` (depth 1; the tool refuses), and one session may have at most `session.max_children` (default `4`, env `SAMAGOTCHI_SESSION_MAX_CHILDREN`) children running at a time, counted from the session files (a finished or idle-exited child does not count; one whose worker is still starting does, for 15 s). A refused call creates no session. Nothing stops children with the parent: `chi sessions stop ID` does.
 - The link is the session's `parent_id`, written before the worker starts, so a respawn keeps it; `GET /api/sessions` and `/api/sessions/:id` carry it, and `SessionManager.children_of` lists a parent's children.
-
-**Ordering:**
-
-- `Session.list` / `SessionManager.list_sessions` / `GET /api/sessions?sort=&order=&limit=&offset=` default to `updated_at desc` (newest activity first). Also supports `created_at`, `asc`. `X-Total-Count` header when paginated.
-- Web UI (`chi web`): the page's scope is in its URL. Started in a git repo, `chi web` opens `/?dir=<that folder>`: that project's sessions, and new chats start in that folder; the header chip says `<project> · all`, and `all` opens the same place without `?dir` (every session; a new chat there starts in the server's own folder, shown on the start page, and cards name their folder; `← <project>` goes back to the project view it came from, or to the server's own project). One server serves every project: a second `chi web` (from another repo) finds it through `GET /api/info` and prints (with `--open`, opens) its page for its own folder instead of starting another. The 3 latest sessions sit above the chat; "All sessions" (or `/`) opens every session at `#/sessions`, with a search over preview, id and status (Esc or Back returns). The open session is in the URL (`#/s/<id>`), so a reload or a copied link opens it again; the chi logo top left goes back to the empty start for a new chat. The message box grows with its text; drag its top edge to keep it taller (double-click resets). The info bar copies `chi --attach <id>` for a terminal. The start page's model picker (bottom left of the composer, `host:model ▾`) chooses the model a new chat starts on: `GET /api/models` lists the hosts' models as chi spells them (`{default, models: [{name, host, id}], warning?}`; bare for the default host, `host:model` for the others, from the same cached lists as `/models`, a bounded wait, a host that is down noted in `warning`), and `POST /api/sessions` takes `model` (blank means the default). The start page's first message goes as later ones do: `POST /api/sessions` with `idle: true` and `preview` (the message, which names the session until its turn is saved), then `POST /api/sessions/:id/turn`, so a failed first turn puts its prompt back in the composer too; a first command line (`/model …`) still starts the session as its `prompt`. The browser remembers the last choice; a running session's model is in the info bar and changes only with `/model`.
-- Web notifications: when a session needs you while the tab is hidden or behind another window (a question or a guardrail approval, a plugin card with buttons during a turn such as check-in's, a failed turn, a turn done after 10 s or more; a delegated session only for its questions, a canceled turn never), the page title counts it, `(N) Chi`, until you come back to the tab. The bell at the right of the top bar also turns on OS notifications ("needs an answer", "needs approval", "needs you", "turn failed", "done in 42 s", under the session's first message; a click opens the session): its first click asks the browser for the permission, and the choice is kept per browser. Any session of the page's scope counts, not only the open one. What was already so when the page loaded never counts, and several chi tabs show one notification per event. A chi tab in front tells the others (a `BroadcastChannel`), so while you look at one, the ones behind neither notify nor count what it shows; coming back to a tab clears those events in the other tabs' titles too. The hub's `session` frames carry what this needs: `pending_question` (`{id, kind}`, kind `question` or `approval`), `pending_card` (`{id, bundle}`: the running turn's card with actions, from `pending_card.json` that the worker keeps in the session's folder while one is open; a card without actions, such as loop-guard's, never counts) and `last_turn` (`{outcome, ended_at, seconds, origin}`, saved in the session's JSON as the engine ends each turn).
-- The web frontend is a zero-build ES-module stack in `lib/samagotchi/web/public/`: `data.js` (retrieval, typed SSE `openStream` for a session and `openEvents` for the session list), `sessions_list.js` (the list as a pure reducer over `GET /api/events`: a snapshot replaces it, an upsert keeps a known card in place, a removal drops it), `notify.js` (which of those events needs the user, for the notifications), `app.js` (presentation/state; a session with no live stream gets one when its `session` event says `bridge_up`, after one re-read: `event_seq` starts over in each worker, so a dropped stream is never resumed with its old cursor), `format.js` (pure formatters such as `previewOf`). Unit-tested via `npm test` (`node --test spec/web/public/*.test.js`).
-- Selecting a session in the web UI is read-only: `GET /api/sessions/:id` never spawns a worker (it reads a live worker's snapshot when one runs, else the session file). A prompt (`POST /turn`) or a command (`POST /command`) wakes the worker, and `/stream` briefly waits for a freshly-spawned bridge before answering. A caught-up SSE reconnect holds the stream open; `reset` markers are only sent for reconnects behind the ring window, or with a cursor from another worker (event ids are `<event_seq>-<epoch>`, one epoch per worker).
-
-**Test-session hygiene:**
-
-- New sessions set `test_run:true` when `SAMAGOTCHI_ENV=test` or `RACK_ENV=test` or `CI` is set (explicit flag, `metadata_version` 2). Old sessions without the flag load as `test_run:false`.
-- Test runs are tagged and obey the same retention. `chi sessions clean` deletes every test session whatever its age (`--days N`: only those older than N days); a live worker or a `keep_status` status still keeps one. `chi sessions prune --test-only` applies the usual age and count rules to test sessions only.
-- A `chi scratch` session (`"scratch": true`) is deleted when its REPL ends; one a killed process left behind is deleted by the next sweep, `prune` or `clean`, whatever its age or status, once nobody owns it. `list` shows it as `[scratch]` (every text form; `scratch: true` in `--format json`); `chi web` never shows one. See [CLI: Scratch sessions](cli.md#scratch-sessions).
-- For ad-hoc manual QA use `SAMAGOTCHI_ENV=test XDG_STATE_HOME=/tmp/chi-test-$USER chi ...` to isolate from real state; the flag also marks sessions that `chi web` or an attached `chi` spawn (their workers inherit the environment), so `clean` finds them if they land in the real state.

data/lib/samagotchi/bootstrap/config_writer.rb

@@ -243,14 +243,13 @@ module Samagotchi
 
         section = data["default"]
         value = section.is_a?(Hash) ? section["model"] : nil
-        value ||= data[ConfigFile::DEFAULT_MODEL_KEY]
         value.to_s.strip.empty? ? nil : value.to_s.strip
       end
 
       # Whether bare model names go somewhere today: a default.model or a
       # server: section. Then a new hosts: block keeps that route as `default`.
       def routed?
-        configured_default_model || data.key?("server") || data.keys.any? { |key| key.to_s.start_with?("SAMAGOTCHI_SERVER_") }
+        configured_default_model || data.key?("server")
       end
 
       # The `default` hosts entry chi derives from server.* when the file has

data/lib/samagotchi/bridge/sse_writer.rb

@@ -187,9 +187,6 @@ module Samagotchi
           "Cache-Control: no-cache\r\n" \
           "Connection: keep-alive\r\n" \
           "X-Accel-Buffering: no\r\n" \
-          "Access-Control-Allow-Origin: *\r\n" \
-          "Access-Control-Allow-Methods: GET, POST, OPTIONS\r\n" \
-          "Access-Control-Allow-Headers: Content-Type, Last-Event-ID\r\n" \
           "\r\n"
         )
         io.flush

data/lib/samagotchi/bridge/turn_accumulator.rb

@@ -146,6 +146,7 @@ module Samagotchi
           part = { kind: "tool", iteration: event[:iteration], call_index: event[:call_index],
                    tool: event[:tool], params: event[:params], status: "running" }
           part[:label] = event[:label] if event[:label]
+          part[:title] = event[:title] if event[:title]
           parts << part
         when :tool_call_completed
           tool = parts.reverse_each.find do |part|
@@ -159,6 +160,7 @@ module Samagotchi
           tool[:output] = capped ? output[0, @max_output_chars] : output.dup
           tool[:output_truncated] = capped || !!event[:output_truncated]
           tool[:images] = event[:images] if event[:images]
+          tool[:diff] = event[:diff] if event[:diff]
         when :pending_input_merged
           # A steer-only merge (count 0) has no user part: the origins stay
           # for the user lines' own merge.

data/lib/samagotchi/bridge.rb

@@ -19,6 +19,7 @@ require_relative "engine"
 require_relative "session_commands"
 require_relative "image_store"
 require_relative "log"
+require_relative "version"
 
 module Samagotchi
   # Bridge is an optional HTTP transport that lets an external web / desktop
@@ -304,8 +305,8 @@ module Samagotchi
         if request[:too_large]
           write_json(io, 413, { "Connection" => "close" }, { error: "too_large", detail: "request body over #{MAX_BODY_BYTES} bytes" })
           break
-        elsif method == "OPTIONS"
-          write_json(io, 204, cors, {})
+        elsif browser_request?(headers)
+          write_json(io, 403, nil, { error: "cross_origin", detail: "the bridge answers chi's own clients only" })
         elsif (m = stream_match(request[:path])) && method == "GET"
           cursor = reconnect_cursor(headers, request[:query])
           Log.debug(:bridge, "stream", method: method, path: request[:path], client_id: stream_client_id(request[:query]))
@@ -343,7 +344,7 @@ module Samagotchi
           payload, status, body = handle_snapshot(m[1])
           write_json(io, status, payload, body)
         else
-          write_json(io, 404, { "Allow" => "GET, POST, OPTIONS" },
+          write_json(io, 404, { "Allow" => "GET, POST" },
                      { error: "not_found", path: request[:path] })
         end
 
@@ -413,12 +414,18 @@ module Samagotchi
       Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
 
-    def cors
-      {
-        "Access-Control-Allow-Origin" => "*",
-        "Access-Control-Allow-Methods" => "GET, POST, OPTIONS",
-        "Access-Control-Allow-Headers" => "Content-Type, Last-Event-ID"
-      }
+    LOOPBACK_NAMES = %w[127.0.0.1 [::1] localhost].freeze
+
+    # Only chi's Ruby clients talk to the Bridge, and they send no Origin and
+    # no Sec-Fetch-Site. A browser page always sends one of them (another
+    # website's text/plain POST needs no preflight), and a DNS-rebound page
+    # also has a foreign Host. Headers are the raw ones, lowercased.
+    def browser_request?(headers)
+      return true if headers.key?("origin")
+      return true if headers.key?("sec-fetch-site") && headers["sec-fetch-site"].downcase != "none"
+
+      host = headers["host"].to_s
+      !host.empty? && !LOOPBACK_NAMES.include?(host.downcase.sub(/:\d*\z/, ""))
     end
 
     def stream_match(path)
@@ -892,8 +899,7 @@ module Samagotchi
         "Content-Type" => "application/json",
         "Content-Length" => data.bytesize.to_s,
         "Connection" => "close",
-        "Cache-Control" => "no-store",
-        "Access-Control-Allow-Origin" => "*"
+        "Cache-Control" => "no-store"
       }.merge(extra_headers)
 
       io.write("HTTP/1.1 #{status} #{reason}\r\n")
@@ -961,7 +967,9 @@ module Samagotchi
         "port" => @port,
         "bind" => @bind,
         "session_id" => @session_id,
-        "started_at" => Time.now.iso8601(3)
+        "started_at" => Time.now.iso8601(3),
+        # The chi this worker runs (chi update reports older ones).
+        "version" => Samagotchi::VERSION
       }
       record["input_format"] = @input_format if @input_format
       path = File.join(session_dir, SIDECAR_FILE)

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

@@ -0,0 +1,10 @@
+---
+name: skills
+version: 0.1.0
+scope: system
+description: "Skills (skill_<name> memories, the steps of a task done together): /skill save, list, show and diff; older versions kept with a short diff line on every update; a nudge when a followed skill's step fails"
+trust_level: reviewed
+plugin:
+  file: plugin.rb
+  sha256: sha256:76758d41e75db107e0a6f7ce35b9eac4944052746af16aeba30f38210cc436dc
+requires_chi: ">= 0.4.0"