robot_lab 0.2.6 → 0.2.7

data/docs/api/core/robot.md

@@ -12,11 +12,22 @@ RubyLLM::Agent
 
 `Robot` inherits from `RubyLLM::Agent`, which creates a persistent `@chat` on initialization. The robot adds template-based prompts, shared memory, hierarchical MCP configuration, and SimpleFlow pipeline integration on top of the base agent.
 
+`Robot` also includes `RobotLab::Runnable` and the mixins
+`Robot::TemplateRendering`, `Robot::MCPManagement`, `Robot::BusMessaging`,
+`Robot::HistorySearch`, `Robot::Budget`, and `Robot::Hooking`, and prepends
+`Robot::AgentSkillMatching`.
+
+## Constants
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `Robot::DEFAULT_MAX_TOOLS` | `128` | Ceiling on the number of tools handed to the provider per turn. Override per robot with `RunConfig#max_tools`; a nil, zero, or negative `max_tools` falls back to this default, so the cap cannot be disabled |
+
 ## Constructor
 
 ```ruby
 Robot.new(
-  name:,
+  name:,                      # required
   template: nil,
   system_prompt: nil,
   context: {},
@@ -33,9 +44,6 @@ Robot.new(
   enable_cache: true,
   bus: nil,
   skills: nil,
-  max_tool_rounds: nil,
-  token_budget: nil,
-  cost_budget: nil,
   temperature: nil,
   top_p: nil,
   top_k: nil,
@@ -43,15 +51,27 @@ Robot.new(
   presence_penalty: nil,
   frequency_penalty: nil,
   stop: nil,
+  max_tool_rounds: nil,
+  token_budget: nil,
+  cost_budget: nil,
+  doom_loop_threshold: nil,
+  mcp_discovery: false,
   config: nil
 )
 ```
 
+!!! warning "The keyword list is closed"
+    `Robot#initialize` has no `**rest`. Any keyword not listed above raises
+    `ArgumentError`. In particular `auto_compact:`, `compact_threshold:`,
+    `ractor_pool_size:`, `max_concurrent_robots:`, and `max_tools:` are
+    **`RunConfig` fields only** — pass them via `config:`, not as constructor
+    kwargs. There is no `memory:`, `learn:`, or `learn_domain:` keyword.
+
 ### Parameters
 
 | Name | Type | Default | Description |
 |------|------|---------|-------------|
-| `name` | `String` | **required** | Unique identifier for the robot |
+| `name` | `String` | **required** | Identifier for the robot. `RobotLab.build` defaults it to the literal string `"robot"`; that default is load-bearing — front-matter `robot_name:` is applied only when the constructor name is still `"robot"` |
 | `template` | `Symbol`, `nil` | `nil` | Prompt template (e.g., `:assistant` loads `prompts/assistant.md`) |
 | `system_prompt` | `String`, `nil` | `nil` | Inline system prompt (appended after template if both given) |
 | `context` | `Hash`, `Proc` | `{}` | Variables passed to the template |
