robot_lab 0.2.6 → 0.2.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d401853bc5fff2646793cfff4fbda7082b18b0e07b833b3f4de6545fca574125
-  data.tar.gz: f9964095406885bed329d8f2e7189cbb582e1c4665e3d53781b83371ee9016c7
+  metadata.gz: de87b78206bc424703b465d3a1f236db723ea38fe4235c07413466ab5b469ead
+  data.tar.gz: 6a7db14e4530e615e258415491422f297567a2f640983035f1542d88e7d200e5
 SHA512:
-  metadata.gz: dd29d885c9ea4e0b91bffe49b757808213e8011302fac48b4632c37d0cc95315a559f80240fabca92c0a309fead3f1f72b1da3ac7eccdb440059451fc53c5a0e
-  data.tar.gz: 518c45909e25437da64e16ad69a5bfe5f361ddd602dc64c0ad475acde1c0b7946a0773fa36960a0baea3294ae7a7cef1835b6d08be2034e3a4a905fa74715eb2
+  metadata.gz: f6814c9a8b86b8e6d1df2adcc2d9b4ab84c176c67211424e8404e9d83c1e08ffd353587523e4c45efec295d0e47bbd731b0cdc6f3e62754cfd4f1ce2a33d7655
+  data.tar.gz: 37682af098203ae333cc83fa6e66a95f1883aae0bed8411524a05d6795bb47b4a99f231353fe3546b2fdae8a5c098d0f45b863e531edaf237aab33e4e1bc3859

data/.envrc

@@ -1,2 +1,6 @@
+# robot_lab_project/robot_lab/.envrc
+
+source_up
+
 export RR=`pwd`
 export BUNDLE_GEMFILE=Gemfile

data/.loki

@@ -18,6 +18,11 @@ class Tasks
     sh "ruby -Ilib:test \"#{path}\""
   end
 
+  desc "Check architecture boundaries with ArchSpec"
+  def archspec
+    sh "bundle exec archspec check"
+  end
+
   class DocsCommands < Tasks
     desc "Build YARD + MkDocs documentation"
     def build

data/Archspec.rb

@@ -0,0 +1,44 @@
+component :robot,         in: "lib/robot_lab/robot.rb"
+component :robot_support, in: "lib/robot_lab/robot/**/*.rb"
+component :network,       in: ["lib/robot_lab/network.rb", "lib/robot_lab/bus_poller.rb"]
+component :memory,        in: ["lib/robot_lab/memory.rb", "lib/robot_lab/memory_change.rb"]
+component :mcp,           in: "lib/robot_lab/mcp/**/*.rb"
+component :sandbox,       in: ["lib/robot_lab/sandbox.rb", "lib/robot_lab/sandbox/**/*.rb"]
+component :streaming,     in: "lib/robot_lab/streaming/**/*.rb"
+component :budget,        in: "lib/robot_lab/budget/**/*.rb"
+component :hooks,         in: %w[
+  lib/robot_lab/hook.rb
+  lib/robot_lab/hook_context.rb
+  lib/robot_lab/hook_registry.rb
+  lib/robot_lab/hooks.rb
+]
+component :tools, in: %w[
+  lib/robot_lab/tool.rb
+  lib/robot_lab/tool_config.rb
+  lib/robot_lab/tool_manifest.rb
+  lib/robot_lab/script_tool.rb
+]
+component :config, in: ["lib/robot_lab/config.rb", "lib/robot_lab/run_config.rb"]
+
+# NOTE: every file here reopens `module RobotLab`, so a `dependencies.forbid`
+# rule keyed on components (e.g. `memory.cannot_use :robot`) treats a plain
+# `RobotLab.config` call as "depends on every component" — every file
+# "defines" the bare RobotLab constant. Naming the actual target constants
+# instead of components sidesteps that ambiguity.
+
+# Memory is a low-level primitive shared by Robot and Network; it must not
+# depend back on the things that depend on it.
+memory.cannot_reference_constants "RobotLab::Robot", "RobotLab::Network"
+
+# MCP is an external-tool integration layer that Robot/Network consume; it
+# must not reach back into the objects that use it.
+mcp.cannot_reference_constants "RobotLab::Robot", "RobotLab::Network"
+
+# Sandbox runs untrusted/generated code paths and should have the smallest
+# possible surface area — no reaching into orchestration or memory internals.
+sandbox.cannot_reference_constants "RobotLab::Robot", "RobotLab::Network", "RobotLab::Memory"
+
+# Config/RunConfig sits at the bottom of the configuration cascade
+# (RobotLab.config -> Network -> Robot -> template -> task -> runtime) and
+# must not depend upward on the objects it configures.
+config.cannot_reference_constants "RobotLab::Robot", "RobotLab::Network"

