samagotchi 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da62382ff837576724b356e7ac03ccb484c382628b4a3a7fcfaacf799de4cc92
-  data.tar.gz: 2822682cf66025598dbb6effc4598f97b3658fec0153cfcfaf5088a7385764dd
+  metadata.gz: 950fbee37d2110efad37f8d3f8981144f49af9a2ccf75649d5953b1fe7773260
+  data.tar.gz: aaad7adb0e9aa3c81b601df48fde4ebab965862ed954454c8b79e2de841f0789
 SHA512:
-  metadata.gz: 860855c62b763f58c44d06e137f8f45abceb81e4e8169c5c46182b69ae00442cc44c285c056e79120ce2b5a6ef2516c3e7fb75739188b650fc6c918644f25796
-  data.tar.gz: 429c0f7b9fc76def59cd87a9493bddaca7813d38f73f8ce974616f9f55af89767aca8b7f9b2cd629b8e0a7fe606e98eee05ee52199a74ec6d3d13c00f23c2e82
+  metadata.gz: 1b4d092f263192c242dead3ae0c556758a38af2f01285dc590362d698696a31d38801c70e64ff85daa33067ceda92be7687915024d1e81802bd0a2c365cc292d
+  data.tar.gz: 7a06a4d47dea9168e40b0ae0ba7bc6cbfe1b377ba9ac29a998d19f0ee17a766de3186786894deea8b6765a78e21b14e3e7ece8238ab401354c43a5eba4d1815b

data/CHANGELOG.md

