samagotchi 0.59.0 → 0.60.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 399c5b5b4ad3423bd266545c1f190e9e269f070a26bc48350640bf774eea7c4b
-  data.tar.gz: 26bfce90ed8fe75c15c777943f07699803f70160f54559ae057ba31eb168d956
+  metadata.gz: ee2aa2b12b6482c02486b2382cc1c287c394d0a323e3bbf851948e49d0ebb2b9
+  data.tar.gz: 7bddba2fddfbcc05dfccba0777a6163963f8e238a26d14b6fbfb49b3d0bc0827
 SHA512:
-  metadata.gz: 042a3460c486987f7bd120fa6615c5cdd65d1ca6da0edfe9548746b83d9b66c6ad532b7088c20af082751b9bfad64252fba93123845fb36cfa0875d1a54ec0bf
-  data.tar.gz: f441e37232ea17b6af0ca047aea5331d7e062b3563382656fb323118f8607459cf97540858fccae714691aabfe989dd666f8de379f2024bc7a4b024864b2a694
+  metadata.gz: fb47d9df8beac57e413f22b01efdf8bbec31c7c9a5be400976b818d8e6dbe6931081b223568cbb3f345dee39c7f1ffc7a6b39def9e01b4033bdcf7ccda017cdd
+  data.tar.gz: 95b1879ed0ee9d093140d2dddaa9cc21c30031d45f7114b1c3311134d2f1082ad1f81480421a8da7f9cd61eb76d4d4aae65b8b29c08c0dd377dcbdab50c98f6d

data/CHANGELOG.md

@@ -8,6 +8,53 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.60.0] - 2026-10-11
+
+### Added
+
+- chi web has a favicon: χ on a blue-to-violet rounded square. Safari showed a "1" monogram before.
+- `chi --append-system-prompt FILE` (repeatable) and a config.yml `append_system_prompt:` list: a file's text goes
+  into the system prompt after AGENTS.md, in the cached part. A relative config entry is looked up where chi runs
+  (`append_system_prompt: [CLAUDE.md]`); the flag's files are saved in the session and kept by forks and continues.
+  `/stats` names the prompt's files on a `prompt files:` line.
+- An analytics `resumed` mark on the turn record of a step-limit Continue (`resumed: true`; every other turn has
+  `resumed: false`). `continue` also marks a reminder's and a wake's turn, so `script/model_notes_report` now counts
+  Continues from `resumed`, falling back to `continue` record by record for older files. `:turn_started` and the
+  `before_turn` hook payload carry `resumed` too.
+- A hook's or plugin's notice can be marked `fallback_for: :editor`: a line naming a file the viewer could open from
+  a ref. The web leaves it out for a viewer on this machine with `web.editor` set; a phone and the terminals show it.
+- `ctx.prompt_files` for plugins: the files whose text is in the session's system prompt now — the AGENTS.md chain
+  and the appended files — as absolute paths in prompt order.
+- The `agents-md` bundle, in the `core` profile (core 0.3.0: `chi update` installs it for existing core users):
+  a nested `AGENTS.md` of the session's checkout — one in a directory the session doesn't run in, which the
+  system prompt never sees — is steered into the conversation the first time a tool (`read`, `write` or
+  `edit`) touches a file under its directory, outermost first, once per session, and never re-injected after a
+  resume or a woken worker. It never stops generation or thinking, and leaves the chain's and appended
+  `AGENTS.md` files alone (`ctx.prompt_files`). Files in another repository, a nested repository or a
+  submodule are ignored. Opt out with `skip_agents_md: true`, as with the chain; `bundles: agents-md:`
+  settings: `tools`, `max_chars`. See "The agents-md bundle" in docs/plugins.md.
+
+### Changed
+
+- The default step limit (`turn.max_iterations`) is 300, up from 100: most long build turns now finish in one turn
+  instead of stopping at the step-limit question. Loops are caught by the loop-guard bundle, and check-in's card
+  (at 50 tool calls, then every 50) still says a turn is long without stopping it. `--no-interrupt` stays 1000.
+- Started in a subdirectory, chi loads every `AGENTS.md` from the top of the git work tree down to the current
+  directory, outermost first, instead of the subdirectory's replacing the root's. A further file is headed with its
+  directory ("Project specific description for pkg/:"); a session with one `AGENTS.md` gets the same prompt as before.
+
+### Fixed
+
+- A step-limit Continue no longer drops the turn's reasoning: on a chat host (`reasoning_history: turn`) the
+  continued turn sends the earlier replies' reasoning back as before the limit, and on a native host
+  (`/completion`) the prompt keeps the run's thought blocks, those before a mid-turn steer too. The model keeps its
+  thinking, and the first request after the Continue matches the last one before the limit (before the fix, a local
+  27B read most of a 17k prompt again: 24.9 s to the first token instead of 4.0 s). Continue's text is a steer, and on a chat host still starts
+  the reasoning afresh from it. After a `/model` change while the question stands, the Continue starts afresh.
+
+Update with `chi update`: the system bundle 0.60.0, the core profile 0.3.0 (now with agents-md) and the new
+agents-md 0.1.0 bundle.
+
 ## [0.59.0] - 2026-10-11
 
 ### Added
