robot_lab-web 0.2.6

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 04b904262b238719fac85842e3ae48532e8bc31988c3323165fe19abf3c116b7
+  data.tar.gz: 6461c66fb622adb4874e7eced683247026d30655ad0e24ec708fb0030a306222
+SHA512:
+  metadata.gz: 98cabb7f7ea51eb42d84bc6750f5d2f47ca36d9bbd507dc095088ebd6bef4b1f15629f4599f852c71e94d7fb6b1ab1cdd9373a13cab71dd181ece556839f396b
+  data.tar.gz: 2b623bfb33bd537e499b36b937f092ae732bbdf2f5f2f827275b9824d52a70a7e6546333805132cec1882f0424a5cba419d9470e011cb4896f4cb09dc44219bb

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: Build MkDocs site
+        run: mkdocs build
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site
+          keep_files: true

data/.loki

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+# robot_lab-web — Sinatra + SSE web console for driving RobotLab robots.
+
+import_up "repo_dev.loki"
+
+class Tasks
+  @@gem_name ||= "robot_lab-web".freeze
+
+  header "robot_lab-web v#{gem_version} — web console (Sinatra + HTMX + SSE)"
+
+  desc "Start the web console (pass a boot file, e.g. asgard server examples/boot.rb)"
+  def server(*args)
+    sh "bundle exec ruby exe/robot_lab-web #{args.join(' ')}"
+  end
+end

data/.quality/reek_baseline.txt

@@ -0,0 +1,8 @@
+1	lib/robot_lab/web.rb
+1	lib/robot_lab/web/components/chat.rb
+1	lib/robot_lab/web/components/dashboard.rb
+1	lib/robot_lab/web/components/layout.rb
+1	lib/robot_lab/web/components/message.rb
+4	lib/robot_lab/web/event.rb
+1	lib/robot_lab/web/event_sink.rb
+1	lib/robot_lab/web/registry.rb

data/.rubocop.yml

@@ -0,0 +1,8 @@
+inherit_from: ../.rubocop-base.yml
+
+Style/FormatStringToken:
+  Enabled: false
+
+Lint/MissingSuper:
+  Exclude:
+    - 'lib/robot_lab/web/components/**/*'

data/CHANGELOG.md

