robot_lab 0.1.0 → 0.2.6

data/docs/api/core/network.md

@@ -56,6 +56,9 @@ result = network.run(
   **context
 )
 # => SimpleFlow::Result
+
+# Runnable protocol: a positional message works too, just like Robot#run
+result = network.run("Help me", customer_id: 123)
 ```
 
 Execute the network pipeline.
@@ -64,7 +67,7 @@ Execute the network pipeline.
 
 | Name | Type | Description |
 |------|------|-------------|
-| `message` | `String` | The input message |
+| `message` | `String`, `nil` | The input message — as the `message:` keyword, or positionally (folded into `message:` when given) |
 | `**context` | `Hash` | Additional context passed to all robots |
 
 **Returns:** `SimpleFlow::Result`
@@ -108,6 +111,15 @@ network.add_robot(robot)
 
 Add a robot without creating a pipeline task. Useful for robots referenced by other tasks.
 
+### remove_robot
+
+```ruby
+network.remove_robot("billing")
+# => Robot, or nil if no robot by that name was present
+```
+
+Remove a dynamically-added robot from the crew by name. Complements `add_robot`. Only removes the robot from `@robots` — it does **not** rewrite the pipeline, so don't remove a robot that is a pipeline task (a `depends_on` reference to a removed robot's task name would then fail).
+
 ### robot / []
 
 ```ruby
@@ -294,6 +306,24 @@ elsif result.context[:technical]
 end
 ```
 
+## Runnable Protocol
+
+`Network` includes `RobotLab::Runnable`, the shared interface it has in common with `Robot` — see [Runnable Protocol](../../architecture/network-orchestration.md#runnable-protocol) for the full picture.
+
+| Method | Returns |
+|--------|---------|
+| `crew` | `robots.values` — the constituent robots, as an `Array`, in pipeline order |
+| `chief` | `crew.first` — the lead robot |
+| `robot_count` | `crew.size` |
+| `network?` | `true` |
+| `single?` | `false` |
+
+```ruby
+network.crew.map(&:name)  # => ["classifier", "billing", "technical"]
+network.chief             # => the first robot
+network.network?          # => true
+```
+
 ## See Also
 
 - [Creating Networks Guide](../../guides/creating-networks.md)

data/docs/api/core/robot.md

@@ -35,6 +35,7 @@ Robot.new(
   skills: nil,
   max_tool_rounds: nil,
   token_budget: nil,
+  cost_budget: nil,
   temperature: nil,
   top_p: nil,
   top_k: nil,
@@ -60,7 +61,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) |
+| `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) |
 | `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)) |
@@ -68,7 +69,8 @@ Robot.new(
 | `bus` | `TypedBus::MessageBus`, `nil` | `nil` | Optional message bus for inter-robot communication |
 | `skills` | `Symbol`, `Array<Symbol>`, `nil` | `nil` | Skill templates to prepend (see [Skills](#skills)) |
 | `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 input tokens exceed this limit |
+| `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) |
 | `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 |
@@ -120,6 +122,7 @@ If `name` is omitted, it defaults to `"robot"`.
 | `total_input_tokens` | `Integer` | Cumulative input tokens sent across all `run()` calls |
 | `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)) |
 
 ## Attributes (Read-Write)
 
@@ -149,13 +152,15 @@ Primary execution method. Sends a message to the LLM with memory/MCP/tools resol
 | `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 |
-| `mcp` | `Symbol`, `Array` | `:none` | Runtime MCP override |
-| `tools` | `Symbol`, `Array` | `:none` | Runtime tools override |
+| `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` |
 | `&block` | `Proc` | `nil` | Per-call streaming block, receives each content chunk |
 
 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).
+
 **Returns:** `RobotResult`
 
 **Examples:**
@@ -271,7 +276,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.
+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.
 
 **Parameters:**
 
