robot_lab 0.1.0 → 0.2.1

data/agent2agent_review.md

@@ -0,0 +1,192 @@
+# Review: `agent2agent` Ruby Gem
+
+**Source:** https://github.com/general-intelligence-systems/agent2agent
+**Docs:** https://general-intelligence-systems.github.io/agent2agent/
+**License:** Apache 2.0
+**Ruby:** >= 3.2
+**Reviewed:** 2026-05-05
+
+---
+
+## What It Is
+
+A complete Ruby implementation of Google's A2A (Agent-to-Agent) protocol — an open standard for interoperable, cross-vendor AI agent communication over HTTP. The gem provides both a server (Rack app) and a client, plus SSE streaming, task persistence, and push notifications.
+
+---
+
+## Wire Protocol
+
+Two parallel transport bindings, both implemented:
+
+| Transport | Path | Format |
+|---|---|---|
+| JSON-RPC 2.0 | `POST /a2a` | `{"jsonrpc":"2.0","method":"SendMessage","params":{...}}` |
+| HTTP+JSON/REST | `POST /message:send`, `GET /tasks/{id}`, etc. | Plain JSON |
+| Agent Discovery | `GET /.well-known/agent-card.json` | Capabilities manifest |
+
+### The 11 Protocol Operations
+
+1. `SendMessage` — POST `/message:send` (synchronous)
+2. `SendStreamingMessage` — POST `/message:stream` (SSE, server-streaming)
+3. `GetTask` — GET `/tasks/{id}`
+4. `ListTasks` — GET `/tasks`
+5. `CancelTask` — POST `/tasks/{id}:cancel`
+6. `SubscribeToTask` — SSE stream of task updates
+7. `CreateTaskPushNotificationConfig` — POST `/tasks/{id}/push`
+8. `GetTaskPushNotificationConfig` — GET `/tasks/{id}/push/{config_id}`
+9. `ListTaskPushNotificationConfigs` — GET `/tasks/{id}/push`
+10. `DeleteTaskPushNotificationConfig` — DELETE `/tasks/{id}/push/{config_id}`
+11. `GetExtendedAgentCard` — GET extended agent card
+
+### Task State Machine
+
+`SUBMITTED → WORKING → INPUT_REQUIRED → COMPLETED / FAILED / CANCELED / REJECTED`
+
+---
+
+## Key Classes and Their Roles
+
+| Class | Role |
+|---|---|
+| `A2A::Agent` | DSL: `on("SendMessage") { \|req\| respond(...) }` — registers operation handlers |
+| `A2A::Server` | Rack app — mountable in any Rack stack or Rails router |
+| `A2A::Client` | Async-HTTP client; all 11 ops auto-generated as snake_case methods |
+| `A2A::Proto` | Parses the real `data/a2a.proto` file — single source of truth for operations |
+| `A2A::Schema` | Loads 47-type `data/a2a.json`; validates with `json_schemer`; camelCase/snake_case |
+| `A2A::TaskStore` | In-memory task CRUD with `Thread::Queue` pub/sub and webhook delivery |
+| `A2A::Store::SQLite` | Production drop-in: WAL mode, indexed, fiber-safe `Async::Queue` pub/sub |
+| `A2A::SSE::Stream` | Subclasses `Protocol::HTTP::Body::Writable`; Falcon passes it untouched |
+| `A2A::Bindings::JsonRpc` | Rack middleware that parses JSON-RPC envelopes and wraps responses |
+
+### Agent DSL Example
+
+```ruby
+agent = A2A::Agent.new do
+  on "SendMessage", "SendStreamingMessage" do |context|
+    task = context.store.create(context.request)
+    stream = context.stream
+
+    Async do
+      result = robot.run(context.request.params[:message])
+      context.store.complete(task.id, result)
+      stream.event(result, type: "result")
+      stream.finish
+    end
+
+    context.respond(task)
+  end
+end
+
+server = A2A::Server.new
+server.register(agent)
+run server
+```
+
+### Client Example
+
+```ruby
+Async do
+  client = A2A::Client.new("http://localhost:9292")
+  card = client.agent_card
+  result = client.send_message(message: { role: "user", parts: [{ text: "Hello" }] })
+  puts result
+end
+```
+
+---
+
+## Notable Patterns
+
+- **Duck-typed stores:** Any object implementing the task store interface can be swapped in — `TaskStore` (in-memory) or `Store::SQLite` (production), or a custom implementation.
+- **Proto as source of truth:** `Proto` parses `data/a2a.proto` directly to extract operation metadata — stays in sync with the Google A2A spec automatically.
+- **Fiber-native:** The SQLite store's pub/sub uses `Async::Queue`; SSE bodies use `Protocol::HTTP::Body::Writable`. Fully fiber-safe when run under Falcon.
+- **`returnImmediately` flag:** Background jobs return a task ID immediately; updates stream via SSE as work proceeds.
+- **`STATE_INPUT_REQUIRED`:** Multi-turn conversations — agent transitions to this state when it needs more user input before continuing. Client sends another `SendMessage` referencing the same task context.
+- **Inline tests via `scampi`:** Tests live inside source files (`test do ... end`), not a separate test directory.
+- **Tenant-prefixed paths:** Every REST route has a variant: `/{tenant}/message:send` for multi-tenant deployments.
+
+---
+
+## Authentication
+
+- **AgentCard** declares supported auth schemes in the capabilities manifest
+- **Push notification configs** carry per-webhook auth: `scheme` + `credentials` sent as `Authorization: Bearer <credentials>` on webhook delivery; optionally also `X-A2A-Notification-Token`
+- Incoming request authentication is left to the application layer (standard Rack middleware pattern)
+
+---
+
+## Dependencies
+
+**Runtime:**
+- `async (~> 2.0)`, `async-http (~> 0.95)` — fiber concurrency and HTTP
+- `rack (~> 3.0)` — server composition (pure Rack, Rails-mountable)
+- `json_schemer (~> 2.5)` — schema validation against 47 A2A types
+- `google-protobuf (~> 4.34)` — proto file parsing
+- `sqlite3` — persistent task store
+- `protocol-http (~> 0.62)` — `Body::Writable` for SSE
+- `scampi` — inline test framework
+- `console` — structured logging
+
+**Development:**
+- `falcon (~> 0.55)` — async HTTP server for running agents
+
+---
+
+## Applicability to Your Projects
+
+### RobotLab — High Value
+
+The most compelling integration: expose each `Robot` or `Network` as a standard A2A service. This enables cross-language orchestration (Python LangChain, JS Genkit, Go agents, Google Cloud agents) without any shared code.
+
+**Robot-as-A2A-Service:**
+- `A2A::Agent` adapter delegates `SendMessage` → `robot.run(request.message)`, result becomes the A2A task result
+- Publish an AgentCard at `/.well-known/agent-card.json` advertising each robot's capabilities and tools
+- Use `A2A::Store::SQLite` to persist tasks across requests (stateless HTTP tier in front of stateful robots)
+
+**Streaming:**
+- `SendStreamingMessage` + `SSE::Stream` maps directly onto RubyLLM's streaming callbacks
+- Streaming events become real-time SSE — no additional infrastructure needed
+
+**Cross-process robot networks:**
+- Instead of `TypedBus` (in-process pub/sub only), robots in separate processes or machines call each other via `A2A::Client`
+- A Network router can delegate to remote robots via `client.send_message(...)` — standard HTTP replaces shared-memory message passing
+
+**Background jobs:**
+- A2A's push notification config CRUD gives external systems a standard webhook protocol for task completion
+- Maps cleanly onto RobotLab's existing async robot semantics
+
+**Multi-turn conversations:**
+- `STATE_INPUT_REQUIRED` maps directly to RobotLab's `AskUser` tool pattern — robot needs user input before continuing
+- Web clients get a proper protocol for handling confirmation flows rather than a terminal prompt
+
+**Compatibility note:** Both RobotLab and `agent2agent` use the `async` gem — they compose cleanly. The main requirement is running under Falcon rather than a plain Ruby process. `TypedBus` (`Async::Queue`) and `A2A::Store::PubSub` (`Async::Queue`) are both fiber-based and compatible.
+
+### AIA — Moderate Value
+
+- `A2A::Client` could delegate tasks to remote A2A-compliant agents (specialized coding agents, search agents, etc.) instead of calling LLM APIs directly
+- AIA could optionally expose itself as a local A2A server on `localhost:PORT` so IDE plugins or other tools can send it tasks via standard protocol
+- AgentCard discovery would let AIA auto-configure available capabilities when connecting to remote agents
+
+### Rails Apps Generally
+
+`A2A::Server` is pure Rack:
+
+```ruby
+# config/routes.rb
+mount A2A::Server.new(agent: my_agent), at: "/agents/myagent"
+```
+
+This works as-is. The 47-type schema validation via `json_schemer` is also useful standalone for validating A2A protocol payloads.
+
+---
+
+## Bottom Line
+
+Production-quality gem for its scope. Clean architecture: Rack middleware chain, duck-typed stores, fiber-safe pub/sub, SSE via `protocol-http`. Inline test coverage is extensive.
+
+**Highest-value opportunity for RobotLab:** Robot-as-A2A-Service — exposing robots as standards-compliant HTTP endpoints enables cross-language agent orchestration that the current `TypedBus` approach (in-process only) cannot support. This would position RobotLab robots as first-class participants in the emerging A2A ecosystem alongside Python, JavaScript, and Go agent frameworks.
+
+**Specific algorithms/patterns worth porting:**
+1. `A2A::Store::SQLite` pub/sub pattern (Async::Queue-based) — applicable to RobotLab's Memory system
+2. AgentCard capability manifest — useful for RobotLab's planned tool/capability discovery
+3. `STATE_INPUT_REQUIRED` state machine entry — formalizes the `AskUser` pattern with a standard protocol state