@@ -2576,7 +2623,8 @@ 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.59.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.60.0...HEAD
+[0.60.0]: https://github.com/dm1try/samagotchi/compare/v0.59.0...v0.60.0
 [0.59.0]: https://github.com/dm1try/samagotchi/compare/v0.58.0...v0.59.0
 [0.58.0]: https://github.com/dm1try/samagotchi/compare/v0.57.0...v0.58.0
 [0.57.0]: https://github.com/dm1try/samagotchi/compare/v0.56.0...v0.57.0

data/README.md

@@ -76,8 +76,9 @@ 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. Then it installs the `core` bundles (loop-guard,
-check-in, guardrails, slow-commands: the safety set for a small local model) and, on a
-terminal, offers `dev` (known-names, mcp, btw, skills, source-links). Edit the
+check-in, guardrails, slow-commands, agents-md: the safety set for a small
+local model) and, on a terminal, offers `dev` (known-names, mcp, btw, skills,
+source-links). Edit the
 file later as in [Configure](#configure); `chi bootstrap --help` has the
 options.
 

data/bin/chi

@@ -82,7 +82,7 @@ ARGV.each do |arg|
   base = arg.split("=", 2).first
   # If dashed version is a known flag (registry or hardcoded), reject underscore variant
   dashed = base.tr("_", "-")
-  known = %w[--prompt --resume --attach --shared --no-shared --model --thinking --memory --mute --llm-context --llm-context-apply --llm-context-budget --no-interrupt --non-interactive --verbose --no-default-input --port --open --new-token] + Samagotchi::Config.cli_entries.map(&:cli_flag)
+  known = %w[--prompt --resume --attach --shared --no-shared --model --thinking --memory --mute --append-system-prompt --llm-context --llm-context-apply --llm-context-budget --no-interrupt --non-interactive --verbose --no-default-input --port --open --new-token] + Samagotchi::Config.cli_entries.map(&:cli_flag)
   if known.include?(dashed) || known.include?(base)
     warn "Unknown option: #{arg} (did you mean #{dashed}?)"
     exit 1
@@ -120,6 +120,8 @@ parser = OptionParser.new do |opts|
                               "before the model's; default unsets it; /thinking changes it). With chi web: the default for the sessions " \
                               "its workers run, below a session's own [env SAMAGOTCHI_THINKING_LEVEL]") { |l| options[:thinking] = l }
   opts.on("--memory NAME", "Preload a memory entry into the system prompt (repeatable; a comma list too)") { |m| (options[:memories] ||= []) << m }
+  opts.on("--append-system-prompt FILE", "Put FILE's text into the system prompt, after AGENTS.md (repeatable; saved in the session; " \
+                                        "config append_system_prompt: is the baseline)") { |f| (options[:append_system_prompt] ||= []) << f }
   opts.on("--mute NAME", "Hide a memory from this session: not in the prompt, refused by memory_read (repeatable; a comma list too)") { |m| (options[:muted] ||= []) << m }
   opts.on("--llm-context LAYERS", "This session's own LLM context strategy: none, or layers such as stale,forget (saved in the session, " \
                                  "before the model's; /llm-context changes it)") { |v| (options[:llm_context] ||= {})[:strategy] = v }
@@ -308,6 +310,23 @@ if options[:llm_context]
   end
 end
 
+# --append-system-prompt: each file is checked here, before anything starts
+# (the user named it, so a missing one is an error), and made absolute
+# against this shell's cwd.
+if options[:append_system_prompt]
+  require "samagotchi/prompt_files"
+  options[:appended_prompt_files] = options[:append_system_prompt].map do |value|
+    path, reason = Samagotchi::PromptFiles.check_cli_file(value)
+    if reason
+      warn "Error: --append-system-prompt #{value}: #{reason}"
+      exit 1
+    end
+    chars = Samagotchi::PromptFiles.large_size(path)
+    warn "Warning: --append-system-prompt #{value} is #{chars} chars; it is in every request" if chars
+    path
+  end.uniq
+end
+
 chi_update_hint.call
 require "samagotchi/launch_mode"
 launch, launch_note = if scratch
@@ -341,7 +360,8 @@ if launch == :attached
                                                        memories: options[:memories] || [],
                                                        muted_memories: options[:muted] || [],
                                                        llm_context: options[:llm_context] || {},
-                                                       thinking: options[:thinking])
+                                                       thinking: options[:thinking],
+                                                       appended_prompt_files: options[:appended_prompt_files] || [])
   rescue Samagotchi::TerminalUI::AttachLauncher::Error => e
     warn "Error: #{e.message}"
     exit 1
@@ -360,6 +380,7 @@ begin
     muted_memories: options[:muted] || [],
     llm_context: options[:llm_context] || {},
     thinking: options[:thinking],
+    appended_prompt_files: options[:appended_prompt_files] || [],
     non_interactive: options[:non_interactive],
     model_name: options[:model],
     scratch: scratch

data/docs/architecture.md