@@ -337,6 +342,49 @@ robot.on_message do |delivery, message|
 end
 ```
 
+### respond_to_tasks
+
+```ruby
+robot.respond_to_tasks(auto_reply: true) { |message| "the reply content" }
+# => self
+```
+
+Auto-answer inbound (non-reply) bus tasks: run the block to produce a reply, and send it back to the sender. This is the symmetric counterpart to how a `robot_lab-cyborg` Cyborg answers its human — one call makes any bus member a first-class responder without hand-wiring `on_message` yourself.
+
+**Parameters:**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `auto_reply` | `Boolean` | `true` | Send the block's result back to the sender via `send_reply` |
+| `&responder` | `Proc` | **required** | Receives the inbound `message`; return the reply content (`nil` means no reply) |
+
+**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.
+
+```ruby
+bob.respond_to_tasks { |message| "handled: #{message.content}" }
+alice.send_message(to: :bob, content: "ping")
+# bob replies "handled: ping" back to alice automatically
+```
+
+### serve
+
+```ruby
+robot.serve(auto_reply: true)
+# => self
+```
+
+The common case of `respond_to_tasks`: run every inbound task through this robot's own `#run` and reply with the result — the one-call way to make a Robot cooperate on the bus the way a Cyborg already does out of the box.
+
+```ruby
+bob.serve
+alice.send_message(to: :bob, content: "Tell me a joke.")
+# bob runs "Tell me a joke." through its LLM and replies with the result
+```
+
+Equivalent to `respond_to_tasks(auto_reply: auto_reply) { |message| run(message.content).reply }` (with Hash-content messages flattened to `"key: value"` lines first).
+
 ### spawn
 
 ```ruby
@@ -349,6 +397,8 @@ child = robot.spawn(
 
 Create a new robot on the same message bus. If the parent has no bus, one is created automatically and the parent is connected to it.
 
+The spawned robot inherits its parent's `model` and `provider` (via `robot.model`/`robot.provider`) so a specialist runs on the same LLM as the robot that spawned it — a robot running on a local Ollama model, for instance, spawns specialists that also target that model rather than falling back to `RobotLab.config.ruby_llm.model` (the global default, typically a cloud model that would fail without credentials). Caller-supplied `model:`/`provider:` in `**options` still override.
+
 **Parameters:**
 
 | Name | Type | Default | Description |
@@ -813,6 +863,10 @@ robot = RobotLab.build(
 result = robot.run("Hello!")
 ```
 