data/agentf_improvements.md

@@ -0,0 +1,253 @@
+# `agentf` Gem Analysis
+
+**Repository:** https://github.com/nealdeters/agentf
+**Author:** Neal Deters
+**Ruby:** 3.3.0+ | **Runtime deps:** `redis ~> 4.8`, `dotenv ~> 2.8`
+
+---
+
+## What It Is
+
+A Ruby multi-agent workflow engine for software development. Orchestrates
+role-specialized agents (Planner, Engineer, QA, Reviewer, Security) that share
+Redis memory — but **never calls an LLM itself**. It runs as an MCP server over
+stdio and lets the IDE's AI (Copilot, OpenCode) do the actual inference.
+It is scaffolding, not an API wrapper.
+
+Three surfaces:
+- **CLI** (`agentf <subcommand>`) — memory management, code exploration, metrics, evals
+- **MCP server** (`agentf mcp-server`) — 19 tools over stdio for IDE integrations
+- **Ruby API** — `WorkflowEngine`, `Agents::*`, `RedisMemory` for programmatic use
+
+---
+
+## Architecture
+
+| Layer | Files | Role |
+|---|---|---|
+| Entry point | `agentf.rb`, `bin/agentf` | Config singleton + CLI boot |
+| CLI | `cli/router.rb`, `cli/memory.rb`, `cli/code.rb` | Subcommand dispatch |
+| Agents | `agents/base.rb`, role subclasses | Role-based agent classes |
+| Workflow | `workflow_engine.rb` | Orchestrator / sequencer |
+| Memory | `memory.rb`, `memory/confirmation_handler.rb` | Redis-backed storage |
+| Contracts | `workflow_contract.rb`, `agent_execution_contract.rb` | Constraint enforcement |
+| Tools | `tools/`, `tools.rb` | Primitive capabilities |
+| Commands | `commands/registry.rb`, `commands/*.rb` | Named command registry |
+| MCP | `mcp/server.rb`, `mcp/stub.rb` | stdio MCP protocol server |
+| Service | `service/providers.rb` | Provider adapters |
+| Installer | `installer.rb` | Manifest generation and provider setup |
+
+---
+
+## Patterns Worth Stealing
+
+### 1. Agents That Describe Themselves at the Class Level
+
+All agent metadata — `description`, `deliverables`, `policy_boundaries`,
+`when_to_use`, `commands` — are class methods, not instance state or external
+YAML. Agents are self-documenting, introspectable at install time, and
+verifiable without instantiating anything. The `Installer` reads these at
+install time to generate markdown manifests.
+
+### 2. Three-Mode Contract Enforcement (advisory / enforcing / off)
+
+A contract object wraps agent execution with `before!`/`after!` validation.
+Run workflows in `advisory` mode during development (log violations, don't
+stop), flip to `enforcing` for production. TDD phase discipline (`"red"` vs
+`"green"`) is enforced at the contract layer, not by convention.
+
+### 3. Human-in-the-Loop Memory Writes
+
+`ConfirmationHandler` wraps Redis writes so that when confirmation is needed,
+instead of raising it returns `{ confirmation: true, payload: ..., instructions: ... }`.
+The caller re-invokes with `confirmedWrite: "confirmed"`. Works identically
+across CLI, MCP, and programmatic callers.
+
+### 4. Deterministic Local Embeddings With No ML Dependency
+
+`EmbeddingProvider` SHA256-hashes tokens, uses the hash to pick a dimension in
+a 64-element float vector, then normalizes it. Zero API calls, zero latency,
+fully reproducible. Crude but sufficient for semantic memory search in a
+dev-tool context.
+
+### 5. Black-Box Shell Script Evals
+
+Each eval scenario is three files: `prompt.txt`, `scenario.yml`, and
+`verify.sh`. The shell script asserts postconditions against real Redis state.
+Simple, portable, no mocking — `agentf eval run all` just executes them.
+
+### 6. Graceful Redis Capability Degradation
+
+The memory layer detects at runtime whether Redis Stack's JSON/Search/Vector
+modules are present and degrades silently. Full semantic search if available;
+plain key-value otherwise. No config flag needed — baked into `RedisMemory`.
+
+### 7. Ruby Generating Its Own TypeScript Integration
+
+The installer generates TypeScript plugin files (`agentf-plugin.ts`,
+`tsconfig.json`, `package.json`) from within Ruby for OpenCode integration.
+A Ruby gem producing its own typed IDE plugin layer is unusual and practical.
+
+### 8. Policies Stored in Code, Not Config
+
+`policy_boundaries` returns `{ "always" => [...], "ask_first" => [...], "never" => [...] }`
+directly from Ruby class methods. Changing a policy means changing Ruby, not
+YAML — no config drift.
+
+### 9. Workflow Profiles as Constants
+
+Workflow compositions are defined as constants in `WorkflowEngine::PROFILES`
+(e.g., `rails_standard`, `rails_37signals`), mapping task types to ordered
+agent sequences. One canonical source of truth for workflow shapes.
+
+---
+
+## RobotLab Applicability Analysis
+
+### Patterns That Don't Apply
+
+**Pattern 7 — Ruby Generating Its Own TypeScript Integration**
+agentf is an IDE tool targeting Copilot/OpenCode. RobotLab is a Ruby library with no IDE integration surface. Not relevant.
+
+**Pattern 6 — Graceful Redis Capability Degradation**
+Already handled. `Memory` already degrades `redis → hash` fallback at initialization. `DocumentStore` uses fastembed, not Redis Stack — separate concern covered below.
+
+---
+
+### Patterns Worth Implementing
+
+---
+
+#### Pattern 1 — Self-Describing Robots/Tools (HIGH VALUE)
+
+This is the missing piece for `tool_manifest_plan.md`. Nothing auto-registers today because there is nowhere to register *to* and no class-level metadata to register. agentf's insight: put descriptors at the class level, not in instances.
+
+```ruby
+class MyTool < RobotLab::Tool
+  self.description = "Fetch current weather for a location"
+  self.tags        = [:network, :read_only]
+end
+```
+
+At class-load time, Zeitwerk triggers auto-registration into `RobotLab.tool_registry`. The selector-robot pattern becomes viable without any explicit registration ceremony. Live callable instances stay per-robot; the global registry holds lightweight descriptors only (name + description). This is the v1 the `tool_manifest_plan.md` actually needs — and avoids the MCP auto-registration problem identified in that plan's review notes.
+
+Robot subclasses get the same treatment:
+```ruby
+class SupportBot < RobotLab::Robot
+  self.description  = "Handles tier-1 customer support"
+  self.capabilities = [:search, :ticket_creation]
+end
+```
+
+This also enables the `Installer`-style manifest generation: `RobotLab.tool_registry.summary` produces the compact name+description list the selector robot reasons over.
+
+---
+
+#### Patterns 2 + 8 — Contract Enforcement + Policy Boundaries (HIGH VALUE, medium effort)
+
+RobotLab has a circuit breaker (`max_tool_rounds`) and an error hierarchy — but no *pre/post validation layer* on execution. As AIA drives RobotLab into production use, this gap is significant.
+
+The three modes map cleanly to the dev→prod lifecycle:
+- `advisory` — log violations, don't block (development default)
+- `enforcing` — raise on violation (production default)
+- `off` — no overhead (test default)
+
+Policies declared at the Tool class level:
+```ruby
+class DeleteFileTool < RobotLab::Tool
+  policy :ask_first   # always prompt user before executing
+end
+
+class FormatDriveTool < RobotLab::Tool
+  policy :never       # contract blocks execution entirely in enforcing mode
+end
+```
+
+The contract wraps `robot.run()` with `before!`/`after!` hooks — checks token budget, validates tool policies, enforces max cost. A `RunConfig` field (`contract: :advisory`) controls the mode and flows through the standard hierarchy. This pairs naturally with the existing `RunConfig` merge semantics and would be the first true safety/governance layer in RobotLab.
+
+---
+
+#### Pattern 9 — Workflow Profiles (LOW EFFORT, good discoverability)
+
+Networks are currently built by hand each time. A `RobotLab::Profiles` module with named constants would reduce boilerplate and document canonical topologies:
+
+```ruby
+RobotLab::Profiles::CONSENSUS   # fan-out to N robots → reconciler
+RobotLab::Profiles::PIPELINE    # sequential chain
+RobotLab::Profiles::PARALLEL    # concurrent, no synthesis
+RobotLab::Profiles::MCP_FAN_OUT # one robot per MCP server
+```
+
+Each profile is a lambda/factory that takes robots + optional router and returns a configured network. This also gives AIA's `RobotFactory` topologies a canonical home in the library itself rather than application-level code.
+
+---
+
+#### Pattern 5 — Eval Framework (MEDIUM EFFORT, high long-term value)
+
+RobotLab has 22 example scripts but **zero assertions**. They are demos, not evals. agentf's `prompt.txt + scenario.yml + verify.sh` per scenario is the right shape.
+
+For RobotLab the natural form:
+- `evals/scenarios/convergence_basic/` — prompt, expected behavior description, `verify.rb` script
+- `rake eval:run[convergence_basic]` replays against a VCR cassette and asserts postconditions
+- `rake eval:run:all` becomes a regression suite for agent behavior
+
+This connects directly to AIA's EDD (Eval-Driven Development) vision and would give confidence before a 1.0 release. The existing VCR/WebMock infrastructure is the right foundation.
+
+---
+
+#### Pattern 4 — Deterministic Embedding Fallback (LOW EFFORT)
+
+`DocumentStore` hard-requires fastembed — no fallback. On first use it downloads an ONNX model, which is slow and requires a working network. `word_hash` (stemmed TF vectors) already exists in the codebase and is used by `compress_history`, `search_history`, and `Convergence`.
+
+A simple degradation path: when fastembed raises `LoadError` or the model is unavailable, `DocumentStore` falls back to `word_hash` cosine similarity with a logged warning. Zero new infrastructure — just wiring what already exists into `DocumentStore#embed`.
+
+---
+
+#### Pattern 3 — HITL Confirmation Protocol (LOW VALUE given AskUser)
+
+The agentf pattern — return `{ confirmation: true, payload: }` instead of raising, re-invoke with `confirmedWrite: "confirmed"` — is elegant for memory writes that need approval. However, RobotLab already has `AskUser` for the primary HITL use case. This pattern only becomes interesting if RobotLab needs programmatic HITL that doesn't require a terminal (e.g., web apps pausing for user approval via HTTP callback). Not urgent.
+
+---
+
+### Priority Ranking
+
+| Priority | Pattern | Effort | Connects To |
+|---|---|---|---|
+| 1 | Self-describing tools/robots (class-level metadata) | Medium | `tool_manifest_plan.md` — makes ToolManifest v1 actionable |
+| 2 | Contract enforcement + Policy boundaries | Medium | Production safety gap; RunConfig integration |
+| 3 | Eval framework | Medium | Long-term regression confidence; AIA EDD |
+| 4 | Workflow profiles | Low | AIA's RobotFactory; discoverability |
+| 5 | DocumentStore word_hash fallback | Low | Dev ergonomics; no ONNX download needed |
+
+**Natural weekly pairing:** Pattern 1 (self-describing classes → ToolManifest v1) + Pattern 9 (workflow profiles) form a coherent "discoverability and composability" theme. Patterns 2+8 are the right *next* architectural investment but scope to a separate week.
+
+---
+
+## Comparison to Other Agent Frameworks
+
+| Aspect | `agentf` | LangChain (Python) | CrewAI (Python) |
+|---|---|---|---|
+| Language | Ruby | Python | Python |
+| LLM calls | None (delegates to IDE) | Direct | Direct |
+| Agent communication | Shared Redis memory | In-process state | Sequential/hierarchical |
+| Memory | Episodic + semantic (Redis Stack) | Various vector stores | Basic |
+| IDE integration | MCP server (Copilot, OpenCode) | None native | None native |
+| Contract enforcement | 3-mode advisory/enforcing/off | None | None |
+| Self-describing agents | Class-method metadata | No | Role strings in YAML |
+| Eval framework | Black-box shell scripts | Unit tests | Unit tests |
+| TDD enforcement | Built-in (red/green contracts) | None | None |
+
+Within Ruby there is essentially no direct equivalent. `ruby-openai` and
+`omniai` handle LLM API calls but have no orchestration. `agentf` is novel in
+the Ruby ecosystem for combining Redis-backed episodic memory, role-specialized
+agent classes, contract enforcement, and an MCP stdio server in one gem.
+
+---
+
+## The Big Takeaway
+
+The most instructive thing about `agentf` is its **division of responsibility**:
+the gem owns memory, sequencing, policies, and tool-exposure via MCP — the
+IDE's AI owns inference. That separation means no API keys, no HTTP calls to
+LLM providers, and no model coupling. If building AI-assisted tooling in Ruby,
+that architecture is worth emulating.

