robot_lab-to 0.2.7 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a600189accdf098fb2cea44bec912fbc3399b89d48b7775d1237a78fd5bac7fd
-  data.tar.gz: 8729282eb38252b3e2227b02cc9b48dc76b04005572ede0d24fccdbab1b47940
+  metadata.gz: 3dad27a958d30948be8ed4f93401f169e799c24d3a4d77fc4d205bf00c80849c
+  data.tar.gz: bdd675595bb524d3e4f2f1e24dce9df7b7ef2070195b5b60e3317780c4e51163
 SHA512:
-  metadata.gz: 58a538bc23b7a68822dae324d6b179f0eba4ea4f8b79bfb489ea6cfcaedd59e82c592197ca67c11873404d52c78bae8a74f26b53b05e061c5753d43ad15c3f68
-  data.tar.gz: bc1e417731a76c43f5671ff3fcfaec038a59884d9ac62a63c1cb2bbb53c8fade6f051560da30db2d1c517645cc2f448100b1e551fd458ea040bf738447edd145
+  metadata.gz: 92a7c42b8b8586085a9894c15d2443e809b65147db939707b1d1c1ec2b83eeaec09752a165fa2193fb38d9f7fb10211fe33b8c0cce8a86b4a40a4987affb4be8
+  data.tar.gz: 06bd6bf4074ea7a35e969736de4ba5946db22a2313ee7551528d93630950fddfc2572acee1e3116bf923fe5b9aeffcbc198234106a7f32e9ebbd67d758887b57

data/.envrc

@@ -1 +1,7 @@
+# robot_lab_project/robot_lab-to/.envrc
+
+source_up
+
 export RR=$(pwd)
+
+# BUNDLE_GEMFILE is inherited from the project root .envrc (asgard dev|prod)

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/README.md