@@ -177,7 +177,8 @@ forwards the raw `KernelLoop` events unchanged (the low-level contract) and adds
 higher-level events so UIs get clean turn boundaries without inferring them:
 
 - `:turn_started` — `{ session_id:, prompt:, turn_id:, cut_after: }` (`cut_after`: the seconds a cut waits for this
-  model's thinking, `0` = never; plus `continue: true` for a continue turn, `images:` with the prompt's image refs)
+  model's thinking, `0` = never; plus `continue: true` for a continue turn, `resumed: true` for a step-limit Continue,
+  `images:` with the prompt's image refs)
 - `:turn_completed` — `{ result:, turn_summary:, display_pending: }` (`result`: the final
   `LLM::ModelResult`; `display_pending`: `after_turn` hooks may still present the answer)
 - `:turn_canceled` — `{ cancellation_reason:, cancelled_by:, duration_ms: }` (`cancelled_by`: the bundle or hook label that
@@ -394,7 +395,8 @@ stream with a fresh `ThoughtStreamSplitter` (Qwen's `<think>` and Gemma's
 `<|channel>thought … <channel|>` are thinking, tool-call bodies are dropped
 from `text:`). The chat loop's model turns keep their `tool_calls` and tool results their `tool_call_id`,
 so later requests and resumed sessions pair them, and their reasoning (`thinking:`), which goes back as
-`reasoning_content` on the running turn's replies (`reasoning_history`). It has its own system prompt
+`reasoning_content` on the running turn's replies (`reasoning_history`; a step-limit Continue's
+turn goes on from the run it resumes, `reasoning_since:`). It has its own system prompt
 (no raw-prompt tool declarations; the tools go as JSON schemas).
 
 `Engine#build_stream_event_handler` is the one seam both loops' streams pass

data/docs/cli.md

@@ -189,6 +189,7 @@ controls exit behavior (`--non-interactive`); `--resume` composes with both.
 | `--thinking LEVEL` | This session's own thinking level: `off`, `low`, `medium` or `high`, saved in the session and first in the order (`default` unsets it). On `--resume` or `--attach` it is set at once, through a `/thinking` on an attached worker. With `chi web` it is instead the default for the sessions its workers run, below a session's own (as env `SAMAGOTCHI_THINKING_LEVEL` is). 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. |
