robot_lab 0.3.0 → 0.3.1

data/agent2agent_review.md

@@ -1,192 +0,0 @@
-# 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

@@ -1,253 +0,0 @@
-# `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

@@ -1,14 +0,0 @@
-### 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/api/core/index.md

@@ -1,147 +0,0 @@
-# Core Classes
-
-The fundamental classes that power RobotLab.
-
-## Overview
-
-```mermaid
-classDiagram
-    class Robot {
-        +name: String
-        +description: String
-        +model: String
-        +template: Symbol
-        +local_tools: Array~Tool~
-        +mcp_tools: Array~Tool~
-        +tools_config: Symbol_or_Array
-        +run(message) RobotResult
-    }
-
-    class RobotResult {
-        +robot_name: String
-        +reply: String
-        +output: Array~TextMessage~
-        +input_tokens: Integer
-        +output_tokens: Integer
-        +export() Hash
-    }
-
-    class Network {
-        +name: String
-        +robots: Hash
-        +config: RunConfig
-        +memory: Memory
-        +run(message) SimpleFlow_Result
-    }
-
-    class RunConfig {
-        +model: String
-        +temperature: Float
-        +merge(other) RunConfig
-        +apply_to(chat)
-    }
-
-    class Tool {
-        +name: String
-        +description: String
-        +robot: Robot
-        +mcp: String
-        +call(args)
-    }
-
-    class Memory {
-        +set(key, value)
-        +get(key)
-        +delete(key)
-        +data: StateProxy
-        +results: Array
-        +messages: Array
-        +session_id: String
-    }
-
-    class RobotMessage {
-        +id: Integer
-        +from: String
-        +content: String
-        +in_reply_to: String
-        +key()
-        +reply?()
-    }
-
-    Network --> Robot : contains
-    Network --> RunConfig : uses
-    Robot --> RunConfig : uses
-    Robot --> Tool : has
-    Robot --> Memory : uses
-    Robot ..> RobotResult : returns
-    Network --> Memory : uses
-    Robot ..> RobotMessage : sends/receives
-    Memory --> StateProxy : data
-```
-
-## Classes
-
-| Class | Purpose |
-|-------|---------|
-| [Robot](robot.md) | LLM agent with templates, tools, memory, and model configuration |
-| [RobotResult](result.md) | Value object returned by `Robot#run` |
-| [Network](network.md) | Container for robots with DAG orchestration |
-| [RunConfig](robot.md#runconfig) | Shared configuration for LLM, tools, callbacks, and infrastructure |
-| [Tool](tool.md) | Callable function with parameters and an `execute` method |
-| [AskUser](tool.md#built-in-askuser) | Built-in tool for terminal-based user interaction |
-| [Memory](memory.md) | Reactive key-value store for sharing data |
-| [StateProxy](state.md) | Hash/method-access wrapper returned by `memory.data` |
-| RobotMessage | Typed envelope for bus-based inter-robot communication |
-| `RobotLab::Runnable` | Shared interface (`crew`, `chief`, `robot_count`, `network?`, `single?`) implemented by both `Robot` and `Network` — see [Runnable Protocol](../../architecture/core-concepts.md#runnable-protocol) |
-
-There is no `RobotLab::State` class and no `RobotLab::NetworkRun` class.
-
-## Quick Examples
-
-### Robot
-
-```ruby
-robot = RobotLab.build(
-  name: "assistant",
-  model: "claude-sonnet-4",
-  system_prompt: "You are helpful.",
-  local_tools: [greet_tool]
-)
-
-result = robot.run("Hello!")              # no tools sent — run() defaults to tools: :none
-result = robot.run("Hello!", tools: :inherit)  # sends greet_tool
-result.reply                              # => String
-```
-
-`Robot#run` returns a [`RobotLab::RobotResult`](result.md), not a `Message`.
-
-### Network
-
-The builder DSL method is `task` (there is no `step`):
-
-```ruby
-network = RobotLab.create_network(name: "my_network") do
-  task :analyzer, analyzer_robot, depends_on: :none
-  task :writer, writer_robot, depends_on: [:analyzer]
-end
-
-result = network.run(message: "Process this")  # => SimpleFlow::Result
-result.value                                   # => RobotResult of the last task
-```
-
-### Memory
-
-```ruby
-memory = RobotLab.create_memory(data: { user_id: "123" })
-memory.set(:category, "billing")
-memory.get(:category)  # => "billing"
-```
-
-### Tool
-
-```ruby
-tool = RobotLab::Tool.create(
-  name: "get_time",
-  description: "Get current time"
-) { |**_| Time.now.to_s }
-```