@@ -61,7 +81,7 @@ Robot.new(
 | `provider` | `String`, `Symbol`, `nil` | `nil` | LLM provider for local providers (e.g., `:ollama`, `:gpustack`). Automatically sets `assume_model_exists: true` |
 | `mcp_servers` | `Array` | `[]` | Legacy MCP server configurations |
 | `mcp` | `Symbol`, `Array` | `:none` | Hierarchical MCP config (`:none`, `:inherit`, or server array) |
-| `tools` | `Symbol`, `Array` | `:none` | Hierarchical tools config (`:none`, `:inherit`, or tool name **array**). Must be tool *names* (String/Symbol) — passing an instance or class raises `ArgumentError` telling you to use `local_tools:` instead. See [Runtime Tool Filtering](../../guides/using-tools.md#runtime-tool-filtering) |
+| `tools` | `Symbol`, `Array` | `:none` | Hierarchical tools config (`:none`, `:inherit`, or tool name **array**). Must be tool *names* (String/Symbol) — `validate_tools_filter!` raises `ArgumentError` for an instance or class, telling you to use `local_tools:` instead. **For a standalone robot, leave this unset at build time**: `tools: :inherit` here resolves against the global parent `:none` and yields an allowlist that matches nothing. Inside a network whose `config:` sets `tools:`, build-time `:inherit` is the correct way to opt in. See [Runtime Tool Filtering](../../guides/using-tools.md#runtime-tool-filtering) |
 | `on_tool_call` | `Proc`, `nil` | `nil` | Callback invoked when a tool is called |
 | `on_tool_result` | `Proc`, `nil` | `nil` | Callback invoked when a tool returns a result |
 | `on_content` | `Proc`, `nil` | `nil` | Stored streaming callback invoked with each content chunk (see [Streaming](#streaming)) |
@@ -71,17 +91,25 @@ Robot.new(
 | `max_tool_rounds` | `Integer`, `nil` | `nil` | Circuit breaker: raise `ToolLoopError` after this many tool calls in one `run()` (see [Tool Loop Circuit Breaker](#tool-loop-circuit-breaker)) |
 | `token_budget` | `Integer`, `nil` | `nil` | Raise `InferenceError` if cumulative tokens exceed this limit after a call; raise `BudgetExceeded` up front if already exhausted (see [Budgets](#budgets)) |
 | `cost_budget` | `Float`, `nil` | `nil` | Same enforcement as `token_budget`, tracked in cumulative dollar cost instead of tokens (requires provider pricing data) |
+| `doom_loop_threshold` | `Integer`, `nil` | `nil` | Tunes the always-on doom-loop detector (default threshold 3). See [Doom Loop Detection](#doom-loop-detection) |
+| `mcp_discovery` | `Boolean` | `false` | When true, the first run narrows the configured MCP server list to those `MCP::ServerDiscovery` judges relevant to the message |
 | `config` | `RunConfig`, `nil` | `nil` | Shared config merged with explicit kwargs (see [RunConfig](#runconfig)) |
-| `temperature` | `Float`, `nil` | `nil` | Controls randomness (0.0-1.0) |
-| `top_p` | `Float`, `nil` | `nil` | Nucleus sampling threshold |
-| `top_k` | `Integer`, `nil` | `nil` | Top-k sampling |
-| `max_tokens` | `Integer`, `nil` | `nil` | Maximum tokens in response |
-| `presence_penalty` | `Float`, `nil` | `nil` | Penalize based on presence |
-| `frequency_penalty` | `Float`, `nil` | `nil` | Penalize based on frequency |
-| `stop` | `String`, `Array`, `nil` | `nil` | Stop sequences |
+| `temperature` | `Float`, `nil` | `nil` | Controls randomness — applied via `chat.with_temperature` |
+| `top_p` | `Float`, `nil` | `nil` | Nucleus sampling threshold — applied via `chat.with_params` |
+| `top_k` | `Integer`, `nil` | `nil` | Top-k sampling — applied via `chat.with_params` |
+| `max_tokens` | `Integer`, `nil` | `nil` | Maximum tokens in response — applied via `chat.with_params` |
+| `presence_penalty` | `Float`, `nil` | `nil` | Penalize based on presence — applied via `chat.with_params` |
+| `frequency_penalty` | `Float`, `nil` | `nil` | Penalize based on frequency — applied via `chat.with_params` |
+| `stop` | `String`, `Array`, `nil` | `nil` | Stop sequences — applied via `chat.with_params` |
 
 When both `config:` and explicit kwargs (e.g., `temperature:`) are provided, explicit kwargs always win.
 
+`model` and `temperature` are applied to the chat with dedicated `with_model` /
+`with_temperature` calls. The remaining six LLM fields (`top_p`, `top_k`,
+`max_tokens`, `presence_penalty`, `frequency_penalty`, `stop`) are collected into
+a single `chat.with_params(...)` call. This distinction matters for template
+front matter — see [Templates](#templates).
+
 ## Factory Method
 
 ```ruby
@@ -93,12 +121,15 @@ robot = RobotLab.build(
   enable_cache: true,
   bus: nil,           # Optional TypedBus::MessageBus
   skills: nil,        # Optional skill templates
+  config: nil,        # Optional RunConfig
   **options           # All other Robot.new parameters
 )
 # => RobotLab::Robot
 ```
 
-If `name` is omitted, it defaults to `"robot"`.
+If `name` is omitted, it defaults to the literal string `"robot"`. `**options`
+is forwarded verbatim to `Robot.new`, whose keyword list is closed — an unknown
+option raises `ArgumentError`.
 
 ## Attributes (Read-Only)
 
@@ -123,6 +154,7 @@ If `name` is omitted, it defaults to `"robot"`.
 | `total_output_tokens` | `Integer` | Cumulative output tokens received across all `run()` calls |
 | `learnings` | `Array<String>` | Accumulated cross-run observations (see [Learning Accumulation](#learning-accumulation)) |
 | `budget_ledger` | `RobotLab::Budget::Ledger`, `nil` | Reserve/reconcile ledger backing `token_budget`/`cost_budget`; `nil` when neither is configured (see [Budgets](#budgets)) |
+| `hooks` | `RobotLab::HookRegistry` | This robot's own hook registry. Populated by [`robot.on`](#on); consulted alongside `RobotLab.hooks` and the network's registry on every run |
 
 ## Attributes (Read-Write)
 
@@ -138,7 +170,9 @@ Used by tools like [`AskUser`](tool.md#built-in-askuser) that need terminal IO.
 ### run
 
 ```ruby
-result = robot.run(message, **kwargs, &block)
+result = robot.run(message = nil, network: nil, task: nil,
+                   network_memory: nil, network_config: nil, memory: nil,
+                   mcp: :none, tools: :none, hooks: nil, **kwargs, &block)
 # => RobotResult
 ```
 
@@ -148,35 +182,63 @@ Primary execution method. Sends a message to the LLM with memory/MCP/tools resol
 
 | Name | Type | Default | Description |
 |------|------|---------|-------------|
-| `message` | `String` | **required** | The user message to send |
-| `network` | `NetworkRun`, `nil` | `nil` | Network context (passed internally) |
-| `network_memory` | `Memory`, `nil` | `nil` | Shared network memory |
-| `memory` | `Memory`, `Hash`, `nil` | `nil` | Runtime memory to merge |
+| `message` | `String`, `nil` | `nil` | The user message to send (positional, optional) |
+| `network` | `Network`, `nil` | `nil` | Network context (passed internally by `Network#run`) |
+| `task` | `Task`, `nil` | `nil` | Task wrapper for the current pipeline step (passed internally); surfaces on hook contexts |
+| `network_memory` | `Memory`, `nil` | `nil` | Shared network memory (passed internally) |
+| `network_config` | `RunConfig`, `nil` | `nil` | Network-level config used when resolving `:inherit` for `mcp`/`tools` (passed internally) |
+| `memory` | `Memory`, `Hash`, `nil` | `nil` | A `Memory` replaces the active memory for this run; a `Hash` is merged into it |
 | `mcp` | `Symbol`, `Array` | `:none` | Runtime MCP override — `:inherit` (all attached servers), `:none`/`[]` (zero this turn), or an explicit array |
 | `tools` | `Symbol`, `Array` | `:none` | Runtime tools override — `:inherit` (all attached tools), `:none`/`[]` (zero this turn), or an explicit name array. See [Runtime Tool Filtering](../../guides/using-tools.md#runtime-tool-filtering) |
-| `**kwargs` | `Hash` | `{}` | Additional keyword arguments passed to `Agent#ask` |
+| `hooks` | `Array`, `nil` | `nil` | Per-run hook handler classes, active only for this call |
+| `**kwargs` | `Hash` | `{}` | See below — **not** a passthrough to `Agent#ask` |
 | `&block` | `Proc` | `nil` | Per-call streaming block, receives each content chunk |
 
+**What `**kwargs` actually does.** Only `:with` is forwarded to the underlying
+`Agent#ask` (`kwargs.slice(:with)`). *Every other* keyword is treated as
+template re-render context: `kwargs.except(:with)` is merged over the build-time
+context and the template is re-rendered before the call. If the robot has no
+`template:`, those extra keywords are simply ignored.
+
+```ruby
+robot = RobotLab.build(name: "support", template: :support)
+robot.run("Help me", company: "Acme")     # re-renders the template with company: "Acme"
+robot.run("Describe this", with: image)   # forwarded to Agent#ask as attachments
+```
+
 When both a stored `on_content` callback and a runtime block are provided, both fire (stored first, then runtime block).
 
-Because `tools`/`mcp` default to `:none` here too, a bare `robot.run(message)` with no override sends **zero** tools/MCP servers for that call — pass `tools: :inherit` (and/or `mcp: :inherit`) explicitly to use what's attached. Each call's resolved tool set *replaces* the chat's tools rather than accumulating, so a subsequent `:none` call correctly clears whatever a prior call attached, and the fully-resolved set is clamped to `max_tools` (128 by default) right before being handed to the provider — see [Tool Capping](../../guides/using-tools.md#tool-capping-and-per-turn-filtering).
+!!! warning "`tools:`/`mcp:` default to `:none` here"
+    A bare `robot.run(message)` sends **zero** tools and connects **no** MCP
+    servers for that call, even when `local_tools:`/`mcp:` were supplied at
+    build time. Pass `tools: :inherit` (and/or `mcp: :inherit`) explicitly to
+    use what is attached. `mcp: :inherit` triggers the connection attempt;
+    `tools: :inherit` is additionally required for the MCP tools to be sent.
+
+Each call's resolved tool set *replaces* the chat's tools rather than accumulating, so a subsequent `:none` call correctly clears whatever a prior call attached, and the fully-resolved set is clamped to `max_tools` (`DEFAULT_MAX_TOOLS = 128` by default) right before being handed to the provider — see [Tool Capping](../../guides/using-tools.md#tool-capping-and-per-turn-filtering).
 
 **Returns:** `RobotResult`
 
 **Examples:**
 
 ```ruby
-# Simple message
+# Simple message — sends no tools, connects no MCP servers
 result = robot.run("What is 2+2?")
 
+# Send the tools attached via local_tools:
+result = robot.run("What is 15 * 7?", tools: :inherit)
+
+# Connect MCP servers and send their tools
+result = robot.run("Search the repo", mcp: :inherit, tools: :inherit)
+
+# Restrict this turn to a named subset
+result = robot.run("Look it up", tools: %w[order_lookup])
+
 # With runtime memory
 result = robot.run("Summarize the data", memory: { data: report })
 
 # With per-call streaming block
 result = robot.run("Tell me a story") { |chunk| print chunk.content }
-
-# With runtime overrides
-result = robot.run("Help me", mcp: :none, tools: :none)
 ```
 
 ### model
@@ -187,6 +249,21 @@ robot.model  # => "claude-sonnet-4" or nil
 
 Returns the model ID string. Resolves through the underlying chat object.
 
+### effective_config
+
+```ruby
+robot.effective_config
+# => { model: "claude-sonnet-4-20250514", temperature: 0.7, max_tokens: 4096 }
+```
+
+Snapshot of the robot's merged `RunConfig` as a plain Hash, `.compact`ed so unset
+fields are omitted. Reports exactly these keys when set: `model`, `temperature`,
+`top_p`, `top_k`, `max_tokens`, `presence_penalty`, `frequency_penalty`, `stop`,
+`tools`, `mcp`, `max_tool_rounds`, `doom_loop_threshold`, `auto_compact`,
+`compact_threshold`, `token_budget`, `cost_budget`.
+
+This is a *view*, not the config object — use `robot.config` for the `RunConfig` itself.
+
 ### update
 
 ```ruby
@@ -203,29 +280,52 @@ robot.update(
 
 Reconfigure the robot after construction. Returns `self` for chaining.
 
+The five named parameters are applied directly (`template` re-renders the prompt;
+`system_prompt`, `model`, and `temperature` call the corresponding `with_*` on the chat).
+
+!!! warning "`**kwargs` only reaches fields the chat exposes as `with_<key>`"
+    Each extra keyword is forwarded as `@chat.with_#{key}(value)` **only if
+    `@chat.respond_to?(:"with_#{key}")`**. `RubyLLM::Chat` has no
+    `with_max_tokens`, `with_top_p`, `with_top_k`, `with_stop`,
+    `with_presence_penalty`, or `with_frequency_penalty` — so
+    `robot.update(max_tokens: 4000)` silently does nothing. Use
+    `robot.with_params(max_tokens: 4000)` for those fields.
+
 ### with_* Methods (Chaining)
 
-All `with_*` methods delegate to the persistent `@chat` and return `self` for chaining:
+`with_*` methods are discovered from `RubyLLM::Chat` at construction time and
+defined as singleton methods that delegate to the persistent `@chat` and return
+`self` for chaining. This is the **complete** set:
 
 | Method | Description |
 |--------|-------------|
 | `with_model(model_id)` | Change the LLM model |
 | `with_temperature(temp)` | Set temperature |
-| `with_top_p(value)` | Set nucleus sampling |
-| `with_top_k(value)` | Set top-k sampling |
-| `with_max_tokens(value)` | Set max response tokens |
-| `with_presence_penalty(value)` | Set presence penalty |
-| `with_frequency_penalty(value)` | Set frequency penalty |
-| `with_stop(sequences)` | Set stop sequences |
 | `with_instructions(prompt)` | Set system instructions |
 | `with_tool(tool)` | Add a single tool |
 | `with_tools(*tools)` | Add multiple tools |
-| `with_params(**params)` | Set additional parameters |
+| `with_params(**params)` | Set arbitrary provider parameters |
 | `with_headers(**headers)` | Set custom headers |
 | `with_schema(schema)` | Set output schema |
 | `with_context(**ctx)` | Set context |
 | `with_thinking(opts)` | Enable extended thinking |
-| `with_bus(bus)` | Connect to a message bus (creates one if nil) |
+
+Plus two defined by RobotLab itself:
+
+| Method | Description |
+|--------|-------------|
+| `with_template(id, **context)` | Apply a prompt_manager template (see below) |
+| `with_bus(bus = nil)` | Connect to a message bus (creates one if nil) |
+
+!!! danger "These do not exist"
+    `with_max_tokens`, `with_top_p`, `with_top_k`, `with_stop`,
+    `with_presence_penalty`, and `with_frequency_penalty` are **not** defined
+    and raise `NoMethodError`. Set those fields with a constructor kwarg
+    (`max_tokens: 2000`) or with `with_params`:
+
+    ```ruby
+    robot.with_params(max_tokens: 2000, top_p: 0.3)
+    ```
 
 **Example:**
 
@@ -234,6 +334,7 @@ robot = RobotLab.build(name: "bot")
 robot
   .with_model("claude-sonnet-4")
   .with_temperature(0.7)
+  .with_params(max_tokens: 2000)
   .with_instructions("Be concise.")
   .run("Hello")
 ```
@@ -276,7 +377,7 @@ message = robot.send_message(to: :bob, content: "Tell me a joke.")
 # => RobotMessage
 ```
 
-Publish a message to another robot's bus channel. Increments the internal message counter, creates a `RobotMessage`, tracks it in the outbox, and publishes to the target channel. The counter and outbox mutation are synchronized with an internal mutex, so concurrent `send_message`/`send_reply` calls from multiple threads and reply correlation on the poller thread never clobber each other.
+Publish a message to another robot's bus channel. Increments the internal message counter, creates a `RobotMessage`, tracks it in the outbox, and publishes to the target channel. The counter and outbox mutation are synchronized with an internal mutex, so concurrent `send_message`/`send_reply` calls from multiple threads and reply correlation never clobber each other.
 
 **Parameters:**
 
@@ -360,7 +461,7 @@ Auto-answer inbound (non-reply) bus tasks: run the block to produce a reply, and
 
 **Returns:** `self`
 
-Messages that are themselves replies (`message.reply?`) are ignored, so a two-way `respond_to_tasks` conversation between robots does not loop. The responder runs on the bus poller's drain thread, so deliveries to this robot are handled one at a time — a long-running responder delays the next inbound message.
+Messages that are themselves replies (`message.reply?`) are ignored, so a two-way `respond_to_tasks` conversation between robots does not loop. The responder runs **inline in the caller's context** — `BusPoller` has no background thread; its `enqueue` either processes the delivery immediately or queues it behind the one in flight and drains it when that finishes. Deliveries to a given robot are therefore handled one at a time, and a long-running responder blocks the sender as well as the next inbound message.
 
 ```ruby
 bob.respond_to_tasks { |message| "handled: #{message.content}" }
@@ -431,6 +532,69 @@ worker2 = bot.spawn(name: "worker", system_prompt: "Worker 2")
 # Messages sent to :worker are delivered to both
 ```
 
+### assign_bus_poller
+
+```ruby
+robot.assign_bus_poller(poller, group: :default)
+# => void — do not rely on the return value
+```
+
+Adopt a shared [`BusPoller`](../support.md#robotlabbuspoller) — normally the
+network's. `Network#task` calls this for every robot that responds to it, passing
+the task's `poller_group:`. Any private poller the robot auto-created is dropped
+first.
+
+**Parameters:**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `poller` | `BusPoller` | **required** | The shared poller to adopt |
+| `group` | `Symbol` | `:default` | Poller group label — informational only; groups share one drain mechanism |
+
+You only call this directly when wiring robots onto a shared poller outside a
+`Network`.
+
+### inherited_llm_settings
+
+```ruby
+robot.inherited_llm_settings
+# => { model: "llama3.2", provider: :ollama }
+```
+
+The model/provider pair a [`spawn`](#spawn)ed child inherits from this robot.
+Returns `{}` when neither is set — each key is included only when the
+corresponding reader is truthy. Exposed so an application building children by
+some route other than `spawn` can apply the same inheritance:
+
+```ruby
+child = RobotLab.build(name: "helper", bus: parent.bus, **parent.inherited_llm_settings)
+```
+
+### rerender_template
+
+```ruby
+robot.rerender_template(run_context)   # internal — see the warning below
+```
+
+Re-renders the robot's template with `run_context` merged over the build-time
+context (skill bodies included, when `skills:` are in play) and reinstalls the
+result as the system prompt, re-appending the inline `system_prompt`. `run` calls
+it automatically when the robot has a `template:` and the call carried extra
+keywords — every keyword except `:with` — which is the mechanism behind
+`robot.run("Help me", company: "Acme")`.
+
+`Robot::AgentSkillMatching` overrides it to re-prepend any matched AgentSkill
+instructions afterward, because a re-render replaces the whole system prompt and
+would otherwise discard them mid-run.
+
+!!! warning "Public only by accident — treat it as internal"
+    `rerender_template` is `private` in `Robot::TemplateRendering`, but the
+    prepended `Robot::AgentSkillMatching` redefines it **above** its own
+    `private` keyword, so the effective method on `Robot` is public. That is an
+    artifact of the override, not a supported entry point: the return value is
+    unspecified, and it mutates the chat's system prompt for the rest of the
+    conversation. Pass template context to `run` instead.
+
 ### with_bus
 
 ```ruby
@@ -506,7 +670,18 @@ Inject pre-connected MCP clients and their tools into this robot. Used by host a
 ```ruby
 # Host app manages MCP connections
 clients = { "github" => github_client }
-tools   = github_client.list_tools.map { |t| RobotLab::Tool.from_mcp(t) }
+
+# There is no Tool.from_mcp — MCP wrappers are built with Tool.create,
+# exactly as RobotLab's own discover_mcp_tools does.
+tools = github_client.list_tools.map do |tool_def|
+  name = tool_def[:name]
+  RobotLab::Tool.create(
+    name:        name,
+    description: tool_def[:description],
+    parameters:  tool_def[:inputSchema],
+    mcp:         "github"
+  ) { |args| github_client.call_tool(name, args) }
+end
 
 robot.inject_mcp!(clients: clients, tools: tools)
 ```
@@ -573,6 +748,147 @@ saved = robot.messages.dup
 robot.replace_messages(saved)
 ```
 
+### compress_history
+
+```ruby
+robot.compress_history(
+  recent_turns: 3,
+  keep_threshold: 0.6,
+  drop_threshold: 0.2,
+  summarizer: nil
+)
+# => self
+```
+
+Shrink the conversation by scoring each older turn against the most recent
+context and dropping or summarizing the least relevant ones. Internally builds a
+`RobotLab::HistoryCompressor` and hands the result to `replace_messages`.
+
+**Parameters:**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `recent_turns` | `Integer` | `3` | Turn pairs at the end that are always kept verbatim |
+| `keep_threshold` | `Float` | `0.6` | Cosine score at or above this → kept verbatim |
+| `drop_threshold` | `Float` | `0.2` | Cosine score below this → dropped |
+| `summarizer` | `#call`, `nil` | `nil` | `callable(text) -> String` applied to the medium tier; `nil` drops the medium tier instead |
+
+**Returns:** `self`
+
+System messages and tool-call/tool-result messages are always preserved.
+
+Scoring uses **term-frequency cosine similarity without IDF** (see
+`RobotLab::Convergence`), so it is a lexical overlap measure, not a semantic one.
+
+**Raises:** `RobotLab::DependencyError` when the optional `classifier` gem
+(`~> 2.3`) is not installed.
+
+```ruby
+robot.compress_history(recent_turns: 5, summarizer: ->(text) { text[0, 200] })
+```
+
+`auto_compact: :context_window` on a `RunConfig` calls this automatically before
+an LLM call once estimated tokens exceed `compact_threshold` (default `0.80`) of
+the model's context window. When the `classifier` gem is missing there, the
+`DependencyError` is caught, logged at `:warn`, and compaction is skipped.
+
+### delegate
+
+```ruby
+result = robot.delegate(to:, task:, async: false, **run_kwargs)
+# => RobotResult (async: false) | DelegationFuture (async: true)
+```
+
+Hand a task to another robot and annotate the result with delegation metadata.
+
+**Parameters:**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `to` | `Robot` | **required** | The robot to delegate to |
+| `task` | `String` | **required** | The message to send |
+| `async` | `Boolean` | `false` | When true, returns a `DelegationFuture` immediately |
+| `**run_kwargs` | `Hash` | `{}` | Forwarded verbatim to the delegatee's `run` — including `tools:`/`mcp:`, which still default to `:none` |
+
+**Synchronous** (default) blocks until the delegatee finishes and returns its
+`RobotResult` with `duration` and `delegated_by` set.
+
+**Asynchronous** (`async: true`) runs the delegatee on a new `Thread` and returns
+a `RobotLab::DelegationFuture`. Call `future.value` to block, `future.value(timeout: N)`
+to block with a deadline (raises `RobotLab::DelegationFuture::DelegationTimeout`),
+or `future.resolved?` to poll. An exception in the delegatee is captured and
+re-raised from `future.value`.
+
+```ruby
+# Synchronous
+result = manager.delegate(to: analyst, task: "What are the risks?")
+result.reply
+result.delegated_by   # => "manager"
+result.duration       # => 1.43
+
+# Async fan-out
+f1 = manager.delegate(to: summarizer, task: "summarize ...", async: true)
+f2 = manager.delegate(to: analyst,    task: "analyze ...",   async: true, tools: :inherit)
+summary  = f1.value
+analysis = f2.value(timeout: 30)
+```
+
+### search_history
+
+```ruby
+results = robot.search_history(query, limit: 5)
+# => Array<RobotLab::Robot::HistorySearch::HistoryResult>
+```
+
+Rank the robot's own conversation messages against a natural-language query
+using stemmed term-frequency cosine similarity.
+
+**Parameters:**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `query` | `String` | **required** | Natural-language search query |
+| `limit` | `Integer` | `5` | Maximum results to return |
+
+**Returns:** `Array<HistoryResult>` sorted by score descending. `HistoryResult`
+is a `Data` type with members `text`, `role`, `score`, and `index`.
+
+Messages shorter than `MIN_SCORE_LENGTH` (20 characters) are skipped, as are
+messages that score zero.
+
+**Raises:** `RobotLab::DependencyError` when the optional `classifier` gem is not installed.
+
+```ruby
+robot.search_history("quarterly revenue", limit: 3).each do |r|
+  puts "[#{r.role}] (#{r.score.round(3)}) #{r.text}"
+end
+```
+
+### on
+
+```ruby
+robot.on(HandlerClass, context: nil)
+# => the registration
+```
+
+Register a hook handler on **this robot's** registry (`robot.hooks`). The robot's
+registry is consulted on every run alongside `RobotLab.hooks` (global) and the
+network's registry, in that order.
+
+**Parameters:**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `handler_class` | `Class` | **required** | The hook handler class |
+| `context` | `Object`, `nil` | `nil` | Optional per-registration context passed to the handler |
+
+!!! note "Task hooks bypass robot registries"
+    The `:task` hook family resolves against `[RobotLab.hooks, network&.hooks]`
+    only. A handler registered with `robot.on` never fires for task hooks —
+    register it with `RobotLab.on` or `network.on` instead.
+
+Handlers can also be scoped to a single call with `robot.run(msg, hooks: [HandlerClass])`.
+
 ### chat_provider
 
 ```ruby
@@ -615,7 +931,23 @@ robot.to_h
 # => Hash
 ```
 
-Returns a hash representation of the robot including name, description, template, skills, system_prompt, local_tools, mcp_tools, mcp_config, tools_config, mcp_servers, model, and bus (true if configured, omitted otherwise). Nil values are compacted out.
+Returns a hash representation of the robot. Keys, in order: `name`,
+`description`, `template`, `skills`, `system_prompt`, `local_tools` (tool names),
+`mcp_tools` (tool names), `mcp_config`, `tools_config`, `mcp_servers` (connected
+client names), `model`, `config` (the `RunConfig` as a JSON-safe hash, omitted
+when the config is empty), and `bus` (`true` if configured, omitted otherwise).
+The whole hash is `.compact`ed, so nil values are dropped.
+
+```ruby
+RobotLab.build(name: "x", max_tokens: 100).to_h
+# => { name: "x", local_tools: [], mcp_tools: [], mcp_config: :none,
+#      tools_config: :none, mcp_servers: [], model: "claude-sonnet-4-20250514",
+#      config: { max_tokens: 100, enable_cache: true } }
+```
+
+The `config` value comes from `RunConfig#to_json_hash`, which omits the
+non-serializable fields (`on_tool_call`, `on_tool_result`, `on_content`, `bus`,
+`auto_compact`).
 
 ## Memory Behavior
 
@@ -640,20 +972,60 @@ Templates are `.md` files with optional YAML front matter, loaded via `prompt_ma
 robot = RobotLab.build(name: "bot", template: :assistant, context: { tone: "friendly" })
 ```
 
-Front matter supports two categories of keys:
+Front matter supports two categories of keys.
+
+**LLM Config:** `model`, `temperature`, `top_p`, `top_k`, `max_tokens`,
+`presence_penalty`, `frequency_penalty`, `stop` are all *parsed* into a
+`RunConfig`.
 
-**LLM Config:** `model`, `temperature`, `top_p`, `top_k`, `max_tokens`, `presence_penalty`, `frequency_penalty`, `stop` — applied to the underlying chat.
+!!! warning "Only `model` and `temperature` actually take effect from front matter"
+    Front-matter LLM fields are applied through `RunConfig#apply_to`, which
+    dispatches `chat.with_<field>` guarded by `respond_to?`. `RubyLLM::Chat`
+    defines only `with_model` and `with_temperature`, so `top_p`, `top_k`,
+    `max_tokens`, `presence_penalty`, `frequency_penalty`, and `stop` are parsed
+    and **silently dropped**. Set those six as constructor kwargs or on a
+    `config:` `RunConfig` instead — that path goes through `with_params` and
+    does work.
 
 **Robot Extras:** `robot_name`, `description`, `tools`, `mcp`, `skills` — applied to the robot's identity and capabilities. Constructor-provided values always take precedence.
 
 | Key | Type | Description |
 |-----|------|-------------|
-| `robot_name` | `String` | Override robot name (when constructor uses the default `"robot"`) |
-| `description` | `String` | Human-readable description |
-| `tools` | `Array<String>` | Tool class names resolved via `Object.const_get` |
-| `mcp` | `Array<Hash>` | MCP server configurations |
+| `robot_name` | `String` | Override robot name — applied only when the constructor name is still the default `"robot"` |
+| `description` | `String` | Human-readable description; applied only when the constructor passed no `description:` |
+| `tools` | `Array` | Tool entries; applied only when `local_tools:` is empty (see below) |
+| `mcp` | `Array<Hash>` | MCP server configurations; applied only when the constructor `mcp:` is `:none` |
 | `skills` | `Array<Symbol>` | Skill templates to prepend (recursive, with cycle detection) |
 
+Templates render with ERB — write `<%= var %>`. `{{ var }}` is not interpolated
+and passes through verbatim.
+
+### Front-matter `tools:` resolution
+
+Front-matter `tools` entries are resolved by `resolve_frontmatter_tools`, and the
+result becomes `local_tools` (real tool objects), **not** the `tools_config`
+name allowlist. Three entry shapes are accepted:
+
+| Entry | Behavior |
+|-------|----------|
+| `String` | Resolved with `Object.const_get`. If the constant is a `Class` that is `< RubyLLM::Tool`, it is **instantiated** (`const.new`); any other constant is used as-is |
+| `Class` | **Instantiated** (`name.new`) |
+| anything else | Used as-is (e.g. an already-built tool instance) |
+
+An unresolvable name does **not** raise. It is logged at `:warn`
+(`"Robot '<name>': tool '<X>' not found, skipping"`) and skipped.
+
+```markdown
+---
+tools:
+  - OrderLookup      # instantiated: OrderLookup.new
+  - RefundProcessor
+---
+```
+
+Because `run()` still defaults to `tools: :none`, front-matter tools are sent
+only when you pass `tools: :inherit` at run time.
+
 ## Skills
 
 Skills compose robot behaviors from reusable templates. Each skill is a standard `.md` template whose prompt body is prepended before the main template. Skills are expanded depth-first with automatic cycle detection.
@@ -704,7 +1076,45 @@ robot = RobotLab.build(
 robot.config  #=> RunConfig with model: "claude-sonnet-4", temperature: 0.9, ...
 ```
 
-RunConfig fields: `model`, `temperature`, `top_p`, `top_k`, `max_tokens`, `presence_penalty`, `frequency_penalty`, `stop`, `mcp`, `tools`, `on_tool_call`, `on_tool_result`, `on_content`, `bus`, `enable_cache`.
+`RunConfig::FIELDS` is the complete, authoritative list. Passing any other key to
+`RunConfig.new` raises `ArgumentError: Unknown RunConfig field: ...`.
+
+| Group | Constant | Fields |
+|-------|----------|--------|
+| LLM | `LLM_FIELDS` | `model`, `temperature`, `top_p`, `top_k`, `max_tokens`, `presence_penalty`, `frequency_penalty`, `stop` |
+| Tools | `TOOL_FIELDS` | `mcp`, `tools` |
+| Callbacks | `CALLBACK_FIELDS` | `on_tool_call`, `on_tool_result`, `on_content` |
+| Infrastructure | `INFRA_FIELDS` | `bus`, `enable_cache`, `max_tool_rounds`, `token_budget`, `cost_budget`, `ractor_pool_size`, `max_concurrent_robots`, `doom_loop_threshold`, `auto_compact`, `compact_threshold`, `max_tools` |
+
+Five of those infrastructure fields are `RunConfig`-only — they are **not**
+`Robot.new` keywords: `ractor_pool_size`, `max_concurrent_robots`,
+`auto_compact`, `compact_threshold`, `max_tools`. (`max_concurrent_robots` is
+consumed by `Network`, not by `Robot`; `ractor_pool_size` by the
+`robot_lab-ractor` extension.)
+
+```ruby
+config = RobotLab::RunConfig.new(auto_compact: :context_window, compact_threshold: 0.7, max_tools: 32)
+robot  = RobotLab.build(name: "long_runner", system_prompt: "...", config: config)
+```
+
+Other `RunConfig` API:
+
+| Method | Description |
+|--------|-------------|
+| `RunConfig.new(**kwargs) { \|c\| ... }` | Keyword construction plus an optional block DSL (`c.model "..."`) |
+| `#merge(other)` | Returns a **new** RunConfig; the other's non-nil values win |
+| `#to_h` | The explicitly-set fields |
+| `#to_json_hash` | `to_h` minus `NON_SERIALIZABLE_FIELDS` (`on_tool_call`, `on_tool_result`, `on_content`, `bus`, `auto_compact`) |
+| `#apply_to(chat, provider: nil, assume_model_exists: false)` | Applies `LLM_FIELDS` via `chat.with_<field>`, guarded by `respond_to?` |
+| `#empty?` / `#key?(field)` | Introspection |
+| `RunConfig.from_front_matter(metadata)` | Builds a RunConfig from a template's parsed metadata |
+
+!!! note "A network-level `config:` only propagates `mcp` and `tools`"
+    LLM fields and callbacks (`on_content`, `on_tool_call`, `on_tool_result`)
+    are read from the robot's own config at construction time and are never
+    inherited from a network. A member robot picks up the network's `mcp`/`tools`
+    only when it opts in with `:inherit`. `max_concurrent_robots` is the one
+    field the network itself consumes.
 
 See [Configuration: RunConfig](../../getting-started/configuration.md#runconfig-shared-operational-defaults) for full details.
 
@@ -778,27 +1188,55 @@ robot.run("Tell me a story") { |chunk| stream_to_client(chunk.content) }
 
 ## Configuration Hierarchy
 
-Tools and MCP servers use hierarchical resolution: **runtime > robot > network > global config**.
+Tools and MCP servers use hierarchical resolution: **runtime > robot > task > network > global config**.
 
 ```
 RobotLab.config (global)
   |
-  +-- Network (config:)
+  +-- Network (config:)  -- propagates only mcp/tools to members
   |     |
-  |     +-- Task (config:)
+  |     +-- Task (config:)  -- likewise only mcp/tools
   |     |     |
   |     |     +-- Robot (config: + build-time mcp:, tools:)
   |     |           |
-  |     |           +-- Template front matter
-  |     |                 |
-  |     |                 +-- run() call (runtime mcp:, tools:)
+  |     |           +-- run() call (runtime mcp:, tools:)  <- default :none
 ```
 
 Values at each level:
 
-- `:none` -- no tools/MCP at this level
-- `:inherit` -- inherit from parent level
-- `Array` -- explicit list of tool names or MCP server configs
+- `:none` -- no tools/MCP at this level (the default at every level)
+- `:inherit` -- inherit from the parent level
+- `Array` -- a filter over the already-attached tools, or a list of MCP server configs. Entries are matched against `tool.name.to_s`, so they must be written in the same form the tool was attached in: a class-attached tool matches `"RefundTool"`, an instance-attached one matches `"refund"`. (The constructor's `tools:` accepts only Strings/Symbols; the class form is usable at the task/`run` level, which is not validated.)
+
+!!! danger "For a standalone robot, do not set `tools: :inherit` at build time"
+    The parent is recomputed on every run as
+    `network_config&.tools || network_parent_config(network)&.tools || RobotLab.config.tools`.
+    For a **standalone** robot that resolves to the global `:none`, so a
+    build-time `:inherit` produces the allowlist `["none"]`, which matches
+    nothing. Leave `tools:` unset on the constructor and pass `tools: :inherit`
+    on `run()` instead.
+
+    | build `tools:` | run `tools:` | tools sent |
+    |---|---|---|
+    | unset | `:none` (default) | none |
+    | unset | `:inherit` | all attached — **the correct pattern** |
+    | `:inherit` | `:inherit` | none — broken |
+    | `:none` | `:inherit` | all attached |
+
+    This does **not** generalize to robots inside a network. When the network's
+    `config:` sets `tools:`/`mcp:`, the parent resolved at run time is that
+    network value, and a build-time `:inherit` is exactly how the robot opts
+    into it. See [MCP in Networks](../mcp/index.md#mcp-in-networks).
+
+### Per-robot config cascade
+
+For a single robot, least- to most-specific:
+
+```
+template front matter  ->  config: (RunConfig)  ->  constructor kwargs
+```
+
+Front matter is the **base**, not an override. Constructor kwargs always win.
 
 ## Examples
 
@@ -848,9 +1286,14 @@ robot = RobotLab.build(
   system_prompt: "You help with math.",
   local_tools: [Calculator]
 )
-result = robot.run("What is 15 * 7?")
+
+# run() defaults to tools: :none — pass :inherit to actually send Calculator
+result = robot.run("What is 15 * 7?", tools: :inherit)
 ```
 
+Note that `param` accepts only `type:`, `desc:`/`description:`, and `required:` —
+there is no `enum:` option. See [Tool](tool.md#param).
+
 ### Robot with Local Provider
 
 ```ruby
@@ -880,10 +1323,15 @@ robot = RobotLab.build(
     }
   ]
 )
-result = robot.run("Search for popular Ruby repos")
+
+# mcp: :inherit triggers the connection; tools: :inherit sends the discovered tools
+result = robot.run("Search for popular Ruby repos", mcp: :inherit, tools: :inherit)
 robot.disconnect
 ```
 
+`transport:` must be a nested hash. MCP connection failures are logged and
+recorded in `robot.failed_mcp_server_names` — they are not raised.
+
 ### Robot with Skills
 
 ```ruby
@@ -985,7 +1433,7 @@ Every `robot.run()` returns a `RobotResult` with token counts for that call. The
 
 ```ruby
 robot.reset_token_totals
-# => nil
+# => the robot itself (returns self, so it chains)
 ```
 
 Reset the cumulative accounting counters to zero. Useful when you want to measure cost for a specific task batch while keeping the robot alive for the next batch.
@@ -1030,7 +1478,7 @@ Each `run()` reserves the remaining budget for every configured dimension before
 - **`RobotLab::BudgetExceeded`** — raised up front when a *prior* call already exhausted a dimension; the new call is refused before it spends anything.
 - **`RobotLab::InferenceError`** — raised after the call when *this* call's actual usage (from `RobotResult#input_tokens`/`output_tokens`, and the response's reported cost when the provider supports pricing) pushes cumulative usage over budget. This is the same error `token_budget` alone has always raised; `cost_budget` uses the analogous message (`"Cost budget exceeded: $X used, budget is $Y"`).
 
-See [Budgets](../../guides/observability.md#budgets-token--cost) for the full walkthrough.
+See [Budgets](../../guides/observability.md#budgets-token-cost) for the full walkthrough.
 
 ## Tool Loop Circuit Breaker
 
@@ -1058,7 +1506,13 @@ robot = RobotLab.build(name: "runner", system_prompt: "...", config: config)
 
 `RobotLab::ToolLoopError < RobotLab::InferenceError`
 
-Raised when the number of tool calls in a single `run()` exceeds `max_tool_rounds`. The error message includes the limit that was exceeded.
+Raised when the number of tool calls in a single `run()` exceeds `max_tool_rounds`. The message reads:
+
+```
+Circuit breaker triggered: <N> tool calls exceeded max_tool_rounds (<M>)
+```
+
+where `N` is the call count that tripped the breaker and `M` is the configured limit.
 
 ### Recovery after ToolLoopError
 
@@ -1070,6 +1524,7 @@ After a `ToolLoopError`, the chat contains a dangling `tool_use` block with no m
 begin
   robot.run("Execute all steps.")
 rescue RobotLab::ToolLoopError => e
+  # "Circuit breaker triggered: 11 tool calls exceeded max_tool_rounds (10)"
   puts "Circuit breaker fired: #{e.message}"
 end
 
@@ -1081,9 +1536,34 @@ puts robot.config.max_tool_rounds  # still set — config unchanged
 result = robot.run("Something new.")
 ```
 
+## Doom Loop Detection
+
+Distinct from the circuit breaker, doom-loop detection is **always on**. Every
+`run()` unconditionally installs a `RobotLab::DoomLoopDetector` over the chat's
+`execute_tool`, and removes it again when the run ends. `doom_loop_threshold:`
+only *tunes* it; it cannot be disabled from the constructor.
+
+```ruby
+robot = RobotLab.build(name: "worker", system_prompt: "...", doom_loop_threshold: 5)
+```
+
+| | |
+|---|---|
+| Default threshold | `RobotLab::DoomLoopDetector::DEFAULT_THRESHOLD` (3) |
+| Set via | `doom_loop_threshold:` constructor kwarg or `RunConfig#doom_loop_threshold` |
+
+When a consecutive or cyclic repetition of the same tool name exceeds the
+threshold, the detector does **not** raise. It appends a self-correction warning
+to that tool's result so the model can change strategy: a `String` result gets
+`"\n\n⚠️ <warning>"` appended, and a `Hash` result gains a `:_doom_loop_warning`
+key. The detector then resets.
+
 ## Learning Accumulation
 
-`robot.learn(text)` records a cross-run observation. On each subsequent `run()`, active learnings are automatically prepended to the user message as a `LEARNINGS FROM PREVIOUS RUNS:` block.
+`robot.learn(text)` records a cross-run observation. On each subsequent `run()`,
+**all** accumulated learnings are prepended to the user message as a
+`LEARNINGS FROM PREVIOUS RUNS:` block. There is no active/inactive distinction —
+every entry in `robot.learnings` is injected.
 
 ### learn
 
@@ -1097,7 +1577,17 @@ Add a learning to the robot's accumulated observations. Learnings are automatica
 - If the new text is a substring of an existing learning, it is dropped (the existing broader learning already covers it).
 - If an existing learning is a substring of the new text, the narrower one is replaced.
 
-Learnings are persisted to `memory[:learnings]` and survive a robot rebuild when the same `Memory` object is reused.
+Learnings are written to the robot's own memory under `memory[:learnings]`.
+
+!!! note "Learnings do not survive process restart on their own"
+    `initialize_memory` always constructs a fresh `Memory.new`, and there is no
+    `memory:` constructor keyword, so a newly built robot starts with an empty
+    `:learnings` key. `learn` reads back whatever is already in `memory[:learnings]`
+    at construction, which means persistence requires an external store — for
+    example the `robot_lab-durable` extension — to repopulate it.
+
+`learn` runs inside the `:learn` hook family (`before_learn` / `around_learn` /
+`after_learn`, plus `on_learn`), so a hook handler can observe or veto the write.
 
 **Parameters:**