robot_lab-to 0.2.7 → 0.2.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a600189accdf098fb2cea44bec912fbc3399b89d48b7775d1237a78fd5bac7fd
-  data.tar.gz: 8729282eb38252b3e2227b02cc9b48dc76b04005572ede0d24fccdbab1b47940
+  metadata.gz: 43c5ef1239f3c91dcf0b033466a2a346f3dafb385897d1e5696e2952a752a49d
+  data.tar.gz: 29fb0fda8e3fbd13f079a3244c577c69e53fcb4e1c8dbdc5066b32c059bd7f67
 SHA512:
-  metadata.gz: 58a538bc23b7a68822dae324d6b179f0eba4ea4f8b79bfb489ea6cfcaedd59e82c592197ca67c11873404d52c78bae8a74f26b53b05e061c5753d43ad15c3f68
-  data.tar.gz: bc1e417731a76c43f5671ff3fcfaec038a59884d9ac62a63c1cb2bbb53c8fade6f051560da30db2d1c517645cc2f448100b1e551fd458ea040bf738447edd145
+  metadata.gz: 7af7eca43dac57ae02b21b24b9ad8b7a813e473b5470372ee5048980948d0bb431e6b164d88f532394da9cd946d7ed75cafe2746efac41f79dc2cc1c0a1aaad6
+  data.tar.gz: beb2270499d125d74f2a3333610c44b9cd030f8ee9142bf4b2b3e87b1f0e410b9f768ffdb83c7187e80e0d1d593ce77ebbf5f89cdee9b5d640432d788b429733

data/.envrc

@@ -1 +1,7 @@
+# robot_lab_project/robot_lab-to/.envrc
+
+source_up
+
 export RR=$(pwd)
+
+export BUNDLE_GEMFILE=Gemfile

data/Archspec.rb

@@ -0,0 +1,34 @@
+# robot_lab-to is a plain Ruby gem (RobotLab::To), not a Rails app -- there is
+# no app/ tree, no controllers/models/views, so the :rails preset doesn't
+# apply. These are the actual boundaries documented in CLAUDE.md.
+
+# Matched by exact constant, not a file glob: every file here reopens the
+# bare `module RobotLab` namespace (shared with the external robot_lab gem's
+# own top-level module), so an `in:` glob would misattribute any bare
+# `RobotLab.xxx` call anywhere in the gem to this component.
+component :orchestrator, constants: "RobotLab::To::Orchestrator"
+component :tools, in: "lib/robot_lab/to/tools/**/*.rb"
+component :guards, in: %w[lib/robot_lab/to/guards.rb lib/robot_lab/to/guards/**/*.rb]
+component :evals, in: "lib/robot_lab/to/evals/**/*.rb"
+component :commit_manager, in: "lib/robot_lab/to/commit_manager.rb"
+
+# Tools are RobotLab::Tool subclasses the robot calls mid-turn (see
+# lib/robot_lab/to/tools/file_tool.rb); Guards are RobotLab::Hook subclasses
+# wired onto a robot by Orchestrator#build_robot; Evals are "orchestrator-owned
+# scorers" per CLAUDE.md. All three are built and consumed by the orchestrator
+# -- the dependency runs one way, never back into the loop that drives them.
+tools.cannot_use :orchestrator,
+                 because: "tools run inside an LLM turn, invoked by the robot -- " \
+                          "they must not reach back into the loop that drives them"
+guards.cannot_use :orchestrator,
+                  because: "guards are wired onto a robot by Orchestrator#build_robot -- " \
+                           "the dependency runs one way"
+evals.cannot_use :orchestrator,
+                 because: "evals are orchestrator-owned scorers (CLAUDE.md) -- " \
+                          "Orchestrator calls Evals.build, not the reverse"
+
+# CLAUDE.md: "CommitManager -- all git ops via Open3.capture3 (no shell
+# interpolation)". Enforce the "no shell interpolation" half architecturally.
+commit_manager.cannot_call :system, receiver: :none,
+                           because: "git ops must go through Open3.capture3 with an argv array, " \
+                                    "never system()/backticks with an interpolated string"