data/CHANGELOG.md

@@ -6,7 +6,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
-## [Unreleased]
+## [0.2.8] - 2026-09-09
 
 ### Added
 - `BusMessaging#respond_to_tasks` and `#serve` — a member auto-answers inbound
@@ -16,6 +16,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   without hand-wiring `on_message`.
 - `.loki` Asgard task file: `test`, `rubocop`, `rubocop_fix`, `flog`, `flay`, `quality`, `build`, `install`, `release`, `integration`, `docs`, and `examples` tasks via the Asgard task runner
 
+### Changed (BREAKING)
+- **Sandboxing extracted to `robot_lab-sandbox`.** `RobotLab::Sandbox`,
+  `RobotLab::Sandbox::Seatbelt`, and `RobotLab::Sandbox::Null` no longer live
+  in core; they moved verbatim to the new `robot_lab-sandbox` gem. Core has no
+  execution limitations of its own: `ScriptTool.execute` now delegates to an
+  optional `ScriptTool.executor` (`nil` by default, in which case it runs the
+  unconfined `Open3.capture2e` path with no timeout exactly as before).
+  Applications that want confined skill-script execution must add
+  `gem "robot_lab-sandbox"` and `require "robot_lab/sandbox"`, which installs
+  itself as the executor; `config.sandbox.*` behavior is unchanged from there.
+  `RobotLab::Capabilities` (the declarative fs_read/fs_write/network/timeout/
+  trust manifest parsed from `SKILL.md`) stays in core since `AgentSkill` needs
+  it regardless of whether sandboxing is enforced.
+- `ScriptTool.run_with_timeout` and `ScriptTool.terminate` moved to
+  `RobotLab::Sandbox::Executor` in `robot_lab-sandbox`.
+
 ### Fixed
 - `BusMessaging` now synchronizes its message counter and outbox with a mutex, so
   concurrent sends and poller-thread reply correlation can't clobber each other.

data/README.md

@@ -1,7 +1,7 @@
 # RobotLab
 
-> [!INFO]
-> See the [CHANGELOG](CHANGELOG.md) for the latest changes.  The [examples directory has a good cross section  of demo apps](examples/README.md) that show-off the various capabilities of the RobotLab library.
+> [!NOTE]
+> See the [CHANGELOG](CHANGELOG.md) for the latest changes.  The [examples directory has a good cross section of demo apps](examples/README.md) that show-off the various capabilities of the RobotLab library.
 
 <br>
 <table>
@@ -21,7 +21,7 @@
 - <strong>Human-in-the-Loop</strong> - AskUser tool for interactive prompting<br>
 - <strong>Content Streaming</strong> - Stored callbacks, per-call blocks, or both<br>
 - <strong>MCP Integration</strong> - Connect to external tool servers with timeouts and retry<br>
-- <strong>Local LLM Providers</strong> - Ollama, GPUStack, LM Studio via provider passthrough<br>
+- <strong>Local LLM Providers</strong> - Ollama and GPUStack via provider passthrough<br>
 - <strong>Shared Memory</strong> - Reactive key-value store with subscriptions<br>
 - <strong>Message Bus</strong> - Bidirectional robot communication via TypedBus<br>
 - <strong>Dynamic Spawning</strong> - Robots create new robots at runtime<br>