@@ -0,0 +1,35 @@
+## [Unreleased]
+
+### Changed
+- Use **Falcon** as the application server (replacing Puma). Its async/fiber
+  reactor is the right fit for the long-lived SSE streams this console serves —
+  fiber-per-connection concurrency, verified with two interleaving streams. The
+  `exe` launches a single Falcon reactor; `config.ru` stays server-agnostic.
+- Style with **Tailwind CSS** (Play CDN) instead of hand-rolled CSS. The dark
+  theme is preserved; styles are Tailwind utilities composed via `@apply` so the
+  server-rendered and JS-built message bubbles share one definition.
+- Render views as **Phlex components** (replacing Slim) — `Layout`, `Dashboard`,
+  `Chat`, `Message`, `ErrorPage` — via `phlex-sinatra`, with inline SVG icons
+  from `phlex-icons-hero`. Drops the `slim` dependency.
+
+### Added
+- Core (Sinatra-free) surface: `RobotLab::Web::Event` (immutable, role-validated,
+  `to_h`/`from_h`), `ActivityLog` (bounded thread-safe ring buffer), `EventSink`
+  (thread-local capture), and `Registry` (in-memory robot registry).
+- `RobotLab::Web::StreamHook` — taps robot_lab's hook system and turns each
+  run/tool/error moment into an `Event` delivered to the current sink.
+- `RobotLab::Web.run(robot, message) { |event| ... }` — stream a run's events
+  from plain Ruby.
+- Token-delta streaming: `RobotLab::Web.run` passes a streaming block to the
+  robot, emitting a `:delta` event per RubyLLM content chunk so the reply renders
+  token by token. Deltas bypass the `ActivityLog`; the final `:robot` event still
+  carries the whole reply. The browser accumulates deltas into a live bubble.
+- Opt-in Sinatra app (`require "robot_lab/web/app"`): dashboard, chat page,
+  `POST /robots/:name/stream` (Server-Sent Events) and a non-streaming
+  `POST /robots/:name/chat` HTMX fallback. CSRF + hashed session secret +
+  cookie hardening + production boot guard.
+- `robot_lab-web` executable and `config.ru` launcher; `examples/boot.rb`.
+
+## [0.1.0] - 2026-06-20
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Dewayne VanHoozer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,96 @@
+# RobotLab::Web
+
+A Rails-free **web console for [robot_lab](../robot_lab)**: register your robots,
+chat with them from the browser, and watch each lifecycle event — tool calls,
+tool results, the final reply, errors — **stream in real time** over
+Server-Sent Events.
+
+It's the standalone counterpart to `robot_lab-rails`: one event stream, a
+Sinatra + HTMX front end, no Turbo and no Rails required.
+
+> ⚠️ **Developer tool.** The console is **unauthenticated by default**. Run it on
+> localhost or a trusted private network. It ships sensible hardening (CSRF with
+> constant-time compare, a hashed session secret, `httponly`/`SameSite` cookies,
+> a production boot guard) but is not meant to face untrusted users.
+
+## How it works
+
+`robot_lab-web` registers a per-run hook (`RobotLab::Web::StreamHook`) on
+robot_lab's own hook system. As a robot runs, the hook turns each moment into an
+immutable `RobotLab::Web::Event` and pushes it to the current sink — an SSE
+stream for the browser, or a plain array in tests. This is robot_lab's native
+equivalent of an `on_event:` callback.
+
+```
+browser ──POST /robots/:name/stream──▶ Sinatra App
+                                         └─ RobotLab::Web.run(robot, msg) { |event| write_sse }
+                                              └─ robot.run(msg, hooks: [StreamHook])
+                                                   └─ StreamHook ─emits─▶ EventSink ─▶ SSE frames
+```
+
+## Usage
+
+Write a boot file that builds your robots and registers each one:
+
+```ruby
+# my_robots.rb
+require "robot_lab"
+require "robot_lab/web"
+
+assistant = RobotLab.build(name: "assistant", system_prompt: "You are concise.")
+RobotLab::Web.register(assistant)
+```
+
+Launch the console (Falcon):
+
+```bash
+robot_lab-web my_robots.rb            # http://127.0.0.1:9292
+robot_lab-web --port 4567 my_robots.rb
+```
+
+…or point Falcon (or any Rack server) at the server-agnostic `config.ru`:
+
+```bash
+ROBOT_LAB_WEB_BOOT=my_robots.rb falcon serve -c config.ru
+```
+
+Then open the dashboard, pick a robot, and chat. (Running a robot needs the
+provider key for its model, e.g. `ANTHROPIC_API_KEY`.)
+
+### Consuming the stream from Ruby
+
+The same path the web routes use is available directly — handy for tests or a
+custom front end:
+
+```ruby
+RobotLab::Web.run(assistant, "Hello") do |event|
+  puts "#{event.role}: #{event.text}"
+end
+```
+
+## Endpoints
+
+| Method | Path                     | Purpose                                              |
+|--------|--------------------------|------------------------------------------------------|
+| GET    | `/`                      | Dashboard: registered robots + recent activity       |
+| GET    | `/robots/:name`          | Chat page for a robot                                 |
+| POST   | `/robots/:name/stream`   | Run a task, stream events as SSE (`message`/`done`/`error`) |
+| POST   | `/robots/:name/chat`     | Non-streaming fallback; returns rendered transcript HTML |
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies, then
+`rake test`. The core (event model, activity log, sink, stream hook) is
+pure-Ruby and unit-tested in isolation; the Sinatra app is covered with
+`rack-test`.
+
+Views are **Phlex components** (`lib/robot_lab/web/components/`), rendered in
+Sinatra via `phlex-sinatra`, styled with Tailwind, with Heroicons from
+`phlex-icons-hero`.
+
+The Sinatra stack is opt-in: `require "robot_lab/web"` loads only the core;
+`require "robot_lab/web/app"` (or `RobotLab::Web.app`) pulls in Sinatra/Falcon/Phlex.
+
+## License
+
+Available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb', 'test/**/test_*.rb'].exclude('**/*_helper.rb')
+  t.verbose = true
+  t.ruby_opts << '-rtest_helper'
+end
+
+task default: :test
+
+desc 'Run tests with verbose output'
+task :test_verbose do
+  ENV['TESTOPTS'] = '--verbose'
+  Rake::Task[:test].invoke
+end
+
+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/config.ru

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Server-agnostic Rack entry point for robot_lab-web. Falcon is the default
+# server (see exe/robot_lab-web), but any Rack server can run this file:
+#
+#   falcon serve -c config.ru          # boots the console at localhost:9292
+#
+# By default no robots are registered. Point ROBOT_LAB_WEB_BOOT at a Ruby file
+# that requires robot_lab, builds your robots, and calls RobotLab::Web.register
+# on each — it is loaded here before the app starts.
+#
+#   ROBOT_LAB_WEB_BOOT=./my_robots.rb falcon serve -c config.ru
+
+require 'robot_lab/web'
+
+boot = ENV.fetch('ROBOT_LAB_WEB_BOOT', nil)
+require File.expand_path(boot) if boot && File.exist?(boot)
+
+run RobotLab::Web.app

data/docs/api_reference.md

@@ -0,0 +1,173 @@
+# API Reference
+
+Every public class, module, and method in `robot_lab-web`. See [How It Works](how_it_works.md) for the concepts behind each one.
+
+## `RobotLab::Web` (module)
+
+### `register(robot, name: nil) → String`
+
+Registers `robot` (anything responding to `#run` and `#name`) so the console can list and drive it. Returns the string key it was stored under. Delegates to `Registry.register`.
+
+```ruby
+RobotLab::Web.register(assistant)
+RobotLab::Web.register(assistant, name: "support")
+```
+
+### `run(robot, message, sink = nil, &block) → RobotResult`
+
+Runs `robot` against `message`, delivering each lifecycle `Event` to `sink` (or `block`, if `sink` is omitted) as it happens, and returning the robot's `RobotResult` once the run completes. This is the one call both Sinatra routes wrap, and the cleanest way to consume the stream from plain Ruby or a test. See [How It Works — `RobotLab::Web.run`](how_it_works.md#robotlabwebrun-the-one-call-that-ties-it-together) for exactly what it wires up.
+
+```ruby
+events = []
+RobotLab::Web.run(assistant, "hello") { |event| events << event }
+```
+
+### `app → RobotLab::Web::App`
+
+Lazily requires `"robot_lab/web/app"` (pulling in Sinatra/Falcon/Phlex on first call) and returns the `App` class — a Rack app, suitable for `run RobotLab::Web.app` in a `config.ru`.
+
+### `Error`
+
+`RobotLab::Web::Error < StandardError` — reserved for gem-specific error conditions. Not currently raised by any code path in this gem's own logic.
+
+---
+
+## `RobotLab::Web::Event`
+
+```ruby
+Event = Struct.new(:role, :content, :robot_name, :timestamp, :event_id, keyword_init: true)
+```
+
+Immutable (deep-frozen on construction). See [How It Works — The Event Model](how_it_works.md#the-event-model) for the full role/content table.
+
+### `new(role:, content:, robot_name: nil, timestamp: nil, event_id: nil)`
+
+Raises `ArgumentError` if `role` isn't one of `Event::ROLES` (`:user`, `:delta`, `:robot`, `:tool_call`, `:tool_result`, `:error`). `timestamp` defaults to `Time.now.utc`; `event_id` defaults to `SecureRandom.uuid`.
+
+### Readers
+
+`role`, `content`, `robot_name`, `timestamp`, `event_id` — plain `Struct` readers.
+
+### `tool_name → String, nil`
+
+`content[:name]`/`content['name']` when `content` is a Hash (works for both `:tool_call` and `:tool_result`); `nil` otherwise.
+
+### `error? → Boolean`
+
+`true` when `role == :error`.
+
+### `error_message → String, nil`
+
+`content[:message]`/`content['message']` (or `content.to_s` for a non-Hash) when `error?`; `nil` otherwise.
+
+### `text → Object`
+
+A role-agnostic display value: for Hash content, `content[:result] || content[:message] || content[:args] || content`; for anything else, `content` itself unchanged.
+
+### `to_h → Hash`
+
+`{role:, content:, robot_name:, timestamp: (ISO 8601, ms precision), event_id:}` — JSON-serializable.
+
+### `self.from_h(hash) → Event, nil`
+
+Rebuilds an `Event` from a Hash with either symbol or string keys (as produced by parsing JSON). Returns `nil` instead of raising if the role fails validation.
+
+---
+
+## `RobotLab::Web::EventSink` (module)
+
+The thread-local hook-to-consumer bridge. See [How It Works](how_it_works.md#eventsink-a-thread-local-mailbox).
+
+### `capture(sink) { ... } → Object`
+
+Installs `sink` (anything responding to `#call`) as the current consumer for the duration of the block, restoring whatever was previously installed (supports nesting) once the block returns or raises.
+
+### `current → #call, nil`
+
+The sink installed by the innermost enclosing `capture` call on this thread, or `nil`.
+
+### `emit(event) → void`
+
+Delivers `event` to `current` if one is installed. Any `StandardError` the sink raises is caught and discarded — a broken consumer must never break the run it's observing.
+
+---
+
+## `RobotLab::Web::ActivityLog`
+
+A thread-safe, bounded ring buffer. See [How It Works](how_it_works.md#activitylog).
+
+### Class methods (delegate to a process-wide singleton, `ActivityLog.instance`)
+
+| Method | Description |
+|---|---|
+| `log(type, details = {})` | Records an entry (`{type:, details:, timestamp:}`); raises if `type`/`details` are malformed |
+| `safe_log(type, details = {})` | Same, but swallows any error — use this from instrumentation paths |
+| `recent(limit = 10)` | The `limit` most recent entries, newest first |
+| `clear` | Empties the log |
+
+### Instance
+
+`MAX_EVENTS = 50` — the ring buffer's capacity; oldest entries are dropped once exceeded. `#log`/`#recent`/`#clear` are the same operations, mutex-guarded, on a fresh instance if you don't want the process-wide singleton (mainly useful in tests).
+
+---
+
+## `RobotLab::Web::Registry` (module)
+
+An in-memory `Hash` of registered robots, keyed by name. See [How It Works](how_it_works.md#registry).
+
+### `Registry.register(robot, name: nil) → String`
+
+Stores `robot` under `(name || robot.name).to_s`, returning that key.
+
+### `fetch(name) → robot, nil`
+
+Looks up a registered robot by name (coerced to `String`).
+
+### `names → Array<String>`
+
+All registered names, alphabetically sorted.
+
+### `all → Array`
+
+All registered robot objects, in insertion order.
+
+### `clear → void`
+
+Empties the registry — mainly useful in tests.
+
+---
+
+## `RobotLab::Web::StreamHook`
+
+`RobotLab::Hook` subclass, `namespace = :web_stream`. See [How It Works — The Hook-to-Sink Bridge](how_it_works.md#the-hook-to-sink-bridge) for the full callback table. Not instantiated directly — registered per-run via `robot.run(message, hooks: [RobotLab::Web::StreamHook])`, which is exactly what `RobotLab::Web.run` does for you.
+
+---
+
+## `RobotLab::Web::App` *(requires `"robot_lab/web/app"`)*
+
+A `Sinatra::Base` subclass — a Rack app. See [Security](security.md) for the session/CSRF/host-authorization configuration, and [How It Works — The SSE Wire Protocol](how_it_works.md#the-sse-wire-protocol) for the streaming route's frame format.
+
+| Route | Behavior |
+|---|---|
+| `GET /` | Renders `Components::Dashboard` with `Registry.names` and `ActivityLog.recent(15)` |
+| `GET /robots/:name` | 404s (via `Components::ErrorPage`) if unregistered; else renders `Components::Chat` |
+| `POST /robots/:name/stream` | SSE stream of one run — see [How It Works](how_it_works.md#the-sse-wire-protocol) |
+| `POST /robots/:name/chat` | Runs to completion, returns rendered transcript HTML fragments (delta events excluded) |
+
+`self.session_secret_source` / `self.persisted_dev_secret` — the session-secret resolution logic; see [Security — Session Secret](security.md#session-secret-persistence).
+
+---
+
+## `RobotLab::Web::Components` *(requires `"robot_lab/web/app"`)*
+
+Phlex (`Phlex::HTML`) view components, each a small, focused constructor + `view_template`:
+
+| Component | Constructor | Renders |
+|---|---|---|
+| `Layout` | `new(csrf:, content:)` | The HTML document shell — Tailwind CDN + shared styles, top nav, and the wrapped page `content` |
+| `Dashboard` | `new(robots:, activity:)` | Registered robot list + recent-activity feed |
+| `Chat` | `new(name:)` | The transcript container, composer form, and the inline vanilla-JS SSE streaming client |
+| `Message` | `new(event:)` | One transcript message from an `Event` — used server-side by the non-streaming `/chat` fallback |
+| `ErrorPage` | `new(message:)` | The 404 page body |
+
+These aren't meant to be used outside `App` itself, but are documented here since they're real, independently-instantiable public classes (not `private_constant`).

data/docs/getting_started.md

@@ -0,0 +1,95 @@
+# Getting Started
+
+## Prerequisites
+
+- Ruby 3.2+ (per the gemspec's `required_ruby_version`)
+- `robot_lab` — a hard dependency; `robot_lab/web` requires it directly (see [How It Works — Core vs. Opt-In Web Stack](how_it_works.md#core-vs-opt-in-web-stack)), so load order relative to your own `require "robot_lab"` never matters
+- A provider API key for whatever model your robots use (e.g. `ANTHROPIC_API_KEY`) — the console itself needs no credentials, but actually running a robot through it does
+
+## Installation
+
+```ruby
+gem "robot_lab"
+gem "robot_lab-web"
+```
+
+```sh
+bundle install
+```
+
+## Writing a Boot File
+
+A boot file just builds your robots and registers each one — the console reads this registry to list and drive them:
+
+```ruby
+# my_robots.rb
+require "robot_lab"
+require "robot_lab/web"
+
+assistant = RobotLab.build(name: "assistant", system_prompt: "You are a concise, friendly assistant.")
+RobotLab::Web.register(assistant)
+
+# Register as many as you like:
+# RobotLab::Web.register(RobotLab.build(name: "support", template: :support))
+```
+
+`register(robot, name: nil)` keys the robot by `name:` if given, otherwise by `robot.name` — see [API Reference](api_reference.md#registryregisterrobot-name-nil-string).
+
+## Launching the Console
+
+**Via the bundled executable** (Falcon, the default server):
+
+```sh
+robot_lab-web my_robots.rb                # http://127.0.0.1:9292
+robot_lab-web --port 4567 my_robots.rb    # custom port
+robot_lab-web --host 0.0.0.0 my_robots.rb # custom bind host
+```
+
+**Or via `config.ru`**, with any Rack server (the app itself is server-agnostic — `exe/robot_lab-web` picks Falcon specifically for its async/fiber reactor, but nothing about the Sinatra app requires it):
+
+```sh
+ROBOT_LAB_WEB_BOOT=my_robots.rb falcon serve -c config.ru
+```
+
+`ROBOT_LAB_WEB_BOOT` (or the boot file argument to the executable) is required by path before the app starts — `config.ru`/`exe/robot_lab-web` both check `File.exist?(boot)` and simply skip loading it if the path doesn't resolve, so a typo'd path silently produces a console with zero registered robots rather than an error.
+
+Then open the dashboard, pick a robot, and start chatting.
+
+## Running from a Source Checkout
+
+If you're working inside a clone of `robot_lab-web` itself (rather than the installed gem), `exe/robot_lab-web` calls `require 'bundler/setup'` when it finds a `Gemfile` sitting beside it — this is what resolves the gem's own `lib` and its dependencies, including a local `robot_lab` path dependency during development (see `Gemfile.local`). Run it from the gem's own directory (or via `bundle exec`) so that path resolution works; an installed gem has no adjacent `Gemfile` and falls through to plain RubyGems resolution instead.
+
+## Consuming the Stream from Ruby
+
+The same path the web routes use is available directly — useful in tests, a script, or a custom front end that isn't the bundled Sinatra app:
+
+```ruby
+require "robot_lab"
+require "robot_lab/web"
+
+RobotLab::Web.run(assistant, "Hello") do |event|
+  puts "#{event.role}: #{event.text}"
+end
+```
+
+This doesn't touch Sinatra/Falcon/Phlex at all — see [How It Works](how_it_works.md#core-vs-opt-in-web-stack) for exactly what loading `"robot_lab/web"` alone gives you versus `"robot_lab/web/app"`.
+
+## The Four Endpoints
+
+| Method | Path | Purpose |
+|---|---|---|
+| `GET` | `/` | Dashboard: registered robots + a recent-activity feed |
+| `GET` | `/robots/:name` | Chat page for one robot |
+| `POST` | `/robots/:name/stream` | Run a task, stream events as Server-Sent Events (`message`/`done`/`error` frames) |
+| `POST` | `/robots/:name/chat` | Non-streaming fallback — runs to completion and returns rendered transcript HTML fragments (for HTMX `hx-swap="beforeend"`-style appending) |
+
+See [How It Works](how_it_works.md#the-sse-wire-protocol) for the exact frame format and why the streaming route can't just be a plain `EventSource`.
+
+## Development
+
+```sh
+bin/setup    # install dependencies
+rake test    # run the test suite
+```
+
+The core (event model, activity log, sink, stream hook) is pure Ruby and unit-tested in isolation; the Sinatra app is covered with `rack-test`.