robot_lab 0.2.7 → 0.3.0

data/docs/api/skills.md

@@ -1,8 +1,12 @@
 # Skills API
 
 Class-level reference for the AgentSkills subsystem: skill bundles, the scripts
-they expose as tools, the capabilities those scripts declare, and the sandbox
-that confines them. For the how-to, see
+they expose as tools, and the capabilities those scripts declare. Core itself
+has **no sandboxing and no execution limitations** — every script runs
+unconfined until the optional
+[`robot_lab-sandbox`](https://github.com/MadBomber/robot_lab-sandbox) gem is
+required, at which point it installs a confinement strategy (see
+[ScriptTool.executor](#scripttoolexecutor) below). For the how-to, see
 [Using Tools: Skill Scripts and Sandboxing](../guides/using-tools.md#skill-scripts-and-sandboxing)
 and [Building Robots: Composable Skills](../guides/building-robots.md#composable-skills).
 
@@ -27,12 +31,16 @@ graph LR
         G[effective grant<br/>declared ∩ ceiling]
     end
 
-    subgraph "Execution"
+    subgraph "Execution (core)"
         T[ScriptTool.from_path<br/>-> RobotLab::Tool]
+        EX{ScriptTool.executor<br/>set?}
+        UN[Open3.capture2e<br/>unconfined, no timeout]
+    end
+
+    subgraph "robot_lab-sandbox (optional gem)"
         SB{Sandbox.enabled?}
         SE[Sandbox::Seatbelt<br/>macOS]
         NU[Sandbox::Null<br/>passthrough]
-        P[script process]
     end
 
     R[Robot<br/>AgentSkillMatching] --> C
@@ -41,12 +49,12 @@ graph LR
     S --> T
     D --> G
     CE --> G
-    T --> SB
+    T --> EX
+    EX -- "nil (default)" --> UN
+    EX -- "installed" --> SB
     SB -- "off, or trust: core,<br/>or non-macOS" --> NU
     SB -- "on + macOS" --> SE
     G --> SE
-    SE --> P
-    NU --> P
 ```
 
 ---
@@ -264,9 +272,9 @@ of the ceiling, and `intersect` keeps the declared value.
 capabilities.core?  # => trust == "core"
 ```
 
-A `core` skill is exempt from confinement: `Sandbox.for` returns a
-[`Null`](#robotlabsandboxnull) strategy for it regardless of platform or config.
-Reserve `trust: core` for bundles you wrote and audited.
+A `core` skill is exempt from confinement: when `robot_lab-sandbox` is loaded,
+`Sandbox.for` returns a `Null` strategy for it regardless of platform or
+config. Reserve `trust: core` for bundles you wrote and audited.
 
 ### intersect
 
@@ -314,43 +322,32 @@ The generated tool takes a single optional `args` string parameter, which is
 [`derive_name`](#scripttoolderive_name) and its description from
 [`extract_description`](#scripttoolextract_description).
 
-### ScriptTool.execute
+### ScriptTool.executor
 
 ```ruby
-RobotLab::ScriptTool.execute(cmd, capabilities:, skill_dir:)  # => String
+RobotLab::ScriptTool.executor          # => #call, or nil (the default)
+RobotLab::ScriptTool.executor = obj    # any object responding to
+                                        # call(cmd, capabilities:, skill_dir:)
 ```
 
-Run a command array and return its combined stdout+stderr, or an error string.
-Two paths:
-
-- **Sandboxing off** (the default) — `Open3.capture2e`, unconfined, **no timeout**.
-- **Sandboxing on** — intersects `capabilities` with `Capabilities.ceiling`, wraps
-  the command with the strategy from `Sandbox.for`, runs it under the grant's
-  timeout, and cleans the strategy up in an `ensure`.
-
-The declared `timeout:` therefore only takes effect when sandboxing is enabled.
+The extension point core exposes for confinement. `nil` by default — core has
+no sandboxing of its own. `robot_lab-sandbox`, when required, sets this to
+`RobotLab::Sandbox::Executor`, which handles `capabilities`/timeout/cleanup
+itself. See that gem's docs for what it does when installed.
 
-### ScriptTool.run_with_timeout
+### ScriptTool.execute
 
 ```ruby
-RobotLab::ScriptTool.run_with_timeout(cmd, timeout)
-# => [String, Process::Status | nil]
+RobotLab::ScriptTool.execute(cmd, capabilities:, skill_dir:)  # => String
 ```
 
-Run `cmd` in its own process group (`pgroup: true`), reading combined output
-until `timeout` seconds elapse. On expiry it terminates the group and returns
-`["<partial output>\n[killed: exceeded <N>s]", nil]` — a `nil` status is the
-timeout signal.
-
-### ScriptTool.terminate
-
-```ruby
-RobotLab::ScriptTool.terminate(pid)
-```
+Run a command array and return its combined stdout+stderr, or an error string.
+Two paths:
 
-`Process.kill('-TERM', ...)` against the process **group** of `pid`, so a script
-that spawned children takes them down with it. Swallows every error and returns
-`nil` — a process that already exited is not an error.
+- **`executor` is `nil`** (the default) — `Open3.capture2e`, unconfined, **no timeout**.
+- **`executor` is set** — delegates entirely to `executor.call(cmd, capabilities:, skill_dir:)`.
+  Core no longer knows or cares what the executor does with `capabilities` or
+  how (or whether) it bounds execution time.
 
 ### ScriptTool.format_result
 
@@ -393,121 +390,27 @@ cannot be read.
 
 ---
 
-## RobotLab::Sandbox
+## Confinement: robot_lab-sandbox
 
-Strategy selector for confining skill-script execution. Module functions.
-
-### Sandbox.enabled?
-
-```ruby
-RobotLab::Sandbox.enabled?              # => Boolean
-RobotLab::Sandbox.enabled?(some_config)
-```
-
-`true` only when the config responds to `sandbox`, that section exists, and
-`sandbox.enabled == true`. **Sandboxing is off by default** — see the
-[`sandbox:` config section](../getting-started/configuration.md#skill-script-sandboxing-sandbox-section).
-
-### Sandbox.macos?
-
-```ruby
-RobotLab::Sandbox.macos?  # => RUBY_PLATFORM.include?("darwin")
-```
-
-### Sandbox.for
-
-```ruby
-strategy = RobotLab::Sandbox.for(grant, skill_dir:, macos: macos?)
-# => Sandbox::Seatbelt or Sandbox::Null
-```
-
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `grant` | `Capabilities` | **required** | The **already-intersected** effective grant |
-| `skill_dir` | `String` | **required** | Bundle root, always granted read access |
-| `macos` | `Boolean` | `macos?` | Injectable so both branches are testable on any host |
+`RobotLab::Sandbox`, `RobotLab::Sandbox::Seatbelt`, and `RobotLab::Sandbox::Null`
+used to live here; they now ship in the separate
+[`robot_lab-sandbox`](https://github.com/MadBomber/robot_lab-sandbox) gem, which
+core has no dependency on. Requiring it installs `RobotLab::Sandbox::Executor`
+as [`ScriptTool.executor`](#scripttoolexecutor):
 
-Selection order: a `trust: core` grant gets `Null`; otherwise macOS gets
-`Seatbelt`; anything else warns once and gets `Null`.
-
-### Sandbox.warn_once_non_macos
-
-```ruby
-RobotLab::Sandbox.warn_once_non_macos
-```
-
-Emits `"Sandbox: OS-level confinement is only available on macOS; scripts run
-unconfined here"` at `warn`, at most once per process. Idempotent, so a run with
-many scripts does not flood the log.
-
----
-
-## RobotLab::Sandbox::Null
-
-Passthrough strategy — used off macOS and for `trust: core` skills.
-
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `wrap(cmd)` | `cmd` | Unchanged |
-| `cleanup` | `nil` | No-op |
-
----
-
-## RobotLab::Sandbox::Seatbelt
-
-macOS strategy: generates a deny-by-default `sandbox-exec` profile from the grant
-and wraps the command as `sandbox-exec -f <profile> <cmd...>`.
-
-### Constants
-
-| Constant | Description |
-|----------|-------------|
-| `SYSTEM_READ` | `/usr /bin /sbin /System /Library /opt /private/etc /dev /var/select` — the locations an interpreter needs to boot |
-| `DEV_WRITE` | `/dev/null /dev/stdout /dev/stderr /dev/dtracehelper /dev/tty` — always writable |
-
-### Constructor
-
-```ruby
-RobotLab::Sandbox::Seatbelt.new(grant, skill_dir:)
-```
-
-### wrap / cleanup
-
-```ruby
-cmd = strategy.wrap(["bash", "script.sh"])
-# => ["sandbox-exec", "-f", "/tmp/robot_lab-sandbox-xxxx.sb", "bash", "script.sh"]
-strategy.cleanup  # unlinks the generated profile
-```
-
-`wrap` writes the profile to a `Tempfile`; `cleanup` unlinks it and swallows any
-error (an already-removed file is fine). `ScriptTool.execute` always calls
-`cleanup` in an `ensure`.
-
-### profile_text
-
-```ruby
-strategy.profile_text  # => String
-```
+- `Sandbox.enabled?` — reads `config.sandbox.enabled` (default `false`).
+- `Sandbox.for(grant, skill_dir:, macos: macos?)` — picks `Sandbox::Seatbelt` on
+  macOS, `Sandbox::Null` (passthrough) elsewhere or for `trust: core` grants.
+- `Sandbox::Seatbelt` — generates a deny-by-default `sandbox-exec` profile from
+  the effective grant (`fs_read`/`fs_write`/`network`), wrapping the command as
+  `sandbox-exec -f <profile> <cmd...>`. `$HOME` is never implicitly readable.
+- `Sandbox::Null` — `wrap(cmd)` returns `cmd` unchanged; `cleanup` is a no-op.
+- `Sandbox::Executor` — the piece that plugs into core: intersects the skill's
+  `Capabilities` with `Capabilities.ceiling`, wraps and runs the command under
+  the chosen strategy, and bounds it with the grant's `timeout`
+  (`Process.kill('-TERM', ...)` on the process group on expiry).
 
-The generated Seatbelt profile. Public so the policy can be asserted in tests
-rather than inferred from behavior. It imports `bsd.sb` (without which a
-deny-default profile aborts the binary before it starts), denies by default, then
-allows: `process-fork`, `process-exec`, `sysctl-read`, `mach-lookup`,
-`file-read-metadata` on any path, `file-read*` on `SYSTEM_READ` + the skill
-directory + granted `fs_read` paths, `file-write*` on `DEV_WRITE` + granted
-`fs_write` paths, and `network*` only when the grant allows it.
-
-Every path is canonicalized to its symlink-free real path first, because macOS
-symlinks `/tmp` → `/private/tmp` and the kernel matches against the real path. For
-write targets that do not exist yet, the nearest existing ancestor is resolved and
-the remainder re-appended.
-
-!!! warning "`$HOME` is never implicitly readable"
-    Which is the point — SSH keys and cloud credentials stay out of reach. But it
-    also means an interpreter installed under `$HOME` (rbenv, asdf, mise, a
-    Homebrew prefix in `~`) is **invisible** to the sandboxed process and the
-    script fails to start. Grant that path explicitly in `fs_read`, or mark the
-    skill `trust: core`.
+Full reference lives in that gem's own docs.
 
 ---
 
@@ -515,5 +418,6 @@ the remainder re-appended.
 
 - [Using Tools: Skill Scripts and Sandboxing](../guides/using-tools.md#skill-scripts-and-sandboxing)
 - [Configuration: `sandbox:` section](../getting-started/configuration.md#skill-script-sandboxing-sandbox-section)
+- [robot_lab-sandbox](https://github.com/MadBomber/robot_lab-sandbox) — the optional confinement gem
 - [Robot: Skills](core/robot.md#skills) — template skills, the other meaning
 - [Tool](core/tool.md) — `Tool.create`, which `ScriptTool` builds on

data/docs/api/support.md

@@ -842,5 +842,5 @@ Thread-safe monotonic counter for event ordering.
 
 - [Core Classes](core/index.md) — `Robot`, `Network`, `Memory`, `Tool`, `RobotResult`
 - [Hooks API](hooks.md) — the extension seam these classes are wired into
-- [Skills API](skills.md) — `AgentSkill`, `Capabilities`, `ScriptTool`, `Sandbox`
+- [Skills API](skills.md) — `AgentSkill`, `Capabilities`, `ScriptTool` (confinement lives in the optional `robot_lab-sandbox` gem)
 - [Errors](errors.md) — including `Errors.retryable?` and `Errors.retryable_classes`

data/docs/architecture/core-concepts.md

@@ -226,7 +226,7 @@ end
 | `:results` | `Array` | Accumulated robot results |
 | `:messages` | `Array` | Conversation history |
 | `:session_id` | `String` | Session identifier |
-| `:cache` | `Module` | Semantic cache (RubyLLM::SemanticCache) |
+| `:cache` | `Module`, `nil` | Semantic cache (RubyLLM::SemanticCache when the optional gem is installed) |
 
 ### Reactive Features
 

data/docs/architecture/index.md

@@ -62,7 +62,7 @@ graph TB
         H[MCP Client]
         I[Tools < RubyLLM::Tool]
         J[Templates / prompt_manager]
-        SK[AgentSkills + Sandbox]
+        SK[AgentSkills<br/>+ optional Sandbox]
     end
 
     subgraph "Execution Layer"
@@ -138,8 +138,9 @@ graph LR
     AS --> CAT[AgentSkillCatalog]
     AS --> CAP[Capabilities]
     AS --> ST[ScriptTool]
-    CAP --> SB[Sandbox<br/>Seatbelt or Null]
-    ST --> SB
+    ST --> EX{ScriptTool.executor}
+    EX -. "installed by<br/>robot_lab-sandbox" .-> SB[Sandbox<br/>Seatbelt or Null]
+    CAP -. "used if installed" .-> SB
 
     HC --> TA[TextAnalysis<br/>TF / TF-IDF]
     HS --> TA
@@ -165,7 +166,7 @@ dependency.
 | **Config** | MywayConfig-based global configuration with env var and file support | [Configuration](#configuration) |
 | **Hook** | Handler base class for the seven hook families — the framework's extension seam | [Hooks API](../api/hooks.md) |
 | **AgentSkill** | A `SKILL.md` bundle whose instructions and `scripts/` become prompt text and tools | [Skills API](../api/skills.md) |
-| **Sandbox** | Opt-in OS-level confinement (macOS Seatbelt) for skill scripts, derived from `Capabilities` | [Skills API](../api/skills.md) |
+| **Sandbox** | Opt-in OS-level confinement (macOS Seatbelt) for skill scripts, derived from `Capabilities`; ships in the optional `robot_lab-sandbox` gem, not core | [Skills API](../api/skills.md) |
 | **RobotMessage** | Immutable envelope for TypedBus inter-robot messaging, serialized per robot by `BusPoller` | [Support API](../api/support.md) |
 | **Budget::Ledger** | Thread-safe reserve/reconcile ledger behind `token_budget` / `cost_budget` | [Support API](../api/support.md) |
 

data/docs/architecture/state-management.md

@@ -13,7 +13,7 @@ memory.data        # StateProxy - custom key-value data with method-style access
 memory.results     # Array<RobotResult> - execution history
 memory.messages    # Array<Message> - conversation history
 memory.session_id  # String - optional persistence identifier
-memory.cache       # RubyLLM::SemanticCache - semantic caching module
+memory.cache       # RubyLLM::SemanticCache when the optional gem is installed, else nil
 ```
 
 ## Standalone Robot Memory
@@ -108,7 +108,7 @@ Memory has five reserved keys with special behavior and dedicated accessors:
 | `:results` | `Array<RobotResult>` | Accumulated robot execution results |
 | `:messages` | `Array<Message>` | Conversation history |
 | `:session_id` | `String` | Conversation session identifier |
-| `:cache` | `RubyLLM::SemanticCache` | Semantic cache module (read-only after init) |
+| `:cache` | `RubyLLM::SemanticCache` or `nil` | Semantic cache module when the optional ruby_llm-semantic_cache gem is installed (read-only after init) |
 
 Reserved keys are accessed through dedicated methods and are excluded from `memory.keys`:
 
@@ -118,7 +118,7 @@ memory.data.category  #=> "billing"   (method-style via StateProxy)
 
 memory.results       #=> []
 memory.session_id    #=> nil
-memory.cache         #=> RubyLLM::SemanticCache (the module itself), or nil when enable_cache: false
+memory.cache         #=> RubyLLM::SemanticCache (the module itself), or nil when enable_cache: false or the optional gem is absent
 ```
 
 ## StateProxy
@@ -319,7 +319,7 @@ memory = Memory.from_hash(hash)
 
 ## Semantic Cache
 
-Memory includes a semantic cache via `RubyLLM::SemanticCache` that reduces costs and latency by returning cached responses for semantically equivalent queries:
+Memory includes a semantic cache via `RubyLLM::SemanticCache` (optional ruby_llm-semantic_cache gem; not yet ruby_llm 2.0-compatible, so `memory.cache` is `nil` without it) that reduces costs and latency by returning cached responses for semantically equivalent queries:
 
 ```ruby
 # Using the cache with fetch

data/docs/concepts.md

@@ -338,7 +338,7 @@ robot.clear_messages(keep_system: true)
 | `:results` | Accumulated robot results |
 | `:messages` | Conversation history |
 | `:session_id` | Session identifier for history persistence |
-| `:cache` | Semantic cache instance (RubyLLM::SemanticCache) |
+| `:cache` | Semantic cache (RubyLLM::SemanticCache when the optional gem is installed, else nil) |
 
 ### Reactive Memory in Networks
 

data/docs/getting-started/configuration.md

@@ -278,7 +278,10 @@ robot = RobotLab.build(
 
 ### 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:
+Core declares this config schema but has no sandboxing behavior of its own — enforcement
+lives in the optional [`robot_lab-sandbox`](https://github.com/MadBomber/robot_lab-sandbox)
+gem. Without it, skill scripts always run unconfined regardless of these values; requiring
+it installs a `RobotLab::ScriptTool.executor` that honors them:
 
 | Key | Default | Description |
 |-----|---------|-------------|

data/docs/getting-started/installation.md

@@ -35,13 +35,10 @@ RobotLab automatically installs these core dependencies:
 
 | Gem | Purpose |
 |-----|---------|
-| `ruby_llm` (~> 1.12) | LLM provider integrations (Anthropic, OpenAI, Gemini, etc.) |
+| `ruby_llm` (~> 2.0.0.rc3) | LLM provider integrations (Anthropic, OpenAI, Gemini, etc.) |
 | `prompt_manager` (~> 1.0) | Template-based prompt management with YAML front matter |
 | `simple_flow` (~> 0.4) | Pipeline workflow execution for networks |
 | `myway_config` (~> 0.1) | Layered configuration (defaults, env vars, config files) |
-| `ruby_llm-mcp` (~> 1.0) | Model Context Protocol client for external tool servers |
-| `ruby_llm-schema` (~> 0.3) | Schema validation for structured outputs |
-| `ruby_llm-semantic_cache` (~> 0.1) | Semantic caching for LLM responses |
 | `zeitwerk` (~> 2.6) | Autoloading and eager loading |
 | `async` (~> 2.0) | Fiber-based concurrency |
 | `async-http` (~> 0.60) | MCP SSE and streamable-HTTP transports |

data/docs/guides/hooks.md

@@ -1076,6 +1076,128 @@ RobotLab.on(RedactionHook)
 
 ---
 
+## Extension Registration
+
+Hooks inject *behavior* ("do this on these events"). A separate, lighter
+mechanism — **extension registration** — answers a different question: *"is
+optional feature X loaded?"* This is how core lights up conditional behavior
+without depending on, or probing for, the gem that provides it. The two
+mechanisms are orthogonal but commonly used together: a gem registers itself
+(discovery), then wires behavior in via a hook (injection).
+
+### The API
+
+```ruby
+RobotLab.register_extension(:audit, RobotLab::Audit)  # gem announces itself
+RobotLab.extension_loaded?(:audit)                     # => true/false — core's guard
+RobotLab.extension(:audit)                             # => RobotLab::Audit
+RobotLab.loaded_extensions                             # => [:audit, :ractor, ...]
+```
+
+It is deliberately tiny: a `Hash` and four methods. The registered value can be
+the extension's primary module, or just a sentinel when the gem only needs a
+presence flag:
+
+```ruby
+RobotLab.register_extension(:ractor, :ractor_extension_loaded)
+```
+
+### How an Extension Announces Itself
+
+At the bottom of the gem's entry file, after everything it provides is
+defined, guarded so the gem can also load standalone or against an older core:
+
+```ruby
+# robot_lab-audit/lib/robot_lab/audit.rb (tail)
+if defined?(RobotLab) && RobotLab.respond_to?(:register_extension)
+  RobotLab.register_extension(:audit, RobotLab::Audit)
+end
+```
+
+The same one-liner appears verbatim in `robot_lab-document_store`,
+`robot_lab-durable`, `robot_lab-discovery`, etc. Registration last, guarded
+always.
+
+### How Core Consumes It
+
+Core guards optional behavior with `extension_loaded?` instead of scattered
+`defined?` / `respond_to?` probes — one named question, asked in one style:
+
+```ruby
+# tool.rb — only use the Ractor pool when the gem is present
+self.class.ractor_safe? && !self.class.name.nil? && RobotLab.extension_loaded?(:ractor)
+
+# memory.rb — semantic features require the document_store gem
+unless RobotLab.extension_loaded?(:document_store)
+  …
+end
+```
+
+When a guarded feature is *requested* without its extension, core raises a
+helpful error naming the exact gem to add — not a cryptic `NoMethodError`:
+
+```ruby
+# network.rb — parallel_mode: :ractor needs the gem
+def run_with_ractor_scheduler(run_context)
+  unless RobotLab.extension_loaded?(:ractor)
+    raise RobotLab::DependencyError,
+          "parallel_mode: :ractor requires the robot_lab-ractor gem. " \
+          "Add `gem 'robot_lab-ractor'` to your Gemfile."
+  end
+  …
+end
+```
+
+### Version-Skew Tolerance
+
+`robot_lab-a2a` ships a fallback so it works even against a core too old to
+provide the registry API: if `register_extension` isn't defined, the gem
+**defines it** (plus `extension_loaded?`/`extension`) over its own private
+`@_extensions` hash, then registers itself:
+
+```ruby
+module RobotLab
+  @_extensions = {} unless instance_variable_defined?(:@_extensions)
+
+  class << self
+    unless method_defined?(:register_extension) || respond_to?(:register_extension)
+      def register_extension(name, mod) = @_extensions[name.to_sym] = mod
+    end
+    unless method_defined?(:extension_loaded?) || respond_to?(:extension_loaded?)
+      def extension_loaded?(name) = @_extensions.key?(name.to_sym)
+    end
+    # … extension(name) likewise …
+  end
+end
+
+RobotLab.register_extension(:a2a, RobotLab::A2A)
+```
+
+The gem never assumes the core's age; it provides the contract if it must.
+
+### How It Composes with Hooks
+
+- `register_extension(:audit, RobotLab::Audit)` — *"I exist"* (discovery).
+- Inside `Audit.enable(db_path:)` → `RobotLab.on(Hook)` — *"do this on these
+  events"* (behavior).
+
+Two common shapes:
+
+- **Auto-wire at load** — register the extension *and* `RobotLab.on(SomeHook)`
+  at require time (always-on features).
+- **Opt-in enable** — register the extension at load, but expose
+  `enable!`/`enable(...)` that registers the hook on demand
+  (`Audit.enable`, `Narrator.enable!`). Lets the user choose scope/config.
+
+> [!TIP]
+> Design decisions worth stealing: a named capability registry beats
+> duck-typing; core never `require`s an extension — the extension `require`s
+> core and announces itself; a sentinel value works when you only need a
+> presence flag; and using a guarded feature without its gem should raise a
+> helpful error naming the exact gem to add.
+
+---
+
 ## See Also
 
 - [examples/35_hooks.rb](https://github.com/MadBomber/robot_lab/blob/main/examples/35_hooks.rb) — full demo with xyzzy extension, perf timer, LLM response cache, and tracer hooks

data/docs/guides/memory.md

@@ -10,7 +10,7 @@ Memory is a reactive key-value store that provides:
 - Reserved keys for structured data (`:data`, `:results`, `:messages`, `:session_id`, `:cache`)
 - Reactive subscriptions and blocking reads for inter-robot communication
 - Optional Redis backend for persistence
-- Semantic caching via `RubyLLM::SemanticCache`
+- Semantic caching via `RubyLLM::SemanticCache` (optional ruby_llm-semantic_cache gem)
 
 ## Standalone Robot Memory
 
@@ -86,7 +86,7 @@ Memory has reserved keys with special behavior:
 | `:results` | Array | Accumulated robot results |
 | `:messages` | Array | Conversation history |
 | `:session_id` | String | Session identifier for history persistence |
-| `:cache` | `RubyLLM::SemanticCache` module, or `nil` | Semantic cache (read-only after init). Set at construction time; `nil` when built with `enable_cache: false` |
+| `:cache` | `RubyLLM::SemanticCache` module, or `nil` | Semantic cache (read-only after init). Set at construction time; `nil` when built with `enable_cache: false` or when the optional gem is absent |
 
 ### The Data Hash
 

data/docs/guides/using-tools.md

@@ -335,13 +335,22 @@ trust: external   # or "core" for trusted, always-unconfined skills
 ---
 ```
 
-Sandboxing itself is **opt-in and off by default** — see the [`sandbox:` config section](../getting-started/configuration.md#skill-script-sandboxing-sandbox-section). When disabled, scripts run exactly as they always have, unconfined. When enabled:
+`Capabilities` (the declaration above) lives in core, but core itself has **no sandboxing
+behavior and no built-in limitations** — a script always runs unconfined via a plain
+`Open3.capture2e`, with no timeout, unless the optional
+[`robot_lab-sandbox`](https://github.com/MadBomber/robot_lab-sandbox) gem is required.
+Requiring it installs `RobotLab::Sandbox::Executor` as `RobotLab::ScriptTool.executor`;
+confinement still stays **opt-in and off by default** from there — see the
+[`sandbox:` config section](../getting-started/configuration.md#skill-script-sandboxing-sandbox-section).
+When enabled:
 
 - The global `sandbox:` config is a **ceiling** (`fs_read`, `fs_write`, `network`, `timeout`); each skill's front matter is its **declared** request. The script actually runs under the **intersection** of the two — a path outside the ceiling's roots is dropped even if the skill declares it, `network` requires both sides to allow it, and `timeout` is the smaller of the two.
 - On macOS, confinement is enforced with a generated `sandbox-exec` (Seatbelt) profile: deny-by-default, with narrow allowances for the interpreter to boot, the granted read/write paths, and (optionally) the network. Notably, `$HOME` is never implicitly readable — SSH keys and cloud credentials stay out of reach unless a path under `$HOME` is explicitly granted.
 - Off macOS, or for any skill declaring `trust: core`, sandboxing is a passthrough — confinement is currently macOS-only and is always skipped for trusted "core" skills regardless of platform.
 - A script that runs past its `timeout` is killed (its whole process group) and reported back to the LLM as a timed-out error rather than hanging the turn.
 
+Full API reference: [robot_lab-sandbox](https://github.com/MadBomber/robot_lab-sandbox).
+
 ## Parameter Types
 
 Define parameters on `RubyLLM::Tool` subclasses using `param`:

data/examples/.envrc

@@ -1 +1,3 @@
+source_up
+
 export ROBOT_LAB_TEMPLATE_PATH="${PWD}/prompts"

data/examples/02_tools.rb

@@ -14,17 +14,17 @@ require_relative "common"
 class Calculator < RubyLLM::Tool
   description "Performs basic arithmetic operations"
 
-  param :operation,
+  parameter :operation,
         type: "string",
-        desc: "The operation to perform (add, subtract, multiply, divide)"
+        description: "The operation to perform (add, subtract, multiply, divide)"
 
-  param :a,
+  parameter :a,
         type: "number",
-        desc: "First operand"
+        description: "First operand"
 
-  param :b,
+  parameter :b,
         type: "number",
-        desc: "Second operand"
+        description: "Second operand"
 
   def execute(operation:, a:, b:)
     case operation
@@ -40,9 +40,9 @@ end
 class FortuneCookie < RubyLLM::Tool
   description "Get a fortune cookie message with wisdom and lucky numbers"
 
-  param :category,
+  parameter :category,
         type: "string",
-        desc: "The category of fortune (wisdom, love, career, adventure)"
+        description: "The category of fortune (wisdom, love, career, adventure)"
 
   FORTUNES = {
     "wisdom" => [

data/examples/03_network.rb

@@ -40,7 +40,7 @@ end
 
 # Shared RunConfig — operational defaults every robot in this network inherits.
 #
-# RunConfig has no `provider` field (see RunConfig::FIELDS), and an Ollama
+# RunConfig has no `provider` field (see RunConfig::FIELDS), and an LM Studio
 # model is absent from RubyLLM's registry, so provider and model still travel
 # together on each robot via **llm_opts. The RunConfig carries the settings
 # that genuinely are shared.

data/examples/04_mcp.rb

@@ -163,14 +163,16 @@ begin
   puts "Query: 'What are the top 3 most starred Ruby web frameworks on GitHub?'"
   hr
 
-  # mcp: :inherit and tools: :inherit are both required. Both keywords default
-  # to :none on run(), which resolves to "no MCP servers this turn" and "send
-  # zero tools this turn" — the discovered MCP tools would never reach the
-  # provider and the model would answer from its training data.
+  # mcp: :inherit is required — run() defaults it to :none, which resolves to
+  # "no MCP servers this turn" and the discovered tools would never reach the
+  # provider. tools: takes an allowlist of tool names; :inherit would send all
+  # ~90 GitHub tools, whose JSON schemas alone exceed 13k tokens and overflow
+  # a local model's context window (LM Studio's default is 8192) before the
+  # query even arrives. Send only the one tool this query needs.
   result = robot.run(
     "What are the top 3 most starred Ruby web frameworks on GitHub? Just list their names and star counts.",
     mcp:   :inherit,
-    tools: :inherit
+    tools: %w[search_repositories]
   )
 
   puts