robot_lab-to 0.2.6

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 27f85b41e0ea5e5a7da88c8e72363f6341670268863c31c6a94bc1bc4280c08b
+  data.tar.gz: 90605d38d5cc683a7af57c88eeef7142600b40e564e39304b6bf63f080fd3ee6
+SHA512:
+  metadata.gz: b2550b48a8e4826e7c7be883cd7ad6865971ad61aa7f07749abd70ff321099a15616a942fa8f04a1b7e8396e1cd8ceabb8e6f912c77023f2fa7d59ae395f3c12
+  data.tar.gz: dee01f98631dae8b4b1f90daed41de5f7478e24a0af377d2faaedeef03b7760bad0f1724a24a88912dc18eea0a204309e70d25050278c6ad7c5a3374878649a3

data/.envrc

@@ -0,0 +1 @@
+export RR=$(pwd)

data/.github/workflows/deploy-github-pages.yml

@@ -0,0 +1,52 @@
+name: Deploy Documentation to GitHub Pages
+on:
+  push:
+    branches:
+      - main
+      - develop
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/deploy-github-pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+
+      - name: Install dependencies
+        run: |
+          pip install mkdocs
+          pip install mkdocs-material
+          pip install mkdocs-macros-plugin
+          pip install mike
+
+      - name: Configure Git
+        run: |
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+
+      - name: Deploy to GitHub Pages
+        run: |
+          if [ "${{ github.ref }}" = "refs/heads/main" ]; then
+            echo "Deploying from main branch"
+            mkdocs gh-deploy --force --clean
+          else
+            echo "Deploying from develop branch"
+            mkdocs gh-deploy --force --clean
+          fi

data/.loki

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+# robot_lab-to — autonomous overnight agent loop ("takeover") for RobotLab.
+
+import_up "repo_dev.loki"
+
+class Tasks
+  @@gem_name ||= "robot_lab-to".freeze
+
+  header "robot_lab-to v#{gem_version} — autonomous overnight loop harness"
+
+  desc "Remove all local robot-to/* branches left over from test runs"
+  def clean_up
+    sh "git checkout develop"
+    branches = `git branch --list 'robot-to/*'`.split.map(&:strip)
+    if branches.empty?
+      puts "No robot-to/* branches to remove."
+    else
+      branches.each { |b| sh "git branch -d #{b}" }
+    end
+  end
+end

data/.quality/reek_baseline.txt

@@ -0,0 +1,17 @@
+7	lib/robot_lab/to/cli.rb
+2	lib/robot_lab/to/commit_manager.rb
+19	lib/robot_lab/to/config.rb
+9	lib/robot_lab/to/decision_manager.rb
+2	lib/robot_lab/to/exit_summary.rb
+1	lib/robot_lab/to/guards/checkpoint.rb
+2	lib/robot_lab/to/guards/quality_monitor.rb
+1	lib/robot_lab/to/guards/run_store.rb
+3	lib/robot_lab/to/notes_manager.rb
+30	lib/robot_lab/to/orchestrator.rb
+1	lib/robot_lab/to/prompt_builder.rb
+4	lib/robot_lab/to/run.rb
+2	lib/robot_lab/to/stop_conditions.rb
+3	lib/robot_lab/to/tools/bash.rb
+3	lib/robot_lab/to/tools/edit.rb
+3	lib/robot_lab/to/tools/request_decision.rb
+1	lib/robot_lab/to/tools/submit_result.rb

data/.rubocop.yml