@@ -244,16 +244,18 @@ RobotLab::To.run(
 ## Local models
 
 `robot_lab-to` can drive a local model running offline against
-[Ollama](https://ollama.com) — no API keys, no per-token cost.
+[LM Studio](https://lmstudio.ai) via the
+[ruby_llm-providers-lms](https://github.com/madbomber/ruby_llm-providers-lms)
+gem — no API keys, no per-token cost.
 
 ```bash
-ollama pull gpt-oss:20b
+lms server start
+lms get qwen/qwen3.8-27b
 
 robot-to "Add a greet(name) method in greeter.rb" \
-  --provider openai \
-  --model gpt-oss:20b \
+  --provider lms \
+  --model qwen/qwen3.8-27b \
   --local-guards \
-  --no-stream \
   --max-iterations 5
 ```
 
@@ -320,8 +322,8 @@ export ROBOT_LAB_TO_STREAM=false
 
 API keys are read by the underlying provider (via RobotLab / RubyLLM), **not** by
 `robot_lab-to` itself — e.g. `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`. Local
-[Ollama](https://ollama.com) models need no key; see the
-[Local Models guide](https://madbomber.github.io/robot_lab-to/local-models/ollama/).
+[LM Studio](https://lmstudio.ai) models need no key; see the
+[Local Models guide](https://madbomber.github.io/robot_lab-to/local-models/lm-studio/).
 
 ---
 

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/docs/concepts/stop-conditions.md

@@ -37,9 +37,9 @@ limit.
 
 - **Streaming runs** (the default) account tokens per chunk and can interrupt an
   in-flight iteration the moment the budget is exhausted.
-- **Non-streaming runs** (`--no-stream`, used for local models) account tokens
-  from each iteration's result and stop at the next iteration boundary. See
-  [Local Models](../local-models/ollama.md#streaming-and-tool-calls).
+- **Non-streaming runs** (`--no-stream`) account tokens from each iteration's
+  result and stop at the next iteration boundary. See
+  [Local Models](../local-models/index.md).
 
 ### Consecutive failures
 

data/docs/configuration/cli.md

@@ -43,7 +43,7 @@ echo "Add request logging middleware and tests" | robot-to
 | `--commit-format` | `default`\|`conventional` | `default` | Commit message format. |
 | `--run-dir` | `PATH` | `.robot_lab_to` | Directory for run state. |
 | `--local-guards` | — | off | Add built-in file tools + small-model guardrails. |
-| `--no-stream` | — | streaming on | Disable streaming (required for local Ollama tool calls). |
+| `--no-stream` | — | streaming on | Disable streaming (tokens are then accounted per iteration instead of per chunk). |
 | `--debug` | — | off | Keep verbose provider logging enabled. |
 | `--version` | — | — | Print version and exit. |
 | `-h`, `--help` | — | — | Show help and exit. |
@@ -92,14 +92,13 @@ robot-to "Write an opinionated guide to the Viable Systems Model" \
   --stop-on-plateau 3
 ```
 
-A fully local run on Ollama (see [Local Models](../local-models/index.md)):
+A fully local run on LM Studio (see [Local Models](../local-models/index.md)):
 
 ```bash
 robot-to "Add a greet(name) method in greeter.rb" \
-  --provider openai \
-  --model gpt-oss:20b \
+  --provider lms \
+  --model qwen/qwen3.8-27b \
   --local-guards \
-  --no-stream \
   --max-iterations 5
 ```
 

data/docs/configuration/index.md

@@ -43,10 +43,9 @@ Create `~/.config/robot_lab/to.yml` to set your own defaults — for example, to
 always use a local model:
 
 ```yaml
-provider: openai          # routes to Ollama's OpenAI-compatible endpoint
-model: gpt-oss:20b
+provider: lms             # LM Studio via the ruby_llm-providers-lms gem
+model: qwen/qwen3.8-27b
 local_guards: true
-stream: false
 max_consecutive_failures: 4
 ```
 

data/docs/configuration/settings.md

@@ -13,8 +13,9 @@ CLI flag, or a `RobotLab::To.run` keyword argument (see
 - **CLI:** `--provider NAME`
 
 The LLM provider, passed through to RobotLab / RubyLLM. Use `anthropic`,
-`openai`, etc. For **local Ollama models**, set this to `openai` and point
-RubyLLM at Ollama's OpenAI-compatible endpoint — see [Ollama Setup](../local-models/ollama.md).
+`openai`, etc. For **local LM Studio models**, require the
+ruby_llm-providers-lms gem and set this to `lms` — see
+[LM Studio Setup](../local-models/lm-studio.md).
 
 ### `model`
 
@@ -22,7 +23,7 @@ RubyLLM at Ollama's OpenAI-compatible endpoint — see [Ollama Setup](../local-m
 - **CLI:** `--model MODEL`
 
 The model identifier for the chosen provider (e.g. `claude-sonnet-4-6`,
-`gpt-5.5`, `gpt-oss:20b`).
+`gpt-5.5`, `qwen/qwen3.8-27b`).
 
 ### `stream`
 
@@ -30,10 +31,9 @@ The model identifier for the chosen provider (e.g. `claude-sonnet-4-6`,
 - **CLI:** `--no-stream` to disable
 
 Whether to stream the model response. Streaming enables per-chunk token
-accounting and mid-iteration token-budget enforcement. **Local Ollama models must
-run with `--no-stream`** — Ollama suppresses tool calls when streaming. With
-streaming off, tokens are accounted from each iteration's result instead. See
-[Streaming and tool calls](../local-models/ollama.md#streaming-and-tool-calls).
+accounting and mid-iteration token-budget enforcement. With streaming off,
+tokens are accounted from each iteration's result instead. See
+[LM Studio Setup](../local-models/lm-studio.md).
 
 ## Loop control
 

data/docs/getting-started/installation.md

@@ -7,7 +7,7 @@
 | Ruby **>= 3.2** | Set in the gemspec `required_ruby_version`. |
 | Git | A repository with at least one commit. The loop creates a branch and commits there. |
 | `robot_lab` | The core framework `robot_lab-to` builds on. |
-| An LLM provider | A cloud API key, **or** a local [Ollama](https://ollama.com) server (see [Local Models](../local-models/index.md)). |
+| An LLM provider | A cloud API key, **or** a local [LM Studio](https://lmstudio.ai) server (see [Local Models](../local-models/index.md)). |
 
 ## Install the gem
 
@@ -46,11 +46,11 @@ RobotLab / RubyLLM. Provide credentials the usual way for your provider:
     robot-to "..." --provider openai --model gpt-5.5
     ```
 
-=== "Local (Ollama)"
+=== "Local (LM Studio)"
 
-    No API key required. See [Ollama Setup](../local-models/ollama.md) for the
-    full configuration — local models need `--provider openai` against Ollama's
-    OpenAI-compatible endpoint plus `--no-stream` and `--local-guards`.
+    No API key required. See [LM Studio Setup](../local-models/lm-studio.md)
+    for the full configuration — require the ruby_llm-providers-lms gem, then
+    run with `--provider lms` and `--local-guards`.
 
 The default provider/model is `openai` / `gpt-5.5` (see
 [Settings Reference](../configuration/settings.md)).

data/docs/index.md

@@ -68,7 +68,7 @@ See [The Iteration Loop](concepts/iteration-loop.md) for the full lifecycle.
   `robot-to --resume <run_id>` continues a stopped run and an external scheduler
   can drive it one commit per tick.
 - **Runs on local models.** With `--local-guards` it ships built-in file tools and
-  small-model guardrails, so it can drive a local Ollama model offline. See
+  small-model guardrails, so it can drive a local LM Studio model offline. See
   [Local Models](local-models/index.md).
 
 ---
@@ -80,7 +80,7 @@ See [The Iteration Loop](concepts/iteration-loop.md) for the full lifecycle.
 - :material-rocket-launch: **[Installation](getting-started/installation.md)** — install the gem and the `robot-to` CLI.
 - :material-play: **[Quick Start](getting-started/quick-start.md)** — your first overnight run in five minutes.
 - :material-cog: **[Configuration](configuration/index.md)** — every setting, the config cascade, and the CLI.
-- :material-laptop: **[Local Models](local-models/index.md)** — drive a local Ollama model with guardrails.
+- :material-laptop: **[Local Models](local-models/index.md)** — drive a local LM Studio model with guardrails.
 - :material-sitemap: **[Architecture](reference/architecture.md)** — how the pieces fit together.
 
 </div>
@@ -93,4 +93,4 @@ See [The Iteration Loop](concepts/iteration-loop.md) for the full lifecycle.
 - A git repository with at least one commit (the loop branches and commits there)
 - The [`robot_lab`](https://github.com/MadBomber/robot_lab) gem and an LLM provider
   (a cloud key such as `ANTHROPIC_API_KEY` / `OPENAI_API_KEY`, **or** a local
-  [Ollama](https://ollama.com) server)
+  [LM Studio](https://lmstudio.ai) server via ruby_llm-providers-lms)

data/docs/local-models/index.md

@@ -1,7 +1,7 @@
 # Local Models
 
 `robot_lab-to` can drive a **local** model — running entirely offline against an
-[Ollama](https://ollama.com) server — instead of a cloud API. This is the
+[LM Studio](https://lmstudio.ai) server via the `:lms` provider — instead of a cloud API. This is the
 "local assistant" mode: no API keys, no per-token cost, no data leaving your
 machine.
 
@@ -19,33 +19,31 @@ Both are enabled together with `--local-guards`.
 
 ```bash
 # 1. Serve a tool-capable model
-ollama pull gpt-oss:20b
+lms server start
+lms get qwen/qwen3.8-27b
 
 # 2. Run robot-to against it
 robot-to "Add a greet(name) method in greeter.rb" \
-  --provider openai \
-  --model gpt-oss:20b \
+  --provider lms \
+  --model qwen/qwen3.8-27b \
   --local-guards \
-  --no-stream \
   --max-iterations 5
 ```
 
-The full setup — including the RubyLLM configuration that points `:openai` at
-Ollama — is on the [Ollama Setup](ollama.md) page.
+The full setup — including requiring the ruby_llm-providers-lms gem — is on
+the [LM Studio Setup](lm-studio.md) page.
 
 ## Why these flags
 
-Driving a local model end-to-end requires three non-obvious settings. Each exists
-because of a concrete limitation discovered in testing:
+Driving a local model end-to-end takes two settings. Each exists because of a
+concrete limitation discovered in testing:
 
 | Flag / setting | Why |
 |----------------|-----|
-| `--provider openai` (+ Ollama base URL) | RubyLLM's native `:ollama` provider doesn't reliably get these models to emit tool calls. Routing through the `:openai` provider against Ollama's OpenAI-compatible `/v1` endpoint does. |
-| `--no-stream` | Ollama suppresses tool calls when the response is streamed. With streaming off, tool calls come through. |
+| `--provider lms` | The ruby_llm-providers-lms gem's LM Studio provider — no API key, and local model ids are assumed to exist. Its default `:chat_completions` protocol supports client tools, structured output, and streaming. |
 | `--local-guards` | Attaches the file tools the model needs to do work, plus guardrails that make those tools safe for a small model. |
 
-See [Ollama Setup → Streaming and tool calls](ollama.md#streaming-and-tool-calls)
-for the details.
+See [LM Studio Setup](lm-studio.md) for the details.
 
 ## The design philosophy
 
@@ -74,15 +72,14 @@ The model **must support tool calling**. In testing on an M2 Max:
 
 | Model | Size | Tool calls? | Notes |
 |-------|------|-------------|-------|
-| `gpt-oss:20b` | 20B | ✅ reliable | Called tools *and* `submit_iteration_result`; completed full runs cleanly. **Recommended.** |
-| `qwen3` | 8B | ✅ tools work | Created files via the write tool, but didn't reliably call `submit_iteration_result` (the final-report step). |
-| `phi4-mini` | 3.8B | ❌ | Explains instead of calling tools. |
+| `qwen/qwen3.8-27b` | 27B | ✅ reliable | Honors `tool_choice` and structured output; the right pick for the autonomous loop. **Recommended.** |
+| `openai/gpt-oss-20b` | 20B | ⚠️ partial | Accepts tool definitions but ignores `tool_choice: required`, and its structured output parses without meaning anything. Fine for simple chat, not for the loop. |
 
 Prefer a larger, instruction-following model for the autonomous loop — it has to
 both use tools *and* remember to submit its result every iteration.
 
 ---
 
-- [Ollama Setup](ollama.md) — install, serve, and configure.
+- [LM Studio Setup](lm-studio.md) — install, serve, and configure.
 - [Built-in Tools](tools.md) — what `read`/`write`/`edit`/`bash` do.
 - [Guardrails](guardrails.md) — the small-model safety policies.

data/docs/local-models/lm-studio.md

@@ -0,0 +1,92 @@
+# LM Studio Setup
+
+This page covers running `robot_lab-to` against a local
+[LM Studio](https://lmstudio.ai) server end-to-end, through the
+[ruby_llm-providers-lms](https://github.com/madbomber/ruby_llm-providers-lms)
+gem, which registers the `:lms` provider with RubyLLM.
+
+## 1. Install and start LM Studio
+
+Install LM Studio, then bootstrap its CLI and start the server:
+
+```bash
+lms bootstrap        # puts the `lms` CLI on your PATH
+lms server start     # serves on http://localhost:1234
+```
+
+## 2. Download a tool-capable model
+
+The model **must** support tool calling *and honor it*. `qwen/qwen3.8-27b` is
+the recommended choice — it obeys `tool_choice` and returns meaningful
+structured output, where `gpt-oss` models accept the request shape but ignore
+it (see [model selection](index.md#choosing-a-model)):
+
+```bash
+lms get qwen/qwen3.8-27b
+```
+
+## 3. Point RubyLLM at LM Studio
+
+`robot_lab-to` reaches the model through RobotLab / RubyLLM. Require the
+provider gem and, only if your server is not on the default endpoint,
+configure the base URL:
+
+```ruby
+require "ruby_llm"
+require "ruby_llm/providers/lms"
+require "robot_lab"
+require "robot_lab/to"
+
+RubyLLM.configure do |c|
+  c.lms_api_base    = "http://localhost:1234/v1"  # the default; override if needed
+  c.request_timeout = 600
+end
+
+RobotLab::To.run(
+  "Add a greet(name) method in greeter.rb",
+  provider: :lms,
+  model: "qwen/qwen3.8-27b",
+  local_guards: true,
+  max_iterations: 5
+)
+```
+
+No API key is needed — LM Studio's local server does not require one.
+
+## 4. Run
+
+From the launcher above, or from the CLI:
+
+```bash
+robot-to "Add a greet(name) method in greeter.rb" \
+  --provider lms \
+  --model qwen/qwen3.8-27b \
+  --local-guards \
+  --max-iterations 5
+```
+
+Because LM Studio is a local provider, RubyLLM assumes any model id you pass
+exists — LM Studio just-in-time loads the model if it isn't loaded yet. No
+registry refresh is needed.
+
+## Protocols
+
+LM Studio serves several API protocols on one port; the `:lms` provider
+defaults to `:chat_completions`, which is the most capable one here — client
+tools, structured output, streaming, and reasoning control all work. Stay on
+the default for `robot_lab-to`. See the
+[ruby_llm-providers-lms README](https://github.com/madbomber/ruby_llm-providers-lms)
+for the full protocol matrix.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Connection error naming `lms server start` | Server not running | `lms server start`. |
+| Tool calls accepted but ignored, or `{"name":"analysis","age":0}`-style junk from schemas | Model doesn't honor `tool_choice` / grammar output (e.g. `gpt-oss`) | Use `qwen/qwen3.8-27b`. |
+| Every iteration "did not submit" | Model too small to follow the final-report step | Use a larger model (e.g. `qwen/qwen3.8-27b`). |
+| No tool calls at all, model only explains | Model lacks tool support | Pick a tool-capable model. |
+
+---
+
+Next: [Built-in Tools](tools.md).

data/docs/reference/architecture.md

@@ -103,10 +103,10 @@ robot actually exposes the submit tool, guarding against that class of mistake.
 
 ### Streaming is optional
 
-By default the robot streams, enabling per-chunk token accounting and mid-stream
-budget enforcement. Local Ollama models run non-streaming (`stream: false`), so
-tokens are accounted from each iteration's result and the budget is enforced at
-iteration boundaries. See [Ollama Setup](../local-models/ollama.md#streaming-and-tool-calls).
+By default the robot streams, enabling per-chunk token accounting and
+mid-stream budget enforcement. Non-streaming runs (`stream: false`) account
+tokens from each iteration's result and enforce the budget at iteration
+boundaries. See [LM Studio Setup](../local-models/lm-studio.md).
 
 ### Interruptible by design
 

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"