@@ -30,6 +30,7 @@
 - <strong>Rails Integration</strong> - Generators, background jobs, Turbo Stream broadcasting (via <a href="https://github.com/MadBomber/robot_lab-rails">robot_lab-rails</a>)<br>
 - <strong>Token &amp; Cost Tracking</strong> - Per-run and cumulative token counts on every robot<br>
 - <strong>Tool Loop Circuit Breaker</strong> - <code>max_tool_rounds:</code> guards against runaway tool call loops<br>
+- <strong>Doom Loop Detection</strong> - always-on detection of repeated or cyclic tool call patterns, tunable via <code>doom_loop_threshold:</code><br>
 - <strong>Learning Accumulation</strong> - <code>robot.learn()</code> builds up cross-run observations with deduplication<br>
 - <strong>Context Window Compression</strong> - <code>robot.compress_history()</code> prunes irrelevant old turns via TF cosine scoring<br>
 - <strong>Convergence Detection</strong> - <code>RobotLab::Convergence</code> detects when independent agents agree, enabling reconciler fast-path<br>
@@ -38,7 +39,7 @@
 </tr>
 </table>
 
-<p>RobotLab enables sophisticated AI applications using multiple specialized robots (LLM agents) that work together to accomplish complex tasks. Each robot has its own instructions, skills, tools, and capabilities.  Review the [full documentation website](https://madbomber.github.io/robot_lab) snd explore the [many examples](examples/README.md) available as working demo applications.</p>
+<p>RobotLab enables sophisticated AI applications using multiple specialized robots (LLM agents) that work together to accomplish complex tasks. Each robot has its own instructions, skills, tools, and capabilities.  Review the [full documentation website](https://madbomber.github.io/robot_lab) and explore the [many examples](examples/README.md) available as working demo applications.</p>
 
 ## Installation
 
@@ -81,7 +82,11 @@ puts result.last_text_content
 
 ### Local LLM Providers
 
-For local LLM providers (Ollama, GPUStack, LM Studio, etc.), use the `provider:` parameter:
+For local LLM providers, use the `provider:` parameter. RubyLLM's provider list is the authority on valid values — `:ollama` and `:gpustack` are the local ones (alongside `:anthropic`, `:azure`, `:bedrock`, `:deepseek`, `:gemini`, `:mistral`, `:openai`, `:openrouter`, `:perplexity`, `:vertexai`, and `:xai`). The provider's API base must be configured first, or building the robot raises `RubyLLM::ConfigurationError`:
+
+```bash
+export ROBOT_LAB_RUBY_LLM__OLLAMA_API_BASE=http://localhost:11434/v1
+```
 
 ```ruby
 robot = RobotLab.build(
@@ -92,13 +97,15 @@ robot = RobotLab.build(
 )
 ```
 
+Specifying `provider:` also sets `assume_model_exists`, so the model name is not validated against a known-model list.
+
 ### Configuration
 
 RobotLab uses [MywayConfig](https://github.com/MadBomber/myway_config) for layered configuration. Configuration is loaded automatically from multiple sources in priority order:
 
 1. Bundled defaults (`lib/robot_lab/config/defaults.yml`)
 2. Environment-specific overrides (development, test, production)
-3. XDG user config (`~/.config/robot_lab/config.yml`)
+3. XDG user config (`~/.config/robot_lab/robot_lab.yml` — note the filename repeats the app name)
 4. Project config (`./config/robot_lab.yml`)
 5. Environment variables (`ROBOT_LAB_*` prefix)
 
@@ -113,7 +120,6 @@ export ROBOT_LAB_RUBY_LLM__MODEL=claude-sonnet-4
 # Access configuration values
 RobotLab.config.ruby_llm.model            #=> "claude-sonnet-4"
 RobotLab.config.ruby_llm.request_timeout  #=> 120
-RobotLab.config.streaming_enabled         #=> true
 ```
 
 Or create a project config file at `./config/robot_lab.yml`:
@@ -192,9 +198,10 @@ tools:
   - CodeSearchTool
 mcp:
   - name: github
-    transport: stdio
-    command: npx
-    args: ["-y", "@modelcontextprotocol/server-github"]
+    transport:
+      type: stdio
+      command: npx
+      args: ["-y", "@modelcontextprotocol/server-github"]
 model: claude-sonnet-4
 ---
 You are a GitHub assistant. Use available tools to help with repository tasks.
@@ -205,7 +212,10 @@ You are a GitHub assistant. Use available tools to help with repository tasks.
 robot = RobotLab.build(template: :github_assistant)
 ```
 
-Front matter supports: `description`, `robot_name`, `tools`, `mcp`, `skills`, `parameters`, and LLM config keys (`model`, `temperature`, `top_p`, `top_k`, `max_tokens`, `presence_penalty`, `frequency_penalty`, `stop`). Constructor-provided values always take precedence over front matter.
+Front matter supports: `description`, `robot_name`, `tools`, `mcp`, `skills`, `parameters`, and LLM config keys. Constructor-provided values always take precedence over front matter.
+
+> [!IMPORTANT]
+> Of the LLM config keys, only **`model`** and **`temperature`** currently take effect from front matter. `top_p`, `top_k`, `max_tokens`, `presence_penalty`, `frequency_penalty`, and `stop` are parsed but not applied — set those as constructor kwargs (or via `config:`), where they do work.
 
 ### Composable Skills
 
@@ -237,7 +247,7 @@ Skills are expanded depth-first and can reference other skills (with automatic c
 
 ### Combining Templates with System Prompts
 
-The `system_prompt` parameter can also be used alongside a template. When both are provided, the template renders first and the `system_prompt` is appended. This is particularly useful during development and testing when you want to add temporary instructions or context to an existing template:
+The `system_prompt` parameter can also be used alongside a template. When both are provided, the template renders first and the `system_prompt` is appended, producing a single combined system message. The appended text also survives template re-rendering, so it persists across `run()` calls that supply runtime context. This is particularly useful during development and testing when you want to add temporary instructions or context to an existing template:
 
 ```ruby
 robot = RobotLab.build(
@@ -250,7 +260,7 @@ robot = RobotLab.build(
 
 ### Shared Configuration with RunConfig
 
-`RunConfig` lets you define operational defaults that flow through the hierarchy: Network -> Robot -> Template -> Task -> Runtime. Use it to share LLM settings across multiple robots or an entire network.
+`RunConfig` lets you define operational defaults. For a single robot they cascade from least- to most-specific: template front matter -> `config:` -> constructor kwargs. Front matter is the *base*, not an override — constructor kwargs always win.
 
 ```ruby
 # Create a shared config
@@ -267,7 +277,7 @@ robot = RobotLab.build(
   config: shared
 )
 
-# Apply to an entire network (all robots inherit these defaults)
+# Apply at the network level (see the note below on what actually propagates)
 network = RobotLab.create_network(name: "pipeline", config: shared) do
   task :analyzer, analyzer_robot, depends_on: :none
   task :writer, writer_robot, depends_on: [:analyzer]
@@ -282,6 +292,11 @@ robot = RobotLab.build(
 )
 ```
 
+> [!IMPORTANT]
+> A network-level `config:` propagates only `mcp` and `tools` down to its robots, and only when the robot opts in with `mcp: :inherit` / `tools: :inherit` — `:none` at any level resolves to an empty list. LLM fields (`model`, `temperature`, `max_tokens`, …) and callbacks (`on_content`) are read from each robot's own config at construction time, so they are **not** inherited from the network. To share LLM settings, pass the same `RunConfig` to each robot via `config:`.
+>
+> `max_concurrent_robots` is the one field the network itself consumes.
+
 RunConfig supports keyword construction, block DSL, and merge semantics:
 
 ```ruby
@@ -301,7 +316,7 @@ effective.model        #=> "claude-sonnet-4"
 
 ### Chaining Configuration
 
-Robots support method chaining to adjust configuration after creation:
+Robots support method chaining to adjust configuration after creation. The `with_*` methods are delegated dynamically from the underlying `RubyLLM::Chat`, so the available set is whatever that class defines — currently `with_context`, `with_headers`, `with_instructions`, `with_model`, `with_params`, `with_schema`, `with_temperature`, `with_thinking`, `with_tool`, and `with_tools`. Each returns the robot, so calls chain.
 
 ```ruby
 robot = RobotLab.build(name: "writer", system_prompt: "You are a creative writer.")
@@ -309,10 +324,18 @@ robot = RobotLab.build(name: "writer", system_prompt: "You are a creative writer
 result = robot
   .with_temperature(0.9)
   .with_model("claude-sonnet-4")
-  .with_max_tokens(2000)
   .run("Write a haiku about Ruby programming")
 ```
 
+There is no `with_max_tokens`. Set token limits in the constructor, or pass them through `with_params`:
+
+```ruby
+robot = RobotLab.build(name: "writer", system_prompt: "...", max_tokens: 2000)
+
+# or, after creation
+robot.with_params(max_tokens: 2000)
+```
+
 ## Graceful Tool Error Handling
 
 `RobotLab::Tool` automatically catches exceptions in `execute` and returns a plain-text error to the LLM instead of crashing the run. The LLM can then reason about the error and try an alternative approach.
@@ -368,9 +391,22 @@ robot = RobotLab.build(
   local_tools: [Magic8Ball]
 )
 
-result = robot.run("Should I start learning Rust?")
+# NOTE the `tools: :inherit` — see the warning below
+result = robot.run("Should I start learning Rust?", tools: :inherit)
 ```
 
+> [!WARNING]
+> `run()` defaults to `tools: :none` and `mcp: :none`, and `:none` means **send zero tools this turn**. Attaching tools with `local_tools:` (or servers with `mcp:`) is therefore not enough on its own — a plain `robot.run("...")` sends the LLM no tools at all and connects no MCP servers.
+>
+> Pass `tools: :inherit` / `mcp: :inherit` on each run to use what the robot has attached:
+>
+> ```ruby
+> robot.run("...", tools: :inherit)              # send attached tools
+> robot.run("...", mcp: :inherit, tools: :inherit)  # connect MCP + send its tools
+> ```
+>
+> `:inherit` means "no filter, use everything attached"; an explicit array acts as a name allowlist. Note that `tools: :inherit` at *build* time behaves differently — it resolves against the parent level, so keep `:inherit` on the `run()` call.
+
 ## Orchestrating Multiple Robots
 
 Networks use [SimpleFlow](https://github.com/MadBomber/simple_flow) pipelines with optional task activation for intelligent routing:
@@ -423,24 +459,29 @@ puts result.value.last_text_content
 
 ## Memory
 
-Both robots and networks have inherent memory that persists across runs:
+Two independent mechanisms carry state across runs, and it is worth keeping them straight:
+
+- **Chat history** — each robot owns a persistent `RubyLLM::Chat`, so conversational context carries forward automatically with no work on your part.
+- **`RobotLab::Memory`** — an explicit key-value store you read and write yourself, shared across robots when they run inside a network.
 
 ```ruby
-# Standalone robot with inherent memory
 robot = RobotLab.build(name: "assistant", system_prompt: "You are helpful.")
 
 robot.run("My name is Alice")
-robot.run("What's my name?")  # Memory persists automatically
+robot.run("What's my name?")  # answered from the persistent chat history
 
-# Access robot's memory
+# Access robot's memory (the explicit key-value store)
 robot.memory[:user_id] = 123
 robot.memory.data[:category] = "billing"
 
 # Runtime memory injection
 robot.run("Help me", memory: { session_id: "abc123", tier: "premium" })
 
-# Reset memory when needed
+# Reset the key-value store (does NOT clear chat history)
 robot.reset_memory
+
+# Clear chat history instead, keeping the system prompt
+robot.clear_messages
 ```
 
 Networks pass context through SimpleFlow::Result:
@@ -467,6 +508,8 @@ billing_result = result.context[:billing]
 puts result.value.last_text_content
 ```
 
+Results are keyed in `result.context` by the **robot's** `name`, not by the task name given to `task`. Keep the two identical unless you have a reason not to.
+
 ## MCP Integration
 
 Connect to external tool servers via Model Context Protocol:
@@ -490,17 +533,18 @@ robot = RobotLab.build(
   mcp: [filesystem_server]
 )
 
-# Optionally connect eagerly (default is lazy on first run)
+# Connect. Do this explicitly — run() defaults to mcp: :none, so a plain
+# run() never connects the servers configured above.
 robot.connect_mcp!
 
 # Check connection status
 puts "Failed: #{robot.failed_mcp_server_names}" if robot.failed_mcp_server_names.any?
 
-# Robot can now use filesystem tools
-result = robot.run("List the files in the current directory")
+# Robot can now use filesystem tools — :inherit is required on the run
+result = robot.run("List the files in the current directory", mcp: :inherit, tools: :inherit)
 ```
 
-MCP connections are resilient: failed servers are automatically retried on subsequent `run()` calls, and one failing server does not prevent others from connecting.
+MCP connections are resilient: failed servers are automatically retried on subsequent `run(mcp: :inherit)` calls, and one failing server does not prevent others from connecting. Connection failures are logged and recorded in `failed_mcp_server_names` rather than raised, so a robot whose servers all failed still builds and runs — just without those tools.
 
 ## Message Bus
 
@@ -634,7 +678,7 @@ robot = RobotLab.build(
 robot.run("Tell me a story") { |chunk| stream_to_client(chunk.content) }
 ```
 
-The `on_content:` callback participates in the RunConfig cascade, so it can be set at the network or config level and inherited by robots.
+The `on_content:` callback is a `RunConfig` field, so it can also be supplied through a robot's `config:` instead of as a constructor kwarg. It is read from the robot's own config at construction time — a network-level `config:` does not supply it.
 
 ## Token & Cost Tracking
 
@@ -675,7 +719,8 @@ robot = RobotLab.build(
 begin
   robot.run("Run all steps.")
 rescue RobotLab::ToolLoopError => e
-  puts e.message  # "Tool call limit of 10 exceeded"
+  puts e.message
+  # "Circuit breaker triggered: 11 tool calls exceeded max_tool_rounds (10)"
 end
 ```
 
@@ -688,14 +733,16 @@ result = robot.run("Something new.")  # robot is healthy again
 
 ## Doom Loop Detection
 
-Doom loop detection catches the subtler failure mode where a robot repeats the same tool call pattern indefinitely — not hitting `max_tool_rounds`, but cycling through the same sequence over and over. Set `doom_loop_threshold:` to enable it:
+Doom loop detection catches the subtler failure mode where a robot repeats the same tool call pattern indefinitely — not hitting `max_tool_rounds`, but cycling through the same sequence over and over.
+
+Unlike the circuit breaker, doom loop detection is **always active** — it is installed on every run. `doom_loop_threshold:` tunes the sensitivity; it does not switch the feature on. The default threshold is `3`.
 
 ```ruby
 robot = RobotLab.build(
   name: "runner",
   system_prompt: "Execute steps.",
   local_tools: [StepTool],
-  doom_loop_threshold: 3   # alert after 3 identical consecutive or cyclic sequences
+  doom_loop_threshold: 5   # tolerate more repetition before warning (default: 3)
 )
 ```
 
@@ -710,27 +757,33 @@ robot  = RobotLab.build(name: "runner", system_prompt: "...", config: config)
 
 `auto_compact` triggers context window compression automatically before each `run()`, preventing context overflow without manual intervention.
 
+`auto_compact` and `compact_threshold` are `RunConfig` fields, not constructor keywords — pass them via `config:`:
+
 ```ruby
 # Built-in trigger: compact when estimated token usage exceeds 80% of context window
 robot = RobotLab.build(
   name: "analyst",
   system_prompt: "You are a research analyst.",
-  auto_compact: :context_window
+  config: RobotLab::RunConfig.new(auto_compact: :context_window)
 )
 
 # Tune the threshold (here: compact at 70%)
 robot = RobotLab.build(
   name: "analyst",
   system_prompt: "You are a research analyst.",
-  auto_compact:      :context_window,
-  compact_threshold: 0.70
+  config: RobotLab::RunConfig.new(
+    auto_compact:      :context_window,
+    compact_threshold: 0.70
+  )
 )
 
 # Application-owned compaction: full control over when and how
 robot = RobotLab.build(
   name: "analyst",
   system_prompt: "You are a research analyst.",
-  auto_compact: ->(r) { r.compress_history(recent_turns: 5) if r.chat.messages.size > 40 }
+  config: RobotLab::RunConfig.new(
+    auto_compact: ->(r) { r.compress_history(recent_turns: 5) if r.chat.messages.size > 40 }
+  )
 )
 ```
 
@@ -740,12 +793,7 @@ robot = RobotLab.build(
 | `:context_window` | Compact when estimated token usage exceeds `compact_threshold` fraction of model's context window |
 | `Proc` | Called with the robot before each `run()`; application decides when and how to compact |
 
-`compact_threshold` defaults to `0.80` (80%). Requires the `classifier` gem when using the built-in `:context_window` strategy. Via `RunConfig`:
-
-```ruby
-config = RobotLab::RunConfig.new(auto_compact: :context_window, compact_threshold: 0.75)
-robot  = RobotLab.build(name: "analyst", system_prompt: "...", config: config)
-```
+`compact_threshold` defaults to `0.80` (80%). The built-in `:context_window` strategy uses the optional `classifier` gem; if it is missing, compaction is skipped with a logged warning rather than raising.
 
 ## Learning Accumulation
 
@@ -763,18 +811,9 @@ reviewer.learn("This codebase prefers map/collect over manual array accumulation
 reviewer.run("Review snippet B")  # learning is injected automatically
 ```
 
-Pass `learn: true` in the constructor to enable automatic end-of-session learning promotion via the `robot_lab-durable` gem:
-
-```ruby
-reviewer = RobotLab.build(
-  name: "reviewer",
-  system_prompt: "You are a Ruby code reviewer.",
-  learn: true,
-  learn_domain: "ruby_review"
-)
-```
+Cross-session learning promotion is provided by the [robot_lab-durable](https://github.com/MadBomber/robot_lab-durable) gem, which hooks the `:learn` lifecycle family. See that gem's documentation for setup.
 
-Learnings deduplicate bidirectionally: if a broader learning is added that contains an existing narrower one, the narrower one is dropped. Learnings are persisted to the robot's `Memory` and survive a robot rebuild when the same `Memory` object is reused.
+Learnings deduplicate bidirectionally: if a broader learning is added that contains an existing narrower one, the narrower one is dropped. Learnings are persisted to the robot's `Memory` for the lifetime of that robot.
 
 ```ruby
 reviewer.learnings          # => ["This codebase prefers map/collect..."]
@@ -783,7 +822,9 @@ reviewer.learn("new fact")  # deduplicates before storing
 
 ## Context Window Compression
 
-`robot.compress_history` prunes old conversation turns using TF-IDF cosine similarity, keeping only turns that are relevant to the most recent context. System messages and tool call/result pairs are always preserved.
+`robot.compress_history` prunes old conversation turns using term-frequency cosine similarity, keeping only turns that are relevant to the most recent context. System messages and tool call/result pairs are always preserved.
+
+Scoring uses raw term frequencies without IDF weighting — on a topic-focused conversation, IDF would suppress exactly the recurring terms that signal relevance.
 
 ```ruby
 # Basic compression: protect the 3 most recent turns, drop unrelated old turns
@@ -811,7 +852,7 @@ gem "classifier", "~> 2.3"
 
 ## Convergence Detection
 
-`RobotLab::Convergence` detects when two independent agents have reached the same conclusion using TF-IDF cosine similarity. Use it as a router fast-path to skip an expensive reconciler LLM call when verifiers already agree.
+`RobotLab::Convergence` detects when two independent agents have reached the same conclusion using term-frequency cosine similarity (no IDF — on a two-document comparison, IDF collapses the shared terms to zero). Use it to skip an expensive reconciler LLM call when verifiers already agree.
 
 ```ruby
 # Check similarity directly
@@ -826,18 +867,30 @@ RobotLab::Convergence.detected?(result_a.reply, result_b.reply)
 RobotLab::Convergence.detected?(text_a, text_b, threshold: 0.75)
 ```
 
-A common pattern is wiring convergence into a network router to skip reconciliation:
+`similarity` returns `0.0` if either text is blank or shorter than 30 characters (`Convergence::MIN_TEXT_LENGTH`), since term-frequency scoring is not meaningful on very short strings. Short replies like `"yes"` will therefore never register as converged.
+
+A common pattern is a gate robot that decides whether reconciliation is needed. Routing is done by overriding `call` and activating an `depends_on: :optional` task — networks have no separate router parameter:
 
 ```ruby
-router = ->(args) do
-  a = args.context[:verifier_a]&.reply.to_s
-  b = args.context[:verifier_b]&.reply.to_s
-  RobotLab::Convergence.detected?(a, b) ? nil : ["reconciler"]
+class ConvergenceGate < RobotLab::Robot
+  def call(result)
+    a = result.context[:verifier_a]&.reply.to_s
+    b = result.context[:verifier_b]&.reply.to_s
+
+    # Converged? Pass the result straight through and leave :reconciler dormant.
+    RobotLab::Convergence.detected?(a, b) ? result : result.activate(:reconciler)
+  end
 end
 
-network = RobotLab.create_network(name: "verify", router: router) do
-  # ...
+network = RobotLab.create_network(name: "verify") do
+  task :verifier_a, verifier_a, depends_on: :none
+  task :verifier_b, verifier_b, depends_on: :none
+  task :gate,       ConvergenceGate.new(name: "gate"), depends_on: [:verifier_a, :verifier_b]
+  task :reconciler, reconciler,  depends_on: :optional
 end
+
+result = network.run(message: "Audit this change")
+result.context.key?(:reconciler)  # => false when the verifiers agreed
 ```
 
 Requires the `classifier` gem (`~> 2.3`).
@@ -943,11 +996,18 @@ RobotLab's optional capabilities are packaged as separate gems:
 
 | Gem | Description |
 |-----|-------------|
-| [robot_lab-ractor](https://github.com/MadBomber/robot_lab-ractor) | CPU parallelism via Ruby Ractors — `ractor_safe` tools and DAG-scheduled parallel networks |
+| [robot_lab-a2a](https://github.com/MadBomber/robot_lab-a2a) | Expose robots and networks as Agent2Agent (A2A) protocol services over HTTP+SSE |
+| [robot_lab-audit](https://github.com/MadBomber/robot_lab-audit) | SQLite-backed execution audit log wired through the Hook system |
+| [robot_lab-discovery](https://github.com/MadBomber/robot_lab-discovery) | Zero-configuration mDNS/DNS-SD robot discovery on local networks |
+| [robot_lab-document_store](https://github.com/MadBomber/robot_lab-document_store) | Embedding-based semantic document store for search / RAG |
+| [robot_lab-durable](https://github.com/MadBomber/robot_lab-durable) | HTM-backed long-term memory and cross-session knowledge persistence |
+| [robot_lab-ractor](https://github.com/MadBomber/robot_lab-ractor) | Ractor-based parallel tool execution and DAG-scheduled parallel networks |
 | [robot_lab-rails](https://github.com/MadBomber/robot_lab-rails) | Rails Engine, generators, `RobotLab::Job` ActiveJob base with Turbo Stream broadcasting |
-| [robot_lab-durable](https://github.com/MadBomber/robot_lab-durable) | Cross-session knowledge persistence via YAML-backed durable store |
-| [robot_lab-document_store](https://github.com/MadBomber/robot_lab-document_store) | In-memory vector store with fastembed embeddings for semantic search / RAG |
-| [robot_lab-acp](https://github.com/MadBomber/robot_lab-acp) | Expose robots and networks as ACP (Agent Communication Protocol) HTTP+SSE services |
+| [robot_lab-to](https://github.com/MadBomber/robot_lab-to) | Autonomous overnight agent loop — iterate a robot toward an objective |
+| [robot_lab-web](https://github.com/MadBomber/robot_lab-web) | Browser console — stream a robot's run over Server-Sent Events |
+
+> [!NOTE]
+> `robot_lab-acp` is retired; its functionality is superseded by `robot_lab-a2a`.
 
 ## Documentation