data/agents.md

@@ -0,0 +1,14 @@
+### Local Agent Context: Repository Root
+
+- Start here, then navigate to the closest directory AGENTS.md before coding.
+- Do not operate from root unless necessary.
+
+## Table of Contents
+
+- [.architecture/reviews](./.architecture/reviews/AGENTS.md): Access `config.yml` for architecture-related settings.
+- [.github/workflows](./.github/workflows/AGENTS.md): Review `deploy-github-pages.yml` for CI/CD pipeline specifics.
+- [.ruby-lsp](./.ruby-lsp/AGENTS.md): Initialize your environment with `Gemfile` dependencies.
+- [docs](./docs/AGENTS.md): Consult `/docs/api/core/robot.md` for robot-related API documentation.
+- [examples](./examples/AGENTS.md): Explore `14_rusty_circuit/open_mic.rb` for demo scripts in action.
+- [lib/generators/robot_lab](./lib/generators/robot_lab/AGENTS.md): Use `templates/initializer.rb.tt` for custom project setup.
+- [test/robot_lab](./test/robot_lab/AGENTS.md): Implement new tests based on `test_helper.rb` configurations.

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
 
@@ -195,14 +201,21 @@ Default chat parameters applied to all robots unless overridden:
 
 ## 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 +374,7 @@ 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`, `ractor_pool_size`, `max_concurrent_robots`, `doom_loop_threshold`, `auto_compact`, `compact_threshold` |
 
 ### RunConfig vs RobotLab.config
 

