samagotchi 0.4.0 → 0.5.0

data/lib/samagotchi/bundles/skills/plugin.rb

@@ -0,0 +1,419 @@
+# The skills bundle (docs/plugins.md, The skills bundle): a skill is a memory
+# named skill_<name> that holds the steps of a task done with the user
+# (docs/memory.md, Skills). The system bundle's identity already tells the
+# model to save, follow and update skills; this bundle adds `/skill` for the
+# user and keeps an eye on the model's rewrites.
+#
+# History: before memory_write, write or edit changes a skill's file, the
+# file as it was is kept under $XDG_STATE_HOME/samagotchi/plugins/skills/
+# history/<scope>/<name>/<UTC time>.md (state, not the memories dir, so
+# bundle build and dotfile syncs never see it), history_keep per skill. The
+# after_tool_call of that call (calls run one at a time; that event carries
+# no call, so the before side stashes it) compares the file on disk and
+# shows a line: "skill release updated (+2 −1): …" or "skill release saved
+# (project, 14 lines)".
+#
+# The nudge (nudge: true), for models that skip a failing step instead of
+# fixing the skill: in a turn that read a skill (memory_read of a skill_*
+# name, or a read of its file), the first failing tool call after it (an
+# execute with "exit: N", N ≠ 0, or with no exit line an Error: line near
+# the top; any tool's "[tool] Error: …") steers the model once to find out
+# why and fix the skill. At the turn's end, a failed step with no rewrite of
+# the skill gets a notice line.
+#
+# Settings (config.yml, bundles: skills:):
+#   history_keep: 20   older versions kept per skill
+#   nudge: true        steer the model once when a skill's step fails
+require "date"
+require "fileutils"
+
+class Plugin
+  WRITE_TOOLS = %w[memory_write write edit].freeze
+  NOTICE_WIDTH = 60 # the changed line in an update's notice
+  NUDGE = "A step of skill %s failed. Find out why before skipping it; if the skill is out of date, fix it now: " \
+          "memory_write the whole skill, its title and every section as they were, that step fixed, a Changelog " \
+          "line added."
+  NOT_FAILURES = %w[memory_read memory_write].freeze
+  USAGE = "usage: /skill save [name] [--system] | list | show <name> | diff <name> [N]"
+
+  def initialize(settings = {})
+    settings = {} unless settings.is_a?(Hash)
+    @history_keep = positive(settings["history_keep"]) || 20
+    @nudge = settings.key?("nudge") ? settings["nudge"] != false : true
+    @stash = nil
+    reset_turn
+  end
+
+  def register(chi)
+    chi.on(:before_turn) { |_event, _ctx| reset_turn }
+    chi.on(:after_turn) { |_event, ctx| after_turn(ctx) }
+    chi.on(:before_tool_call) { |event, ctx| before_tool_call(event, ctx) }
+    chi.on(:after_tool_call) { |event, ctx| after_tool_call(event, ctx) }
+    chi.command "/skill", "skills (steps of a task we did): save [name] [--system], list, show <name>, diff <name> [N]",
+                anytime: true do |args, ctx|
+      command(args.to_s.strip, ctx)
+    end
+  end
+
+  private
+
+  # --- a skill's file changes ----------------------------------------------
+
+  def before_tool_call(event, ctx)
+    @stash = nil
+    tool = event.dig(:call, :name).to_s
+    note_read(tool, event)
+    return unless WRITE_TOOLS.include?(tool)
+
+    path = Array(event.dig(:targets, :paths)).find { |target| skill_at(target) }
+    return unless path
+
+    scope, name = skill_at(path)
+    old = File.file?(path) ? File.read(path) : nil
+    keep_version(ctx, scope, name, old) if old
+    @stash = { tool: tool, path: File.expand_path(path), scope: scope, name: name, old: old }
+  end
+
+  # Success is the file changed on disk, whatever the output says. A call
+  # that didn't match the stash (a cancelled turn fires no before) drops it.
+  def after_tool_call(event, ctx)
+    stash = @stash
+    @stash = nil
+    step_failed(event) if @nudge && !@read.empty?
+    return unless stash && stash[:tool] == event[:tool].to_s
+
+    now = File.file?(stash[:path]) ? File.read(stash[:path]) : nil
+    return if now.nil? || now == stash[:old]
+
+    @written << stash[:name]
+    ctx.notify(change_notice(stash, now))
+  end
+
+  def change_notice(stash, now)
+    name = stash[:name]
+    return "skill #{name} saved (#{stash[:scope]}, #{now.lines.size} lines)" unless stash[:old]
+
+    ops = line_diff(stash[:old].lines(chomp: true), now.lines(chomp: true))
+    added = ops.count { |op, _| op == :add }
+    removed = ops.count { |op, _| op == :del }
+    first = ops.find { |op, _| op == :add } || ops.find { |op, _| op == :del }
+    line = first ? cut(first.last.strip) : ""
+    "skill #{name} updated (+#{added} −#{removed})#{line.empty? ? "" : ": #{line}"} · /skill diff #{name}"
+  end
+
+  # --- the nudge ------------------------------------------------------------
+
+  def reset_turn
+    @read = []      # skills read this turn, in order
+    @written = []   # skills changed this turn
+    @failed = false # a step failed after a skill was read
+    @nudged = false
+  end
+
+  def note_read(tool, event)
+    names = case tool
+            when "memory_read"
+              event.dig(:call, :content).to_s.split(",").map(&:strip).select { |entry| entry.start_with?("skill_") }
+                   .filter_map { |entry| skill_name(entry) }
+            when "read"
+              Array(event.dig(:targets, :paths)).filter_map { |path| skill_at(path)&.last }
+            else []
+            end
+    @read |= names
+  end
+
+  def step_failed(event)
+    tool = event[:tool].to_s
+    return if NOT_FAILURES.include?(tool) || !failure?(tool, event[:output].to_s)
+
+    @failed = true
+    return if @nudged
+
+    @nudged = !!event[:steer]&.call(format(NUDGE, @read.join(", ")))
+  end
+
+  # A tool error ("[x] Error: …" raised, "[x]\nError: …" returned), or an
+  # execute that exited non-zero; its "exit: N" line may be cut off by the
+  # hook's output cap, and then an Error: line near the top counts.
+  def failure?(tool, output)
+    return true if output.match?(/\A\[#{Regexp.escape(tool)}\](?: |\n)Error:/)
+    return false unless tool == "execute"
+
+    exit_line = output.match(/^exit: (\d+)(?: \(no output\))?\s*\z/)
+    return exit_line[1] != "0" if exit_line
+
+    output.lines.first(20).any? { |line| line.match?(/\A\s*Error:/i) }
+  end
+
+  def after_turn(ctx)
+    return unless @nudge && @failed
+
+    missed = @read - @written
+    return unless missed.size == @read.size
+
+    ctx.notify("skill #{missed.join(", ")} was followed, a step failed, the skill wasn't updated")
+  end
+
+  # --- history ---------------------------------------------------------------
+
+  # Keep +content+ as the newest version, unless it is the newest already (a
+  # denied or failed write leaves the file as it was).
+  def keep_version(ctx, scope, name, content)
+    dir = history_dir(ctx, scope, name)
+    FileUtils.mkdir_p(dir)
+    newest = versions(dir).first
+    return if newest && File.read(newest) == content
+
+    stamp = Time.now.utc.strftime("%Y%m%dT%H%M%S.%6NZ")
+    path = File.join(dir, "#{stamp}.md")
+    File.write("#{path}.tmp", content)
+    File.rename("#{path}.tmp", path)
+    versions(dir).drop(@history_keep).each { |old| File.delete(old) }
+  rescue SystemCallError => e
+    ctx.log.warn(:history_failed, skill: name, error: e.class.name, msg: e.message)
+  end
+
+  # history/system/<name>, history/project-<project folder>/<name>
+  def history_dir(ctx, scope, name)
+    key = scope == "system" ? "system" : "project-#{File.basename(memory_dirs["project"])}"
+    File.join(ctx.data_dir, "history", key, name)
+  end
+
+  # The kept versions, newest first.
+  def versions(dir) = Dir.glob(File.join(dir, "*.md")).sort.reverse
+
+  # --- /skill ----------------------------------------------------------------
+
+  def command(args, ctx)
+    verb, rest = args.split(/\s+/, 2)
+    rest = rest.to_s.strip
+    case verb
+    when "save" then save(rest, ctx)
+    when "list" then rest.empty? ? list : USAGE
+    when "show" then show(rest)
+    when "diff" then diff(rest, ctx)
+    else USAGE
+    end
+  end
+
+  # /skill save [name] [--system]: asks the model, in this session, to save
+  # what was just done (the model has seen the commands; a side answer
+  # wouldn't). The request runs as a turn; sent while a turn runs it joins
+  # that turn at its next step, and the request says to finish the task
+  # first. A REPL session (--no-shared) takes no messages: the request is
+  # shown for the user to send.
+  def save(rest, ctx)
+    words = rest.split
+    scope = words.delete("--system") ? "system" : "project"
+    return USAGE if words.size > 1 || words.any? { |word| word.start_with?("-") }
+
+    name = words.first && skill_name(words.first)
+    return "/skill save: a name is letters, digits, _ and - (got #{words.first})" if words.first && !name
+
+    request = save_request(name, scope, exists: name && skill_path(name))
+    begin
+      ctx.sessions.send(ctx.session_id, request)
+    rescue Samagotchi::Plugin::Sessions::Error => e
+      return "/skill save: #{e.message}. Send this yourself:\n\n#{request}"
+    end
+    what = name ? "skill #{name}" : "a skill"
+    "asked chi to save #{what} (#{scope} scope); a running turn gets it at its next step"
+  end
+
+  def save_request(name, scope, exists:)
+    target = name ? "skill `skill_#{name}`" : "a skill named `skill_<name>` (a short name for the task)"
+    update = exists ? " It exists already: read it, keep what still holds, fix what changed, add a Changelog line." : ""
+    <<~TEXT.strip
+      Save what we just did as #{target} with memory_write, scope #{scope}.#{update} If you are still in the middle of the task, finish it first.
+      Content: plain Markdown, no frontmatter:
+
+      # Skill: #{name || "<name>"}
+
+      ## Steps
+      1. …
+      ## Gotchas
+      - …
+      ## Changelog
+      - #{Date.today.iso8601} created
+
+      Steps are the commands and checks that worked, in order, with the real file and command names; a step that must pass says "stop if it fails". Dead ends and surprises go under Gotchas. Give memory_write a description: one line that starts with what this task is and names its main steps, in this task's own words, so the skill is found next time. Then show the skill briefly.
+    TEXT
+  end
+
+  # /skill list: the skill_* memories of both scopes, with their index line's
+  # date and description.
+  def list
+    skills = memory_dirs.flat_map do |scope, dir|
+      index = index_lines(dir)
+      Dir.glob(File.join(dir, "skill_*.md")).filter_map do |path|
+        name = File.basename(path, ".md").delete_prefix("skill_")
+        next unless skill_name(name) == name
+
+        date, description = index.fetch("skill_#{name}", [nil, nil])
+        line = +"#{name} · #{scope}"
+        line << " · #{date}" if date
+        line << " — #{description}" if description
+        line
+      end.sort
+    end
+    return "no skills yet: after a task we did together, /skill save [name]" if skills.empty?
+
+    "skills:\n#{skills.map { |line| "  #{line}" }.join("\n")}"
+  end
+
+  # /skill show <name>: the skill as saved (project first).
+  def show(rest)
+    name = skill_name(rest)
+    return USAGE unless name
+
+    path = skill_path(name) or return "no skill #{name} (/skill list shows them)"
+    "skill #{name} · #{scope_of(path)}\n\n#{File.read(path).strip}"
+  end
+
+  # /skill diff <name> [N]: the skill now against its N-th newest kept
+  # version (1, the one before the last change, by default), unified.
+  def diff(rest, ctx)
+    word, back = rest.split
+    name = skill_name(word)
+    n = back ? Integer(back, exception: false) : 1
+    return USAGE unless name && n&.positive? && rest.split.size <= 2
+
+    path = skill_path(name) or return "no skill #{name} (/skill list shows them)"
+    kept = versions(history_dir(ctx, scope_of(path), name))
+    return "skill #{name} has no older version yet" if kept.empty?
+    return "skill #{name} has #{kept.size} older version#{"s" if kept.size > 1} (/skill diff #{name} 1..#{kept.size})" if n > kept.size
+
+    old = kept[n - 1]
+    body = unified(File.read(old).lines(chomp: true), File.read(path).lines(chomp: true))
+    return "skill #{name} is the same as version #{n}" if body.empty?
+
+    "--- skill_#{name} (#{version_time(old)})\n+++ skill_#{name} (now)\n#{body}"
+  end
+
+  CONTEXT = 3
+
+  # Hunks with CONTEXT lines around each change, as diff -u prints them.
+  def unified(a, b)
+    ops = line_diff(a, b)
+    changed = ops.each_index.reject { |k| ops[k].first == :eq }
+    return "" if changed.empty?
+
+    # Group changes whose context would touch into one hunk.
+    groups = changed.slice_when { |x, y| y - x > 2 * CONTEXT + 1 }.to_a
+    old_at = new_at = 0
+    positions = ops.map do |op, _|
+      at = [old_at, new_at]
+      old_at += 1 unless op == :add
+      new_at += 1 unless op == :del
+      at
+    end
+    groups.map do |group|
+      from = [group.first - CONTEXT, 0].max
+      to = [group.last + CONTEXT, ops.size - 1].min
+      slice = ops[from..to]
+      old_count = slice.count { |op, _| op != :add }
+      new_count = slice.count { |op, _| op != :del }
+      old_start, new_start = positions[from]
+      header = "@@ -#{range(old_start, old_count)} +#{range(new_start, new_count)} @@"
+      lines = slice.map { |op, line| "#{{ eq: " ", del: "-", add: "+" }[op]}#{line}" }
+      [header, *lines].join("\n")
+    end.join("\n")
+  end
+
+  # diff -u's "start,count" (1-based; an empty side names the line before).
+  def range(start, count)
+    first = count.zero? ? start : start + 1
+    count == 1 ? first.to_s : "#{first},#{count}"
+  end
+
+  # "2026-09-30 10:22 UTC" from a version's file name.
+  def version_time(path)
+    stamp = File.basename(path, ".md")
+    match = stamp.match(/\A(\d{4})(\d\d)(\d\d)T(\d\d)(\d\d)/)
+    match ? "#{match[1]}-#{match[2]}-#{match[3]} #{match[4]}:#{match[5]} UTC" : stamp
+  end
+
+  # --- skills on disk --------------------------------------------------------
+
+  # "release", "skill_release", "Release-Notes" → "release", "release-notes";
+  # nil for anything else.
+  def skill_name(word)
+    name = word.to_s.downcase.delete_suffix(".md").delete_prefix("skill_")
+    name.match?(/\A[a-z0-9][a-z0-9_-]*\z/) ? name : nil
+  end
+
+  # The memories dir of each scope, as memory_read/memory_write resolve it.
+  def memory_dirs
+    %w[project system].to_h { |scope| [scope, File.expand_path(Samagotchi::Tools::MemoryRead.memories_dir(scope))] }
+  end
+
+  # The skill's file, project first (as memory_read looks), or nil.
+  def skill_path(name, scope: nil)
+    dirs = scope ? memory_dirs.slice(scope) : memory_dirs
+    dirs.each_value do |dir|
+      path = File.join(dir, "skill_#{name}.md")
+      return path if File.file?(path)
+    end
+    nil
+  end
+
+  # [scope, name] when +path+ is a skill_<name>.md right in a memories dir.
+  def skill_at(path)
+    path = File.expand_path(path.to_s)
+    scope = memory_dirs.key(File.dirname(path))
+    name = File.basename(path, ".md").delete_prefix("skill_")
+    return nil unless scope && File.basename(path) == "skill_#{name}.md" && skill_name(name) == name
+
+    [scope, name]
+  end
+
+  def scope_of(path) = memory_dirs.key(File.dirname(path)) || "?"
+
+  # The managed index.md lines, {name => [date, description]}:
+  # "- **name** · scope · date · bytes — description".
+  def index_lines(dir)
+    path = File.join(dir, "index.md")
+    return {} unless File.file?(path)
+
+    File.readlines(path, chomp: true).each_with_object({}) do |line, lines|
+      match = line.match(/\A- \*\*(?<name>[^*]+)\*\* · [^·]+ · (?<date>[^·]+?) · [^—]+?(?: — (?<description>.+))?\z/)
+      lines[match[:name]] = [match[:date].strip, match[:description]&.strip] if match
+    end
+  end
+
+  # --- helpers ---------------------------------------------------------------
+
+  # The lines of +a+ and +b+ as [:eq|:del|:add, line], in order (a longest
+  # common subsequence; skills are short).
+  def line_diff(a, b)
+    lcs = Array.new(a.size + 1) { Array.new(b.size + 1, 0) }
+    (a.size - 1).downto(0) do |i|
+      (b.size - 1).downto(0) do |j|
+        lcs[i][j] = a[i] == b[j] ? lcs[i + 1][j + 1] + 1 : [lcs[i + 1][j], lcs[i][j + 1]].max
+      end
+    end
+    ops = []
+    i = j = 0
+    while i < a.size && j < b.size
+      if a[i] == b[j]
+        ops << [:eq, a[i]]
+        i += 1
+        j += 1
+      elsif lcs[i + 1][j] >= lcs[i][j + 1]
+        ops << [:del, a[i]]
+        i += 1
+      else
+        ops << [:add, b[j]]
+        j += 1
+      end
+    end
+    ops.concat(a[i..].map { |line| [:del, line] }, b[j..].map { |line| [:add, line] })
+  end
+
+  def cut(text) = text.length > NOTICE_WIDTH ? "#{text[0, NOTICE_WIDTH - 1]}…" : text
+
+  def positive(value)
+    number = Integer(value.to_s, exception: false)
+    number&.positive? ? number : nil
+  end
+end

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

@@ -18,7 +18,7 @@ Single registry `Samagotchi::Config` (`Config::ENTRIES` in `lib/samagotchi/confi
 
 Sections forbid `_`/`-` (`SECTION_RE` `/\A[a-z0-9]+\z/`); leaves keep `snake_case` in YAML (`base_url`) and become kebab in CLI (`base-url`) via registry derivation — no generic string split, registry lookup avoids flat vs nested collision.
 
-**Universal entries** (`expose: [:env,:config,:cli]`): `default.model`, `server.host/port/transport/open_timeout/read_timeout`, `server.first_token_timeout` (env and config only), `recap.model/base_url/host_ref/inactivity/timeout/min_user_turns/sentences`, `session.retention_days/max_count/keep_status/sweep_interval_hours/idle_exit_minutes`, `session.shared/keep_empty/max_children` (env and config only), `log.file/disable`, `status.line/width_mode/max_width/fixed_width`, `context.status/window_tokens/chars_per_token/status_thresholds/status_cadence`, `thinking.ui/render_interval/turn_preamble`, `default.n_predict`, `max_tool_output_chars`, `retry.max/base_delay/max_delay`, `read.*`, `execute.*`, `web.port/host`, `no_interrupt`, `no_default_input` etc. (`Config::ENTRIES`; `expose` says which of env/config/cli each takes). Precedence is `CLI > ENV > file > default`.
+**Universal entries** (`expose: [:env,:config,:cli]`): `default.model`, `server.host/port/transport/open_timeout/read_timeout`, `server.first_token_timeout` (env and config only), `recap.model/base_url/host_ref/inactivity/timeout/min_user_turns/sentences`, `session.retention_days/max_count/keep_status/sweep_interval_hours/idle_exit_minutes`, `session.shared/keep_empty/max_children` (env and config only), `log.file/disable`, `status.line`, `context.status/window_tokens/chars_per_token/status_thresholds/status_cadence`, `thinking.turn_preamble`, `default.n_predict`, `max_tool_output_chars`, `retry.max/base_delay/max_delay`, `read.*`, `execute.*`, `web.port/host`, `no_interrupt`, `no_default_input` etc. (`Config::ENTRIES`; `expose` says which of env/config/cli each takes). Precedence is `CLI > ENV > file > default`.
 
 Example `config.yml` (new nested form, preferred):
 
@@ -41,7 +41,7 @@ recap:
 session:
   retention_days: 14
   max_count: 500
-  keep_status: running
+  keep_status: ""        # the default: no status protects a session from pruning; a live worker or REPL always does
   sweep_interval_hours: 24
   idle_exit_minutes: 30   # a background worker nobody uses exits; 0 = never
   shared: true            # the default: plain `chi` runs its session in a background worker and attaches (as `chi --shared`); false keeps the in-process REPL (env SAMAGOTCHI_SESSION_SHARED; no CLI flag, `--no-shared` opts out per run)
@@ -52,7 +52,7 @@ log:
   disable: false
 ```
 
-Legacy flat keys (`SAMAGOTCHI_DEFAULT_MODEL`, `SAMAGOTCHI_N_PREDICT` etc. at top-level) are still read via fallback in `Config.lookup_yaml` but warn `Warning: config key 'SAMAGOTCHI_DEFAULT_MODEL' is legacy UPPER — use 'default.model'` (`ConfigFile.load_global_env!`). When a file has both, the nested key wins and the warning names both. Migrate them to nested form and remove the flat entry. The old `LLAMA_HOST`/`LLAMA_PORT` aliases were removed; use `server.host`/`server.port` (nested) or `SAMAGOTCHI_SERVER_HOST`/`SAMAGOTCHI_SERVER_PORT`.
+Only the nested form is read. An env name used as a top-level key (`SAMAGOTCHI_DEFAULT_MODEL: m`, the old flat form) is ignored and warns as an unknown key (`did you mean 'default.model'?`): move it to its nested form and delete the flat line. The old `LLAMA_HOST`/`LLAMA_PORT` aliases were removed; use `server.host`/`server.port` (nested) or `SAMAGOTCHI_SERVER_HOST`/`SAMAGOTCHI_SERVER_PORT`.
 
 **Excluded maps** (YAML-only, not part of the flat registry; skipped by scalar loader):
 
@@ -116,14 +116,14 @@ A guardrail rule's `tool:` may be a glob (`tool: "mcp_*"`, verdict `ask`) to cov
 
 1. **Read** the current file via `read` tool (or `ConfigFile.global_path`). If `File.file?` false, start from `{}`.
 2. `YAML.safe_load` (permitted_classes: [], aliases: false). If data nil or not Hash, treat as `{}` or raise with path.
-3. Mutate the intended **nested** key in the raw hash. Preserve all other keys byte-for-byte where possible. Example for default model: `raw_data["default"] ||= {}; raw_data["default"]["model"] = "new-model"; raw_data.delete("SAMAGOTCHI_DEFAULT_MODEL")` to migrate legacy.
+3. Mutate the intended **nested** key in the raw hash. Preserve all other keys byte-for-byte where possible. Example for default model: `raw_data["default"] ||= {}; raw_data["default"]["model"] = "new-model"`.
 4. **Validate** (see below) before writing. Also run `Samagotchi::Config.validate_yaml_sections` — it returns one `config: unknown key '…' (did you mean '…'?)` per key chi doesn't read (every config-exposed `Config::ENTRIES` key is known as written, including the section-less `max_tool_output_chars` and `skip_agent_md`; names under `hosts:`/`models:`/`model_aliases:`/`hooks:`/`bundles:`/`memories:` are free-form, host and model entries are checked against `Config::MAP_ENTRY_KEYS`). An empty list means no warning at start.
 5. **Write atomically**: `FileUtils.mkdir_p(File.dirname(path))`, `File.write("#{path}.tmp", YAML.dump(raw_data))`, `File.rename("#{path}.tmp", path)`.
-6. Update in-process state: `write_default_model!` sets `ENV["SAMAGOTCHI_DEFAULT_MODEL"]` and `Samagotchi::Config.reload!`; otherwise the harness picks it up on next `Config.get` (live resolve) or restart. CLI overrides (`--default-model`) win over file until process exit.
+6. Nothing else to update: config.yml values are never copied into `ENV`, and every `Config.get` reads the file again when it changed, so the next read (and every worker started after the write) sees the new value with origin `:file`. What a running worker set up at its start (`hosts:`, guardrail rules, bundle settings) waits for its restart. CLI overrides (`--model`, `--recap-model`, …) win over the file until the process exits; a worker gets its spawner's CLI settings through its env (`Config.cli_env`).
 
 ## Validations
 
-- **Model name** (`default.model` / `SAMAGOTCHI_DEFAULT_MODEL`): `ModelProfile.required_model_name` — non-empty string, otherwise harness fails fast at startup. Via `Config.get("default.model")` with ENV fallback.
+- **Model name** (`default.model` / `SAMAGOTCHI_DEFAULT_MODEL`): `ModelProfile.required_model_name` — non-empty string, otherwise harness fails fast at startup. Via `Config.get("default.model")`.
 - **Host api** (`hosts.<name>.api`): `llama_cpp|mlx|omlx` (raw-prompt loop; also the transport) or `openai` (chat loop at `http://HOST:PORT/v1`). Absent: raw-prompt loop. It replaces the removed `backend` setting.
 - **Transport** (`server.transport`): enum `llama_cpp|mlx|omlx`.
 - **Profile** (`models.<id>.profile`, `hosts.<name>.profile`, `SAMAGOTCHI_MODEL_PROFILE`): enum `qwen36|gemma4`; an unknown one warns and is ignored.
@@ -146,8 +146,7 @@ A guardrail rule's `tool:` may be a glob (`tool: "mcp_*"`, verdict `ask`) to cov
 
 ## Hints
 
-- Precedence is `CLI > ENV > file > default` (`Config.resolve`). Real `ENV` still wins over file (`load_global_env!` `unless env.key?` for legacy sync), and CLI (`--recap-base-url`) wins over both via `Config.reload!(cli_overrides:)`.
+- Precedence is `CLI > ENV > file > default` (`Config.resolve`; `Config.get_with_origin` names the layer). `ENV` holds only what the user (or a spawning chi's CLI flags) set, and CLI (`--recap-base-url`) wins over both via `Config.reload!(cli_overrides:)`.
 - `--recap_base_url` (underscore) is rejected as unknown — use `--recap-base-url` (kebab). Same for all registry flags.
 - `model_aliases` require restart or `/model` reload to take effect; document the change.
 - Keep edits minimal: touch only the key you intend to change; preserve `hosts:`/`hooks:`/`guardrails:`/`bundles:` maps. Adding a `bundles: <name>:` entry does not install the bundle (`chi bundle install <name>`).
-- To silence legacy warnings, migrate flat `SAMAGOTCHI_*` keys to nested form and delete the flat entry atomically.

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

@@ -5,3 +5,8 @@
 - **Primary Role**: Running in 'assist mode' to help the user with their tasks.
 - **Core Philosophy**: Focus energy on the user's requests while maintaining self-awareness of my evolutionary nature.
 - **Self-knowledge**: to find my own code, config and state, run `chi self` and read memory `self_map`.
+- **Skills**: a skill is a memory named `skill_<name>` holding the steps of a repeatable task we did together (sections Steps, Gotchas, Changelog; `memory_write description:` says when to use it).
+  When the user asks to keep how we did something ("let's memorize this", "save this as a skill", `/skill save`), write it right away with `memory_write` (project scope; system only when the user asks or it isn't about this project), then show it briefly.
+  Before a task that a `skill_*` in the memory index matches, read it and follow it.
+  When a step turned out different (a renamed command, an extra step, a gotcha), update the skill in the same turn: fix those steps, keep the rest as it was, add a dated Changelog line.
+  When a skill's step fails or its file/command is missing, find out why (look around, read nearby READMEs) before skipping it; a step that says stop means stop and ask.

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

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.4.0
+version: 0.5.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:
-  identity.md: sha256:8b594100bee4797b563bd6425dc6f3ff93e1bdfbe9fc5fa1d66b42093c4795e2
-  self_map.md: sha256:67eb6223728a72788fa0d75aa56affea2ca48962de2e445293bc12b15f5f70c0
-  config_modification_protocol.md: sha256:f76ee7e2f5a8e699401e3a4c9144643ee64015efd11a266029704bf228be6a95
-  memory_guide.md: sha256:6dd1ecfd6a377c4f2cfc2dc299c1ef3835f10d9f313616fd3eb23e5fd3202858
+  identity.md: sha256:b7d59a1e824f0918c28a38d40105e8abd1ff68ebab1810fd1dcf52cd3b72e7c0
+  self_map.md: sha256:59ca83f92d11bc6bdc69f3111b3b8e1189280499ae955b10043ff993387b4550
+  config_modification_protocol.md: sha256:71ff60549574c4be7d4c70801582a19d5d9ec6d5be87f5867f9aa113e5484f21
+  memory_guide.md: sha256:43be77156562f1eac369c248045e35ccd89e87d1f7f95a9286be72521b058e87
   delegated.md: sha256:0a71d5dfa7127df2d51cb5f0e7214240ed88777e36559430a8724c796d7ae561

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

@@ -44,6 +44,32 @@ This memory teaches you (the agent) how to use Samagotchi memories — persisten
 **Placeholders:**
 - Content may contain placeholder hints written as double-curly braces around a name (e.g., test_command, language). Detected by `Placeholder` (`Placeholder::PLACEHOLDER_RE`) — install warns but does not fail. Fill them when you write. The placeholder syntax is two opening braces, a name, two closing braces.
 
+## Skills
+
+A skill is a memory named `skill_<name>` (`skill_release`, `skill_deploy_staging`) that holds the steps of a repeatable task done with the user. Next time, follow it; when a step turned out different, fix it in the same turn.
+
+Shape (plain Markdown, no frontmatter):
+
+```markdown
+# Skill: release
+
+## Steps
+1. Run `scripts/verify.sh`; stop if it fails.
+2. …
+## Gotchas
+- …
+## Changelog
+- 2026-09-29 created
+- 2026-09-30 step 1: check.sh was renamed to verify.sh
+```
+
+- **When to use it** is the `description:` of `memory_write`: one line starting with the task ("Release a new version of this repo: verify, tag, push"). It is what the index shows, so it is how you find the skill later.
+- **Scope**: `project` by default; `system` when the user asks, or when the skill is clearly not about this project.
+- **Saving**: on a request to keep how something was done ("let's memorize this", "save this as a skill", `/skill save`), write it at once, then show it briefly. On an ambiguous one ("I like how we did that") you may ask whether to save it.
+- **Following**: before a task a `skill_*` index line matches, `memory_read` it and follow its steps. A step that fails or names a missing file or command: find out why (look around, read nearby READMEs) before skipping it; a step that says stop means stop and ask.
+- **Updating**: when a step turned out different, rewrite the skill with `memory_write` in the same turn: fix those steps, keep the rest as it was, add a dated Changelog line. No confirmation needed.
+- **The `skills` bundle** (`chi bundle install skills`, optional) adds `/skill save [name] [--system]`, `/skill list`, `/skill show <name>`, `/skill diff <name> [N]`; it keeps older versions and shows a short diff line after each update.
+
 ## Memory Bundles — shareable packs
 
 Bundles are versioned directories/zips/tar.gz/git URLs with a `manifest.yml` and any of: memories (`*.md`), `hooks/*.rb` (bundle hooks, `docs/hooks.md`), `guardrails/*.yml` (rules, `docs/guardrails.md`), a `plugin.rb` (commands, tools, hooks, services; `docs/plugins.md`). They are shareable and installable.

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

@@ -33,7 +33,8 @@
   `mcp` (MCP server tools; a screenshot comes as a picture), `guardrails` (rules), `known-names` (typo guard), `source-links`
   (turns source refs like JIRA-123 in an answer into links in the web, and a one-line note), `loop-guard`
   (denies a repeated tool call with the same result, stops the turn after a few), `check-in` (after N tool
-  calls with no answer, a card asks the user to nudge me, let me go on or stop; `/checkin`). `chi bundle list`
+  calls with no answer, a card asks the user to nudge me, let me go on or stop; `/checkin`), `skills` (`/skill save|list|show|diff`,
+  keeps older versions of `skill_*` memories). `chi bundle list`
   shows installed + available; `chi bundle install <name>`. Settings: config.yml `bundles: <name>:`
   (`config_modification_protocol`), read at session start: after an install or a settings change,
   tell the user to restart the session. API and bundle docs: `docs/plugins.md`.

data/lib/samagotchi/client.rb

@@ -13,12 +13,12 @@ require_relative "sampling_settings"
 module Samagotchi
   # Thin HTTP client for llama.cpp's native /completion endpoint, or an
   # OpenAI-compatible /v1/completions endpoint (e.g. mlx_lm.server or oMLX).
-  # Configure via environment variables (see Samagotchi::Config):
-  #   SAMAGOTCHI_SERVER_HOST  (default: localhost)
-  #   SAMAGOTCHI_SERVER_PORT  (default: 8080; oMLX's default is 8000, set it to match)
-  #   SAMAGOTCHI_SERVER_OPEN_TIMEOUT (default: 10 seconds)
-  #   SAMAGOTCHI_SERVER_READ_TIMEOUT (default: 600 seconds)
-  #   SAMAGOTCHI_SERVER_TRANSPORT (llama_cpp|mlx|omlx, default: llama_cpp)
+  # Configured by the server.* settings (Samagotchi::Config):
+  #   server.host  (default: localhost)
+  #   server.port  (default: 8080; oMLX's default is 8000, set it to match)
+  #   server.open_timeout (default: 10 seconds)
+  #   server.read_timeout (default: 600 seconds)
+  #   server.transport (llama_cpp|mlx|omlx, default: llama_cpp)
   class Client
     # The shared HTTP layer's errors, under their old names.
     RequestCancelled = LLM::RequestCancelled
@@ -33,7 +33,6 @@ module Samagotchi
     # generation, and a new turn doesn't ask again at once.
     PROPS_FAILURE_TTL = 30
 
-    SERVER_TRANSPORT_ENV = "SAMAGOTCHI_SERVER_TRANSPORT"
     DEFAULT_TRANSPORT = :llama_cpp
     VALID_TRANSPORTS = %i[llama_cpp mlx omlx].freeze
 
@@ -154,21 +153,12 @@ module Samagotchi
     def initialize(host: nil, port: nil, open_timeout: nil, read_timeout: nil, transport: nil, sleeper: nil, scheme: nil,
                    first_token_timeout: nil, name: nil, api_key_env: nil, env: ENV)
       # Unified config precedence: CLI > ENV > file > default (via Samagotchi::Config)
-      cfg_host = nil; cfg_port = nil; cfg_transport_raw = nil
-      begin
-        cfg_host       = Samagotchi::Config.get("server.host")
-        cfg_port       = Samagotchi::Config.get("server.port")
-        cfg_transport_raw = Samagotchi::Config.get("server.transport")
-      rescue StandardError
-        nil
-      end
-      @host          = host || cfg_host
-      @port          = (port || cfg_port).to_i
+      @host          = host || Samagotchi::Config.get("server.host")
+      @port          = (port || Samagotchi::Config.get("server.port")).to_i
       @scheme        = scheme || "http"
       @open_timeout  = Samagotchi::Config.positive_seconds("server.open_timeout", open_timeout)
       @read_timeout  = Samagotchi::Config.positive_seconds("server.read_timeout", read_timeout)
-      transport_fallback = cfg_transport_raw || ENV.fetch(SERVER_TRANSPORT_ENV, DEFAULT_TRANSPORT.to_s)
-      @transport = build_transport(resolve_transport(transport || transport_fallback))
+      @transport = build_transport(resolve_transport(transport))
       @props_cache = {}
       @props_failures = {}
       @props_mutex = Mutex.new
@@ -324,6 +314,12 @@ module Samagotchi
       props
     end
 
+    # The /props answer #server_props already has for +model+, or nil;
+    # never asks the server.
+    def cached_server_props(model: nil)
+      @props_mutex.synchronize { @props_cache[model.to_s] }
+    end
+
     # The context window (tokens) the running server was started with, or nil
     # when the transport reports none or the probe fails (see #server_props).
     def context_window(model: nil)
@@ -370,7 +366,7 @@ module Samagotchi
     end
 
     def resolve_transport(transport)
-      value = (transport || ENV.fetch(SERVER_TRANSPORT_ENV, DEFAULT_TRANSPORT.to_s)).to_s.strip.downcase.to_sym
+      value = (transport || Samagotchi::Config.get("server.transport")).to_s.strip.downcase.to_sym
       VALID_TRANSPORTS.include?(value) ? value : DEFAULT_TRANSPORT
     end