+`provider:` is threaded through on every re-application of the effective `RunConfig` — including when a template's front matter is re-rendered mid-run — so a local-provider robot (Ollama, GPUStack, LM Studio) doesn't fall back to RubyLLM's static model registry lookup on later turns and raise a spurious "model not found" error.
+
+Some local/thinking-mode models (e.g. `qwen3` on Ollama) route all of their output through reasoning content rather than the normal response text. When `response.content` is `nil`, `result.reply` falls back first to `response.thinking.text` (RubyLLM's extended-thinking text), then to the most recent assistant text from later in *the current turn only* — never a stale reply left over from a previous turn.
+
 ### Robot with MCP
 
 ```ruby
@@ -958,6 +1012,26 @@ robot.reset_token_totals
 puts robot.total_input_tokens   # => 0
 ```
 
+### Budgets
+
+`token_budget:` and `cost_budget:` turn the counters above into enforceable ceilings, backed by a thread-safe `RobotLab::Budget::Ledger` (`robot.budget_ledger`, `nil` when neither is configured):
+
+```ruby
+robot = RobotLab.build(
+  name: "capped",
+  system_prompt: "...",
+  token_budget: 10_000,
+  cost_budget: 0.50
+)
+```
+
+Each `run()` reserves the remaining budget for every configured dimension before the LLM call, and reconciles the reservation with actual usage after:
+
+- **`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.
+
 ## Tool Loop Circuit Breaker
 
 Set `max_tool_rounds:` to guard against a robot looping indefinitely through tool calls. After the limit is reached, `RobotLab::ToolLoopError` is raised.
@@ -1084,6 +1158,18 @@ robot.learn("avoid using puts and p in production code")
 # => broader learning replaces narrower; robot.learnings.size == 1
 ```
 
+## Runnable Protocol
+
+`Robot` includes `RobotLab::Runnable`, the shared interface it has in common with `Network` — see [Runnable Protocol](../../architecture/core-concepts.md#runnable-protocol) for the full picture. For a single robot:
+
+| Method | Returns |
+|--------|---------|
+| `crew` | `[self]` — a robot is a crew of one |
+| `chief` | `self` |
+| `robot_count` | `1` |
+| `network?` | `false` |
+| `single?` | `true` |
+
 ## See Also
 
 - [Building Robots Guide](../../guides/building-robots.md) (includes [Composable Skills](../../guides/building-robots.md#composable-skills))

data/docs/api/errors.md

@@ -15,7 +15,8 @@ StandardError
     ├── RobotLab::MCPError
     ├── RobotLab::BusError
     ├── RobotLab::RactorBoundaryError
-    └── RobotLab::ToolError
+    ├── RobotLab::ToolError
+    └── RobotLab::BudgetExceeded
 ```
 
 Additionally, `DelegationFuture` defines its own scoped error:
@@ -118,6 +119,8 @@ rescue RobotLab::MCPError => e
 end
 ```
 
+`MCPError.new(message, retryable: true)` marks a specific instance as safe to retry (see [Retryable Errors](#retryable-errors) below). The connection-lost and timeout errors raised internally by `MCP::ConnectionPoller` are always constructed with `retryable: true`.
+
 ---
 
 ## RobotLab::BusError
@@ -160,6 +163,48 @@ rescue RobotLab::ToolError => e
 end
 ```
 
+Like `MCPError`, `ToolError.new(message, retryable: true)` marks a specific instance as retryable. When a tool raises inside `Tool#call`, RobotLab appends `" (retryable)"` to the formatted error text returned to the LLM whenever `RobotLab::Errors.retryable?(error)` is true, so the model itself can see that another attempt is worth trying.
+
+---
+
+## RobotLab::BudgetExceeded
+
+Raised when a Robot's configured `token_budget` or `cost_budget` is already exhausted **before** an LLM call is attempted (see [Budgets](../guides/observability.md#budgets-token--cost) and `RobotLab::Budget::Ledger`). This is distinct from the pre-existing `InferenceError` "Token budget exceeded" message, which covers a call that *completed* but pushed cumulative usage over budget — `BudgetExceeded` means the call was refused outright, before any tokens were spent.
+
+```ruby
+robot = RobotLab.build(name: "capped", system_prompt: "...", cost_budget: 0.50)
+
+begin
+  robot.run("Do the expensive thing")
+rescue RobotLab::BudgetExceeded => e
+  puts e.message  # "budget exceeded for cost: 0.62 > 0.5"
+end
+```
+
+---
+
+## Retryable Errors
+
+`RobotLab::Errors.retryable?(error)` classifies whether a host (an ActiveJob `retry_on` list, `robot_lab-to`'s takeover loop, a custom retry wrapper) should retry the operation that raised `error`:
+
+| Error | Retryable? |
+|-------|------------|
+| `InferenceError` (and subclasses, except `ToolLoopError`) | Always |
+| `ToolLoopError` | Never — it's a circuit breaker; retrying immediately re-triggers the same loop |
+| `MCPError` / `ToolError` | Only when raised with `retryable: true` at the raise site |
+| Everything else (`ConfigurationError`, `ToolNotFoundError`, `DependencyError`, `RactorBoundaryError`, `BusError`, `BudgetExceeded`, non-RobotLab errors) | Never |
+
+```ruby
+begin
+  robot.run(task)
+rescue RobotLab::Error => e
+  retry if RobotLab::Errors.retryable?(e)
+  raise
+end
+```
+
+`RobotLab::Errors.retryable_classes` returns `[RobotLab::InferenceError]` — an always-retryable allow-list for explicit ActiveJob-style `retry_on` declarations. It excludes `MCPError`/`ToolError` because their retryability is per-raise (via `retryable:`), not per-class.
+
 ---
 
 ## RobotLab::DelegationFuture::DelegationTimeout
@@ -181,5 +226,5 @@ end
 ## Related
 
 - [Building Robots](../guides/building-robots.md) — Tool loop circuit breaker, delegation
-- [Ractor Parallelism](../guides/ractor-parallelism.md) — Ractor boundary and tool errors
+- [Observability & Safety](../guides/observability.md) — circuit breaker and tool loop errors
 - [MCP Integration](../guides/mcp-integration.md) — MCP connection errors

data/docs/api/index.md

@@ -56,6 +56,9 @@ RobotLab.reload_config!      # => reload from all sources
 RobotLab.build(name:, template:, system_prompt:, context:, **options)
 RobotLab.create_network(name:, concurrency:) { ... }
 RobotLab.create_memory(data:, enable_cache:, **options)
+
+# Rendering a template to a String (not a robot) -- see Building Robots guide
+RobotLab.render_template(name, **context)  # => String
 ```
 
 See individual class documentation for detailed method references.

data/docs/architecture/core-concepts.md

@@ -415,6 +415,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 on the poller thread can't clobber each other — the bus is safe to send on from more than one thread at a time.
+
+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 +440,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 +492,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/network-orchestration.md

@@ -19,6 +19,10 @@ network = RobotLab.create_network(name: "customer_service") do
 end
 ```
 
+## Runnable Protocol
+
+`Network` implements `RobotLab::Runnable` — the same interface `Robot` implements — so code that needs to run "a robot or a network" doesn't have to branch on `is_a?(RobotLab::Network)`. For a `Network`: `crew` returns `robots.values` (pipeline order), `chief` is `crew.first`, `robot_count` is `crew.size`, and `network?` is `true`. `run(message = nil, **opts)` accepts a positional message the same way `Robot#run` does — it's folded into `message:` — while the existing `run(message: ...)` keyword form still works unchanged. See [Runnable Protocol](../architecture/core-concepts.md#runnable-protocol) in Core Concepts for the full comparison against `Robot`.
+
 ## Creating Networks
 
 Networks are created via `RobotLab.create_network` with a block DSL:
@@ -352,6 +356,10 @@ network.available_robots      #=> [Robot, Robot, ...]
 # Add a robot without a task
 network.add_robot(extra_robot)
 
+# Remove a dynamically-added robot (returns it, or nil if absent).
+# Only affects the crew (@robots) -- does not rewrite the pipeline.
+network.remove_robot(:extra_robot)
+
 # Convert to hash
 network.to_h
 #=> { name: "support", robots: ["classifier", "billing"], tasks: [...], optional_tasks: [...] }

data/docs/architecture/robot-execution.md

@@ -294,7 +294,7 @@ def call(result)
     .with_context(@name.to_sym, robot_result)
     .continue(robot_result)
 rescue Exception => e
-  # Error is wrapped in a RobotResult with the elapsed duration
+  elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
   error_result = RobotResult.new(
     robot_name: @name,
     output: [TextMessage.new(role: 'assistant', content: "Error: #{e.class}: #{e.message}")]

data/docs/examples/index.md

@@ -14,10 +14,11 @@ These examples show how to use RobotLab for common scenarios, from simple chatbo
 | [Multi-Robot Network](multi-robot-network.md) | Customer service with routing |
 | [Tool Usage](tool-usage.md) | External API integration |
 | [MCP Server](mcp-server.md) | Creating an MCP tool server |
-| [Rails Application](rails-application.md) | Full Rails integration |
 | [Message Bus](#message-bus) | Bidirectional robot communication with convergence |
 | [Spawning Robots](#spawning-robots) | Dynamic specialist creation at runtime |
 
+> **Rails example** — see [robot_lab-rails](https://github.com/MadBomber/robot_lab-rails/blob/main/docs/examples/rails-application.md) for a full Rails integration example.
+
 ## Quick Links
 
 ### Simple Examples
@@ -158,7 +159,7 @@ puts result.last_text_content
 
 3. Run example:
    ```bash
-   ruby examples/basic_chat.rb
+   ruby examples/01_simple_robot.rb
    ```
 
 Or use the provided rake tasks:
@@ -168,6 +169,40 @@ bundle exec rake examples:all          # Run all examples
 bundle exec rake examples:run[1]       # Run specific example by number
 ```
 
+## Shared Example Setup (`examples/common.rb`)
+
+All numbered examples (`01_*.rb` through `34_*.rb`) begin with:
+
+```ruby
+require_relative "common"
+```
+
+`common.rb` handles the shared boilerplate so individual examples stay focused:
+
+- **`LLM` hash** — frozen lookup of provider/model pairs accessible as `LLM[:default]`, `LLM[:local]`, `LLM[:anthropic]`. Each entry is a `LlmConfig = Data.define(:provider, :model)` value, so you access the model string as `LLM[:default].model`.
+- **`RubyLLM.configure`** — sets a null logger and `LLM[:default].model` as the `default_model`.
+- **`RobotLab.configure`** — sets a null logger.
+- **Output helpers** — `banner(title)`, `section(title)`, `hr`, and `show_code(ruby_string, label:)` (Rouge-highlighted) for consistent terminal formatting.
+
+## Template Path via direnv
+
+Examples that bundle their own `prompts/` directory ship with a `.envrc` file:
+
+```
+examples/.envrc
+examples/14_rusty_circuit/.envrc
+examples/15_memory_network_and_bus/.envrc
+examples/16_writers_room/.envrc
+```
+
+Each sets `ROBOT_LAB_TEMPLATE_PATH` to the local `prompts/` directory when [direnv](https://direnv.net/) is active. `common.rb` also sets this variable as a fallback if `direnv` has not loaded the `.envrc`:
+
+```ruby
+ENV["ROBOT_LAB_TEMPLATE_PATH"] ||= File.join(__dir__, "prompts")
+```
+
+This means examples work correctly whether you run them from the project root with rake tasks or directly from inside the example's own directory.
+
 ## Message Bus
 
 Robots can communicate bidirectionally via a message bus, enabling convergence loops and negotiation patterns. This example demonstrates a comedy critic tasking a comedian to generate jokes until one passes:

data/docs/getting-started/configuration.md

@@ -31,8 +31,14 @@ RobotLab.config.streaming_enabled          #=> true
 RobotLab.config.development?  #=> true/false
 ```
 
-!!! warning "No configure block"
-    RobotLab does **not** use a `RobotLab.configure do |config| ... end` pattern. All configuration comes from config files, environment variables, or direct assignment on `RobotLab.config`.
+!!! tip "configure block"
+    `RobotLab.configure` yields the config object for block-style setup — useful for setting runtime-only attributes like the logger. For static settings (API keys, timeouts, model defaults) prefer config files or environment variables.
+
+    ```ruby
+    RobotLab.configure do |c|
+      c.logger = Logger.new(File::NULL)   # silence all RobotLab logging
+    end
+    ```
 
 ## Environment Variables
 
@@ -193,16 +199,37 @@ Default chat parameters applied to all robots unless overridden:
 | `chat.with_params.frequency_penalty` | `null` | Frequency penalty (-2.0 to 2.0) |
 | `chat.with_params.stop` | `null` | Stop sequences |
 
+### Skill-Script Sandboxing (`sandbox:` section)
+
+Opt-in confinement for the scripts a [skill bundle](../guides/using-tools.md#skill-scripts-and-sandboxing) exposes as tools. Disabled by default — scripts run exactly as before until you turn it on:
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `sandbox.enabled` | `false` | Turn on OS-level confinement for skill scripts |
+| `sandbox.fs_read` | `["."]` | Ceiling: paths any skill script may read (relative to cwd) |
+| `sandbox.fs_write` | `[]` | Ceiling: paths any skill script may write |
+| `sandbox.network` | `false` | Ceiling: whether any skill script may use the network |
+| `sandbox.timeout` | `60` | Ceiling: max seconds a skill script may run |
+
+These are a **ceiling**, not a grant — the actual permissions a script runs with are the intersection of this ceiling and what the individual SKILL.md declares for itself. See [Skill Scripts and Sandboxing](../guides/using-tools.md#skill-scripts-and-sandboxing) for how the two combine and which platforms actually enforce confinement.
+
 ## Runtime-Only Attributes
 
-Some attributes can only be set at runtime, not through config files:
+Some attributes can only be set at runtime, not through config files. Use direct assignment on `RobotLab.config` or the `RobotLab.configure` block:
 
 ```ruby
-# Logger (defaults to Rails.logger in Rails, or Logger.new($stdout) otherwise)
-RobotLab.config.logger = Logger.new(nil)        # silence logging
-RobotLab.config.logger = Logger.new("robot.log") # log to file
+# Direct assignment
+RobotLab.config.logger = Logger.new(nil)          # silence logging
+RobotLab.config.logger = Logger.new("robot.log")  # log to file
+
+# Block-style configure (equivalent, useful when setting multiple values)
+RobotLab.configure do |c|
+  c.logger = Logger.new(File::NULL)
+end
 ```
 
+`RobotLab.configure` yields the same `Config` object returned by `RobotLab.config`.
+
 ## Reloading Configuration
 
 To reload configuration from all sources:
@@ -361,7 +388,9 @@ effective.temperature  #=> 0.9 (overridden)
 | **LLM** | `model`, `temperature`, `top_p`, `top_k`, `max_tokens`, `presence_penalty`, `frequency_penalty`, `stop` |
 | **Tools** | `mcp`, `tools` |
 | **Callbacks** | `on_tool_call`, `on_tool_result` |
-| **Infrastructure** | `bus`, `enable_cache`, `max_tool_rounds`, `token_budget`, `ractor_pool_size`, `max_concurrent_robots` |
+| **Infrastructure** | `bus`, `enable_cache`, `max_tool_rounds`, `token_budget`, `cost_budget`, `max_tools`, `ractor_pool_size`, `max_concurrent_robots`, `doom_loop_threshold`, `auto_compact`, `compact_threshold` |
+
+`cost_budget` mirrors `token_budget` for cumulative dollar spend — see [Budgets](../guides/observability.md#budgets-token--cost). `max_tools` overrides the default 128-tool ceiling enforced on every turn before tools are handed to the provider — see [Tool Capping](../guides/using-tools.md#tool-capping-and-per-turn-filtering).
 
 ### RunConfig vs RobotLab.config
 
@@ -412,10 +441,13 @@ robot = RobotLab.build(
   name: "calculator",
   system_prompt: "You solve math problems.",
   mcp: :none,
+  tools: :inherit,          # required: without this, local_tools below is never sent
   local_tools: [Calculator]
 )
 ```
 
+> **`tools:` defaults to `:none` at every level**, including `run()` itself. Attaching tools via `local_tools:` does not by itself make them available — an explicit `:none` (or an unset runtime override, which is equivalent) now sends **zero** tools for that call. Pass `tools: :inherit` wherever you want a robot's attached tools to actually be used. See [Runtime Tool Filtering](../guides/using-tools.md#runtime-tool-filtering) for the full `:inherit`/`:none`/array semantics.
+
 ## Next Steps
 
 - [Building Robots](../guides/building-robots.md) - Create custom robots

data/docs/guides/building-robots.md

@@ -63,7 +63,9 @@ robot = RobotLab.build(
 )
 ```
 
-When `provider:` is set, `assume_model_exists: true` is automatically applied. The provider is available via `robot.provider`.
+When `provider:` is set, `assume_model_exists: true` is automatically applied. The provider is available via `robot.provider`. This context is preserved across every re-application of the robot's config — including when a template's front matter re-renders mid-run — so a local-provider robot doesn't fall back to RubyLLM's static model registry (and raise a "model not found" error) on later turns.
+
+Some local models route their entire response through reasoning/thinking content instead of the normal response text (e.g. `qwen3` on Ollama). When that happens, `result.reply` falls back to the thinking text automatically — see [Robot with Local Provider](../api/core/robot.md#robot-with-local-provider) for details.
 
 ### System Prompt
 
@@ -144,6 +146,17 @@ The following YAML front matter keys are applied to the robot's chat automatical
 
 Constructor-provided values always take precedence over frontmatter values.
 
+### Rendering a Template to a String
+
+`RobotLab.render_template` renders a named template directly to a `String` — using the same configured template library (`prompts_dir` / `ROBOT_LAB_TEMPLATE_PATH`) as `template:` on `RobotLab.build` — without constructing a robot. Front-matter parameters are supplied as keyword arguments:
+
+```ruby
+RobotLab.render_template(:objective, topic: "commit messages")
+# => "<rendered body of prompts/objective.md, with topic substituted>"
+```
+
+Unlike `template:` on `build` (which renders a template as a robot's *system prompt*), this returns the plain text — useful as a one-off task message, an evaluation rubric, or any other place you want a parameterized `.md` template's body without the overhead of a robot.
+
 ### Self-Contained Templates
 
 Templates can declare everything a robot needs — identity, tools, MCP servers, and LLM config — making the `.md` file a complete robot definition:
@@ -686,6 +699,30 @@ The `on_message` block arity controls delivery handling:
 
 See [Message Bus](../architecture/core-concepts.md#message-bus) for details.
 
+### Auto-Responding to Bus Tasks
+
+The `Comedian`/`ComedyCritic` example above hand-wires `on_message` to run and reply. For the common case — run every inbound task through the robot and reply with the result — `respond_to_tasks`/`serve` do it in one call:
+
+```ruby
+bob = RobotLab.build(name: "bob", template: :comedian, bus: bus)
+bob.serve  # every inbound task runs through bob.run and replies automatically
+
+alice.send_message(to: :bob, content: "Tell me a funny robot joke.")
+```
+
+`serve` is shorthand for `respond_to_tasks(auto_reply: true) { |message| run(message.content).reply }`. Use `respond_to_tasks` directly when the reply shouldn't just be `run(...).reply` — e.g. post-processing the result first:
+
+```ruby
+bob.respond_to_tasks do |message|
+  joke = run(message.content.to_s).reply.strip
+  joke.end_with?("!") ? joke : "#{joke}!"
+end
+```
+
+Both ignore messages that are themselves replies (`message.reply?`), so two robots calling `serve`/`respond_to_tasks` on each other don't loop.
+
+See [Message Bus](../architecture/core-concepts.md#message-bus) for details.
+
 ### Spawning Robots Dynamically
 
 Create new robots at runtime using `spawn`. The bus is created lazily — no upfront wiring required:
@@ -728,6 +765,7 @@ Key features of `spawn`:
 - Creates a bus lazily if the parent doesn't have one
 - Spawned robots can immediately send and receive messages
 - Multiple robots with the same name enable fan-out messaging
+- The child inherits the parent's `model`/`provider` (caller-supplied `model:`/`provider:` still override) — a dispatcher running on a local Ollama model spawns specialists that also target that model, instead of falling back to the global default model/provider
 
 Robots can also join a bus after creation:
 

data/docs/guides/creating-networks.md

@@ -105,7 +105,7 @@ network = RobotLab.create_network(name: "launch_assessment", config: config) do
 end
 ```
 
-`nil` (the default) means unlimited — identical to pre-existing behavior. For Rails deployments, size the cap to match your database connection pool and API rate tier. See [Example 31](../../examples/31_launch_assessment.rb) for a working demo.
+`nil` (the default) means unlimited — identical to pre-existing behavior. For Rails deployments, size the cap to match your database connection pool and API rate tier. See [examples/31_launch_assessment.rb](https://github.com/MadBomber/robot_lab/blob/main/examples/31_launch_assessment.rb) for a working demo.
 
 ### Optional Tasks
 
@@ -441,8 +441,13 @@ network["billing"]        # => Robot instance (alias)
 network.available_robots  # => Array of Robot instances
 network.memory            # => Memory instance (shared)
 network.to_h              # => Hash representation
+
+network.add_robot(extra_robot)      # add without a pipeline task -> self
+network.remove_robot(:extra_robot)  # remove by name -> the removed Robot, or nil
 ```
 
+`remove_robot` only drops the robot from the crew — it doesn't touch the pipeline, so don't remove a robot that's still a `depends_on` target of a task.
+
 ## Configuration Inheritance
 
 Networks accept a `config:` parameter that establishes default LLM settings for all member robots. This is useful when you want consistent behavior across a pipeline without configuring each robot individually.