@@ -8,6 +8,120 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-09-29
+
+### Added
+
+- `chi bootstrap [HOST[:PORT]|URL]`: the first setup in one command. It finds
+  out whether the server is llama.cpp or OpenAI-compatible (with no target, it
+  looks on localhost's usual ports), picks the model, sends a test request and
+  writes config.yml; an existing config gets a `hosts:` entry added after a
+  backup, its other lines untouched. `--key-env VAR` for a server that wants a
+  key, `--model`, `--name`, `--no-test`, `--dry-run`. The first-run "no model
+  configured" line points at it.
+- Web notifications: a session that needs you (a question or approval, a
+  failed turn, a turn done after 10 s or more) while the tab is in the
+  background counts in the page title, `(N) Chi`, and with the new bell in the
+  top bar on, shows an OS notification that opens the session.
+- `chi scratch`: a one-time session in the terminal that leaves nothing behind.
+  It is deleted however it ends, saves no memories and starts no other
+  sessions; one left by a killed process goes at the next sweep or
+  `chi sessions clean`.
+- Archiving a session: `chi sessions archive ID`, `/archive` in a terminal or
+  `archive` in the web's info bar hides it (and its delegates) from every list
+  and keeps it for good; `chi sessions list --archived` and "include archived"
+  in the web's all sessions find it, and a message you send to it brings it
+  back.
+- `chi send --new` starts a session with the message, the way the web does, so
+  it shows in the web at once (`--dir`, `--model`); `chi send --wait` (new or
+  one existing session) blocks and prints the answer, exit 3 when the turn
+  waits for your answer.
+- The `check-in` bundle (`chi bundle install check-in`): after 50 tool calls
+  in one turn with no answer (then every 50 more) a card asks you to nudge
+  the model, let it keep going or stop the turn; `mode: nudge` nudges it by
+  itself. `/checkin` shows and changes it for the session.
+- Plugins can steer the running turn: `ctx.steer(text)` and a hook's
+  `event[:steer]` put text into the turn as its own message at the loop's
+  next step, shown as `<bundle>> nudged: …`; `ctx.stop_turn(reason)` stops it.
+- The `source-links` bundle (`chi bundle install source-links`): refs like
+  `JIRA-123` or `GH-45` in an answer become links in the web, and a one-line
+  `sources:` note follows the turn in the terminal. Sources are patterns in
+  `bundles: source-links:`.
+- Plugins can change how an answer is shown without changing what the model
+  sees: an after_turn hook's `event[:present]` sets a display version of the
+  answer, which the web renders (and keeps after a reload).
+- Annotate presets: selecting text in an answer offers quick replies next to
+  Annotate (default "Agreed" and "Could you please elaborate?"); a pill puts
+  the quote and the text in the composer without sending.
+  `web.annotate_presets` (`|`-separated or a YAML list; `""` turns them off).
+- `sampling:` on a `hosts:` or `models:` entry (temperature, top_p, top_k,
+  min_p, penalties, …) is sent with every request to that host or model;
+  `temperature: null` sends none, so the provider's default applies.
+- `retry.empty_answer` (default 1): when the model returns an empty answer
+  (or runs out of tokens while thinking), chi asks again once in the same
+  turn; the terminal and the web show "↻ empty answer, asking again".
+- The context fill is saved with the session: `chi sessions list` and the web
+  list show it (`ctx 12%`), and `/stats`, the status line and the web meter
+  show it right after a restart or a reload. Token totals now cover the whole
+  session across worker restarts.
+- `chi send --wait ID` with no message waits for the session's next reply
+  without sending anything (also on a running session), e.g. after `--wait`
+  exited 3 for a question.
+- The desktop panel has a "New session in <folder>" row (⏎ starts a session
+  with the selection there).
+- Web notifications also cover a check-in card waiting for you, and a chi tab
+  in front keeps the tabs behind it from notifying twice.
+
+### Changed
+
+- Stop ends a turn that is waiting in `task_wait` or running `execute` within
+  about a second, and a Stop right after a turn starts ends it at once. A
+  background task keeps running: the model is told it's still running and how
+  to continue or stop it, and the cancel note lists the session's tasks still
+  running. A stopped wait shows as "stopped".
+- config.yml: a nested key now wins over its legacy flat `SAMAGOTCHI_*` key
+  (one warning names both); an unknown key warns with a did-you-mean;
+  top-level keys like `max_tool_output_chars` no longer warn; `no_interrupt`
+  and `no_default_input` work from config and env.
+- A refused connection to a host fails at once with "can't reach host … — is
+  the server running?" instead of retrying for half a minute.
+- A host whose `/props` doesn't answer costs one probe per 30 s, not a wait
+  at every turn.
+- `chi -p … --non-interactive` with an empty answer says so on stderr and
+  exits 1.
+- docs/configuration.md uses nested keys throughout and lists every setting;
+  the README starts with `chi bootstrap`.
+
+### Removed
+
+- The unused config keys `bridge.enable` and `thinking.preview_lines` (they
+  now warn as unknown).
+
+### Fixed
+
+- The web keeps a failed turn's prompt and reason after a reload, and a failed
+  turn's prompt comes back to the composer, also for a first message from the
+  start page.
+- Web answer links appear with the answer instead of being swapped in after it.
+- The title badge clears when you switch to the tab in Safari, and drops a
+  question answered from another tab or client.
+- `/archive` and `/exit` typed in the web composer get a short reply instead
+  of an error.
+- An approval card for a tool without a command or path shows its arguments.
+- A hook notice from before the turn stays in its step after a reload.
+- Card actions (check-in's Nudge, …) no longer leave a command bubble or line.
+- A 404 from a native (llama.cpp) host hints at `api: openai`.
+- A config `memories:` entry that can't be loaded is no longer called `--memory`.
+- `chi --resume`/`--attach` refuse a leftover scratch session.
+- `chi sessions list --live/--cwd/--format` show `[scratch]` too.
+- The legacy-key warning names the right nested key.
+
+### Bundles
+
+- New: `check-in` 0.1.1 (`chi bundle install check-in`, needs chi 0.3.0) and
+  `source-links` 0.2.0 (`chi bundle install source-links`). No other bundle
+  changed since 0.2.0.
+
 ## [0.2.0] - 2026-09-27
 
 The first public release. chi is an agent harness for local models
@@ -39,5 +153,6 @@ and long-lived sessions.
 - A macOS desktop helper (`chi desktop install`): a "Send to chi" Service and a
   hotkey panel that send selected text or the clipboard to your sessions.
 
-[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/dm1try/samagotchi/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/dm1try/samagotchi/releases/tag/v0.2.0

data/README.md

@@ -32,9 +32,28 @@ bin/chi self
 `bin/chi` runs the checkout; `bundle exec rake gem:install` installs it as a
 local gem, which puts `chi` on your PATH.
 
+## Set up
+
+Point chi at your model server; it works out the rest and writes
+`~/.config/samagotchi/config.yml`:
+
+```sh
+chi bootstrap 192.168.1.29:8081          # llama.cpp on another machine
+chi bootstrap localhost:11434            # Ollama (any OpenAI-compatible server)
+chi bootstrap https://openrouter.ai/api/v1 --key-env OPENROUTER_API_KEY
+chi bootstrap                            # look on this machine's usual ports
+```
+
+It finds out whether the server is llama.cpp or OpenAI-compatible, picks the
+model (or asks, when there are several), sends one test request and writes
+the config. With a config already there, it adds a `hosts:` entry and keeps
+the rest of the file. Edit the file later as in [Configure](#configure);
+`chi bootstrap --help` has the options.
+
 ## Configure
 
-Create `~/.config/samagotchi/config.yml` (or `$XDG_CONFIG_HOME/samagotchi/config.yml`):
+To write the config by hand instead, or to change it later: create
+`~/.config/samagotchi/config.yml` (or `$XDG_CONFIG_HOME/samagotchi/config.yml`):
 
 ```yaml
 default:
@@ -44,7 +63,20 @@ server:
   port: 8080
 ```
 
-Other settings (multiple hosts, transports, timeouts, the idle recap) are in
+`server:` is a llama.cpp `llama-server`. For any other OpenAI-compatible
+server (vLLM, LM Studio, Ollama, a gateway), name it under `hosts:` with
+`api: openai` instead:
+
+```yaml
+default:
+  model: local:qwen3:8b    # host:model; the ids are in GET <url>/models
+hosts:
+  local:
+    url: http://localhost:11434/v1   # the API base, /v1 included
+    api: openai
+```
+
+`chi self` shows the model and host chi will use. Other settings (multiple hosts, transports, timeouts, the idle recap) are in
 [Configuration](docs/configuration.md).
 
 ## Use
@@ -58,11 +90,12 @@ chi web --open                            # web UI: this project's sessions (--s
 chi sessions list                         # this project's saved sessions (--scope=all: every one)
 pbpaste | chi note --source slack <id>    # background context for a session (no turn)
 pbpaste | chi send -m "same bug?" <id>    # a message to a session, the clipboard quoted above it
+chi send --new --wait -m "review feat/x"  # a new session you can watch in the web; prints the answer
 ```
 
 `@shot.png` in a prompt (or a pasted/dropped image in the web UI) shows the model an image, when it can see them; see [Images](docs/cli.md#images).
 
-`/model` switches models, Ctrl-C cancels a turn, and Ctrl-D or `/detach` detaches (the session keeps running; `chi --attach ID` comes back). `/exit` detaches and stops the session's worker too, unless something still needs it (a running turn, another UI); `chi --resume ID` picks the conversation up again. `/exit --delete` also deletes the session once the worker has gone; `chi sessions delete ID` deletes one from the shell.
+`/model` switches models, Ctrl-C cancels a turn, and Ctrl-D or `/detach` detaches (the session keeps running; `chi --attach ID` comes back). `/exit` detaches and stops the session's worker too, unless something still needs it (a running turn, another UI); `chi --resume ID` picks the conversation up again. `/exit --delete` also deletes the session once the worker has gone; `chi sessions delete ID` deletes one from the shell. `/archive` (or `chi sessions archive ID`) hides a session from every list and keeps it for good; `chi sessions list --archived` finds it again.
 
 ### Context notes
 
@@ -78,7 +111,9 @@ reply (a normal session: `chi --attach <id>` steers it).
 
 `chi send` is the other half: the text goes in as your message, the same as
 typing it in the attached terminal or the web composer, and a turn runs. Piped
-stdin plus `-m` puts the stdin above the message as a `>` quote.
+stdin plus `-m` puts the stdin above the message as a `>` quote. `chi send --new`
+starts a session with the message instead (it shows in the web at once), and
+`--wait` blocks and prints the answer.
 
 ### Send to chi (macOS)
 
@@ -119,6 +154,7 @@ once, for the session, for the repo, or for the whole rule in the repo.
 ```sh
 bundle exec rspec    # Ruby specs
 npm test             # web frontend specs
+npm run e2e          # web UI happy paths in Chromium, fake model (once: npx playwright install chromium)
 ```
 
 ## License

data/bin/chi

@@ -38,16 +38,18 @@ if ARGV[0] == "sessions"
   sessions_args = ARGV[1..] || []
   sub = sessions_args[0]
   if sub.nil? || %w[-h --help help].include?(sub)
-    puts "Usage: chi sessions <list|stop|delete|prune|clean> [options]"
+    puts "Usage: chi sessions <list|stop|archive|unarchive|delete|prune|clean> [options]"
     puts "  list [--sort updated_at|created_at] [--order desc|asc] [--limit N]"
-    puts "       [--live] [--cwd PATH] [--format text|json|tsv]"
+    puts "       [--live] [--cwd PATH] [--format text|json|tsv] [--archived]"
     puts "       --live: sessions a worker runs now (the ones chi note reaches), 10 unless --limit"
     puts "       --cwd PATH: sessions in PATH or below; json/tsv (id<TAB>description) are for scripts"
     puts "       [--scope=all]: every project's sessions; by default only this git project's (all outside a repo)"
+    puts "       --archived: archived sessions too (marked [archived]; json: archived: true)"
     puts "  stop ID...   # stop each session's worker (IDs or unique prefixes); chi --resume ID then starts a fresh one"
+    puts "  archive ID...   # hide sessions (and their delegates) from every list and keep them for good; unarchive ID... brings them back"
     puts "  delete [--force] ID...   # delete sessions for good (IDs or unique prefixes); --force stops a live worker first"
     puts "  prune [--dry-run] [--days N] [--keep N] [--keep-status running,...] [--test-only]"
-    puts "  clean [--dry-run] [--days N]   # test sessions (SAMAGOTCHI_ENV=test, CI): all of them, or those older than N days"
+    puts "  clean [--dry-run] [--days N]   # test sessions (SAMAGOTCHI_ENV=test, CI) and leftover chi scratch ones: all of them, or those older than N days"
     puts "Defaults: days=14 keep=500 keep_status=running (env overrides: SAMAGOTCHI_SESSION_RETENTION_DAYS etc.)"
     exit 0
   end
@@ -60,6 +62,7 @@ if ARGV[0] == "sessions"
   order = nil
   limit = nil
   live = sessions_args.include?("--live")
+  include_archived = sessions_args.include?("--archived")
   cwd = nil
   format = nil
   scope = nil
@@ -89,6 +92,9 @@ if ARGV[0] == "sessions"
   when "delete"
     require "samagotchi/session_delete_command"
     exit Samagotchi::SessionDeleteCommand.new(sessions_args[1..]).run
+  when "archive", "unarchive"
+    require "samagotchi/session_archive_command"
+    exit Samagotchi::SessionArchiveCommand.new(sub, sessions_args[1..]).run
   when "list"
     unless format.nil? || %w[text json tsv].include?(format)
       warn "Unknown format #{format.inspect}: use --format text|json|tsv"
@@ -107,7 +113,8 @@ if ARGV[0] == "sessions"
     # and test runs stay out.
     if live || cwd || (format && format != "text")
       summaries = Samagotchi::SessionManager.session_summaries(
-        live: live, cwd: cwd, limit: limit || (live ? 10 : nil), include_tests: false, project_root: project
+        live: live, cwd: cwd, limit: limit || (live ? 10 : nil), include_tests: false, project_root: project,
+        include_archived: include_archived
       )
       case format
       when "json"
@@ -115,7 +122,11 @@ if ARGV[0] == "sessions"
         # or nil; recap: the saved recap's first sentence, or nil; project:
         # its git project's root, or nil
         # parent_id: the session that delegated it (the delegate tool), or nil
-        keys = %i[id short_id desc cwd project updated_at live busy owner recap parent_id]
+        # archived: hidden from the lists (only with --archived can it be true)
+        # scratch: a `chi scratch` session (deleted when its REPL ends, a
+        # leftover one at the next sweep)
+        # ctx_pct: how full the context was after the last turn, or nil
+        keys = %i[id short_id desc cwd project updated_at live busy owner recap parent_id archived scratch ctx_pct]
         puts JSON.generate(summaries.map { |summary| summary.slice(*keys) })
       when "tsv"
         summaries.each { |summary| puts "#{summary[:id]}\t#{summary[:desc]}" }
@@ -131,7 +142,10 @@ if ARGV[0] == "sessions"
           end
           # A delegated session points at its parent.
           child = summary[:parent_short_id] ? "  ↳ #{summary[:parent_short_id]}" : ""
-          puts "#{summary[:id]}  #{state.ljust(8)}  #{summary[:updated_at]}  #{desc}#{child}"
+          flag = summary[:scratch] ? " [scratch]" : ""
+          flag += " [archived]" if summary[:archived]
+          ctx = Samagotchi::SessionMetrics.context_label(summary[:ctx_pct])
+          puts "#{summary[:id]}  #{state.ljust(8)}  #{ctx.ljust(8)}  #{summary[:updated_at]}  #{desc}#{flag}#{child}"
         end
         if project
           puts "#{summaries.empty? ? "" : "\n"}#{scope_note.call(summaries.size)}"
@@ -143,7 +157,8 @@ if ARGV[0] == "sessions"
     end
     sort ||= "updated_at"
     order ||= "desc"
-    sessions = Samagotchi::SessionManager.list_sessions(sort: sort, order: order, limit: limit, project_root: project)
+    sessions = Samagotchi::SessionManager.list_sessions(sort: sort, order: order, limit: limit, project_root: project,
+                                                        include_archived: include_archived)
     # The saved recap's first sentence, else the last prompt, cut as before.
     state_dir = Samagotchi::Session.default_state_dir
     list_text = lambda do |s|
@@ -152,9 +167,14 @@ if ARGV[0] == "sessions"
     end
     # A delegated session points at its parent: ↳ <parent's short id>.
     row = lambda do |s|
-      flag = s.test_run ? " [test]" : ""
+      flag = s.scratch ? " [scratch]" : (s.test_run ? " [test]" : "")
+      flag += " [archived]" if s.archived
       child = s.parent_id ? "  ↳ #{s.parent_id[0, 8]}" : ""
-      "#{s.id}  #{s.status.ljust(8)}  #{s.updated_at}  #{list_text.call(s)}#{flag}#{child}"
+      # How full the context was after the last turn: "ctx 12%", blank when unknown.
+      ctx = Samagotchi::SessionMetrics.context_label(
+        Samagotchi::SessionMetrics.saved_context_pct(Samagotchi::Session.session_dir(s.id, state_dir: state_dir))
+      )
+      "#{s.id}  #{s.status.ljust(8)}  #{ctx.ljust(8)}  #{s.updated_at}  #{list_text.call(s)}#{flag}#{child}"
     end
     if project
       sessions.each { |s| puts row.call(s) }
@@ -214,7 +234,7 @@ if ARGV[0] == "sessions"
     end
     exit 0
   else
-    warn "Unknown sessions subcommand: #{sub}. Use: list, stop, delete, prune, clean"
+    warn "Unknown sessions subcommand: #{sub}. Use: list, stop, archive, unarchive, delete, prune, clean"
     exit 1
   end
 end
@@ -231,6 +251,12 @@ if ARGV[0] == "send"
   exit Samagotchi::SendCommand.new(ARGV[1..] || []).run
 end
 
+# `chi bootstrap`: find a model server and write config.yml, before OptionParser (--model, --name are its own)
+if ARGV[0] == "bootstrap"
+  require "samagotchi/bootstrap_command"
+  exit Samagotchi::BootstrapCommand.new(ARGV[1..] || []).run
+end
+
 # `chi desktop`: the native "Send to chi" helper, before OptionParser (its own flags)
 if ARGV[0] == "desktop"
   require "samagotchi/desktop_command"
@@ -881,7 +907,13 @@ if ARGV[0] == "bundle"
   exit 0
 end
 
-options = { verbose: false, no_interrupt: false, non_interactive: false, no_default_input: false, web: false, web_port: nil, web_open: false, web_markdown: nil, web_turn_view: nil }
+# `chi scratch`: the run options below, for a session that leaves nothing
+# behind (TerminalUI scratch:). The word goes before OptionParser sees it.
+scratch = ARGV[0] == "scratch"
+ARGV.shift if scratch
+
+# no_interrupt / no_default_input start from config.yml or the env; the flags below turn them on.
+options = { verbose: false, no_interrupt: Samagotchi::Config.get("no_interrupt"), non_interactive: false, no_default_input: Samagotchi::Config.get("no_default_input"), web: false, web_port: nil, web_open: false, web_markdown: nil, web_turn_view: nil }
 cli_overrides = {}
 
 if ARGV.any? { |arg| arg == "--backend" || arg.start_with?("--backend=") }
@@ -908,10 +940,12 @@ end
 parser = OptionParser.new do |opts|
   opts.banner = <<~BANNER
     Usage: chi [options]
+           chi bootstrap [HOST[:PORT]|URL]  first setup: find the model server, write config.yml
+           chi scratch [options]            a one-time session in this terminal: nothing is kept
            chi web [--port PORT] [--open] [--scope=all]   the web UI
-           chi sessions <list|stop|delete|prune|clean>
+           chi sessions <list|stop|archive|unarchive|delete|prune|clean>
            chi note [--source NAME] [-m TEXT] ID...|--all   background context for sessions
-           chi send [-m TEXT] ID...         a message into sessions, as if typed there
+           chi send [-m TEXT] ID...|--new   a message into sessions, as if typed there
            chi bundle <install|upgrade|uninstall|status|diff|list|build>
            chi desktop <install|upgrade|uninstall|status>   macOS "Send to chi" helper
            chi self                         version, paths, model and bundles
@@ -938,7 +972,8 @@ parser = OptionParser.new do |opts|
           "every session outside a repo) or all") { |v| options[:scope] = v }
   # Accepted values of string entries that the registry doesn't type as enums.
   value_hints = { "thinking.ui" => "spinner|off", "status.line" => "on|off", "status.width_mode" => "terminal_cap|fixed",
-                  "web.host" => "127.0.0.1|::1|localhost", "recap.sentences" => "N|N-M" }
+                  "web.host" => "127.0.0.1|::1|localhost", "recap.sentences" => "N|N-M",
+                  "web.annotate_presets" => "text|text" }
   # Universal config flags (implicit convention: ENV SAMAGOTCHI_* ↔ YAML dotted ↔ CLI --kebab)
   # Generated from Samagotchi::Config registry — Option A: snake leaf in YAML, kebab in CLI.
   Samagotchi::Config.cli_entries.each do |entry|
@@ -981,12 +1016,22 @@ end
 # The subcommands with their own parsers ran above; what parse! leaves is
 # `web` or nothing. Anything else is a typo, not a prompt: refuse it rather
 # than start a session.
-stray = ARGV.first == "web" ? ARGV[1] : ARGV.first
+web = ARGV.first == "web" && !scratch
+stray = web ? ARGV[1] : ARGV.first
 if stray
-  warn "Error: #{ARGV.first == "web" ? "unexpected argument" : "unknown command"} #{stray} (see chi --help)"
+  warn "Error: #{web || scratch ? "unexpected argument" : "unknown command"} #{stray} (see chi --help)"
   exit 1
 end
 
+# A scratch session is new, runs here and goes when it ends.
+if scratch
+  flag = { resume: "--resume", attach: "--attach", shared: "--shared" }.find { |key, _flag| options[key] }&.last
+  if flag
+    warn "Error: chi scratch starts a new session in this terminal and keeps nothing; it can't take #{flag}"
+    exit 1
+  end
+end
+
 # Apply CLI precedence: CLI > ENV > file
 unless cli_overrides.empty?
   Samagotchi::Config.reload!(cli_overrides: cli_overrides)
@@ -1039,7 +1084,8 @@ if options[:web]
   turn_view = options[:web_turn_view]
   turn_view = Samagotchi::Config.get("web.turn_view") if turn_view.nil?
   exit Samagotchi::Web::Server.launch(port: port, scope: options[:scope] || "project", open_browser: options[:web_open],
-                                      markdown: markdown, turn_view: turn_view)
+                                      markdown: markdown, turn_view: turn_view,
+                                      annotate_presets: Samagotchi::Config.get("web.annotate_presets"))
 end
 
 # --resume and --attach take a unique id prefix too, like git.
@@ -1050,6 +1096,22 @@ rescue Samagotchi::Session::AmbiguousId => e
   exit 1
 end
 
+# A `chi scratch` session a killed REPL left behind would turn into a kept
+# one if opened again; the next sweep deletes it.
+%i[resume attach].each do |key|
+  next unless options[key]
+
+  leftover = begin
+    Samagotchi::Session.load(options[key]).scratch
+  rescue ArgumentError
+    false # no such session: the launch says so
+  end
+  next unless leftover
+
+  warn "Error: that's a leftover scratch session; it is deleted at the next sweep (chi sessions clean)"
+  exit 1
+end
+
 # --memory and --mute names are checked here, before the launch: a worker's
 # stderr goes nowhere, so its engine's warnings would not be seen. Warnings
 # only; the session starts either way.
@@ -1082,7 +1144,11 @@ if options[:memories] || options[:muted]
 end
 
 require "samagotchi/launch_mode"
-launch, launch_note = Samagotchi::LaunchMode.resolve(options, shared_config: Samagotchi::Config.get("session.shared"))
+launch, launch_note = if scratch
+                        [:repl, nil]
+                      else
+                        Samagotchi::LaunchMode.resolve(options, shared_config: Samagotchi::Config.get("session.shared"))
+                      end
 warn launch_note if launch_note
 
 if launch == :attached
@@ -1124,7 +1190,8 @@ begin
     memories: options[:memories] || [],
     muted_memories: options[:muted] || [],
     non_interactive: options[:non_interactive],
-    model_name: options[:model]
+    model_name: options[:model],
+    scratch: scratch
   ).run
 rescue Samagotchi::TerminalUI::SessionBusy, Samagotchi::TerminalUI::SessionNotFound, Samagotchi::ModelProfile::MissingModel => e
   warn "Error: #{e.message}"

data/docs/cli.md

@@ -2,22 +2,60 @@
 
 ## 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] (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)); `--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 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.
 
 ## Flags
 
@@ -64,6 +102,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 +114,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 +183,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 +196,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
@@ -316,6 +393,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: