robot_lab 0.2.1 → 0.2.7

data/docs/architecture/core-concepts.md

@@ -25,11 +25,17 @@ robot = RobotLab.build(
     say so honestly.
   PROMPT
   local_tools: [OrderLookup, RefundProcessor],  # RubyLLM::Tool subclasses
-  mcp: :inherit,                                 # Use network's MCP servers
+  mcp: :inherit,                                 # Use the network's MCP servers
   temperature: 0.7                               # Inference parameter
 )
 ```
 
+The build-time `mcp: :inherit` above assumes this robot will be added to a
+network whose `config:` supplies an `mcp:` list. The parent is resolved on every
+run, so `:inherit` picks up whatever the enclosing network provides. For a robot
+that will run **standalone**, `:inherit` resolves against the global default
+`:none` and yields nothing — give it an explicit array instead.
+
 Or with a template:
 
 ```ruby
@@ -83,24 +89,32 @@ result = robot.run("What is the weather in Berlin?")
 puts result.last_text_content
 ```
 
-With runtime overrides:
+`run` defaults to `mcp: :none, tools: :none`. Those defaults are *explicit* "send nothing this turn" values, not "unset" — so a plain `run` connects no MCP servers and sends the LLM zero tools even when `local_tools:`/`mcp:` were supplied at build time. Opt in per run:
+
+```ruby
+robot.run("...", tools: :inherit)                 # send the attached local tools
+robot.run("...", mcp: :inherit, tools: :inherit)  # connect MCP servers and send their tools
+```
+
+With other runtime overrides:
 
 ```ruby
 result = robot.run("Analyze this",
   memory: { data: report },
-  mcp: :none,
-  tools: :none
+  tools: :inherit
 )
 ```
 
-With streaming:
+With streaming — the block receives a `RubyLLM::Chunk`, whose text is in `content`:
 
 ```ruby
-robot.run("Tell me a story") do |event|
-  print event.text if event.respond_to?(:text)
+robot.run("Tell me a story") do |chunk|
+  print chunk.content
 end
 ```
 
+An `on_content:` callback (constructor kwarg or `RunConfig` field) fires on every run. When both an `on_content` callback and a block are supplied, both fire, stored callback first.
+
 ## Tool
 
 Tools give robots the ability to interact with external systems. There are two patterns for defining tools.
@@ -208,7 +222,7 @@ end
 
 | Key | Type | Description |
 |-----|------|-------------|
-| `:data` | `Hash` | Runtime data (accessible via `memory.data.key_name`) |
+| `:data` | `StateProxy` | Runtime data (hash-style `memory.data[:key]` and method-style `memory.data.key_name`) |
 | `:results` | `Array` | Accumulated robot results |
 | `:messages` | `Array` | Conversation history |
 | `:session_id` | `String` | Session identifier |
@@ -227,7 +241,7 @@ memory.get(:sentiment)  # => { score: 0.8 } or nil
 
 # Blocking read (waits until value exists)
 memory.get(:sentiment, wait: true)    # Blocks indefinitely
-memory.get(:sentiment, wait: 30)      # Blocks up to 30 seconds
+memory.get(:sentiment, wait: 30)      # Blocks up to 30s, then raises RobotLab::AwaitTimeout
 
 # Subscribe to changes
 memory.subscribe(:sentiment) do |change|
@@ -296,13 +310,21 @@ The output from a robot execution:
 result = robot.run("Hello!")
 
 result.robot_name       # => "support_agent"
-result.output           # => [TextMessage, ...]
-result.tool_calls       # => [ToolResultMessage, ...]
-result.stop_reason      # => "stop"
+result.output           # => [TextMessage] built from the final response text
+result.tool_calls       # => [] — see note below
+result.stop_reason      # => nil — always (see below)
 result.created_at       # => Time
 result.id               # => UUID string
+result.input_tokens     # => Integer
+result.output_tokens    # => Integer
+result.duration         # => Float, nil (set by Robot#call during pipeline execution)
+result.checksum         # => "sha256-hex"
 ```
 
+`stop_reason` is always `nil` on a `Robot#run` result — `build_result` only copies it when the response responds to `stop_reason`, and `RubyLLM::Message` does not. The table above describes `Message::VALID_STOP_REASONS`, which applies to message objects you construct yourself, not to `RobotResult`. As a consequence `result.stopped?` reduces to `!result.has_tool_calls?`.
+
+`output` is always a single `TextMessage` synthesized from the final response text — it is not a transcript of the turn. `tool_calls` is read off that final assistant message, which no longer carries tool calls once RubyLLM's tool loop has finished, so in practice it is empty; use the `on_tool_call`/`on_tool_result` callbacks or the tool hooks to observe tool usage.
+
 ### Accessing Response Content
 
 ```ruby
@@ -323,21 +345,44 @@ result.to_json    # => JSON string
 
 ## Configuration
 
-RobotLab uses `MywayConfig` for configuration. There is no `RobotLab.configure` block. Configuration is loaded from:
+Global configuration uses `MywayConfig`. Sources are layered lowest to highest:
 
 1. Bundled defaults (`lib/robot_lab/config/defaults.yml`)
-2. Environment-specific overrides
-3. XDG config files (`~/.config/robot_lab/config.yml`)
-4. Project config (`./config/robot_lab.yml`)
-5. Environment variables (`ROBOT_LAB_*` prefix)
+2. Environment-specific overrides (development / test / production)
+3. XDG config file (`~/.config/robot_lab/robot_lab.yml` — note the filename repeats the app name; `config.yml` is never read, and this loader does **not** run ERB)
+4. Project config (`./config/robot_lab.yml` — ERB is evaluated here)
+5. Environment variables (`ROBOT_LAB_*` prefix, double underscore for nesting)
+6. Constructor params
+
+The two file layers treat top-level wrappers differently:
+
+- **XDG file** (`~/.config/robot_lab/robot_lab.yml`) — a section named for the current environment **is** honoured. The loader checks `parsed.key?(env)` first (env comes from `Anyway::Settings.current_environment`, then `RAILS_ENV`, then `RACK_ENV`, defaulting to `"development"`) and falls back to the root when no such key exists. So `development:` works, a flat file works, and `production:` is simply skipped while you are in development. Only a `defaults:` wrapper is meaningless — it is not an environment name, so the whole hash is read as flat config and `defaults` is an unknown key.
+- **Project file** (`./config/robot_lab.yml`) — outside Rails this must be flat; every wrapper, `defaults:` and environment names alike, is ignored. Inside Rails, `anyway_config` sets `current_environment` to `Rails.env`, which makes this file environmental: a flat project file is then ignored and keys must be nested under `development:` / `test:` / `production:`.
 
-Access via `RobotLab.config`:
+Read via `RobotLab.config`, or set values with the `RobotLab.configure` block, which yields the same `Config` object:
 
 ```ruby
 RobotLab.config.ruby_llm.model            # => "claude-sonnet-4"
 RobotLab.config.ruby_llm.request_timeout  # => 120
+
+RobotLab.configure do |c|
+  c.logger = Logger.new($stdout)
+end
 ```
 
+### RunConfig
+
+Global `Config` is distinct from `RunConfig`, the per-run settings object that flows `RobotLab.config → Network → Task → Robot → template front matter → constructor kwargs`. Its fields are:
+
+- **LLM**: `model`, `temperature`, `top_p`, `top_k`, `max_tokens`, `presence_penalty`, `frequency_penalty`, `stop`
+- **Capabilities** (`TOOL_FIELDS`): `mcp`, `tools`
+- **Callbacks**: `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`
+
+`TOOL_FIELDS` is exactly `[:mcp, :tools]` — those are the two a network propagates. `max_tools` is an infrastructure field, so it is *not* inherited that way.
+
+Per robot, template front matter is the **base**, a `config:` RunConfig merges over it, and constructor kwargs always win. A network-level `config:` propagates only `mcp` and `tools` down to member robots (and only when a robot opts in with `:inherit`); LLM fields and callbacks are never inherited from a network. `max_concurrent_robots` is the one field the network itself consumes.
+
 ## Configuration Hierarchy
 
 Tools and MCP servers use a cascading configuration system:
@@ -348,29 +393,32 @@ RobotLab.config (global)
 +-- mcp: [server1, server2]
 +-- tools: [tool1, tool2]
 |
-+-- Network
++-- Network config: (RunConfig)
 |     |
 |     +-- mcp: :inherit | :none | [servers]
 |     +-- tools: :inherit | :none | [tools]
 |     |
-|     +-- Task (per-step config)
-|     |     +-- context: { department: "billing" }
-|     |     +-- mcp: :none | :inherit | [servers]
-|     |     +-- tools: :none | :inherit | [tools]
-|     |
 |     +-- Robot (build-time config)
 |           |
 |           +-- mcp: :inherit | :none | [servers]
 |           +-- tools: :inherit | :none | [tools]
 |           |
-|           +-- run() call (runtime config)
-|                 +-- mcp: :none | [servers]
-|                 +-- tools: :none | [tools]
+|           +-- Task (per-task) / run() call -- the RUNTIME level
+|                 +-- mcp: :none (default) | :inherit | [servers]
+|                 +-- tools: :none (default) | :inherit | [tools]
 ```
 
