samagotchi 0.2.0 → 0.4.0

data/docs/cli.md

@@ -2,22 +2,120 @@
 
 ## Commands
 
+- `chi bootstrap [HOST[:PORT]|URL]` — first setup: find the model server (llama.cpp or OpenAI-compatible), pick the model, send a test request and write config.yml, or add a `hosts:` entry to an existing one (see [First setup](#first-setup))
 - `chi` — start a session in a background worker and attach the terminal to it, so the Web UI (or another terminal) can share it (see [Sharing a session](#sharing-a-session))
 - `chi -p "your prompt"` — run a prompt, then stay attached
 - `chi -p "your prompt" --non-interactive` — run a prompt, print the answer, exit
 - `chi --resume <session-id>` — resume a prior session (in its worker)
 - `chi --no-shared [--resume <session-id>]` — the plain in-process REPL instead, for this run
+- `chi scratch [options]` — a one-time session in the plain in-process REPL, in this folder, that leaves nothing behind (see [Scratch sessions](#scratch-sessions))
 - `chi --attach <session-id>` — attach the terminal to a session's worker (e.g. one started from the Web UI), waking one if it has exited
-- A session id can be shortened to any unique prefix (like git): `chi --attach 2ea8`. `--resume`, `--attach`, `sessions stop` and `sessions delete` take one; an ambiguous prefix lists the sessions it matches.
+- A session id can be shortened to any unique prefix (like git): `chi --attach 2ea8`. `--resume`, `--attach`, `sessions stop`, `sessions archive` and `sessions delete` take one; an ambiguous prefix lists the sessions it matches.
 - `chi web [--port 4567] [--open] [--scope=all]` — start the Web UI (single localhost port session control plane) on this git project's sessions (`--scope=all`, or a folder in no repo: every session); if a chi web already runs on the port, print (with `--open`, open) its page for this folder and exit. Something else on the port (an older chi web too) exits 1 with "port N is in use"
 - `chi web --web-markdown` — opt in to sanitized Markdown rendering for completed assistant messages
 - `chi web --no-web-turn-view` — show turns as the classic row of bubbles instead of the default turn view (each turn as one block of steps, the running one at the bottom); `?view=turn|chat` on the page URL overrides it (see [Web turn view](#web-turn-view))
-- `chi sessions list|stop|delete|prune|clean` — manage persisted sessions; `list` shows this git project's, `list --scope=all` every one, a delegated session with `↳ <parent>` (see [Sessions](sessions.md))
+- `chi sessions list|stop|archive|unarchive|delete|prune|clean` — manage persisted sessions; `list` shows this git project's, `list --scope=all` every one, a delegated session with `↳ <parent>`, `list --archived` the archived ones too (see [Sessions](sessions.md))
 - `chi note [--source NAME] [-m TEXT] (ID|PREFIX)... | --all` — add a context note (TEXT or stdin) to sessions: background the model sees on its next turn; it starts no turn (see [Sessions: Context notes](sessions.md#context-notes))
-- `chi send [-m TEXT] (ID|PREFIX)...` — send a message to sessions as if typed there: a turn starts (or a running one picks it up); piped stdin goes above `-m` as quoted context (see [Sessions: Sending a message](sessions.md#sending-a-message))
+- `chi send [-m TEXT] [--image PATH]... (ID|PREFIX)...` — send a message to sessions as if typed there: a turn starts (or a running one picks it up); piped stdin goes above `-m` as quoted context, and `--image` attaches images (see [Sessions: Sending a message](sessions.md#sending-a-message)); `--new` starts a session with it instead, and `--wait` prints the answer (`--wait ID` with no message waits for the next reply without sending; see [Starting a session](sessions.md#starting-a-session))
 - `chi desktop install|upgrade|uninstall|status` — the macOS "Send to chi" helper: a Service and a ⌃⌥⌘N hotkey that send text to live sessions as context notes (see [Desktop helper](desktop.md))
 - `chi self` — print version, source dir (checkout or installed gem), config/memory/session paths, model/host and bundles
-- `chi bundle install|upgrade|uninstall|status|diff|list|build` — manage memory bundles (see [Bundle hooks](hooks.md#bundle-hooks-unified-workflow-bundle)); `list` shows the installed ones and the ones shipped with chi, which `install <name>` installs (see [Guardrails](guardrails.md), [Plugins](plugins.md#the-btw-bundle), [the mcp bundle](plugins.md#the-mcp-bundle) and [the loop-guard bundle](plugins.md#the-loop-guard-bundle))
+- `chi update [--dry-run] [--no-gem] [--no-bundles] [--no-desktop]` — update an installed chi: the gem, the system bundle, the shipped bundles you installed and the desktop helper, in one table (see [Updating](#updating))
+- `chi bundle install|upgrade|uninstall|status|diff|list|build` — manage memory bundles (see [Bundle hooks](hooks.md#bundle-hooks-unified-workflow-bundle)); `list` shows the installed ones and the ones shipped with chi, which `install <name>` installs (see [Guardrails](guardrails.md), [Plugins](plugins.md#the-btw-bundle), [the mcp bundle](plugins.md#the-mcp-bundle) [the loop-guard bundle](plugins.md#the-loop-guard-bundle) and [the check-in bundle](plugins.md#the-check-in-bundle))
+
+### First setup
+
+`chi bootstrap TARGET` names the model server and writes the config for it:
+
+```sh
+chi bootstrap 192.168.1.29:8081          # host:port (port 8080 when none)
+chi bootstrap https://openrouter.ai/api/v1 --key-env OPENROUTER_API_KEY
+chi bootstrap                            # try localhost 8080, 11434, 1234, 8000
+```
+
+- **What it is.** llama.cpp's `/props` answering means the native API (no
+  `api:`); otherwise `GET /v1/models` answering means an OpenAI-compatible
+  server (`api: openai`). A URL with a path is the API base as given
+  (`…/api/v1`); a domain without a scheme is tried over https, then http.
+  Each request is tried once, with 5 s timeouts, so a refused port answers
+  at once.
+- **The key.** A server that answers 401/403 wants an API key: `--key-env VAR`
+  names the environment variable holding it (on a terminal chi asks for the
+  name). Only the variable's name is written, never the key.
+- **The model.** One model is taken; with several, `--model ID` picks one
+  (a terminal gets a numbered list, a script the ids and exit 2). A llama.cpp
+  server also shows its context size and the prompt profile its chat template
+  matches.
+- **The test.** One short chat request ("test: answered in 1.1 s"); `--no-test`
+  skips it. A failed test still writes the config, says so and exits 1.
+- **The file.** With no config.yml it writes a small commented one:
+  `default.model` as `<host>:<model>` and one `hosts:` entry named `local`
+  (localhost), `lan` (an IP) or after the domain (`openrouter`); `--name`
+  sets it. An existing file is left as it is apart from the new entry, added
+  at the end of its `hosts:` block (it gets a `hosts:` block, with a
+  `default` entry for its `server:` first, when it has none), after a backup
+  to `config.yml.bak-<time>`. `default.model` is set only when the file has
+  none. A server already in the file writes nothing; a file in YAML flow style
+  or with anchors gets the lines printed to paste instead. `--dry-run` shows
+  what it would write.
+
+### Updating
+
+`chi update` brings an installed chi up to date and prints one table:
+
+```
+component      from   to     status
+chi (gem)      0.2.0  0.3.0  updated
+system bundle  0.2.0  0.3.0  updated (kept your edits in identity.md: chi bundle diff samagotchi-system identity.md)
+btw            0.1.1         up to date
+known-names    0.1.0  0.1.1  updated
+infra_tools    1.0.0         skipped (not from chi)
+Chi Helper     0.2.0         up to date (launch file refreshed)
+workers                      2 live on 0.2.0: they move to 0.3.0 at idle exit (30 min) or chi sessions stop 2ea8c1f0 91b0d2aa
+Also shipped, not installed: check-in, source-links (chi bundle install NAME)
+done
+```
+
+- **The gem.** It asks rubygems.org for the newest samagotchi (5 s timeout)
+  and, when that's newer, runs `gem install samagotchi` with the gem command
+  of the Ruby chi runs on (the real one, not a mise/rbenv/asdf shim). Then it
+  hands over to the new chi, which does the rest and prints the table. Old
+  versions stay installed: running workers and an old `chi web` still use
+  them (so don't `gem cleanup` while they run). Offline, the row says
+  "couldn't check" and the rest still runs; a failed install fails the row
+  and the rest runs on the current version. Under Bundler (`bundle exec`)
+  the row says `bundle update samagotchi` instead.
+- **The system bundle** normally updated itself when the new chi started;
+  the row says what it did.
+- **Shipped bundles**: each one you installed from chi (`chi bundle install
+  NAME`) is upgraded when chi ships a newer version. Memory files get the
+  3-way merge of `chi bundle upgrade`: an unedited file is updated, an edited
+  one that the new version also changes is kept, and the row says so (`chi
+  bundle diff NAME FILE` shows it; `chi bundle upgrade NAME --force` takes the
+  bundle's). Hooks, rules and the plugin are replaced; an edited one didn't
+  load anyway (its sha no longer matched) and the row says it was replaced.
+  A bundle of the same name from elsewhere (a zip, git) is skipped ("not from
+  chi"), a newer installed one is left, one whose new version needs a newer
+  chi is skipped, and bundles you didn't install stay uninstalled.
+- **The desktop helper** (macOS) is rebuilt and restarted only when its Swift
+  sources changed (or the Ruby it runs moved); otherwise only its launch file
+  is refreshed. See [Desktop helper](desktop.md).
+- **Running processes** are reported, never stopped: live workers on another
+  version, and a `chi web` on `web.port` running an older chi (sessions it
+  starts run that version too: restart it).
+
+`--dry-run` shows the table with "would update" and changes nothing. It is
+this version's view: bundles that only a newer gem ships newer show up once
+that gem is installed (the real run installs it first and hands over).
+`--no-gem`, `--no-bundles` and `--no-desktop` leave a part alone for one run;
+`update.gem`, `update.bundles` and `update.desktop: false` in config.yml turn
+one off for good. It exits 0 when nothing failed (kept edits and skips are
+fine), 1 when a part failed, 2 on a usage error. A second run changes nothing
+and ends with "everything is up to date".
+
+From a checkout it refuses (`git pull`, or `chi bundle upgrade NAME` for one
+bundle). After a gem update, the first interactive start of the new version
+(`chi`, `chi web`; not `-p` or `--non-interactive`) says in one line when
+bundles or the helper can be updated.
 
 ## Flags
 
@@ -33,6 +131,7 @@ controls exit behavior (`--non-interactive`); `--resume` composes with both.
 | `--no-shared` | Run the plain in-process REPL for this run. |
 | `--attach SESSION_ID` | Attach to a session's worker, waking one if it has exited. |
 | `--model NAME` | Use this model for the run (overrides the configured default and a resumed session's model). |
+| `--thinking LEVEL` | How much the model thinks this run: `off`, `low`, `medium`, `high` or `default` (env `SAMAGOTCHI_THINKING_LEVEL`), over the config's levels. A session already running keeps its own. See "Thinking" in configuration.md. |
 | `--profile NAME` | Prompt profile (`qwen36` or `gemma4`) for every model in this run, over config and the server's template (same as `--model-profile`, env `SAMAGOTCHI_MODEL_PROFILE`). See "Prompt profile" in configuration.md. |
 | `--memory NAME` | Preload a memory entry into the system prompt (repeatable; a comma list too). Merged under the config.yml `memories:` baseline. Works attached: the list is stored on the session, so its worker builds the same prompt on every respawn. |
 | `--mute NAME` | Hide a memory from this session (repeatable; a comma list too): its index line is not in the prompt, `memory_read` refuses it, the identity auto-load skips it, and it is dropped from the preloads (config baseline or `--memory`). A name matches in both scopes (`gh-helper`, `project/gh-helper` and `gh-helper.md` all hide `gh-helper`). Nothing on disk changes. See [Muting a memory](#muting-a-memory). |
@@ -64,6 +163,7 @@ it sees one.
 | `chi --resume ID -p "next step" --non-interactive` | Resume `ID`, run the prompt, save, exit. |
 | `chi --resume ID -p "next step"` | Resume `ID`, send the prompt, **stay attached** to that session. |
 | `chi --no-shared [...]` | The same, in the plain in-process REPL. |
+| `chi scratch [-p ...] [--non-interactive]` | A new session in the plain REPL, deleted when it ends. |
 
 Notes:
 
@@ -75,6 +175,28 @@ Notes:
 - Non-interactive runs (`-p` with `--non-interactive`, or bare `--non-interactive`)
   print only the final result output — no spinner, status line, or REPL.
 
+### Scratch sessions
+
+`chi scratch` is `chi --no-shared` for a session you won't keep: a quick
+question, a try-out. It takes the run options (`-p`, `--non-interactive`,
+`--model`, `--profile`, `--memory`, `--mute`, `-v`, …); `--resume`, `--attach`
+and `--shared` are refused. Its first line says it is a scratch session.
+
+- The session is deleted however it ends: `/exit`, Ctrl-D, Ctrl-C at the
+  prompt, an error, SIGTERM or SIGHUP. There is no recap, and the lines typed
+  are not added to the prompt history.
+- It never shows in `chi web`. A process killed with `kill -9` leaves its
+  session behind, marked `"scratch": true` in its session.json: `chi sessions
+  list` shows it as `[scratch]`, and the next sweep or `chi sessions clean`
+  deletes it. `chi --resume` and `--attach` refuse it (exit 1), so it never
+  turns into a kept session.
+- Memories are read and preloaded as usual, but nothing is saved: `memory_write`
+  answers "scratch session: nothing is saved", and `write`/`edit` into the
+  memories folder are denied (a guardrail, rule `scratch-session`). `execute`
+  can still write files anywhere, memories included.
+- No child sessions: the `delegate` tools are not offered, and a plugin's
+  `ctx.sessions.fork` (btw's side session) refuses, since they would outlive it.
+
 ### Sharing a session
 
 Plain `chi` runs the session in a background worker and attaches the terminal
@@ -122,7 +244,8 @@ A worker nobody uses exits after `session.idle_exit_minutes` (30 by default, `0`
 for never): no turn running or queued, no UI attached (an open web tab or an
 attached terminal counts, even an idle one) and no reminder registered. The next
 prompt or `--attach` wakes a new worker with the conversation intact; `/stats`
-counters start over (the recap is saved with the session).
+keeps counting from the turns before (they are saved in the session's
+`analytics.json`, one record per turn), and the recap is saved with the session.
 
 A session you leave with nothing in it (no prompt sent, no `/model` switch, no
 note or image) is deleted as its worker exits, and `/exit` says so; set
@@ -134,6 +257,21 @@ a `chi --resume ID` after it starts a fresh one. A worker still running an
 older chi (from before an upgrade) takes turns but not commands; the attached
 terminal and the Web UI say so, with that restart line.
 
+`chi sessions archive ID...` hides sessions from every list (the terminal's,
+the web's, `list_sessions`) and keeps them for good: the retention sweep never
+deletes an archived session, nor counts it. Its delegates go with it. A live
+worker is stopped first; a session running a turn (or with a delegate running
+one), open in a plain REPL, or a `chi scratch` one is refused. `chi sessions
+list --archived` shows them too, marked `[archived]` (`archived: true` in
+`--format json`); `chi sessions unarchive ID...` brings them back, and so does
+a message you send to one (the web, an attached terminal, `chi send`), but not
+a delegate's follow-up or a reminder. The web archives from the info bar
+(`archive`, before `stop`); "include archived" by the all-sessions search
+finds archived sessions. `/archive` in a terminal leaves the session and
+archives it (an empty session is discarded instead; `chi scratch` refuses
+it). See
+[Sessions](sessions.md#archiving-a-session).
+
 `chi sessions delete [--force] ID...` deletes sessions for good: the
 session file and its whole directory (notes, images, queued input). Each id
 (or unique prefix) gets one line: `deleted`, or `refused` with the reason. A
@@ -202,7 +340,7 @@ REPL alike:
   typed comes back once it closes. The choices then go, and one line stays:
   `? Pick a fruit → Banana`.
 - Ctrl-C cancels the turn and keeps what you typed.
-- In the plain REPL, Ctrl-D on an empty prompt (or `exit`, `/exit`) mid-turn
+- In the plain REPL, Ctrl-D on an empty prompt (or `exit`, `/exit`, `/quit`) mid-turn
   exits once the turn ends: `(exits after this turn; Ctrl-C cancels it)`
   (`/exit --delete` deletes the session then too). In an
   attached terminal it detaches at once and the turn goes on in the worker
@@ -213,7 +351,7 @@ turns.
 
 ### Images
 
-A model that can see images gets them three ways:
+A model that can see images gets them these ways:
 
 - **`@path` in a prompt** (REPL, attached terminal, `-p`): `what's wrong in
   @shot.png?`, `@~/Desktop/a.jpg`, `@"my shot.png"`. Each `@` token that names an
@@ -228,6 +366,12 @@ A model that can see images gets them three ways:
 - **The Web UI**: paste or drop images into the composer. Each shows as a chip
   (× removes it) and is sent with the message; an image alone is sent as
   `[image: name]`. Messages show thumbnails; a click opens one full size.
+- **`chi send --image PATH`** (repeatable, up to 20) with a message, from a
+  script or another terminal: `chi send --image shot.png -m "why is this red?"
+  3fa2`. The attached terminal and the web show it like an image typed there.
+- **The desktop panel** (macOS, [Desktop](desktop.md#images)): a screenshot on
+  the clipboard, an image selected in Finder, or one dropped on the panel goes
+  as an attachment with the message.
 
 Images are downscaled to a 1568 px long side (with `sips` on macOS or
 ImageMagick; without either, a larger image is refused with a hint) and stored
@@ -298,7 +442,10 @@ from the saved messages (each step's thinking, narration, tool parameters
 and output, the output capped at 2000 characters) and the timing records
 (status and duration per row). On an `api: openai` host the model's
 reasoning is saved with each step for this (never sent back to the model);
-steps saved before that have none, so they show no thinking.
+steps saved before that have none, so they show no thinking. An `edit` or
+`write` row has a closed `diff +3 −1` under it that opens to the change it
+made (up to 120 lines or 8 KB), live and after a reload (see
+[Guardrails](guardrails.md#ask) for the diff an approval shows first).
 
 ```sh
 chi web --no-web-turn-view   # the classic chat view; --web-turn-view is the default
@@ -316,6 +463,32 @@ and `?view=turn` the turn view, whatever the config says; the parameter is dropp
 when you switch between the project and all-sessions views. The terminal
 UIs are not affected.
 
+### Web annotate presets
+
+Selecting text in an answer, a thinking block, a tool row or one of your
+messages shows **Annotate**, which quotes the selection into the composer
+for a note under it. Next to it sit quick replies, by default `Agreed` and
+`Could you please elaborate?`: a click quotes the selection the same way
+with that text already written as the note. It only fills the composer,
+never sends, so you can collect several quotes and edit before sending.
+
+The list is `web.annotate_presets`, `|`-separated (at most five; a preset
+can't contain `|`; a YAML list works too):
+
+```sh
+chi web --web-annotate-presets "Yes|No|Why this way?"
+chi web --web-annotate-presets ""   # only Annotate
+```
+
+```yaml
+web:
+  annotate_presets: "Agreed|Could you please elaborate?"
+```
+
+`SAMAGOTCHI_WEB_ANNOTATE_PRESETS` overrides the file, but an empty value
+there means the default, not "none": use `""` in the file or on the command
+line. A `chi web` that already runs keeps its list; restart it.
+
 ## Runtime Model Switch (Assist Mode)
 
 In interactive assist mode, you can switch the request model without restarting:
@@ -479,7 +652,9 @@ During assist-mode thinking (while the spinner is active), you can cancel an in-
 Behavior notes:
 
 - Cancellation returns control to the prompt immediately; what you typed there stays.
-- Partial model output from the canceled request is not committed as a completed model turn.
+- Visible text the canceled request had streamed stays in the conversation, marked `[interrupted]`, so the next
+  message (or a continue) picks up from the half-finished reply; the canceled request's thinking and any unfinished
+  tool call are dropped.
 
 ## Iteration Limit Behavior