data/CHANGELOG.md

@@ -8,6 +8,10 @@ and [Conventional Commits](https://www.conventionalcommits.org/) (see `COMMITS.m
 
 ## [Unreleased]
 
+## [0.2.8] - 2026-09-09
+
+Released in lockstep with `robot_lab` core v0.2.8: this gem now resolves the released core gem from RubyGems instead of the local sibling checkout (local-path development remains available via `BUNDLE_GEMFILE=Gemfile.local`). Also in this release: reek pass completed, archspec added to the development bundle, and shared LM Studio example configuration extracted for the examples.
+
 ### Added
 
 - **Human-in-the-loop decision files.** When the robot hits a choice it must not

data/CLAUDE.md

@@ -11,7 +11,8 @@ autonomous loop toward a stated objective, committing one focused change per ite
 bundle install
 bundle exec rake test          # all tests
 bundle exec rake test_verbose  # verbose
-bundle exec rake quality       # tests + rubocop + flog
+asgard quality                 # all *_check gates in parallel (tests + coverage,
+                               #   rubocop, flog, flay, reek, fasterer, typos, ...)
 bin/console                    # IRB shell
 ```
 
@@ -71,4 +72,4 @@ All run state lives in `.robot_lab_to/runs/<run_id>/` (added to `.git/info/exclu
 ## Testing
 
 Minitest. Git-dependent tests use `Dir.mktmpdir` with real `git init`.
-Coverage gate: 95% line / 75% branch (`rake quality` also runs rubocop + flog + flay).
+Coverage gate: 95% line / 75% branch (`asgard quality` also runs rubocop + flog + flay + reek + more).

data/Rakefile

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
-require 'bundler/gem_tasks'
+# Quality gates (quality, rubocop_check, flog_check, flay_check, ...),
+# documentation tasks (doc_builder, doc_server), and the gem lifecycle
+# (build, install, release) live in asgard — see .loki and the shared
+# dev/*.loki files it imports. This Rakefile keeps only the task asgard
+# itself delegates to: the test suite.
+
 require 'rake/testtask'
 
 Rake::TestTask.new(:test) do |t|
@@ -23,110 +28,3 @@ desc 'Run a single test file'
 task :test_file, [:file] do |_t, args|
   ruby "test/#{args[:file]}"
 end
-
-desc 'Check code complexity with Flog (warn >=20, fail >=50)'
-task :flog_check do
-  require 'flog'
-
-  method_warn = 20.0
-  method_fail = 50.0
-
-  flogger = Flog.new(all: true)
-  flogger.flog(*Dir.glob('lib/**/*.rb'))
-
-  warnings = []
-  failures = []
-
-  flogger.each_by_score do |method, score|
-    next if method.end_with?('#none')
-
-    if score > method_fail
-      failures << "#{format('%.1f', score)}: #{method}"
-    elsif score > method_warn
-      warnings << "#{format('%.1f', score)}: #{method}"
-    end
-  end
-
-  unless warnings.empty?
-    puts "\nFlog warnings (#{method_warn}–#{method_fail}) — target for future refactoring:"
-    warnings.each { |v| puts "  #{v}" }
-  end
-
-  if failures.empty?
-    puts "\nFlog: no methods exceed the failure threshold (>=#{method_fail})"
-  else
-    puts "\nFlog failures (>=#{method_fail}) — must be refactored:"
-    failures.each { |v| puts "  #{v}" }
-    abort "\nFlog quality gate failed: #{failures.size} method(s) exceed #{method_fail}"
-  end
-end
-
-desc 'Check for structural code duplication with Flay (mass >= 50)'
-task :flay_check do
-  require 'flay'
-
-  mass_threshold = 50
-
-  flay = Flay.new({ mass: mass_threshold, diff: false, verbose: false, summary: false, timeout: 60 })
-  flay.process(*Dir.glob('lib/**/*.rb'))
-  flay.analyze
-
-  if flay.hashes.empty?
-    puts "\nFlay: no structural duplication detected (mass >= #{mass_threshold})"
-  else
-    puts "\nFlay found structural duplication (mass >= #{mass_threshold}):"
-    flay.report
-    abort "\nFlay quality gate failed: #{flay.hashes.length} pattern(s) detected"
-  end
-end
-
-desc 'Run all quality checks: tests (with coverage), RuboCop, Flog, and Flay'
-task :quality do
-  gates = [
-    ['Tests + Coverage', 'bundle exec rake test'],
-    ['RuboCop',          'bundle exec rubocop'],
-    ['Flog Complexity',  'bundle exec rake flog_check'],
-    ['Flay Duplication', 'bundle exec rake flay_check']
-  ]
-
-  results = gates.map do |label, command|
-    puts "\n#{'=' * 60}"
-    puts "Quality Gate: #{label}"
-    puts '=' * 60
-    [label, system(command) ? :pass : :fail]
-  end
-
-  green = ->(s) { "\e[32m#{s}\e[0m" }
-  red   = ->(s) { "\e[31m#{s}\e[0m" }
-  width = results.map { |label, _| label.length }.max
-
-  puts "\n#{'=' * 60}"
-  puts 'Quality Gate Summary'
-  puts '=' * 60
-  results.each do |label, status|
-    badge = status == :pass ? green.call('PASS') : red.call('FAIL')
-    puts "  [#{badge}] #{label.ljust(width)}"
-  end
-  puts '-' * 60
-
-  passed = results.count { |_, s| s == :pass }
-  failed = results.count { |_, s| s == :fail }
-  tally  = "#{passed} passed, #{failed} failed"
-  puts "  #{failed.zero? ? green.call(tally) : red.call(tally)}"
-  puts '=' * 60
-
-  abort "\n#{red.call('Quality gate failed.')}" unless failed.zero?
-  puts "\n#{green.call('All quality gates passed.')}"
-end
-
-namespace :docs do
-  desc 'Build MkDocs documentation'
-  task :build do
-    sh 'mkdocs build'
-  end
-
-  desc 'Serve MkDocs documentation locally on http://localhost:8000'
-  task :serve do
-    sh 'mkdocs serve'
-  end
-end

data/examples/.envrc

@@ -0,0 +1,8 @@
+# robot_lab-to/examples/.envrc
+
+source_up
+
+export LMS_BASE_URL=http://localhost:1234/v1
+
+export RLTO_PROVIDER=lms
+export RLTO_MODEL=qwen/qwen3.8-27b

data/examples/01_basic_usage/README.md

@@ -30,14 +30,13 @@ the `1..3999` range, round-trip correctness, case-insensitive parsing, and
 
 ## Prerequisites
 
-Either a **local Ollama** server (default, no API key) or a **cloud** provider key.
+Either **local LM Studio** (default, no API key) or a **cloud** provider key.
 
-=== "Local Ollama (default)"
+=== "Local LM Studio (default)"
 
-    ```bash
-    ollama serve &                # if not already running
-    ollama pull qwen3.6:latest    # a tool-capable model
-    ```
+    Nothing to start by hand -- `common.rb` (required by the script) starts the
+    LM Studio server and loads the model for you if they aren't already
+    running/loaded.
 
 === "Cloud provider"
 
@@ -50,7 +49,7 @@ Either a **local Ollama** server (default, no API key) or a **cloud** provider k
 From the gem root:
 
 ```bash
-# Local Ollama (default)
+# Local LM Studio (default)
 bundle exec ruby examples/01_basic_usage/basic_usage.rb
 
 # A cloud model instead
@@ -64,10 +63,10 @@ All optional, set via environment variables:
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `RLTO_LOCAL` | `true` | Use a local Ollama model. Set `false` for a cloud provider. |
-| `RLTO_PROVIDER` | `openai` (local) | LLM provider passed to `RobotLab::To.run`. |
-| `RLTO_MODEL` | `qwen3.6:latest` (local) | Model id. Any tool-capable model works. |
-| `OLLAMA_BASE` | `http://localhost:11434/v1` | Ollama's OpenAI-compatible endpoint. |
+| `RLTO_LOCAL` | `true` | Use a local LM Studio model. Set `false` for a cloud provider. |
+| `RLTO_PROVIDER` | `lms` (local) | Provider label. `lms` resolves to RubyLLM's `:openai` adapter pointed at `LMS_BASE_URL` -- ruby_llm has no native `lms` adapter. |
+| `RLTO_MODEL` | `qwen/qwen3.8-27b` (local) | Model id. Any tool-capable model works. |
+| `LMS_BASE_URL` | `http://localhost:1234/v1` | LM Studio's OpenAI-compatible endpoint. |
 
 ## What you'll see
 
@@ -77,7 +76,7 @@ live, so the run never sits silent while the model works:
 ```
 Cleaning leftover: .../examples/01_basic_usage/project
 Project dir:     examples/01_basic_usage/project
-Provider/model:  openai/qwen3.6:latest (local Ollama)
+Provider/model:  lms/qwen/qwen3.8-27b (local LM Studio)
 Objective:       implement lib/roman_numeral.rb to pass the test suite
 
       🤔 thinking…
@@ -157,10 +156,10 @@ The whole example is one call:
 ```ruby
 RobotLab::To.run(
   objective,
-  provider:       :openai,    # routes to Ollama for local runs
-  model:          "qwen3.6:latest",
+  provider:       :openai,    # "lms" (RLTO_PROVIDER's default) resolves to :openai, routed at LM Studio
+  model:          "qwen/qwen3.8-27b",
   local_guards:   true,       # built-in file tools + guardrails
-  stream:         false,      # Ollama tool calls need non-streaming
+  stream:         false,      # local LM Studio tool calls run non-streaming
   max_iterations: 6,
   verify_command: "ruby -Ilib -Itest test/roman_numeral_test.rb",
   stop_when:      "test/roman_numeral_test.rb passes with 0 failures and 0 errors"

data/examples/01_basic_usage/basic_usage.rb

@@ -2,7 +2,7 @@
 # frozen_string_literal: true
 #
 # Basic Usage would generally be as a CLI tool; however, its a library
-# so that means you can build it inot an application program.
+# so that means you can build it into an application program.
 #
 # ===========================================================================
 # 01_basic_usage — drive robot_lab-to programmatically
@@ -32,8 +32,8 @@
 # ---------------------------------------------------------------------------
 # Run it
 # ---------------------------------------------------------------------------
-#   # Local Ollama (default — no API key needed; requires `ollama serve`):
-#   ollama pull gpt-oss:20b
+#   # Local LM Studio (default — no API key needed; common.rb starts the server
+#   # and loads the model for you if they aren't already running/loaded):
 #   bundle exec ruby examples/01_basic_usage/basic_usage.rb
 #
 #   # A cloud model instead:
@@ -41,17 +41,15 @@
 #     ANTHROPIC_API_KEY=sk-... \
 #     bundle exec ruby examples/01_basic_usage/basic_usage.rb
 #
-# Configuration (all optional, via environment):
-#   RLTO_LOCAL     true|false   use a local Ollama model (default true)
-#   RLTO_PROVIDER  name         LLM provider (default: openai for local)
-#   RLTO_MODEL     id           model id (default: gpt-oss:20b for local)
-#   OLLAMA_BASE    url          Ollama OpenAI endpoint (default localhost:11434/v1)
+# Configuration (all optional, via environment; examples/.envrc sets these for you):
+#   RLTO_LOCAL     true|false   use a local LM Studio model (default true)
+#   RLTO_PROVIDER  name         LLM provider label (default: lms for local)
+#   RLTO_MODEL     id           model id (default: qwen/qwen3.8-27b for local)
+#   LMS_BASE_URL   url          LM Studio OpenAI-compatible endpoint (default localhost:1234/v1)
 # ===========================================================================
 
 require "fileutils"
-require "logger"
 require "open3"
-require "net/http"
 
 # Make the example runnable straight from the repo during development, with or
 # without `bundle exec`. (When the gem is installed normally, these paths simply
@@ -61,52 +59,22 @@ require "net/http"
   File.expand_path("../../../robot_lab/lib", __dir__) # sibling robot_lab/lib
 ].each { |p| $LOAD_PATH.unshift(p) if Dir.exist?(p) }
 
-require "ruby_llm"
 require "robot_lab"
 require "robot_lab/to"
+require_relative "../common"
 
 # --- configuration ---------------------------------------------------------
 
 LOCAL    = ENV.fetch("RLTO_LOCAL", "true") == "true"
-PROVIDER = ENV.fetch("RLTO_PROVIDER", LOCAL ? "openai" : "anthropic").to_sym
-MODEL    = ENV.fetch("RLTO_MODEL", LOCAL ? "qwen3.6:latest" : "claude-sonnet-4-6")
-OLLAMA   = ENV.fetch("OLLAMA_BASE", "http://localhost:11434/v1")
-
-# For a local model we route RubyLLM's :openai provider at Ollama's
-# OpenAI-compatible endpoint, refresh the registry so tool attachment works, and
-# run non-streaming (Ollama suppresses tool calls when streaming). See the
-# "Local Models" guide in the docs for why.
-def configure_local!
-  RubyLLM.configure do |c|
-    c.openai_api_base = OLLAMA
-    c.openai_api_key  = "ollama" # ignored by Ollama, but RubyLLM wants a value
-    c.request_timeout = 600
-  end
-  RubyLLM.logger.level = Logger::ERROR
-  RubyLLM.models.refresh!
-rescue StandardError => e
-  warn "warning: could not refresh Ollama models (#{e.class}: #{e.message})"
-end
+PROVIDER = ENV.fetch("RLTO_PROVIDER", LOCAL ? "lms" : "anthropic").to_sym
+MODEL    = ENV.fetch("RLTO_MODEL", LOCAL ? "qwen/qwen3.8-27b" : "claude-sonnet-4-6")
 
-# Fail fast with a friendly message if a local run can't reach Ollama.
-def preflight_local!
-  uri = URI.join(OLLAMA, "models")
-  Net::HTTP.start(uri.host, uri.port, open_timeout: 2, read_timeout: 2) do |http|
-    http.get(uri.request_uri)
-  end
-rescue StandardError
-  abort <<~MSG
-    Cannot reach an Ollama server at #{OLLAMA}.
-    Start it and pull a tool-capable model first:
-
-      ollama serve &
-      ollama pull #{MODEL}
-
-    Or run against a cloud model:
-      RLTO_LOCAL=false RLTO_PROVIDER=anthropic RLTO_MODEL=claude-sonnet-4-6 \\
-        ANTHROPIC_API_KEY=sk-... ruby #{File.basename(__FILE__)}
-  MSG
-end
+# ruby_llm has no native "lms" adapter. "lms" is this example's friendly label for
+# "a local LM Studio model"; setup (common.rb) resolves it to RubyLLM's :openai
+# adapter pointed at LM Studio, starting the server and loading MODEL as needed.
+# Everything passed to RobotLab uses the resolved provider; PROVIDER itself is
+# kept only for display.
+LLM_PROVIDER = setup(provider: PROVIDER, model: MODEL)
 
 # --- sandbox repository ----------------------------------------------------
 
@@ -352,15 +320,10 @@ OBJECTIVE = <<~OBJ.strip
   file. Call submit_result when the suite passes.
 OBJ
 
-if LOCAL
-  preflight_local!
-  configure_local!
-end
-
 clean_slate! # delete any project / .robot_lab_to left by a previous run
 sandbox = make_sandbox
 puts "Project dir:     #{sandbox}"
-puts "Provider/model:  #{PROVIDER}/#{MODEL} (#{LOCAL ? 'local Ollama' : 'cloud'})"
+puts "Provider/model:  #{PROVIDER}/#{MODEL} (#{LOCAL ? 'local LM Studio' : 'cloud'})"
 puts "Objective:       implement lib/roman_numeral.rb to pass the test suite"
 puts
 
@@ -370,10 +333,10 @@ RobotLab.on(FeedbackHook)
 Dir.chdir(sandbox) do
   RobotLab::To.run(
     OBJECTIVE,
-    provider:       PROVIDER,
+    provider:       LLM_PROVIDER,
     model:          MODEL,
     local_guards:   LOCAL,    # built-in file tools + small-model guardrails
-    stream:         !LOCAL,   # local Ollama tool calls require non-streaming
+    stream:         !LOCAL,   # local LM Studio tool calls run non-streaming
     max_iterations: 6,        # a richer task needs room to iterate
     run_dir:        RUN_DIR,  # keep logs + notes under this example directory
     # The change only commits if the seeded test suite passes:

data/examples/02_advanced_usage/README.md

@@ -11,7 +11,7 @@ autonomously implements the plan behind a real **quality gate**.
 │  (AskUser tool)   │   │  acceptance      │ spec │  passes AND the quality gate  │
 │                   │   │  test suite      │      │  is clean                     │
 └───────────────────┘   └──────────────────┘      └───────────────────────────────┘
-        gpt-5.5 (cloud)  ·  robot_lab Network          qwen3.6:latest (local Ollama)
+        gpt-5.5 (cloud)  ·  robot_lab Network          qwen/qwen3.8-27b (local LM Studio)
 ```
 
 This is the natural progression from
@@ -25,11 +25,11 @@ the implementer) writes the spec, so the implementer still can't game it.
 |-------|-------------------|-------|
 | 1 — Ideate | `AskUser` tool, network task, templated robot | OpenAI `gpt-5.5` |
 | 2 — Plan | sequential network `task … depends_on`, data hand-off, file tools | OpenAI `gpt-5.5` |
-| 3 — Implement | `RobotLab::To.run` autonomous loop, verify gate, `stop_when`, guardrails | local Ollama `qwen3.6:latest` |
+| 3 — Implement | `RobotLab::To.run` autonomous loop, verify gate, `stop_when`, guardrails | local LM Studio `qwen/qwen3.8-27b` |
 
 The reasoning phases run on a capable cloud model; the implementation loop runs
 fully local. Because both use RubyLLM's `:openai` provider but different endpoints
-(`api.openai.com` vs Ollama's `/v1`), and `openai_api_base` is global, the example
+(`api.openai.com` vs LM Studio's `/v1`), and `openai_api_base` is global, the example
 toggles it between the sequential phases.
 
 ## The quality gate
@@ -55,10 +55,12 @@ flog + flay) into an autonomous gate. Tune the thresholds with `FLOG_MAX` /
 
 ```bash
 export OPENAI_API_KEY="sk-..."     # ideation + planning (gpt-5.5)
-ollama serve &                     # implementation (local)
-ollama pull qwen3.6:latest
 ```
 
+`common.rb` starts the LM Studio server and loads the build model itself if
+they aren't already running/loaded, so there's nothing to start by hand for
+the implementation phase.
+
 ## Run it
 
 ```bash
@@ -75,8 +77,9 @@ acceptance suite and the local model implement it.
 |----------|---------|-------------|
 | `RLTO_REASON_MODEL` | `gpt-5.5` | model for ideate + plan |
 | `RLTO_REASON_PROVIDER` | `openai` | provider for ideate + plan |
-| `RLTO_BUILD_MODEL` | `qwen3.6:latest` | model for implementation |
-| `OLLAMA_BASE` | `http://localhost:11434/v1` | Ollama OpenAI-compatible endpoint |
+| `RLTO_BUILD_PROVIDER` | `lms` (falls back to `RLTO_PROVIDER`) | provider label for implementation; `lms` resolves to `:openai` routed at `LMS_BASE_URL` |
+| `RLTO_BUILD_MODEL` | `qwen/qwen3.8-27b` (falls back to `RLTO_MODEL`) | model for implementation |
+| `LMS_BASE_URL` | `http://localhost:1234/v1` | LM Studio OpenAI-compatible endpoint |
 | `FLOG_MAX` | `25` | per-method complexity ceiling |
 | `FLAY_MAX` | `40` | duplication-mass ceiling |
 

data/examples/02_advanced_usage/advanced_usage.rb

@@ -18,28 +18,29 @@
 #       suite* into the project (test/). It does not implement anything. Its
 #       reply is a one-paragraph implementation objective.
 #
-#   Phase 3  IMPLEMENT (robot_lab-to, local Ollama qwen3.6:latest)
+#   Phase 3  IMPLEMENT (robot_lab-to, local LM Studio qwen/qwen3.8-27b)
 #       robot_lab-to runs an autonomous loop that writes lib/ code until the
 #       Planner's acceptance suite passes AND a quality gate is clean. The
 #       verify command (quality_gate.rb) runs tests + rubocop + flog + flay, so
 #       the robot must earn each commit on correctness AND quality.
 #
 # Models (per your request): reasoning on OpenAI gpt-5.5, building on local
-# Ollama qwen3.6. Because both use RubyLLM's :openai provider but different
-# endpoints (api.openai.com vs Ollama's /v1), and openai_api_base is global, we
-# toggle it between the (sequential) phases.
+# LM Studio qwen/qwen3.8-27b. Because both use RubyLLM's :openai provider but different
+# endpoints (api.openai.com vs LM Studio's /v1), and openai_api_base is global,
+# we toggle it between the (sequential) phases.
 #
 # Everything stays under examples/02_advanced_usage/ (project/, .robot_lab_to/),
 # both git-ignored and recreated on each run.
 #
-# Run it (from the gem root, with OPENAI_API_KEY set and Ollama serving qwen3.6):
+# Run it (from the gem root, with OPENAI_API_KEY set; common.rb starts the LM
+# Studio server and loads the build model for you if they aren't already
+# running/loaded):
 #   bundle exec ruby examples/02_advanced_usage/advanced_usage.rb
 # ===========================================================================
 
 require "fileutils"
 require "logger"
 require "open3"
-require "net/http"
 
 # Make the example runnable straight from the repo, with or without bundler.
 [
@@ -47,17 +48,19 @@ require "net/http"
   File.expand_path("../../../robot_lab/lib", __dir__) # sibling robot_lab/lib
 ].each { |p| $LOAD_PATH.unshift(p) if Dir.exist?(p) }
 
-require "ruby_llm"
 require "robot_lab"
 require "robot_lab/to"
+require_relative "../common"
 
 # --- configuration ---------------------------------------------------------
 
 REASON_PROVIDER = ENV.fetch("RLTO_REASON_PROVIDER", "openai").to_sym
-REASON_MODEL    = ENV.fetch("RLTO_REASON_MODEL", "gpt-5.5")        # real OpenAI
-BUILD_PROVIDER  = ENV.fetch("RLTO_BUILD_PROVIDER", "openai").to_sym
-BUILD_MODEL     = ENV.fetch("RLTO_BUILD_MODEL", "qwen3.6:latest")  # local Ollama
-OLLAMA_BASE     = ENV.fetch("OLLAMA_BASE", "http://localhost:11434/v1")
+REASON_MODEL    = ENV.fetch("RLTO_REASON_MODEL", "gpt-5.5")     # real OpenAI
+# Falls back to the shared RLTO_PROVIDER / RLTO_MODEL (examples/.envrc sets these)
+# so the build phase picks up the same local model as the other examples unless
+# RLTO_BUILD_PROVIDER / RLTO_BUILD_MODEL override it specifically.
+BUILD_PROVIDER  = ENV.fetch("RLTO_BUILD_PROVIDER", ENV.fetch("RLTO_PROVIDER", "lms")).to_sym
+BUILD_MODEL     = ENV.fetch("RLTO_BUILD_MODEL", ENV.fetch("RLTO_MODEL", "qwen/qwen3.8-27b")) # local LM Studio
 
 SANDBOX_DIR = File.expand_path("project", __dir__)
 RUN_DIR     = File.expand_path(".robot_lab_to", __dir__)
@@ -95,28 +98,17 @@ def use_real_openai!
   RubyLLM.logger.level = Logger::ERROR # keep raw API traffic out of the feed
 end
 
-# Implementation phase routes the :openai provider at the local Ollama endpoint.
-def use_ollama!
-  RubyLLM.configure do |c|
-    c.openai_api_base = OLLAMA_BASE
-    c.openai_api_key  = "ollama" # ignored by Ollama
-    c.request_timeout = 600
-  end
-  RubyLLM.logger.level = Logger::ERROR
-  RubyLLM.models.refresh! # register local models so tool attachment works
-rescue StandardError => e
-  warn "warning: could not refresh Ollama models (#{e.class}: #{e.message})"
+# Implementation phase routes the :openai provider at the local LM Studio endpoint
+# (or whatever BUILD_PROVIDER resolves to). common.rb's setup starts the LM Studio
+# server and loads BUILD_MODEL as needed; the "lms" label resolves to :openai.
+def use_build_provider!
+  setup(provider: BUILD_PROVIDER, model: BUILD_MODEL)
 end
 
 # --- preflight -------------------------------------------------------------
 
 def preflight!
   abort "Set OPENAI_API_KEY (the ideation/planning phases use #{REASON_MODEL})." unless ENV["OPENAI_API_KEY"]
-
-  uri = URI.join(OLLAMA_BASE, "models")
-  Net::HTTP.start(uri.host, uri.port, open_timeout: 2, read_timeout: 2) { |h| h.get(uri.request_uri) }
-rescue StandardError
-  abort "Cannot reach Ollama at #{OLLAMA_BASE}. Start it and `ollama pull #{BUILD_MODEL}`."
 end
 
 # --- sandbox ---------------------------------------------------------------
@@ -243,7 +235,7 @@ RobotLab::Narrator.enable! # live narration for every robot, across all phases
 
 puts "Project dir:  #{sandbox}"
 puts "Reasoning:    #{REASON_PROVIDER}/#{REASON_MODEL} (cloud)   →  ideate + plan"
-puts "Building:     #{BUILD_PROVIDER}/#{BUILD_MODEL} (local Ollama)  →  implement"
+puts "Building:     #{BUILD_PROVIDER}/#{BUILD_MODEL} (local LM Studio)  →  implement"
 puts
 
 # -- Phases 1 & 2: ideate -> plan, as a robot_lab network --------------------
@@ -289,15 +281,15 @@ puts "Objective derived from the spec.\n\n"
 
 # -- Phase 3: autonomous implementation with robot_lab-to --------------------
 puts "── Phase 3: implementation (robot_lab-to, quality-gated) ──"
-use_ollama!
+build_llm_provider = use_build_provider!
 
 Dir.chdir(sandbox) do
   RobotLab::To.run(
     objective,
-    provider:       BUILD_PROVIDER,
+    provider:       build_llm_provider,
     model:          BUILD_MODEL,
     local_guards:   true,   # built-in file tools + small-model guardrails
-    stream:         false,  # Ollama tool calls require non-streaming
+    stream:         false,  # local LM Studio tool calls run non-streaming
     max_iterations: 8,
     run_dir:        RUN_DIR,
     verify_command: "ruby quality_gate.rb", # tests + rubocop + flog + flay