-Resolution order: **runtime > robot build-time > task > network > global config**.
+Resolution order: **task/runtime > robot build-time > network > global config**.
+
+A `Task`'s `mcp:`/`tools:` are not a separate tier between network and robot. The task injects them into `run_params`, and `Robot#call` pulls them out and passes them to `run` — so they arrive as the *runtime* value and are resolved against the robot's build-time value.
 
-The `:inherit` value pulls from the parent level. `:none` explicitly disables.
+The `:inherit` value pulls from the parent level. `:none` explicitly disables. An explicit array is a **filter over the already-attached tools**, not a local-vs-MCP switch.
+
+Three consequences worth internalizing:
+
+- `run()` defaults both to `:none`, so the runtime level is a deliberate "send nothing this turn" unless you override it. Pass `tools: :inherit` (and `mcp: :inherit`) to use what the robot was built with.
+- Build-time `:inherit` depends on there being a parent to inherit from. The parent is recomputed on every run (`network_config&.tools || network_parent_config(network)&.tools || RobotLab.config.tools`), so inside a network whose `config:` sets `tools:`/`mcp:` it is exactly the right way to opt in. For a robot that runs **standalone** the parent is the global `:none`, so build-time `:inherit` matches nothing — leave `tools:` unset there and opt in at run time.
+- An explicit array is compared with `tool.name.to_s`, and `Class#name` differs from `RubyLLM::Tool#name`. A tool attached as a class matches `[RefundTool]` (`"RefundTool"`); the same tool attached as an instance matches `%w[refund]`. Both forms work — but the array must be written in the same form the tool was attached in, or it filters everything out. Note that the **build-time** `tools:` kwarg is validated (`validate_tools_filter!`) and accepts only Strings/Symbols; the class form is available only at the task/runtime level, which is not validated. See [Network Orchestration](network-orchestration.md#task-configuration).
 
 ## Message Bus
 
@@ -378,7 +426,7 @@ The **Message Bus** provides bidirectional, cyclic communication between robots,
 
 ### How It Works
 
-Robots connect to a shared `TypedBus::MessageBus` via the `bus:` parameter. Each robot gets a typed channel (accepting only `RobotMessage` objects) named after its `name`. Messages are delivered asynchronously via the `async` gem's fiber scheduler.
+Robots connect to a shared `TypedBus::MessageBus` via the `bus:` parameter. Each robot gets a typed channel (accepting only `RobotMessage` objects) named after its `name`. Delivery is routed through a shared `BusPoller`, which runs the handler **in the caller's execution context** (Async fiber or OS thread) rather than on a background thread of its own. A mutex serializes deliveries per robot: if a robot is already processing a message, later ones are queued and drained after the current one returns.
 
 ```ruby
 bus = TypedBus::MessageBus.new
@@ -415,6 +463,16 @@ end
 
 Block arity controls delivery handling: 1 argument auto-acks; 2 arguments give manual control over `delivery.ack!`/`delivery.nack!`.
 
+`send_message`/`send_reply` synchronize the per-robot message counter and outbox with an internal mutex, so concurrent sends from multiple threads and reply correlation can't clobber each other — the bus is safe to send on from more than one thread at a time. (There is no poller thread doing the correlating: as described above, `BusPoller#enqueue` processes deliveries inline in the caller's context.)
+
+For the common case of a robot that should simply answer whatever tasks arrive on the bus, `respond_to_tasks`/`serve` do the `on_message` wiring above in one call:
+
+```ruby
+bob.serve  # equivalent to the on_message block above, running bob.run and replying automatically
+```
+
+`respond_to_tasks` takes a block instead when the reply needs post-processing, and both ignore inbound messages that are themselves replies, so two robots calling `serve` on each other don't loop. See [Auto-Responding to Bus Tasks](../guides/building-robots.md#auto-responding-to-bus-tasks).
+
 ### Dynamic Spawning
 
 Robots can create new robots at runtime using `spawn`. The bus is created lazily — no upfront wiring required:
@@ -430,6 +488,8 @@ answer = helper.run("What is 2+2?").last_text_content
 helper.send_message(to: :dispatcher, content: answer)
 ```
 
+The spawned robot inherits its parent's `model`/`provider`, so a dispatcher running on a local provider (e.g. Ollama) spawns specialists targeting that same model instead of falling back to the global default (which would fail without cloud credentials). Explicit `model:`/`provider:` passed to `spawn` still override.
+
 Robots can also join a bus after creation using `with_bus`:
 
 ```ruby
@@ -480,6 +540,34 @@ Networks provide:
 - **Per-task configuration** via the `Task` wrapper
 - **Broadcast messaging** for network-wide announcements
 
+Robots can be added to a network without a pipeline task via `add_robot`, and removed again with `remove_robot(name)` (returns the removed robot, or `nil` if absent). `remove_robot` only drops the robot from the crew — it doesn't rewrite the pipeline, so avoid removing a robot that's still referenced by a task's `depends_on`.
+
+## Runnable Protocol
+
+`RobotLab::Runnable` is a shared interface implemented by both `Robot` and `Network`, so callers can treat either uniformly instead of branching on `is_a?(RobotLab::Network)`:
+
+```ruby
+def summarize(runnable)
+  runnable.crew.each { |r| puts r.name }
+  puts "chief: #{runnable.chief.name}"
+  puts runnable.network? ? "network of #{runnable.robot_count}" : "single robot"
+end
+
+summarize(robot)    # crew: [robot], chief: robot, "single robot"
+summarize(network)  # crew: network.robots.values, chief: crew.first, "network of N"
+```
+
+| Method | Robot | Network |
+|--------|-------|---------|
+| `crew` | `[self]` | `robots.values` (pipeline order) |
+| `chief` | `self` | `crew.first` |
+| `robot_count` | `1` | `crew.size` |
+| `network?` | `false` | `true` |
+| `single?` | `true` | `false` |
+| `run(message = nil, **opts)` | accepts a positional message (already did) | now also accepts a positional message, folded into `message:` — the keyword form still works |
+
+`crew` is the only method implementers must define themselves; `chief`, `robot_count`, and `single?` all derive from it, and `network?` defaults to `false` unless overridden (as `Network` does).
+
 ## Next Steps
 
 - [Robot Execution](robot-execution.md) - Detailed execution flow

data/docs/architecture/index.md

@@ -44,24 +44,31 @@ graph TB
     subgraph "RobotLab Core"
         B[Network]
         C[Task]
-        D[Robot < RubyLLM::Agent]
+        D[Robot &lt; RubyLLM::Agent]
         E[Memory]
         F[RobotResult]
     end
 
     subgraph "Configuration"
-        G[Config < MywayConfig::Base]
+        G[Config &lt; MywayConfig::Base]
+        R[RunConfig]
+    end
+
+    subgraph "Cross-Cutting"
+        HK[Hooks<br/>HookRegistry x3]
     end
 
     subgraph "Integration Layer"
         H[MCP Client]
-        I[Tools < RubyLLM::Tool]
+        I[Tools &lt; RubyLLM::Tool]
         J[Templates / prompt_manager]
+        SK[AgentSkills + Sandbox]
     end
 
     subgraph "Execution Layer"
         K[SimpleFlow::Pipeline]
         L[RubyLLM Chat]
+        TB[TypedBus + BusPoller]
     end
 
     subgraph "Provider Layer"
@@ -77,20 +84,74 @@ graph TB
     C --> D
     B --> K
     B --> E
+    B --> TB
     D --> E
     D --> L
+    D --> TB
     D --> H
     D --> I
     D --> J
+    D --> SK
     D --> F
+    SK --> I
+    G --> R
+    R --> B
+    R --> C
+    R --> D
     G --> D
     G --> L
+    HK -.wraps.-> B
+    HK -.wraps.-> C
+    HK -.wraps.-> D
+    HK -.wraps.-> I
     L --> M
     L --> N
     L --> O
     H --> P
 ```
 
+The dotted `wraps` edges are the hook system: `Hooks.run` brackets every network
+run, task, robot run, LLM generation, tool call, compaction, and `learn` call. It
+is the framework's extension seam — the extension gems (`robot_lab-audit`,
+`robot_lab-durable`, …) attach here rather than subclassing core objects. See the
+[Hooks API](../api/hooks.md).
+
+### Robot subsystems
+
+A `Robot` composes several small collaborators, each documented on the
+[Support](../api/support.md) and [Skills](../api/skills.md) API pages:
+
+```mermaid
+graph LR
+    D[Robot]
+
+    D --> BM[BusMessaging<br/>RobotMessage envelopes]
+    BM --> BP[BusPoller<br/>per-robot serialization]
+    D --> BD[Budget::Ledger<br/>token_budget / cost_budget]
+    D --> DL[DoomLoopDetector<br/>always installed per run]
+    D --> HC[HistoryCompressor<br/>compress_history / auto_compact]
+    D --> DF[DelegationFuture<br/>delegate async: true]
+    D --> HS[HistorySearch<br/>search_history]
+    D --> ASM[AgentSkillMatching<br/>prepended around run]
+
+    ASM --> AS[AgentSkill<br/>SKILL.md bundle]
+    AS --> CAT[AgentSkillCatalog]
+    AS --> CAP[Capabilities]
+    AS --> ST[ScriptTool]
+    CAP --> SB[Sandbox<br/>Seatbelt or Null]
+    ST --> SB
+
+    HC --> TA[TextAnalysis<br/>TF / TF-IDF]
+    HS --> TA
+    CV[Convergence] --> TA
+    SD[MCP::ServerDiscovery] --> TA
+```
+
+`TextAnalysis` is the shared floor under every similarity feature — history
+compression, history search, convergence detection, and MCP server discovery all
+route through it, which is why they share the one optional `classifier`
+dependency.
+
 ## Core Components
 
 | Component | Description | Documentation |
@@ -100,30 +161,44 @@ graph TB
 | **Memory** | Reactive key-value store with pub/sub and blocking reads | [Memory Management](state-management.md) |
 | **Task** | Wraps a robot for pipeline execution with per-task config | [Network Orchestration](network-orchestration.md) |
 | **RobotResult** | Captures LLM output, tool calls, and metadata from a run | [Message Flow](message-flow.md) |
-| **Config** | MywayConfig-based configuration with env var and file support | [Configuration](#configuration) |
+| **RunConfig** | Per-run settings object (LLM fields, `mcp`/`tools`, callbacks, infrastructure) that cascades global → network → task → robot | [Core Concepts](core-concepts.md) |
+| **Config** | MywayConfig-based global configuration with env var and file support | [Configuration](#configuration) |
+| **Hook** | Handler base class for the seven hook families — the framework's extension seam | [Hooks API](../api/hooks.md) |
+| **AgentSkill** | A `SKILL.md` bundle whose instructions and `scripts/` become prompt text and tools | [Skills API](../api/skills.md) |
+| **Sandbox** | Opt-in OS-level confinement (macOS Seatbelt) for skill scripts, derived from `Capabilities` | [Skills API](../api/skills.md) |
+| **RobotMessage** | Immutable envelope for TypedBus inter-robot messaging, serialized per robot by `BusPoller` | [Support API](../api/support.md) |
+| **Budget::Ledger** | Thread-safe reserve/reconcile ledger behind `token_budget` / `cost_budget` | [Support API](../api/support.md) |
 
 ## Configuration
 
-RobotLab uses MywayConfig (`Config < MywayConfig::Base`) instead of a `configure` block. Configuration is loaded from multiple sources in priority order:
+Global configuration is a MywayConfig subclass (`Config < MywayConfig::Base`). It is loaded from multiple sources in priority order:
 
 1. **Bundled defaults** (`lib/robot_lab/config/defaults.yml`)
-2. **Environment overrides** (development, test, production sections)
-3. **XDG user config** (`~/.config/robot_lab/config.yml`)
-4. **Project config** (`./config/robot_lab.yml`)
+2. **Environment overrides** (development, test, production)
+3. **XDG user config** (`~/.config/robot_lab/robot_lab.yml` — the filename repeats the app name; `config.yml` is never read)
+4. **Project config** (`./config/robot_lab.yml` — the only file with an ERB pass)
 5. **Environment variables** (`ROBOT_LAB_*` prefix, double underscore for nesting)
+6. **Constructor params**
+
+Top-level wrappers behave differently per file. In the **XDG user config**, a section named for the current environment is honoured — the loader looks for `parsed.key?(env)` (`Anyway::Settings.current_environment`, else `RAILS_ENV`, else `RACK_ENV`, else `"development"`) and falls back to the root when absent — so both `development:` and a flat file work there. A `defaults:` wrapper is not an environment name, so it is ignored. The **project config** must be flat outside Rails (all wrappers ignored); under Rails, `anyway_config` sets `current_environment` to `Rails.env` and the project file becomes environmental, so a flat file is ignored and keys must sit under `development:` / `test:` / `production:`. See [Core Concepts](core-concepts.md#configuration) for details.
 
 ```ruby
 # Access configuration
 RobotLab.config.ruby_llm.model            #=> "claude-sonnet-4"
 RobotLab.config.ruby_llm.request_timeout  #=> 120
+
+# Block form (yields the same Config object)
+RobotLab.configure do |c|
+  c.logger = Logger.new($stdout)
+end
 ```
 
 ## Data Flow
 
 1. **Input**: User calls `robot.run("message")` or `network.run(message: "...")`
 2. **Memory**: Robot resolves active memory (standalone or network-shared)
-3. **MCP**: Robot resolves and initializes MCP clients from hierarchical config
-4. **Tools**: Robot resolves and filters tools from hierarchical config
+3. **MCP**: Robot resolves MCP servers from hierarchical config and connects clients. `run` defaults to `mcp: :none`, so a plain `run` connects nothing
+4. **Tools**: Robot resolves and filters tools from hierarchical config. `run` defaults to `tools: :none`, so a plain `run` sends the LLM zero tools; pass `tools: :inherit` to send the robot's attached tools
 5. **Execution**: Robot delegates to `Agent#ask` which calls `@chat.ask` on RubyLLM
 6. **Tool Loop**: LLM may invoke tools; RubyLLM handles the tool call/result loop
 7. **Result**: Robot builds and returns a `RobotResult`
@@ -161,7 +236,7 @@ robot = RobotLab.build(name: "bot")
 
 ### Hierarchical Configuration
 
-Tools and MCP servers use hierarchical resolution: `runtime > robot build > network > global config`. Values can be `:none`, `:inherit`, or explicit arrays.
+Tools and MCP servers use hierarchical resolution: `run()/task > robot build-time > network > global config`. Values can be `:none`, `:inherit`, or an explicit array (which filters the already-attached tools by name — entries must match how the tool was attached, class or instance). `run()` defaults both to `:none`, so the runtime level is an explicit "send nothing" unless you override it.
 
 ### SimpleFlow Pipeline
 

data/docs/architecture/message-flow.md

@@ -4,7 +4,7 @@ This page explains how messages move through RobotLab, from user input to LLM re
 
 ## Message Types
 
-RobotLab uses four primary message types:
+`RobotLab::Message` is the abstract base for three conversation message classes. `ToolMessage` is a plain value object that they reference, and two further message classes — `UserMessage` and `RobotMessage` — live outside the hierarchy entirely:
 
 ```mermaid
 classDiagram
@@ -12,22 +12,30 @@ classDiagram
         <<abstract>>
         +type: String
         +role: String
-        +content: String
+        +content
         +stop_reason: String
-    }
-
-    class TextMessage {
         +text?() bool
+        +tool_call?() bool
+        +tool_result?() bool
+        +system?() bool
         +user?() bool
         +assistant?() bool
-        +system?() bool
+        +stopped?() bool
+        +tool_stop?() bool
+        +to_h() Hash
+    }
+
+    class TextMessage {
+        +content: String
     }
 
     class ToolMessage {
+        <<PORO>>
         +id: String
         +name: String
         +input: Hash
-        +tool_call?() bool
+        +to_h() Hash
+        +to_json() String
     }
 
     class ToolCallMessage {
@@ -37,7 +45,10 @@ classDiagram
     class ToolResultMessage {
         +tool: ToolMessage
         +content: Hash
-        +tool_result?() bool
+        +success?() bool
+        +error?() bool
+        +data()
+        +error()
     }
 
     Message <|-- TextMessage
@@ -47,6 +58,15 @@ classDiagram
     ToolMessage -- ToolResultMessage
 ```
 
+`ToolMessage` does **not** inherit from `Message` — its superclass is `Object`. It has no `type`, `role`, or predicate methods; only `id`, `name`, `input`, `to_h`, and `to_json`. The `tool_call?` predicate lives on `Message`, so it answers for `ToolCallMessage`, not for `ToolMessage`.
+
+The two classes outside the hierarchy:
+
+| Class | Role |
+|-------|------|
+| `UserMessage` | Envelope for user input carrying `session_id`, an extra `system_prompt`, `metadata`, `id`, `created_at`. `UserMessage.from` normalizes a String/Hash/TextMessage; `#to_message` converts to a `TextMessage` |
+| `RobotMessage` | Immutable `Data.define(:id, :from, :content, :in_reply_to)` envelope for robot-to-robot traffic on the message bus, with `#key` (`"from:id"`) and `#reply?` |
+
 ### TextMessage
 
 Regular text content from users or assistants:
@@ -66,16 +86,20 @@ TextMessage.new(
 
 ### ToolMessage
 
-Represents a tool invocation with its parameters:
+A standalone value object (not a `Message`) representing a tool invocation and its parameters:
 
 ```ruby
-ToolMessage.new(
+tool = ToolMessage.new(
   id: "tool_123",
   name: "get_weather",
   input: { location: "Paris" }
 )
+
+tool.to_h  #=> { type: "tool", id: "tool_123", name: "get_weather", input: { location: "Paris" } }
 ```
 
+Note that the `type: "tool"` key appears only in `to_h`; there is no `type` reader and no predicate methods.
+
 ### ToolCallMessage
 
 LLM's request to execute one or more tools:
@@ -83,14 +107,17 @@ LLM's request to execute one or more tools:
 ```ruby
 ToolCallMessage.new(
   role: "assistant",
-  content: nil,
-  stop_reason: "tool",
   tools: [
     ToolMessage.new(id: "call_1", name: "get_weather", input: { location: "Paris" })
-  ]
+  ],
+  stop_reason: "tool"
 )
 ```
 
+The signature is `initialize(role:, tools:, stop_reason: nil)` — `role` and
+`tools` are required and there is **no** `content:` keyword. Passing one raises
+`ArgumentError`.
+
 ### ToolResultMessage
 
 Result from tool execution:
@@ -126,8 +153,8 @@ sequenceDiagram
     Robot->>Robot: ensure_mcp_clients
 
     Robot->>Tools: resolve_tools_hierarchy
-    Tools-->>Robot: filtered tools
-    Robot->>Chat: @chat.with_tools(...)
+    Tools-->>Robot: filtered + capped tools
+    Robot->>Chat: @chat.with_tools(*filtered, replace: true)
 
     Robot->>Agent: ask("message")
     Agent->>Chat: @chat.ask("message")
@@ -161,13 +188,13 @@ sequenceDiagram
 
 4. **Set Current Writer**: Sets `memory.current_writer = robot.name` so subscription callbacks know which robot wrote a value.
 
-5. **Resolve MCP Hierarchy**: Resolves MCP server configuration through the hierarchy: `runtime > robot build > network > global config`.
+5. **Resolve MCP Hierarchy**: Resolves MCP server configuration through the hierarchy: `runtime (run/task) > robot build-time > network > global config`. `run` defaults `mcp:` to `:none`, so nothing is connected unless you pass `mcp: :inherit` or an explicit list.
 
-6. **Ensure MCP Clients**: Initializes or updates MCP client connections. Discovers tools from connected MCP servers.
+6. **Ensure MCP Clients**: Initializes or updates MCP client connections and discovers tools from them. Connection failures are logged and recorded in `failed_mcp_server_names`, never raised.
 
-7. **Resolve Tools Hierarchy**: Resolves which tools are available through the same hierarchy.
+7. **Resolve Tools Hierarchy**: Resolves which tools are available through the same hierarchy. `run` defaults `tools:` to `:none`, which means "send zero tools this turn" — pass `tools: :inherit` to send the robot's attached tools.
 
-8. **Filter Tools**: Applies the resolved tool list to `@chat.with_tools(...)`.
+8. **Filter Tools**: Filters by the resolved allowlist, clamps to `max_tools` (128 by default), and applies the set with `@chat.with_tools(*filtered, replace: true)` so the persistent chat holds exactly this turn's tools.
 
 9. **Agent#ask**: Delegates to the parent class `RubyLLM::Agent#ask`, which calls `@chat.ask(message)`.
 
@@ -212,11 +239,11 @@ sequenceDiagram
 
 ### Key Points
 
-- **Network creates initial result**: `SimpleFlow::Result.new(run_context, context: { run_params: run_context })`
-- **Task wraps robot**: Each `Task` deep-merges its own context with the run params before delegating to the robot
-- **Robot extracts context**: `extract_run_context(result)` pulls the message, MCP, tools, and memory from the SimpleFlow result
+- **Network creates initial result**: `SimpleFlow::Result.new(run_context, context: { run_params: run_context })`, after injecting `network_memory`, `network`, and (when non-empty) `network_config` into the run context, all wrapped in the `:network_run` hook
+- **Task wraps robot**: Each `Task` runs the `:task` hook and deep-merges its own context, `mcp`, `tools`, `memory`, and `config` into the run params before delegating to the robot
+- **Robot extracts context**: `extract_run_context(result)` pulls the message, MCP, tools, memory, network, and task out of the SimpleFlow result and passes them to `run` as keyword arguments
 - **Shared memory**: All robots use `network.memory` during network execution
-- **Result accumulation**: Each task stores its `RobotResult` in `result.context[:task_name]`
+- **Result accumulation**: Each robot stores its `RobotResult` in `result.context[:robot_name]` — the key comes from `@name.to_sym` in `Robot#call`, so it is the **robot's** name, not the task name. They match only when the two are spelled the same way
 
 ## RobotResult
 
@@ -226,16 +253,24 @@ The return value of `robot.run("message")`:
 result = robot.run("What is Ruby?")
 
 result.last_text_content  #=> "Ruby is a dynamic programming language..."
+result.reply              #=> alias for last_text_content
 result.has_tool_calls?    #=> false
 result.robot_name         #=> "assistant"
 result.output             #=> [TextMessage(role: "assistant", content: "...")]
 result.tool_calls         #=> []
-result.stop_reason        #=> "stop"
+result.stop_reason        #=> nil (always — see below)
 result.created_at         #=> Time
 result.id                 #=> "uuid"
 result.checksum           #=> "sha256-hex"
+result.input_tokens       #=> 42
+result.output_tokens      #=> 128
+result.duration           #=> Float, nil
 ```
 
+`stop_reason` is always `nil` on a `Robot#run` result: `build_result` reads it as `response.respond_to?(:stop_reason) ? response.stop_reason : nil`, and `RubyLLM::Message` does not define the method. It is consequently dropped from `export`, and `result.stopped?` reduces to `!result.has_tool_calls?`.
+
+`output` always holds exactly one synthesized `TextMessage` built from the final response text — it is not a transcript of the turn, and it never contains `ToolCallMessage` or `ToolResultMessage` entries. `tool_calls` is read off the final assistant message, which carries no tool calls once RubyLLM's tool loop has finished, so it is effectively always empty. To observe tool activity, use the `on_tool_call` / `on_tool_result` callbacks or the tool hooks.
+
 ### Result Serialization
 
 ```ruby
@@ -254,7 +289,7 @@ result = RobotResult.from_hash(hash)
 
 ## Message Predicates
 
-Check message types:
+These are defined on `Message`, so every `TextMessage`, `ToolCallMessage`, and `ToolResultMessage` responds to all of them. `ToolMessage` responds to none of them:
 
 ```ruby
 message.text?         # Is it a TextMessage?
@@ -269,6 +304,8 @@ message.stopped?      # Is stop_reason "stop"?
 message.tool_stop?    # Is stop_reason "tool"?
 ```
 
+Valid values are constrained at construction: `type` must be one of `text`, `tool_call`, `tool_result`; `role` one of `system`, `user`, `assistant`, `tool_result`; `stop_reason` one of `tool`, `stop`. Anything else raises `ArgumentError`.
+
 ## Creating Messages
 
 ### From Strings
@@ -317,11 +354,11 @@ robot = RobotLab.build(
 
 The template resolution process:
 1. `PM.parse(:helper)` loads the template file from the configured prompts directory
-2. YAML front matter is extracted and applied to the chat (model, temperature, etc.)
-3. The template body is rendered with the provided context
-4. The rendered text is set as system instructions via `@chat.with_instructions(rendered)`
+2. Non-LLM front matter (`robot_name`, `description`, `tools`, `mcp`, `skills`) is applied to the robot, filling in only what the constructor did not provide
+3. The LLM front-matter keys become a `RunConfig` that the robot's own `@config` merges over — front matter is the base, constructor kwargs win — and `apply_to` dispatches `chat.with_<field>` for each field the chat supports. In practice only `model` and `temperature` reach the chat this way; `top_p`, `top_k`, `max_tokens`, `presence_penalty`, `frequency_penalty`, and `stop` are parsed and silently dropped because `RubyLLM::Chat` defines no `with_` method for them. Set those via constructor kwargs instead
+4. The template body is rendered with ERB (`<%= var %>`; `{{ var }}` is not interpolated) and set as system instructions via `@chat.with_instructions(rendered)`
 
-If both `template:` and `system_prompt:` are provided, the template is applied first, then the system prompt is appended via a second `@chat.with_instructions` call.
+If both `template:` and `system_prompt:` are provided, the system prompt is appended to the rendered template, producing one combined system message — and it is re-appended on every template re-render, so supplying run-time context never silently drops it.
 
 ## Next Steps