+| `--append-system-prompt FILE` | Put `FILE`'s text into the system prompt, after AGENTS.md and before the memory indexes (repeatable; relative to the shell's directory). Added after the config.yml `append_system_prompt:` list. A missing or unreadable file is an error, exit 1. Saved in the session, so a respawned worker, a fork and a continue keep it; ignored with `--attach`/`--resume` (one line, as `--memory`). See [Appended prompt files](configuration.md#appended-prompt-files). |
 | `--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). |
 | `--llm-context LAYERS` | This session's own LLM context strategy: `none`, or layers such as `stale` or `stale,forget` (comma, space or `\|` separated). Saved in the session, before the model's `llm_context_strategy`. With `--resume` it is set on the resumed session; on an attached or resumed worker it runs as `/llm-context` before the first prompt (after `--model`'s `/model`). A value that isn't one is an error before anything starts. See "LLM context: a session's own strategy" in configuration.md. |
 | `--llm-context-apply RULE` | This session's own apply rule: `payoff`, `next_request` or `turn_end`. |
@@ -504,7 +505,8 @@ back from the next turn on, and where that came from (`session`,
 comes first; `/reasoning-history default` unsets it. It is saved and carried as
 `/thinking`'s is, and a native host ignores it (the reply says so). A change to
 or from `all` once an earlier reply has thinking rewrites the earlier replies;
-`drop` ↔ `turn` costs nothing. `/stats` shows it on its `reasoning history:`
+`drop` ↔ `turn` costs nothing. Under `turn` a step-limit Continue keeps the
+reasoning of the turn it continues. `/stats` shows it on its `reasoning history:`
 line, the web as the `reasoning` chip. See "Reasoning history" in
 [configuration.md](configuration.md).
 
@@ -997,7 +999,7 @@ Behavior notes:
 ## Iteration Limit Behavior
 
 - A turn's step limit (model ↔ tool rounds) is `turn.max_iterations` in config.yml (env
-  `SAMAGOTCHI_TURN_MAX_ITERATIONS`, default `100`, an integer of 1 or more). `--no-interrupt` and
+  `SAMAGOTCHI_TURN_MAX_ITERATIONS`, default `300`, an integer of 1 or more). `--no-interrupt` and
   `--non-interactive` turns get the larger of 1000 and it. Reminder turns follow it too.
 - Tool side effects that already ran before the limit are not rolled back.
 - `Samagotchi::KernelLoop#run` returns a resumable result object with the visible output plus the accumulated
@@ -1016,9 +1018,13 @@ Behavior notes:
 - In the plain REPL (`--no-shared`) the CLI asks at the `? ` prompt, with the choices listed under it: `yes` (Enter
   alone, or `/continue`) resumes, `no` stops, and `no, <explanation>` stops while keeping the reason in conversation
   context. Once answered, one line stays: `? The turn ran out of iterations. Continue it? → no, too slow`.
+- Continue goes on with the same turn: the model keeps the reasoning (thinking) of the run it continues, on chat and
+  native hosts, so a local server's prompt cache stays warm. Continue's text is a steer: on a chat host the reasoning
+  starts again from it. See "Reasoning history" in [configuration.md](configuration.md).
 - Stop keeps the interrupted turn's work in the conversation, as a Ctrl-C or a new prompt does, with a note for the
   model that it wasn't continued (or your reason); `!rollback` still erases it.
 - `--non-interactive` (`chi -p`) has nobody to ask: the turn ends there. A `chi send --wait` on a session nobody can
   answer (an older worker) reports `limit` (exit 1) with how to continue it: `chi send ID -m '/continue yes'`.
 - The check-in bundle's card closes as the turn ends, before the step-limit question opens, so the two never stand
-  together; with check-in's default `after: 50` and the limit of 100 a long turn usually shows a check-in card first.
+  together; with check-in's default `after: 50` and the limit of 300 a long turn shows check-in cards (at 50, 100, …)
+  well before it.

data/docs/configuration.md

@@ -81,6 +81,13 @@ session:
 memories:
   # - system/user_preferences
   # - project/feature-env-template
+
+# Files whose text goes into the system prompt after AGENTS.md (same as
+# --append-system-prompt, which adds to these). A relative entry is looked up
+# in the directory chi runs in; a missing one is skipped.
+append_system_prompt:
+  # - CLAUDE.md
+  # - ~/notes/house-rules.md
 ```
 
 Behavior:
@@ -108,8 +115,8 @@ Besides the settings sections, the file holds maps that are read by their
 own subsystems: `hosts:` (below), `models:` (see "Prompt profile" and
 "Images"), `model_aliases:`, `hooks:` (see [Hooks](hooks.md)),
 `guardrails:` (see [Guardrails](guardrails.md)), `bundles:` (a bundle's
-settings for its hooks, see [Hooks: Settings](hooks.md#settings)) and
-`memories:`. Their entry names (host names, model ids, aliases) are yours to
+settings for its hooks, see [Hooks: Settings](hooks.md#settings)),
+`memories:` and `append_system_prompt:` (see "Appended prompt files"). Their entry names (host names, model ids, aliases) are yours to
 choose. The `memories:` list is the persistent baseline for preloaded memory entries —
 the same name shape as `--memory` (bare name or `scope/name`), merged under
 any per-run `--memory` values (config baseline first, deduped). A per-run
@@ -561,8 +568,13 @@ models:
   reasoning as `reasoning_content`, which is what Qwen's, Gemma 4's and DeepSeek's chat templates and the hosted APIs
   (OpenRouter takes it for DeepSeek, Qwen and other text-reasoning models) expect. The running turn starts at the
   last message you sent (a prompt, or a steer: as the chat template counts it) and never before the turn's own start,
-  so a turn that goes on by itself (a reminder, a context wake, a continue after a stop) sends nothing of the one
-  before it, an interrupted reply's partial thought included.
+  so a turn that goes on by itself (a reminder, a context wake, a delegate report's wake) sends nothing of the one
+  before it, an interrupted reply's partial thought included. A **step-limit Continue** is the same turn going on: it
+  keeps the reasoning of the run it continues (back to the first run of a chain of Continues), so its first request
+  matches the last one before the limit and the server's prompt cache stays warm. Continue's text, or a `!cmd` run
+  while the step-limit question stands, is a user message: the reasoning before it goes, as for any steer, and that
+  Continue reads the conversation again once (a re-prefill on a local server). After a `/model` change while the
+  question stands the Continue starts afresh (no other model's reasoning is sent).
 - `drop` sends none (what chi did before this setting).
 - `all` sends every reply's reasoning, earlier turns too. It sends only the field: a local template that leaves out
   earlier turns' reasoning (Qwen's) needs `sampling: {chat_template_kwargs: {preserve_thinking: true}}` as well.
@@ -586,7 +598,8 @@ models:
   | nothing thought yet, the same level, or a native host | none |
 
 - The native loop (`/completion`) ignores it: it always keeps the running turn's reasoning, a mid-turn steer included
-  (the chat loop starts again after a steer).
+  (the chat loop starts again after a steer), and a step-limit Continue keeps the thoughts of the run it continues,
+  a mid-turn steer's earlier ones included.
 - When a host answers a request that sent reasoning back with an HTTP 400 about reasoning, chi asks again without it,
   sends none to that model from then on (until the worker restarts) and says so once. If the request without it is
   refused too, the thinking fields get the same fallback ("Thinking") and the reasoning goes back on the next step.
@@ -1074,13 +1087,50 @@ The helper reads these from its launch file: after editing them run
 If an AGENTS.md file is present in the project root, samagotchi injects its
 contents into the system prompt under a "Project specific description:" section.
 The project root is the top of the git work tree chi runs in (a linked
-worktree's own checkout), or the current directory outside a repository. An
-AGENTS.md in the current directory is read instead when there is one; only one
-file is read.
+worktree's own checkout), or the current directory outside a repository.
+
+Started in a subdirectory, chi loads the chain: every AGENTS.md from the work
+tree top down to the current directory, outermost first. The first keeps the
+plain header; each further one is headed with its directory, e.g. "Project
+specific description for pkg/:". Outside a repository only the current
+directory's AGENTS.md is read. Edits are picked up by a new process or a
+prompt rebuild (`/model`).
 
-To skip loading AGENTS.md, set `skip_agents_md: true` at the top level of
+To skip loading AGENTS.md (all of the chain), set `skip_agents_md: true` at the top level of
 `config.yml` (env `SAMAGOTCHI_SKIP_AGENTS_MD=true`).
 
+Nested `AGENTS.md` files (in directories the session doesn't run in) are
+steered into the conversation on first touch by the `agents-md` bundle
+([The agents-md bundle](plugins.md#the-agents-md-bundle)); `skip_agents_md`
+disables that steering too.
+
+## Appended prompt files
+
+`append_system_prompt:` (a top-level list) and `chi --append-system-prompt FILE`
+(repeatable) put a file's text into the system prompt right after the AGENTS.md
+chain and before the memory indexes, in the stable part a prompt cache keeps.
+Each file is one section, `Appended from <path>:`, the path relative to the
+work tree top when inside it, else with `~`.
+
+- The config list comes first, then the flag's files; a repeat, or a file the
+  AGENTS.md chain already holds, is left out, and so is an empty file.
+- A config entry: `~` is expanded, and a relative one is looked up in the
+  directory chi runs in, so `append_system_prompt: [CLAUDE.md]` loads a
+  project's `CLAUDE.md` wherever there is one. A missing entry is skipped
+  without a warning. The list is read when the session's engine starts (a new
+  process picks up an edit).
+- `--append-system-prompt FILE`: relative to the shell's directory. A missing,
+  unreadable or non-file `FILE` stops chi (`Error: --append-system-prompt FILE:
+  no such file`); above 32,000 chars it warns once (`… is N chars; it is in
+  every request`). The files are saved in the session (`appended_prompt_files`),
+  so a respawned worker builds the same prompt, and a fork or a continue keeps
+  them; a delegate child doesn't. With `--attach` or `--resume` the flag is
+  ignored with one line, as `--memory` is; a REPL `--resume` (`--no-shared`)
+  adds them for that run only.
+- The files' text is read at each prompt build, as AGENTS.md's is: an edit is
+  picked up by a new process or a rebuild (`/model`). `/stats` lists the files
+  in the prompt on its `prompt files:` line.
+
 ## LLM context: the forget layer
 
 Experimental, off by default. With `forget` in a model's `llm_context.strategy` (next to `stale`), chi offers that
@@ -1219,8 +1269,8 @@ Every setting below takes the three forms described in
 `config.yml`, `SAMAGOTCHI_<DOTTED_NAME>` in the environment (not for one
 marked config.yml only) and, where the CLI
 column says so, a `--kebab-name` flag. The maps (`hosts:`, `models:`,
-`model_aliases:`, `hooks:`, `guardrails:` rules, `bundles:`, `memories:`) are
-described in their own sections.
+`model_aliases:`, `hooks:`, `guardrails:` rules, `bundles:`, `memories:`,
+`append_system_prompt:`) are described in their own sections.
 
 | Setting | Default | CLI | What it does |
 |---|---|---|---|
@@ -1306,7 +1356,7 @@ described in their own sections.
 | `retry.empty_answer` | `1` | | Times a turn asks again after an empty answer (at most 3, `0` = off). See "Llama Network Retry Behavior". |
 | `steer.cut_after` | `20` | | Seconds a generation must have streamed only thinking before a message sent as a cut (`/cut TEXT`, `chi send --cut`) cuts it; other messages go in at the next step; `0` = never. `models.<key>.steer_cut_after` and `hosts.<name>.steer_cut_after` come first; see [Messages during a running turn](#messages-during-a-running-turn-steer-and-cut). |
 | `models.<key>.steer_cut_after`, `hosts.<name>.steer_cut_after` | none | | A model's or host's seconds a cut waits for its thinking: whole seconds, `0` = never (e.g. a slow local thinker). `/model` shows the resolved one. See [Messages during a running turn](#messages-during-a-running-turn-steer-and-cut). |
-| `turn.max_iterations` | `100` | | A turn's step limit: model ↔ tool rounds before it stops and asks to continue (an integer ≥ 1). `--no-interrupt` turns get the larger of 1000 and this. See [CLI: Iteration Limit Behavior](cli.md#iteration-limit-behavior). |
+| `turn.max_iterations` | `300` | | A turn's step limit: model ↔ tool rounds before it stops and asks to continue (an integer ≥ 1). `--no-interrupt` turns get the larger of 1000 and this. See [CLI: Iteration Limit Behavior](cli.md#iteration-limit-behavior). |
 | `turn.parent_continue` | `true` | | Whether a parent agent (`chi answer`) may answer Continue to a session's step-limit question; `false`: Stop only. config.yml only: no environment variable. See [Sub-agent](sub-agent.md) and [Guardrails](guardrails.md#approvals-from-a-parent-agent). |
 | `update.gem` | `true` | | `false`: `chi update` never installs a newer gem (`--no-gem` for one run). See [CLI: Updating](cli.md#updating). |
 | `update.bundles` | `true` | | `false`: `chi update` leaves the shipped bundles to `chi bundle upgrade` (`--no-bundles`). |

data/docs/hooks.md

@@ -50,7 +50,7 @@ The plugin class must respond to `#call(event)` — duck-typed, no base class re
 | Event | When it fires | Event payload |
 |-------|--------------|---------------|
 | `:session_start` | The first turn this chi process runs for the session (so again after `--resume`, a worker that idle-exited and woke, or a restart) | `{ type: :session_start, session_id: "..." }` |
-| `:before_turn` | Before each turn starts | `{ type: :before_turn, session_id: "...", prompt: "..." (nil on a continue), messages: [...] (the history before this turn) }` |
+| `:before_turn` | Before each turn starts | `{ type: :before_turn, session_id: "...", prompt: "..." (nil on a continue), resumed: true \| false (true on a step-limit Continue, which resumes the run before it; false on every other turn, a reminder's or a wake's too), messages: [...] (the history before this turn) }` |
 | `:after_turn` | After a turn completed or was stopped once the model was asked (not after one that failed, was cut short by an interrupt signal (SIGINT), or was stopped before its `:before_turn` hooks) | `{ type: :after_turn, status: "completed" \| "canceled", present: (see [Presenting the answer](#presenting-the-answer-display-only)), messages: [...] (the conversation the turn stored; a cancelled or empty turn ends it with a `kind: turn_note` system message, and a context line is `kind: context`, see [sessions.md](sessions.md#notes-a-turn-leaves-for-the-model)) }` |
 | `:before_generation` | Before each LLM API call (both loops) | `{ type: :before_generation, iteration: N }` |
 | `:after_generation` | After LLM returns (both loops); not after a generation a hook cut (`stop_generation`) | `{ type: :after_generation, iteration: N, response: "...", messages: [...] (the conversation as sent) }` |
@@ -117,7 +117,7 @@ known-names)` for a bundle hook, `audit.rb (config)` for a config hook,
 `turn hook` for one registered at runtime.
 
 `event[:notify]` also takes `fallback_for:`, what the line stands in for, so
-that a UI that already shows it can leave the line out. The one value is
+that a UI that already shows it can leave the line out. The main value is
 `:display`: the line repeats what the hook's
 [`event[:present]`](#presenting-the-answer-display-only) display shows (its
 links), for a UI that doesn't render that display. The hook never names a UI;
@@ -125,7 +125,13 @@ each decides by what it renders. The web with markdown on (`web.markdown` and
 the commonmarker gem) leaves such a line out, live and after a reload; with
 markdown off it shows, as it does in the REPL, the attached TUI and
 `chi -p`, which print the answer as text. The log keeps the line with
-`fallback_for=display`. Another value, or none, shows the line everywhere.
+`fallback_for=display`. `:editor` marks a line that names a file the viewer
+could open from a ref in its editor: the web leaves it out for a viewer on
+this machine with `web.editor` set, and every other UI and viewer (a phone,
+the terminals) shows it. Name only a file the page shows as a ref (one a
+tool row touched): a loopback viewer with `web.editor` set never sees the
+line, so a file it can't open from a ref would be lost to it. Another value,
+or none, shows the line everywhere.
 Mark a line only when the display really shows all of it (source-links marks
 its note only when the answer links every URL the note names). It needs chi
 0.35.0: an older chi's `event[:notify]` raises `ArgumentError` on the keyword,
@@ -507,7 +513,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). There `ctx.notify`, `ctx.steer` and the other `ctx` helpers act as this page's `event[:notify]`… do for the event the block runs for.
-- Shipped bundles (each in a profile: `core` or `dev`, see [Bundle profiles](memory.md#bundle-profiles-core-and-dev)): `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)), `chi bundle install slow-commands` (a plugin: commands that ran past the execute limit are run as tasks next time, see [Plugins](plugins.md#the-slow-commands-bundle)) and `chi bundle install skills` (a plugin: `/skill`, versions of skills, see [Plugins](plugins.md#the-skills-bundle)).
+- Shipped bundles (each in a profile: `core` or `dev`, see [Bundle profiles](memory.md#bundle-profiles-core-and-dev)): `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)), `chi bundle install slow-commands` (a plugin: commands that ran past the execute limit are run as tasks next time, see [Plugins](plugins.md#the-slow-commands-bundle)), `chi bundle install agents-md` (a plugin: a nested AGENTS.md is steered into the conversation on the first touch under its directory, see [Plugins](plugins.md#the-agents-md-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:

data/docs/internals/engine.md

@@ -16,25 +16,28 @@ Engine#run_turn → backend.complete(...) → KernelLoop#run (native) or ChatLoo
 
 ```
 Engine#run_turn(session, prompt, on_event:, max_iterations:, cancel_controller:, max_tool_output_chars:,
-                pending_input:, continue:, origin:, images:, id:)
+                pending_input:, continue:, origin:, images:, id:, resumed:, resume_from:)
   │
   ├── begin_turn(session, prompt, on_event:, cancel_controller:, origin:, continue:, id:)
+  │     # (then, on a continue, turn.resumed = resumed (a step-limit Continue) and
+  │     #  turn.resume_from = resume_from (its run's start; nil: it starts cold))
   │     # @session = session, session.status = RUNNING, used memories absorbed,
   │     # TurnState#begin!(controller:, sink:) (a new CancellationController when none is given),
   │     # a recap in flight invalidated, GuardrailWiring#begin_turn(origin)
   │     # Returns a Turn {session, prompt (nil on a continue), continue, on_event, controller,
-  │     #                 origin, started_at, id (the caller's id:, else a new uuid)}
+  │     #                 origin, started_at, id (the caller's id:, else a new uuid), resumed, resume_from}
   │
   ├── Client.swap_probe_cancel(turn.controller)   # a Stop cuts this turn's /props probes
   │
   ├── prepare_turn(turn, images)
   │     # Emits :turn_started {session_id, prompt, turn_id, continue: true (only on a continue),
+  │     #                      resumed: true (only on a step-limit Continue: resumed: given),
   │     #                      images (only when there are any), cut_after (the model's cut wait, s)}
   │     # refresh_profile! (may ask the server's /props once)
   │     # turn.settings = LLM::TurnSettings (vision, sampling, thinking; model_name is set in generate)
   │     # announces guardrail load failures, starts and awaits plugin init tasks, applies staged tools
   │     # fires the :session_start hook on the Engine's first turn, then the :before_turn hook
-  │     #   (a frozen copy of the history, and the prompt)
+  │     #   (a frozen copy of the history, the prompt, and resumed)
   │     # turn_messages: system head + history + due reminders (:reminder_injected) + the user message
   │     # Returns false when a Stop came during the probes or the init wait, else true
   │
@@ -128,10 +131,13 @@ parses tool calls out of the generated text.
 
 ```
 KernelLoop#run(messages, max_iterations:, on_stream_event:, cancel_controller:,
-               model_name:, max_tool_output_chars:, pending_input:)
+               model_name:, max_tool_output_chars:, pending_input:, reasoning_since:)
   │
   │ turn = start_turn(...)   # turn.conversation = prepare_conversation(messages): a copy,
-  │                          # old model messages without their thought blocks
+  │                          # old model messages without their thought blocks, but a resumed
+  │                          # run's (a step-limit Continue's reasoning_since:, #thought_floor:
+  │                          # all of them, a steer merged mid-run included; only a user entry
+  │                          # added after the run's last reply starts them past itself)
   │ each iteration:
   │ 1. Queued input (user lines, plugin steers) goes in at the boundary (Steer.inject!)
   │ 2. Format the conversation as prompt text (Prompt.format_with_images); a context
@@ -179,8 +185,10 @@ The differences from the native loop:
   `Session#reasoning_history`, `/reasoning-history`): `all` on every model message, `turn` past
   `ChatLoop#reasoning_boundary`: the later of the last query (a `role: "user"` entry: a prompt, a steer, merged input,
   the chat template's `last_query_index`; or a `turn_start` entry) and the Run's start (`Run`'s `@start`, the
-  conversation length at `#complete`), so a continue turn (reminder, context wake, continue after a stop) replays
-  nothing of the run before. `Run#prompt_chars` counts it (`#reasoning_chars`). The native loop differs on a steer:
+  conversation length at `#complete`), so a continue turn (reminder, context wake, delegate report wake) replays
+  nothing of the run before. A step-limit Continue's Run starts where the run it resumes did: `#complete`'s
+  `reasoning_since:` (the Engine's `resume_from`, checked against the messages' length in `#resumed_run_start`) is
+  the Run's `@start`. `Run#prompt_chars` counts it (`#reasoning_chars`). The native loop differs on a steer:
   `KernelLoop#inject_pending_input!` doesn't re-sanitize, so native keeps the turn's reasoning across a mid-turn
   steer, where the chat loop starts again (as the template does).
 - A 400 about reasoning (`BadRequest#reasoning_refused?`) for a request that sent reasoning back asks the step again
@@ -322,7 +330,7 @@ Turn events (the main ones; `Events` in `events.rb` keeps the shared sets):
 
 | Event | When | Payload |
 |---|---|---|
-| `:turn_started` | `prepare_turn` | `{session_id, prompt, turn_id, continue?, images?, cut_after}` |
+| `:turn_started` | `prepare_turn` | `{session_id, prompt, turn_id, continue?, resumed?, images?, cut_after}` (`resumed`: a step-limit Continue) |
 | `:reminder_injected` | due reminders went into the turn | `{reminders}` |
 | `:context_status` | every request (unless `context.status` is off), the current estimate before it | `{iteration, status, usage, bucket, source}` (internals/context-telemetry.md) |
 | `:generation_started` | a request begins | `{iteration, context_window_tokens, context_window_source, price}` (`price`: the turn's `ModelPrice#to_h`, nil without one; native adds `profile`, `profile_source`) |

data/docs/internals/gemma4-contract.md

@@ -18,6 +18,7 @@ Thought handling follows the Gemma guidance:
 - When thinking mode is active, the model may emit internal reasoning as `<|channel>thought ... <channel|>`.
 - Standard multi-turn: prior model thoughts are stripped from conversation history before the next turn.
 - Function/tool-calling exception: during a single turn that includes tool calls, thoughts are not stripped between those tool-call rounds.
+- A step-limit Continue is that same turn going on: the run it resumes keeps its thoughts (`KernelLoop#run`'s `reasoning_since:`, from the Engine's `resume_from`), from its start, a steer merged inside that run included (nothing re-sanitizes within a run, so the prompt before the limit had them); only a user entry added after the run's last reply (a `!cmd`'s output) starts them past itself. Every other turn (a prompt, a reminder, a wake) strips them as above.
 - Final model output returned to the caller is thought-stripped.
 - While a generation streams, the thought channel goes to the stream's `thinking:` lane, not `text:` (`ThoughtStreamSplitter.for_profile`, fresh per generation), so the UIs show it as thinking and `:generation_progress` hooks count it in `thinking_chars`.
 

data/docs/internals/prompt-caching.md

@@ -31,8 +31,9 @@ right-hand column happens.
 │   system identity (+ model overlay)                                      │  /model, editing a
 │   model notes (model_notes_* matching the model)                         │  memory / AGENTS.md
 │   explicit (preloaded) memories                                          │
-│   AGENTS.md                                                              │  (picked up by a new
-│   project + system memory indexes                                        │  process or a rebuild)
+│   AGENTS.md (root → cwd)                                                 │  (picked up by a new
+│   appended files (append_system_prompt:, --append-system-prompt)         │  process or a rebuild)
+│   project + system memory indexes                                        │
 │                         ◄── remote Claude: cache_control breakpoint #1   │
 ├──────────────────────────────────────────────────────────────────────────┤
 │ SYSTEM, volatile tail (per session, least → most changing)               │

data/docs/memory.md

@@ -269,7 +269,7 @@ profiles, meta bundles that install a set of them:
 
 | profile | bundles |
 |---|---|
-| `core` | loop-guard, check-in, guardrails, slow-commands: the recommended safety set |
+| `core` | loop-guard, check-in, guardrails, slow-commands, agents-md: the recommended safety set |
 | `dev` | known-names, mcp, btw, skills, source-links, github-pr, coordinator |
 
 `chi bootstrap` installs `core` and, on a terminal, offers `dev`. An existing

data/docs/plugins.md

@@ -515,7 +515,8 @@ full label, `plugin.rb (bundle my-bundle)`.
 | `ctx.log` | `ctx.log.info(:event, key: value)`: debug-log records tagged `plugins`, with `bundle=<bundle>` |
 | `ctx.messages` | the conversation, as a frozen copy, without the system prompt. While a turn runs, a session worker's (attached, web) adds that turn so far: its prompt, the model's text and the lines merged into it (no tool calls or thinking); the REPL's is the conversation before that turn |
 | `ctx.messages_partial?` | whether `ctx.messages` leaves out a running turn (the REPL mid-turn), so a plugin can say what its answer is about |
-| `ctx.notify(text, level: :info, fallback_for: nil)` | one line to the user, labelled by the bundle (`my-bundle> …`). Every UI shows it, during a turn (a tool, a hook) or between turns (a command). `fallback_for: :display` marks a line that repeats the answer's display (`event[:present]`), which a UI that renders the display leaves out: see [Hooks](hooks.md#what-a-hook-can-do-the-runtime). The keyword needs chi 0.35.0 (it raises on an older chi) |
+| `ctx.prompt_files` | the files whose text is in the session's system prompt now: the AGENTS.md chain (the work tree top down to the cwd) and the appended files (`append_system_prompt:`, `--append-system-prompt`); absolute paths, in prompt order, `[]` before the first build |
+| `ctx.notify(text, level: :info, fallback_for: nil)` | one line to the user, labelled by the bundle (`my-bundle> …`). Every UI shows it, during a turn (a tool, a hook) or between turns (a command). `fallback_for: :display` marks a line that repeats the answer's display (`event[:present]`), which a UI that renders the display leaves out (`fallback_for: :editor`: a file the viewer could open from a ref in its editor): see [Hooks](hooks.md#what-a-hook-can-do-the-runtime). The keyword needs chi 0.35.0 (it raises on an older chi) |
 | `ctx.card(title:, body: "", actions: [], level: :info, id: nil)` | a card in every UI, returning its id: see [Cards](#cards) |
 | `ctx.ask_user(question:, options:, header: nil, allow_freeform: false)` | a single-select question through the question flow: `{selected:, freeform:, selected_indices:}`, or nil (no one to ask, cancelled, bad options) |
 | `ctx.cancelled?` | whether the running turn was cancelled (a long tool should stop) |
@@ -1254,6 +1255,54 @@ bundles:
 | `/slow-commands` | this project's slow commands, numbered |
 | `/slow-commands forget 2` / `forget all` | drop one (a wrong entry) or all of them |
 
+## The agents-md bundle
+
+`chi bundle install agents-md` (or the `core` profile) installs the bundle shipped
+with chi (`lib/samagotchi/bundles/agents-md/plugin.rb`): two `chi.on` hooks
+(`:before_turn` rebuilds the steered set, `:after_tool_call` steers), and no memory file.
+
+chi's system prompt holds only the `AGENTS.md` chain from the checkout top down
+to the session's cwd, so an `AGENTS.md` in a directory the session doesn't run
+in (say `pkg/inner/` while the session runs in `pkg/`) is never seen. The
+bundle closes that gap in history, not in the system prompt: the first `read`,
+`write` or `edit` (its `tools` setting) of a file under a directory with an
+`AGENTS.md` steers that file into the running turn, at the loop's next
+boundary, as its own user message — with a first line that says which
+directory it belongs to:
+
+```
+AGENTS.md for pkg/inner/ (applies to work under pkg/inner/):
+<content>
+```
+
+- It steers the **outermost candidates first** (each directory from the
+  touched file's directory up to, but not including, the checkout top), so a
+  deep file can bring in several `AGENTS.md`s at once, outermost to nearest.
+- It **never re-injects**: each directory steers once per session, and a
+  `before_turn` pass over the conversation rebuilds that set from the steers
+  already there. A steer the model answered past (never injected) is absent,
+  so it fires again on the next touch; a resume, a woken worker or a fork
+  pick the set up from their messages. It never stops generation or thinking.
+- **Scope:** the touched file's own git root must be the session's checkout:
+  a file in another repository, a nested repository or a submodule is
+  ignored. Paths compare by `File.realpath`, so a symlinked cwd (a macOS
+  `/tmp`) still matches.
+- Directories whose `AGENTS.md` is already in the system prompt (`ctx.prompt_files`:
+  the chain and appended files) are skipped, as is a file at the checkout top
+  (its `AGENTS.md` is the chain's first).
+
+```yaml
+# config.yml
+bundles:
+  agents-md:
+    tools: [read, write, edit]   # the calls that count as a touch
+    max_chars: 16000            # the content is cut here, with a "[cut at N
+                                # of M chars: read <absolute path> for the rest]" last line
+```
+
+`skip_agents_md: true` disables the bundle, as it does the chain's loading
+(see [Configuration](configuration.md#project-specific-description)).
+
 ## The skills bundle
 
 `chi bundle install skills` (or the `dev` profile) installs the bundle shipped with chi