data/docs/guides/index.md

@@ -40,21 +40,11 @@ If you're new to RobotLab, start here:
 
 -   [:octicons-pulse-24: **Observability & Safety**](observability.md)
 
-    Token tracking, circuit breakers, and learning accumulation
+    Token tracking, circuit breakers, doom loop detection, auto compaction, and learning accumulation
 
--   [:material-cpu-64-bit: **Ractor Parallelism**](ractor-parallelism.md)
+-   [:octicons-search-24: **Knowledge & Retrieval**](knowledge.md)
 
-    True CPU parallelism for tools and robot pipelines via Ruby Ractors
-
-</div>
-
-## Framework Integration
-
-<div class="grid cards" markdown>
-
--   [:material-language-ruby:{ .lg } **Rails Integration**](rails-integration.md)
-
-    Use RobotLab in Ruby on Rails applications
+    Chat history search and embedding-based document store for RAG workflows
 
 </div>
 
@@ -68,6 +58,16 @@ If you're new to RobotLab, start here:
 | [MCP Integration](mcp-integration.md) | External tool servers | 10 min |
 | [Streaming](streaming.md) | Real-time responses | 5 min |
 | [Memory](memory.md) | Shared data store | 5 min |
-| [Rails Integration](rails-integration.md) | Rails application setup | 15 min |
-| [Observability & Safety](observability.md) | Token tracking, circuit breaker, learning loop | 10 min |
-| [Ractor Parallelism](ractor-parallelism.md) | CPU-parallel tools and robot pipelines | 15 min |
+| [Observability & Safety](observability.md) | Token tracking, circuit breaker, doom loop detection, auto compaction, learning loop | 10 min |
+| [Knowledge & Retrieval](knowledge.md) | Chat history search and embedding-based document store (RAG) | 10 min |
+
+## Extension Gems
+
+Additional capabilities are available as separate gems:
+
+| Gem | Description | Docs |
+|-----|-------------|------|
+| [robot_lab-rails](https://github.com/MadBomber/robot_lab-rails) | Rails generators, background jobs, Turbo Stream broadcasting | [Rails Integration guide](https://github.com/MadBomber/robot_lab-rails/blob/main/docs/guides/rails-integration.md) |
+| [robot_lab-ractor](https://github.com/MadBomber/robot_lab-ractor) | True CPU parallelism for tools and robot pipelines via Ruby Ractors | [Ractor Parallelism guide](https://github.com/MadBomber/robot_lab-ractor/blob/main/docs/guides/ractor-parallelism.md) |
+| [robot_lab-durable](https://github.com/MadBomber/robot_lab-durable) | Cross-session knowledge persistence with YAML-backed storage | [robot_lab-durable README](https://github.com/MadBomber/robot_lab-durable) |
+| [robot_lab-document_store](https://github.com/MadBomber/robot_lab-document_store) | Embedding-based semantic document search via fastembed | [robot_lab-document_store README](https://github.com/MadBomber/robot_lab-document_store) |

data/docs/guides/knowledge.md

@@ -171,7 +171,13 @@ result = robot.run("Use the following context:\n#{context}\n\nQuestion: #{user_q
 
 ### Dependency
 
-`fastembed` is a core RobotLab dependency — no optional gem required. The ONNX model is downloaded on first use.
+The embedding-based document store requires the [`robot_lab-document_store`](https://github.com/MadBomber/robot_lab-document_store) extension gem. Add it to your Gemfile:
+
+```ruby
+gem "robot_lab-document_store"
+```
+
+This gem bundles `fastembed` for ONNX-based embeddings. The `BAAI/bge-small-en-v1.5` model (~23 MB) is downloaded on first use and cached in `~/.cache/fastembed/`. Without `robot_lab-document_store` loaded, calling `memory.store_document` or `memory.search_documents` raises `RobotLab::DependencyError`.
 
 ---