@@ -0,0 +1,7 @@
+inherit_from: ../.rubocop-base.yml
+
+Style/FormatStringToken:
+  Enabled: false
+
+Style/StderrPuts:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+All notable changes to `robot_lab-to` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
+and [Conventional Commits](https://www.conventionalcommits.org/) (see `COMMITS.md`).
+
+## [Unreleased]
+
+### Added
+
+- **Human-in-the-loop decision files.** When the robot hits a choice it must not
+  make autonomously, it calls `request_decision` and the orchestrator writes a
+  decision file (situation, options, and its recommended "lean") under
+  `runs/<id>/decisions/`. A human resolves it out-of-band by editing the file
+  (`status: resolved` + `resolution:`); a later iteration reads the answer back.
+  New `Decision` value object, `DecisionManager`, and `RequestDecision` tool.
+- **Blocking decisions gate the loop.** `--decision-mode wait` (default) polls
+  until the decision is resolved (`--decision-poll`, `--decision-timeout`);
+  `--decision-mode exit` stops the run with a `--resume` hint. Disable with
+  `--no-decisions`.
+- **Resumable runs.** Run state is persisted to `run.json`; `robot-to --resume
+  <run_id>` (or `RobotLab::To.resume`) continues a stopped run on the same
+  branch — enabling cron/scheduled operation.
+- **`decisions` subcommand.** `robot-to decisions [run_id]` lists pending and
+  resolved decisions with their file paths.
+- **Local-model support.** Drive a local [Ollama](https://ollama.com) model
+  end-to-end with `--local-guards` and `--no-stream`.
+- **Built-in workspace tools** (`read`, `write`, `edit`, `bash`) attached to the
+  per-iteration robot when `--local-guards` is set.
+- **Small-model guardrails** — `write-guard`, `read-before-edit`, `checkpoint`,
+  and `quality-monitor` `RobotLab::Hook` policies that make tool use safe for
+  small local models.
+- **`stream` setting** (`--no-stream`) — disable response streaming, required for
+  Ollama tool calls; tokens are then accounted from each iteration's result.
+- **Documentation site** (`docs/`, `mkdocs.yml`) plus a GitHub Pages deploy
+  workflow.
+
+### Fixed
+
+- Tools were passed to `RobotLab.build` via `tools:` (a tool-name allowlist
+  filter) instead of `local_tools:` (the instance list), so the
+  `submit_iteration_result` tool was never attached to the robot. Now passed via
+  `local_tools:`, with a regression test asserting the built robot exposes the
+  tool.
+
+## [0.1.0]
+
+Initial release.
+
+### Added
+
+- Autonomous overnight loop (`Orchestrator`): a fresh robot per iteration, commit
+  on success, `git reset --hard` on failure.
+- `SubmitResult` tool and `IterationResult` value object.
+- Cross-iteration memory via `notes.md` (`NotesManager`).
+- Stop conditions: `--max-iterations`, `--max-tokens`,
+  `--max-consecutive-failures`, and natural-language `--stop-when`.
+- Independent verification gate (`--verify-command`, `Verifier`).
+- Interruptible exponential `Backoff` for transient-error retries.
+- JSONL event log (`JsonlLogger`) and post-run `ExitSummary`.
+- `robot-to` CLI and `RobotLab::To.run` programmatic entry point.
+- `Config` cascade (`myway_config`): defaults → user file → env → CLI.
+
+[Unreleased]: https://github.com/MadBomber/robot_lab-to/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/MadBomber/robot_lab-to/releases/tag/v0.1.0

data/CLAUDE.md

@@ -0,0 +1,74 @@
+# CLAUDE.md
+
+## Project: robot_lab-to
+
+`robot_lab-to` ("takeover") is a robot_lab extension gem that runs a RobotLab Robot in an
+autonomous loop toward a stated objective, committing one focused change per iteration.
+
+## Commands
+
+```bash
+bundle install
+bundle exec rake test          # all tests
+bundle exec rake test_verbose  # verbose
+bundle exec rake quality       # tests + rubocop + flog
+bin/console                    # IRB shell
+```
+
+## Architecture
+
+- **`Orchestrator`** — main loop: setup → iterate → **eval-gated** commit/rollback → stop
+- **`Evals`** — orchestrator-owned scorers (`Evals.build` factory + `register_eval` registry). `Base` returns a `Score(gate_ok, improved, met_target, value, detail, output)`. `Null` (default, unscored), `Code` (measured: verify floor + `--measure`/`--target`, composes `Verifier`), `Prose` (pairwise LLM judge vs. the parent commit + optional `--floor`). Commit requires `gate_ok && improved`; the run stops on `met_target`. `Base#protected_paths` feeds `GraderLock`.
+- **`Guards::GraderLock`** — always-on hook (independent of `--local-guards`) that refuses write/edit/bash on the eval's grader artifacts (spec + `--protect-path`); wired in `Orchestrator#build_robot`.
+- **`SubmitResultTool`** — `RobotLab::Tool` the robot must call to report its result
+- **`RequestDecisionTool`** — `RobotLab::Tool` the robot calls to escalate a choice (async HITL)
+- **`IterationResult`** — `Data.define` value object (success, summary, key_changes, key_learnings, should_fully_stop)
+- **`Decision`** — `Data.define` snapshot of one decision file (status, blocking, question, recommendation, resolution)
+- **`DecisionManager`** — read/write/query decision files; parallels `NotesManager`
+- **`CommitManager`** — all git ops via `Open3.capture3` (no shell interpolation); `checkout_branch` for resume
+- **`NotesManager`** — cross-iteration memory file (notes.md); orchestrator writes, robot reads
+- **`StopConditions`** — max_iterations, max_tokens, consecutive_failures, stop_when, **stop_on_plateau** (N iterations without improvement — the primary terminator for prose)
+- **`Backoff`** — exponential (60 × 2^n seconds) + fixed `sleep_seconds` for decision polling; interruptible via `interrupt!`
+- **`PromptBuilder`** — builds per-iteration system prompt with objective, notes, resolved decisions, a **score-feedback section** (best score / target / plateau warning for scored runs), and conditional sections
+- **`JsonlLogger`** — JSONL event log with 100-event pre-init buffer
+- **`ExitSummary`** — post-run metrics table and next-step commands
+- **`CLI`** — `OptionParser`-based, binary `robot-to`; also `--resume` and the `decisions` subcommand
+- **`Config`** — `MywayConfig::Base`, file `~/.config/robot_lab/to.yml`, prefix `ROBOT_LAB_TO_*`
+
+## Key Pattern: Per-Iteration Robot
+
+A fresh `RobotLab::Tool` (`SubmitResult`, plus `RequestDecision` when decisions are
+enabled) and `RobotLab::Robot` are created per iteration. After `robot.run()`
+returns, the orchestrator reads `submit_tool.captured_result` (nil → treated as
+failure) and persists any `decision_tool.captured_requests` as decision files.
+
+## Async Human-in-the-Loop (decision files)
+
+When the robot hits a choice it must not make alone it calls `request_decision`;
+the orchestrator writes a decision file with YAML front matter + a human-readable
+body. Status lifecycle: `pending` → `resolved` (human edits the file) → `closed`
+(resolution injected into a committed iteration). A **blocking** decision gates
+the loop via `handle_blocking_decisions`: `decision_mode: wait` polls until
+resolved (`decision_wait_poll` / `decision_timeout`); `decision_mode: exit` stops
+with a `--resume` hint. See `decision_files_plan.md` in the parent workspace.
+(Note: the workspace's `hitl_plan.md` is a *separate*, synchronous terminal-gate
+design — not this feature.)
+
+## Resume / cron
+
+Each iteration writes `run.json` (`Run#to_h`). `robot-to --resume <run_id>` /
+`RobotLab::To.resume` reloads it (`Run.load`), checks out the branch, and
+re-enters the loop — so an external scheduler can drive one commit per tick.
+
+## Run State
+
+All run state lives in `.robot_lab_to/runs/<run_id>/` (added to `.git/info/exclude`):
+- `notes.md` — cross-iteration log
+- `run.log` — JSONL event log
+- `run.json` — serialized `Run` snapshot (enables `--resume`)
+- `decisions/d-*.md` — decision files
+
+## 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).

data/COMMITS.md

@@ -0,0 +1,27 @@
+# Commit Message Convention
+
+This project follows Conventional Commits.
+
+## Format
+
+```
+<type>(<scope>): <short summary>
+
+[optional body]
+```
+
+## Types
+
+- `feat` — new feature
+- `fix` — bug fix
+- `refactor` — code change that is neither a fix nor feature
+- `test` — adding or updating tests
+- `docs` — documentation only
+- `chore` — build, deps, tooling
+- `perf` — performance improvement
+
+## Rules
+
+- Summary line: imperative mood, lowercase, no trailing period, under 60 chars
+- No co-author credits
+- Reference GitHub issues as `(#123)` in the summary or body

data/README.md

@@ -0,0 +1,352 @@
+<div align="center">
+  <img src="docs/assets/images/robot_lab-to.jpg" alt="robot_lab-to" width="320"><br />
+  "Robot, takeover!"
+</div>
+
+# robot_lab-to
+
+**Autonomous overnight agent loop for [RobotLab](https://github.com/MadBomber/robot_lab) — run a robot while you sleep.**
+
+`robot_lab-to` ("takeover") runs a RobotLab `Robot` in an autonomous loop toward a
+stated objective, committing **one focused change per iteration**. Each iteration
+spins up a fresh robot, lets it work, and asks it to report a result. Good
+iterations are committed; failures are rolled back. A running log (`notes.md`)
+carries memory across iterations so the robot learns from what came before.
+
+Start it before bed; review the branch in the morning.
+
+```bash
+robot-to "Increase test coverage of the parser to 90%" \
+  --max-iterations 20 \
+  --verify-command "bundle exec rake test"
+```
+
+> 📖 **Full documentation:** <https://madbomber.github.io/robot_lab-to>
+
+---
+
+## How it works
+
+Every iteration is an independent, sandboxed attempt at *one* improvement. The
+orchestrator owns the git history and the stop conditions; the robot owns the
+work.
+
+1. **Build a fresh robot** with a per-iteration system prompt that includes the
+   objective and the accumulated notes.
+2. **The robot works** and calls `submit_iteration_result` to report success or
+   failure.
+3. **The orchestrator decides** — an independent `--verify-command` (if set) must
+   pass, then the change is committed. Otherwise the working tree is reset
+   (`git reset --hard`).
+4. **Notes are updated** with what happened, becoming context for the next round.
+5. **Stop conditions are checked** — iterations, tokens, consecutive failures, or
+   a natural-language `--stop-when` — and the loop continues or ends.
+
+---
+
+## Scoring: evals
+
+By default a "good" iteration is one the robot *reports* as success (and that
+passes `--verify-command`, if set). That works for "don't break the build," but it
+can't answer *"is this actually better?"* — and an agent will happily report
+success on a change that made no real progress. An **eval** replaces the robot's
+self-report with an orchestrator-owned, measurable judgement, and makes the loop
+**descend toward a target** instead of merely not-breaking.
+
+Two built-in evals cover the two kinds of product.
+
+### Code — measured descent
+
+For software, "better" is measurable. Give the loop a **measure** command that
+prints a number (higher = better), and optionally a **target**:
+
+```bash
+robot-to "Raise parser coverage to 90%" \
+  --verify  "bundle exec rake test" \      # floor: must stay green (correctness)
+  --measure "bundle exec rake coverage" \  # descent signal (higher = better)
+  --target  90                             # stop once the score reaches this
+```
+
+An iteration is committed only if it **improves** the measured score *and* the
+verify floor still passes; a change that scores no better is rolled back, so the
+branch descends monotonically and the run stops itself when the target is met.
+Relax the monotonic gate with `--no-require-improvement`.
+
+### Prose — pairwise judgement
+
+For a document, an opinion piece, or a book there is no `rake coverage`. The
+**prose** eval scores each draft with an LLM judge that compares it *pairwise*
+against the last committed version — an LLM's absolute scores are too noisy to
+descend, but "is B better than A?" is reliable:
+
+```bash
+robot-to "Write an opinionated guide to the Viable Systems Model" \
+  --eval  prose \
+  --spec  outline.md \          # the spec the judge measures against
+  --floor "rake docs:lint" \    # optional mechanizable checks (links, TODOs)
+  --stop-on-plateau 3           # stop after 3 drafts with no improvement
+```
+
+A draft is committed only when the judge rules it **better** than its parent.
+There is no absolute target, so the run ends on `--stop-on-plateau` (N drafts with
+no improvement) or when you stop it.
+
+### Guarding the grader
+
+Whatever the eval, the robot must not be able to "win" by editing the criteria it
+is scored against. The **spec** and any `--protect-path` files are locked for the
+whole run — write/edit/bash attempts against them are refused. (The code test
+suite is deliberately *not* locked; adding tests is legitimate work.)
+
+### Custom evals
+
+Point `--eval` at a strategy registered with `RobotLab::To.register_eval`, or in
+Ruby pass any object responding to `#score(context)` (or a proc) as `eval:`. See
+`RobotLab::To::Evals::Base`.
+
+---
+
+## Human-in-the-loop: decision files
+
+The loop runs unattended, so it can't stop and ask you a question the way a chat
+agent can. Instead, when the robot hits a choice it **shouldn't make on its own**
+— an irreversible change, a public API contract, a genuine ambiguity about intent
+— it calls `request_decision` and the orchestrator writes a **decision file**:
+the situation, the options, and the robot's own recommendation (its "lean").
+
+A decision file is plain markdown with YAML front matter, under the run directory:
+
+```markdown
+---
+id: d-20260701-143022-a1b2c3
+status: pending          # you change this to: resolved
+blocking: true
+resolution:              # you fill this in
+---
+# Decision: Return 404 or 410 for deleted records?
+
+## Options
+1. 404 Not Found
+2. 410 Gone
+
+## Recommendation (robot's lean)
+Option 2 (410 Gone) — the records are permanently deleted...
+```
+
+You resolve it out-of-band by editing the file: set `status: resolved` and fill
+`resolution:`. The robot reads your answer on a later iteration and acts on it.
+
+List what's waiting on you:
+
+```bash
+robot-to decisions              # pending decisions for the latest run
+robot-to decisions <run_id>     # ...for a specific run
+```
+
+**Blocking decisions** gate the loop until you answer, in one of two modes:
+
+- `--decision-mode wait` (default) — the process stays alive and polls the
+  decision file until you resolve it (or `--decision-timeout` elapses).
+- `--decision-mode exit` — the process commits its safe work and **stops**,
+  telling you how to resume. Ideal for cron: nothing runs until you decide.
+
+### Resuming a run (and cron scheduling)
+
+Every run persists its state to `run.json`, so a stopped run can be continued on
+the same branch:
+
+```bash
+robot-to --resume <run_id>
+```
+
+This makes `robot_lab-to` schedulable — a cron entry that runs
+`robot-to --resume <run_id>` each hour advances the work or re-pauses on the next
+open decision, one commit at a time.
+
+---
+
+## Installation
+
+Requires **Ruby >= 3.2** and a git repository with at least one commit.
+
+```bash
+gem install robot_lab-to
+```
+
+Or in a `Gemfile`:
+
+```ruby
+gem "robot_lab-to"
+```
+
+This installs the `robot-to` executable.
+
+---
+
+## Quick start
+
+```bash
+cd my-project
+git commit --allow-empty -m "initial"   # the loop needs a HEAD to branch from
+
+robot-to "Add a CHANGELOG.md and document the public API in the README" \
+  --max-iterations 5 \
+  --provider anthropic \
+  --model claude-sonnet-4-6
+```
+
+The loop creates a `robot-to/<slug>-<timestamp>` branch and commits one focused
+change per successful iteration. Review it in the morning:
+
+```bash
+git log --oneline robot-to/...     # one commit per iteration
+git diff main..HEAD                # the full change
+cat .robot_lab_to/runs/*/notes.md  # the reasoning log
+```
+
+### Programmatic use
+
+```ruby
+require "robot_lab"
+require "robot_lab/to"
+
+RobotLab::To.run(
+  "Add a CHANGELOG.md and document the public API",
+  provider: :anthropic,
+  model: "claude-sonnet-4-6",
+  max_iterations: 5,
+  verify_command: "bundle exec rake test"
+)
+```
+
+---
+
+## Key features
+
+- **Bounded, reviewable history** — each iteration is a single commit; bad
+  attempts are reset before the next try.
+- **Cross-iteration memory** — `notes.md` records summaries, changes, and
+  learnings so the robot doesn't repeat itself.
+- **Independent verification** — the robot can't self-certify success; a real
+  command you choose (`--verify-command`) is the deciding authority.
+- **It stops on its own** — `--max-iterations`, `--max-tokens`,
+  `--max-consecutive-failures`, and a natural-language `--stop-when`.
+- **Asks before overstepping** — the robot escalates irreversible or ambiguous
+  choices as **decision files** you resolve out-of-band, instead of guessing.
+- **Resumable & cron-friendly** — run state is persisted to `run.json`;
+  `robot-to --resume <run_id>` continues a stopped run, so 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 to drive a local Ollama model offline.
+
+---
+
+## Local models
+
+`robot_lab-to` can drive a local model running offline against
+[Ollama](https://ollama.com) — no API keys, no per-token cost.
+
+```bash
+ollama pull gpt-oss:20b
+
+robot-to "Add a greet(name) method in greeter.rb" \
+  --provider openai \
+  --model gpt-oss:20b \
+  --local-guards \
+  --no-stream \
+  --max-iterations 5
+```
+
+`--local-guards` attaches built-in `read`/`write`/`edit`/`bash` tools plus
+guardrail hooks (`write-guard`, `read-before-edit`, `checkpoint`,
+`quality-monitor`) adapted from [`little-coder`](https://github.com/itayinbarr/little-coder)
+that catch the mistakes small models reliably make. `--no-stream` is required —
+Ollama suppresses tool calls when streaming, and `:openai` is used as the
+provider against Ollama's OpenAI-compatible endpoint.
+
+See the [Local Models guide](https://madbomber.github.io/robot_lab-to/local-models/)
+for the full setup, including the RubyLLM configuration and model selection.
+
+---
+
+## Configuration
+
+Settings cascade from lowest to highest precedence:
+
+```
+bundled defaults → ~/.config/robot_lab/to.yml → ROBOT_LAB_TO_* env → CLI flags
+```
+
+Run `robot-to --help` for all flags, or see the
+[Configuration reference](https://madbomber.github.io/robot_lab-to/configuration/settings/).
+
+### Environment variables
+
+Every persistent setting can be set with a `ROBOT_LAB_TO_*` environment variable
+(integers and booleans are coerced automatically). An env var overrides the
+bundled default and the user config file, but is overridden by a CLI flag.
+
+| Environment variable | Setting | Default |
+|----------------------|---------|---------|
+| `ROBOT_LAB_TO_PROVIDER` | LLM provider | `openai` |
+| `ROBOT_LAB_TO_MODEL` | Model identifier | `gpt-5.5` |
+| `ROBOT_LAB_TO_STREAM` | Stream responses (`--no-stream` to disable) | `true` |
+| `ROBOT_LAB_TO_LOCAL_GUARDS` | Attach file tools + small-model guardrails | `false` |
+| `ROBOT_LAB_TO_MAX_TOOL_ROUNDS` | Max tool-call rounds per iteration | `100` |
+| `ROBOT_LAB_TO_MAX_CONSECUTIVE_FAILURES` | Abort after N consecutive failures | `3` |
+| `ROBOT_LAB_TO_MAX_VERIFY_REPAIRS` | Repair-in-place attempts on verify failure | `2` |
+| `ROBOT_LAB_TO_MAX_RETRIES` | Retries for transient (e.g. API) errors | `2` |
+| `ROBOT_LAB_TO_MAX_SUBMIT_NUDGES` | Re-prompts when no result is submitted | `1` |
+| `ROBOT_LAB_TO_VERIFY_TIMEOUT` | Timeout (seconds) for `--verify-command` | `600` |
+| `ROBOT_LAB_TO_COMMIT_FORMAT` | `default` or `conventional` | `default` |
+| `ROBOT_LAB_TO_RUN_DIR` | Directory for run state | `.robot_lab_to` |
+| `ROBOT_LAB_TO_DECISIONS_ENABLED` | Offer the `request_decision` tool | `true` |
+| `ROBOT_LAB_TO_DECISION_MODE` | On a blocking decision: `wait` or `exit` | `wait` |
+| `ROBOT_LAB_TO_DECISION_WAIT_POLL` | Seconds between polls while waiting | `30` |
+| `ROBOT_LAB_TO_DEBUG` | Keep verbose provider logging enabled | `false` |
+
+```bash
+export ROBOT_LAB_TO_MODEL="gpt-oss:20b"
+export ROBOT_LAB_TO_LOCAL_GUARDS=true
+export ROBOT_LAB_TO_STREAM=false
+```
+
+> **Per-run settings have no env var.** `--max-iterations`, `--max-tokens`,
+> `--stop-when`, `--verify-command`, and `--decision-timeout` are intentionally
+> CLI-only (they default to "unset / no limit") and must be passed on the command
+> line or to `RobotLab::To.run`.
+
+### Provider credentials
+
+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/).
+
+---
+
+## Development
+
+```bash
+bundle install             # install dependencies
+bundle exec rake test      # run the test suite (SimpleCov coverage)
+bundle exec rubocop        # lint
+```
+
+Documentation is built with [MkDocs Material](https://squidfunk.github.io/mkdocs-material/):
+
+```bash
+mkdocs serve               # preview at http://127.0.0.1:8000
+mkdocs build               # render to site/
+```
+
+---
+
+## Contributing
+
+Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/);
+see `COMMITS.md`. See `CHANGELOG.md` for release history.
+
+## License
+
+Released under the [MIT License](https://opensource.org/licenses/MIT).