ruby_llm-browser 0.1.0 → 0.2.0

data/docs/RELEASE_ACTION_PLAN.md

@@ -7,26 +7,41 @@ llms: false
 
 # Release action plan
 
+This is the historical 0.1.0 release record. Use the
+[roadmap to 1.0]({% link _reference/roadmap.md %}) for upcoming development.
+
 The owner selected the offline-only first release as `0.1.0`, authorized its publication,
-and requested tag-based release automation. This plan preserves the live-provider limits
-and records the release checks.
+and requested tag-based release automation. Version `0.1.0` is published. This plan records
+the outcome and preserves the live-provider limits for future work.
 
 ## Current position
 
-- Hardening baseline: `0ec34d4`.
-- Expanded remote CI is green: seven test jobs and the package/install/advisory job.
+- Hardening baseline: `0ec34d4`; release workflow fix: `8f0e8e7`.
+- Expanded remote CI passed before release. Tagged verification and publication passed in
+  [release run 39110148539](https://github.com/yorzi/ruby_llm-browser/actions/runs/39110148539).
+- RubyGems lists [ruby_llm-browser 0.1.0](https://rubygems.org/gems/ruby_llm-browser).
+  Publication used the registered trusted publisher for `yorzi/ruby_llm-browser`,
+  `.github/workflows/release.yml`, and environment `release`; MFA publication is recorded.
+- The [GitHub Release](https://github.com/yorzi/ruby_llm-browser/releases/tag/v0.1.0)
+  includes the gem and `SHA256SUMS`. The gem SHA-256 is
+  `0159bf5b4d50fc1a5d129ce8e6d8235ff9a5181704d5e8168c2facb429808ed3`.
+- The post-release Pages build passed in
+  [Docs run 39110265391](https://github.com/yorzi/ruby_llm-browser/actions/runs/39110265391).
+  The [custom-domain docs site]({% link index.md %}) shows `0.1.0 (stable)`.
+- The first publish attempt failed before upload because the action's optional
+  experimental attestation patch activated Ruby's default zlib before Bundler. The
+  unpublished tag was moved to a fix that disables that patch; OIDC publication remains.
 - Owner decision on 2026-10-18: first release is read-only; defer live Act and mark the
   built-in Stagehand backend unsupported until egress and cleanup are qualified.
 - No live provider calls are authorized or were run for this decision.
 - Independent H1 and owner H2 are complete for exact candidate Q
   `22d488987517b10dcd96d2713ed3d47e8818b36b`. H2 approves handoff, not RubyGems publication.
-- The RubyGems page for `ruby_llm-browser` returned 404 during the pre-release check on
-  2026-10-18; that did not reserve the name. The resolved 26-gem runtime license inventory
-  matches installed gemspec metadata; Stagehand is covered by its pinned source MIT text.
-- The owner later instructed publication of gem version `0.1.0`; that instruction is
-  separate from H2's handoff approval. RubyGems MFA is enabled on the signed-in publisher
-  account. Trusted publishing must match this repository's `release.yml` workflow and
-  `release` environment.
+- The pre-release exact-name check returned 404 on 2026-10-18; it did not reserve the
+  name. Version `0.1.0` is now registered on RubyGems. The resolved 26-gem runtime license
+  inventory matches installed gemspec metadata; Stagehand is covered by its pinned source
+  MIT text.
+- The owner instructed publication separately from H2's handoff approval. The gem requires
+  MFA, and RubyGems records the successful publication as MFA-protected.
 
 ## Release scope
 
@@ -42,9 +57,9 @@ exact Q `22d488987517b10dcd96d2713ed3d47e8818b36b`; the approved Specs candidate
 | --- | --- | --- |
 | Release scope / Act | H2 approved the read-only scope and KPI proposal against exact Q. Live Act remains a later-version feature. | Keep the Stagehand adapter disabled and preserve the H2 decision in release docs. |
 | Provider qualification | No live call is authorized for the first release. A later live release needs a named deployment and approval of data-processing/billing owners. | Record the unsupported egress and cleanup guarantees. Do not use a host assertion as qualification. |
-| Name and account | The owner authorized publication as `ruby_llm-browser`; the account has MFA enabled. | Recheck name availability at publication and use the pending trusted publisher configured for this repo and workflow. |
+| Name and account | The owner authorized publication as `ruby_llm-browser`; version `0.1.0` is registered and MFA-protected. | Use the existing trusted publisher for future tags; do not add a long-lived RubyGems API key to GitHub. |
 | Formal approval | H1 and H2 are complete for exact Q; C/R registration and implementation baseline receipt remain pending. | Preserve the historical approval. Do not represent H2 as RubyGems authorization; the owner's later release instruction supplies that authorization. |
-| Publication | Owner instructed publication of package version `0.1.0`. | Verify the matching tag, run the release workflow, then record the RubyGems, GitHub Release and Pages outcomes. |
+| Publication | Version `0.1.0` is published under tag `v0.1.0`; GitHub Release assets and stable Pages are live. | For each later version, align gem/docs/changelog metadata and push the matching tag. The release workflow verifies tests, advisories and package contents before OIDC publishing; Docs deploys after success. |
 
 ## Provider questions to resolve before live tests
 

data/docs/RELEASE_AUDIT.md

@@ -156,3 +156,22 @@ does not authorize provider calls, make Stagehand supported, or implement live A
 approved Specs Q remains identified by its historical candidate label `0.3.0-draft`.
 RubyGems publication and GitHub Pages deployment results are recorded separately from
 this pre-release audit snapshot.
+
+## Publication outcome (2026-10-18)
+
+The owner authorized publishing the offline-only `0.1.0` package after the earlier audit
+snapshot. The RubyGems trusted publisher is registered for repository `yorzi/ruby_llm-browser`,
+workflow `release.yml`, and environment `release`. The corrected tagged workflow
+[39110148539](https://github.com/yorzi/ruby_llm-browser/actions/runs/39110148539) passed
+tagged-package verification and published the gem with GitHub OIDC. RubyGems lists
+[version 0.1.0](https://rubygems.org/gems/ruby_llm-browser), published with MFA metadata;
+the [GitHub Release](https://github.com/yorzi/ruby_llm-browser/releases/tag/v0.1.0)
+contains the gem and checksum. The custom-domain [documentation site]({% link index.md %})
+is deployed and shows `0.1.0 (stable)`.
+
+The first tag run, [39109944660](https://github.com/yorzi/ruby_llm-browser/actions/runs/39109944660),
+failed before upload because the action's optional experimental attestation patch loaded
+RubyGems before Bundler and activated Ruby's default zlib. The unpublished tag was moved
+to a workflow fix that disables that optional patch; OIDC publishing remains active.
+This release does not close provider qualification: no live egress, TTL, billing, or
+cleanup calls were made. Stagehand remains unsupported, and full live Act remains deferred.

data/docs/RELEASING.md

@@ -47,6 +47,7 @@ BUNDLE_GEMFILE=gemfiles/rails_8_0.gemfile bundle install
 BUNDLE_GEMFILE=gemfiles/rails_8_0.gemfile bundle exec rspec
 
 bundle exec rake build
+bin/verify-release --candidate # for unreleased development candidates
 bundle exec ruby bin/verify-package --rails --audit
 ```
 
@@ -101,10 +102,16 @@ made for `0.1.0`.
 ## Releasing a version
 
 For a later version, update the gem version in `lib/ruby_llm/browser/version.rb` and the
-documentation version in `docs/_config.yml` to the same value. Keep `released: false` on
-`main`; the documentation builder uses release tags for the stable site and builds the
-working tree under `/next/`. Add a matching release entry to `CHANGELOG.md` and
-`docs/_reference/release-history.md`.
+documentation version in `docs/_config.yml` to the same value. Keep `released: false`
+while preparing a candidate. Set it to `true` and update `stable_version` when the
+owner authorizes a release. The documentation builder uses release tags
+for the stable site and builds the working tree under `/next/`. Add a matching release
+entry to `CHANGELOG.md` and `docs/_reference/release-history.md`.
+
+During candidate development, keep changes under `Unreleased` in the changelog and
+run `bin/verify-release --candidate`. Before tagging, move them to a dated release
+section and run `bin/verify-release` without that flag. The tag workflow requires
+released metadata; local candidate verification cannot enable publication.
 
 Run the checks above, review the package contents and push the completed commit to
 `main`. Then create and push a matching tag, for example `v0.2.0` for gem version
@@ -127,5 +134,5 @@ workflow `release.yml`, and environment `release` before the first tag.
 ## Next steps
 
 - Review the requirement evidence in the source repository's `docs/WORK.md` and the [remaining audit findings]({% link RELEASE_AUDIT.md %}).
-- Follow the source repository's `docs/RELEASE_ACTION_PLAN.md` for the selected scope and
-  future version workflow.
+- Follow the [roadmap to 1.0]({% link _reference/roadmap.md %}) for proposed version scope.
+  The source repository's `docs/RELEASE_ACTION_PLAN.md` preserves the 0.1.0 release record.

data/docs/SECURITY_MODEL.md

@@ -113,5 +113,5 @@ qualification. Cleanup and TTL are best-effort, and cost values are advisory.
 
 ## Next steps
 
-- Follow [Rails recovery]({% link RAILS.md %}) to schedule cleanup and protect status access.
+- Follow [Rails recovery]({% link _advanced/rails-integration.md %}) to schedule cleanup and protect status access.
 - Review [the release audit]({% link RELEASE_AUDIT.md %}) for evidence and remaining blockers.

data/docs/WORK.md

@@ -242,6 +242,28 @@ the tag's stable documentation only after that release workflow succeeds. The fi
 is pushed only after the trusted publisher is registered for this repository and the
 `release.yml` workflow under the `release` GitHub environment.
 
+### 0.1.0 publication receipt (2026-10-18)
+
+The first tagged workflow run failed before the gem upload because the action's optional
+experimental attestation patch loaded RubyGems before Bundler and activated Ruby 3.3's
+default zlib instead of the locked patched zlib. No gem was published by that attempt.
+The release action now has attestations disabled; trusted OIDC publishing remains enabled.
+The unpublished `v0.1.0` tag was moved to the workflow-fix commit before retrying.
+
+| Check | Result |
+| --- | --- |
+| Tagged release workflow | PASS: [run 39110148539](https://github.com/yorzi/ruby_llm-browser/actions/runs/39110148539); tagged package verification and RubyGems publish jobs succeeded |
+| RubyGems | PASS: [ruby_llm-browser 0.1.0](https://rubygems.org/gems/ruby_llm-browser); published by `yorzi/ruby_llm-browser` via `.github/workflows/release.yml` and `release` environment; MFA publication is recorded |
+| Gem SHA-256 | `0159bf5b4d50fc1a5d129ce8e6d8235ff9a5181704d5e8168c2facb429808ed3` |
+| GitHub Release | PASS: [v0.1.0](https://github.com/yorzi/ruby_llm-browser/releases/tag/v0.1.0) contains the `.gem` file and `SHA256SUMS` |
+| Documentation Pages | PASS: [run 39110265391](https://github.com/yorzi/ruby_llm-browser/actions/runs/39110265391); the [custom-domain docs site]({% link index.md %}) shows `0.1.0 (stable)` |
+| Live provider egress, TTL, billing and cleanup | NOT RUN; Stagehand remains unsupported until provider qualification |
+| Full live Act protocol | NOT IMPLEMENTED; offline simulation only, deferred to a later version |
+
+The published gem metadata reports MFA publication. No long-lived RubyGems API key was
+added to GitHub; the release workflow uses the registered trusted publisher and GitHub
+OIDC. The first failed run was [39109944660](https://github.com/yorzi/ruby_llm-browser/actions/runs/39109944660).
+
 ## Commit log
 
 Small, meaningful commits land one piece at a time. See `git log` for the authoritative

data/docs/_advanced/development-and-testing.md

@@ -0,0 +1,100 @@
+---
+layout: default
+title: Development and Testing
+nav_order: 3
+description: Verify changes with offline contracts, installed packages, and a local browser workbench.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+
+After reading this guide, you will know:
+
+- How to run the local verification loop.
+- How to review browser behavior and retain fixture screenshots.
+- What offline, browser, and installed-package checks establish.
+
+## Run the Offline Checks
+
+```sh
+bin/setup
+bin/check
+```
+
+Start a behavior change with a focused failing spec. Implement the smallest public
+contract, update its guide, then run `bin/check`. The command runs specs and RuboCop,
+the RubyLLM 2.0 and Rails 8.0 alternate bundles, and the plain-Ruby and Rails examples.
+Install each alternate bundle first if needed. Database suites run sequentially.
+RuboCop uses the writable `tmp/rubocop` cache. Default tests block unmocked HTTP.
+
+Commit each completed change with its docs and checks. Keep the next work item in the
+[roadmap]({% link _reference/roadmap.md %}); do not create a second task ledger.
+
+## Review the Offline Workbench
+
+```sh
+BUNDLE_GEMFILE=gemfiles/browser.gemfile bundle install
+bin/workbench
+# Open http://127.0.0.1:4024, then Ctrl-C to stop.
+```
+
+The single fixture in `dev/workbench.rb` runs the real Ruby tools with FakeBackend,
+a deterministic resolver, and an in-memory operation store. Inspect and Extract show
+their returned hashes and fake start/cleanup counts. Enter an unapproved host to
+exercise a denial, run offline Doctor, or check that Stagehand remains blocked. The
+Stagehand diagnostic uses synthetic fixture credentials and never calls the provider.
+
+The host serves local HTML and CSS, escapes returned content, requires a form token,
+and accepts loopback Host values only. It is a development fixture, not a production
+controller or a new public gem API. It does not load the requested page or use provider
+credentials. The fixture and browser libraries are excluded from the gem.
+
+## Run Browser Tests
+
+```sh
+bin/check-browser
+# Or include browser tests after the offline checks:
+bin/check --browser
+```
+
+Use installed Chrome. `CHROME_BIN` can select its binary; `CHROMEDRIVER` can select an
+installed matching driver to avoid Selenium Manager's driver resolution. Screenshots
+go into the printed, ignored `tmp/browser/` directory. The runner fails if tests fail
+or no screenshot is produced. CI retains fixture screenshots for seven days.
+
+Browser scenarios cover inspect/extract, denial before dispatch, keyboard recovery at
+a 390px device viewport, and offline/blocked-Stagehand Doctor output. Capture screenshots before closing the
+active session, including on assertion failures. Inspect failure artifacts before
+retrying. Screenshots support visual review; assertions establish the expected behavior.
+
+The Puma host and Selenium port probe bind loopback. Browser test HTTP clients allow
+loopback only; this is not a Chrome network firewall. No live provider request is part
+of this suite. Tests close their driver sessions, and Puma ends with the test process.
+Stop manual previews and verify no task-owned service remains after your review.
+
+## Verify a Candidate Package
+
+```sh
+bin/check --browser --package
+bin/verify-release --candidate
+docs/bin/build.sh
+```
+
+The package option builds the gem and runs `bin/verify-package --rails --audit`. It
+installs into an empty GEM_HOME outside the checkout, resolves dependencies from the
+registry, runs shipped examples, tests the generated migration, and audits the activated
+runtime. Refresh the advisory database first with `bundle exec bundle-audit check --update`.
+Package verification needs registry access; offline test success cannot replace it.
+
+`bin/verify-release --candidate` checks version alignment, the Unreleased changelog,
+the unreleased docs flag, and package exclusions. Without `--candidate`, it requires
+released docs and a dated changelog; the tag workflow never passes the candidate flag.
+The install verifier copies the input artifact before testing and prints that snapshot's
+SHA-256. A later build cannot replace the file under verification.
+
+Record the exact artifact hash, dependency versions, checks, and not-run boundaries in
+the candidate validation note. Local browser tests prove fixture application wiring.
+They do not establish real provider egress, session TTL, cleanup, billing, external
+adoption, remote CI success, or publication. Follow the
+[release checklist]({% link RELEASING.md %}) before releasing.

data/docs/_advanced/live-backend-qualification.md

@@ -34,6 +34,11 @@ built-in Stagehand backend as unsupported: `egress_isolation` remains `:unverifi
 the Engine refuses to start a session. The host cannot override this status with a
 constructor option. A custom backend must enforce its own browser-side network boundary.
 
+The fake report has `mode: :offline` and skips provider credential and SDK checks.
+Stagehand reports `mode: :live` even though it remains unsupported; mode describes
+the backend, not its qualification. See [Checking Configuration]({% link _core_features/diagnostics.md %})
+for the report fields and checks applied to each backend.
+
 Browserbase's documented [Allowed Domains feature](https://docs.browserbase.com/platform/browser/security/allowed-domains)
 applies to top-frame navigations. It does not block iframe or subresource requests such
 as scripts, images, and XHR. That setting alone cannot qualify provider egress. Any future

data/docs/_advanced/rails-integration.md

@@ -1,56 +1,170 @@
 ---
 layout: default
-title: Running work in Rails
+title: Rails Jobs and Recovery
 nav_order: 1
-description: Run durable inspect and extract operations with the Rails 8 adapter.
+redirect_from:
+  - /RAILS/
+description: Run bounded read-only operations with durable state and independently scheduled cleanup.
 ---
 
-# {{ page.title }}
+# Rails jobs and recovery
 
-{{ page.description }}
-{: .fs-6 .fw-300 }
+Run bounded read-only operations with durable state and independently scheduled cleanup.
 
 After reading this guide, you will know:
 
-* Which framework versions and components the adapter expects.
-* How to install its tables.
-* What the host must own in background jobs and cleanup.
+- How to install the adapter's tables.
+- How to build a freshly authorized job context with matching budgets.
+- How to inspect status, cancel work, and recover orphaned sessions.
 
-## Install the Adapter
+## Installing the adapter
 
-The adapter is optional. Add Rails 8 Active Record and Active Job to the host application,
-then require the Rails entry point and install its migration:
+Your application supplies Rails 8, Active Record, Active Job, and a database adapter.
+They are not runtime dependencies of the plain-Ruby gem.
 
 ```ruby
 require "ruby_llm/browser/rails"
 ```
 
-```sh
+```bash
 bin/rails generate ruby_llm:browser:install
 bin/rails db:migrate
 ```
 
-The generator creates durable operation and approval tables plus per-actor reservation
-locks. The jobs accept `inspect` and `extract`; Act is not available in background jobs.
+The generator creates operations, approvals, and per-actor reservation-lock tables.
+SQLite and PostgreSQL are accepted by the store, but only SQLite concurrency is tested
+locally. MySQL is not supported by this adapter's partial indexes/locking contract.
+Use a database timeout appropriate to your workload. Database lock failures fail closed;
+they must not be handled by retrying a browser call with a new operation ID.
 
-## Keep Authorization in the Host
+`Schema.create!` is for disposable fixtures, not production migrations or schema upgrades.
+The [offline Rails example](https://github.com/yorzi/ruby_llm-browser/blob/main/examples/rails_adapter.rb) requires no full Rails app.
 
-The context factory runs in the worker and must reload trusted records, recheck actor and
-run authorization, and use the same operation store and budget limits as the reservation.
-Never put provider credentials or authorization decisions in model arguments or job
-payloads. Protect queue storage because URLs, instructions, and schemas are persisted.
+## Configuring the trusted context factory
 
-## Schedule Recovery
+```ruby
+# config/initializers/ruby_llm_browser.rb
+require "ruby_llm/browser/rails"
+
+browser_budget = RubyLLM::Browser::Budget.new(max_seconds: 30, max_steps: 6)
+RubyLLM::Browser::Rails.context_factory = lambda do |actor_id:, run_id:|
+  # Resolve authenticated host records and recheck authorization, consent and revocation.
+  # Build policy/backend from those records, never from job or model-supplied credentials.
+  RubyLLM::Browser::Context.new(
+    actor_id: actor_id, run_id: run_id,
+    backend: qualified_backend, source_policy: policy,
+    operation_store: RubyLLM::Browser::Rails.operation_store,
+    budget: browser_budget
+  )
+end
+```
+
+`qualified_backend` and `policy` above are host objects, not global APIs supplied by the
+gem. The factory must use the **same operation-store instance and budget limits** as
+the queued reservation. Construct different budgets per run only from trusted records
+that the factory can retrieve again. An optional approval store does not enable Act in
+jobs; `OperationJob` accepts only `inspect` and `extract`.
+
+## Enqueuing a read-only operation
+
+```ruby
+operation = RubyLLM::Browser::Rails::OperationJob.enqueue(
+  actor_id: current_user.id.to_s, run_id: research_run.id.to_s,
+  kind: :inspect, url: "https://docs.example.com/",
+  budget: browser_budget, idempotency_key: "research-#{research_run.id}"
+)
+```
+
+For extraction, pass `kind: :extract` and a host-pinned JSON `schema:`. Optional
+`instruction:` and `max_bytes:` have the same meaning as on the tools.
+
+One actor/run/key identifies one exact payload and budget. A changed payload using the
+same key is rejected. Repeated enqueue calls may add duplicate queue deliveries, but
+they attach to the same durable operation. Starting is atomically claimed once. A job
+that sees a started, unknown, pending-cleanup, or terminal operation cannot start it
+again. No automatic browser retry is configured.
+
+Reservation and queue insertion are separate transactions. If enqueueing fails, retain
+the returned operation identity when available and use the same idempotency key after
+investigation. Schedule the reaper to reclaim expired reservations that never started.
 
-Run `RubyLLM::Browser::Rails::Reaper` on a separate schedule. Worker cleanup alone cannot
-recover sessions left by a killed process. Do not free quota for an unknown or pending
-session based only on elapsed time. The job does not durably store result bodies, so the
-host must implement authorized result storage and delivery if it needs them.
+Configure `RubyLLM::Browser::Rails.job_queue = :browser` if you need a separate queue.
+Jobs suppress argument logging, but queues still persist URLs, instructions and schemas.
+Protect queue access, storage, retention and encryption in the host application.
+
+## Reading status and progress
+
+```ruby
+store = RubyLLM::Browser::Rails.operation_store
+operation = store.fetch!(operation_id)
+# Authorize this read against the authenticated actor/run before returning anything.
+summary = operation.summary
+```
+
+`summary` omits provider session IDs and budget internals. It reports state, steps,
+bytes, fence, timestamps, error code and cancellation flag. It is coarse progress,
+not a percentage-complete promise. No result body is durably stored by the job; the
+host must explicitly implement authorized result storage/delivery if needed. Do not
+rely on an Active Job return value after asynchronous execution.
+
+The stores are trusted server APIs, not tenant-safe controllers. They expose unscoped
+fetch/sweep methods for workers; never expose them directly to model arguments or HTTP.
+Tool progress callbacks are feature-detected on RubyLLM 2.1+, and contain no raw URL.
+
+## Cancelling and reaping
+
+```ruby
+store.cancel(operation_id, actor_id: current_user.id.to_s,
+             run_id: research_run.id.to_s, now: Time.now.utc)
+RubyLLM::Browser::Rails::Reaper.new(backend: qualified_backend).sweep
+```
+
+Cancellation of a never-started reservation is terminal immediately. Otherwise it sets
+`cancel_requested`, fences stale workers, and remains `cleanup_pending` with quota held.
+It cannot undo an in-flight provider request. A returned session ID is persisted even
+if cancellation raced with session creation.
+
+Run a reaper regularly in an independent scheduler, not only in the operation worker's
+ensure block. A reaper fences workers **before** reconciliation/cleanup, tries to end
+known sessions even when provider reconciliation is unavailable, and reports `failed`
+rather than claiming a database write succeeded. `ttl_seconds:` is an optional positive
+idle threshold, not proof that the provider's billable session has expired.
+
+Stagehand exposes no correlation endpoint here. An unknown start without a session ID
+remains unknown and holds quota until the host supplies provider-confirmed evidence.
+Alert on unknown/pending/failed entries. Never free quota just because enough local time
+passed. An unknown action outcome remains in the result/error code even if session
+cleanup succeeds; do not replay it.
+
+One reaper/backend instance must cover only operations belonging to that provider
+configuration. The current table has no backend credential-configuration binding.
+Multi-provider/multi-credential deployments need a host-scoped store or a future schema
+extension before a global sweep is safe.
+
+## Upgrading an earlier development snapshot
+
+If you installed the generator from an earlier development snapshot, preserve your data
+and add an explicit migration for these new fields instead of rerunning `create_table`
+or dropping the database:
+
+```ruby
+class HardenBrowserBookkeeping < ActiveRecord::Migration[8.1]
+  def change
+    create_table :ruby_llm_browser_actors, id: :string do |t|
+      t.integer :sequence, null: false, default: 0
+    end
+    add_column :ruby_llm_browser_operations, :cancel_requested, :boolean, default: false, null: false
+    add_column :ruby_llm_browser_operations, :request_digest, :string
+  end
+end
+```
 
-SQLite concurrency is exercised locally. PostgreSQL still needs separate qualification,
-and MySQL is not supported by the adapter's locking contract. See the [full Rails guide]({% link RAILS.md %}) for a context factory, enqueueing, status access, migration recovery, and reaper details.
+Adapt this migration if any additions already exist. Drain workers during the upgrade.
+Legacy rows without request digests are not payload-bound, so do not reuse their
+idempotency keys for new work. Inspect earlier terminal cancellations for sessions that
+may not have been confirmed closed before reclaiming them.
 
-## Next Steps
+## Next steps
 
-* [Bounding operation work]({% link _core_features/operation-lifecycle.md %}) - understand budgets and state transitions.
-* [Qualifying a live backend]({% link _advanced/live-backend-qualification.md %}) - review provider requirements.
+- Review [the API]({% link _reference/api-and-configuration.md %}) for result interpretation and budget semantics.
+- Review [release blockers]({% link RELEASE_AUDIT.md %}) before production deployment.

data/docs/_config.yml

@@ -94,16 +94,20 @@ exclude:
   - Gemfile
   - Gemfile.lock
   - README.md
+  - API.md
+  - RAILS.md
   - RELEASE_ACTION_PLAN.md
   - SPEC_BASELINE.md
   - WORK.md
+  - evidence
 
 # The language of code examples; `project-docs` uses it for new pages.
 code_language: ruby
 
 # Values that change between releases. Pages read them as {{ site.version }}
-# and {{ site.examples.NAME }}. Keep `released: false` on main; the docs builder
-# reads a release's version from its matching Git tag.
-released: false
-version: "0.1.0"
+# and {{ site.examples.NAME }}. Candidates remain unreleased; the docs builder
+# reads stable docs from the latest release tag and main under /next/.
+released: true
+version: "0.2.0"
+stable_version: "0.2.0"
 examples: {}

data/docs/_core_features/diagnostics.md

@@ -0,0 +1,68 @@
+---
+layout: default
+title: Checking Configuration
+nav_order: 5
+description: Diagnose the configured backend without opening a session or making a provider request.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+
+After reading this guide, you will know:
+
+- How to check offline configuration without provider credentials.
+- Which checks apply to each backend.
+- Why a local pass cannot qualify a live deployment.
+
+## Check an Offline Backend
+
+```ruby
+require "ruby_llm/browser"
+
+report = RubyLLM::Browser::Doctor.new(backend: RubyLLM::Browser::FakeBackend.new).report
+puts report[:mode] # => offline
+puts report[:ok]   # => true
+puts report[:summary]
+# => configuration checks passed; live provider guarantees are not verified
+```
+
+Doctor checks RubyLLM compatibility and the fake backend's capabilities. It does not
+load the Stagehand SDK, inspect provider credentials or endpoint overrides, or open a
+session. You do not need provider credentials to run offline checks.
+
+## Interpret the Report
+
+Use `ok` to decide whether configuration checks passed. Use `mode` to identify which
+backend the report describes, not whether that backend is supported. The existing
+`summary` and `checks` fields remain available. Each check has `name`, `status`, and
+`detail`; statuses are `pass`, `warn`, `info`, or `fail`. Any failure makes `ok` false.
+
+| Mode | Meaning | Checks |
+| --- | --- | --- |
+| `offline` | FakeBackend with fake server mode | RubyLLM and backend capabilities; no provider environment or SDK checks |
+| `live` | Stagehand or another non-offline backend | RubyLLM and backend capabilities; Stagehand also checks its SDK and environment |
+| `unconfigured` | No backend supplied | RubyLLM and a failed backend/egress check |
+
+A custom backend does not depend on Stagehand diagnostics. Its capability checks
+still enforce unverified egress, an unpinned local server, and unapproved custom-header
+capabilities as failures. A backend's enforced-egress assertion is not independent
+evidence of its deployment behavior.
+
+## Diagnose Stagehand Without Calling It
+
+Pass your host-created Stagehand backend to `Doctor.new(backend:)`. It reports `live`
+mode and a failed `egress_isolation` check because the built-in adapter is unsupported.
+Having an installed SDK or environment credentials cannot enable live operations.
+
+Stagehand diagnostics report the SDK version, endpoint override names, and credential
+presence in the supplied environment without printing values. These observations do
+not configure the backend or replace explicit constructor credentials. Doctor never
+calls the provider to test credentials, billing, egress, or session cleanup.
+
+## Next Steps
+
+- Read [live-backend qualification]({% link _advanced/live-backend-qualification.md %})
+  for the deployment evidence needed before live use.
+- Use [development and testing]({% link _advanced/development-and-testing.md %}) to
+  exercise diagnostics in the offline browser workbench.

data/docs/_core_features/inspect-extract.md

@@ -41,8 +41,7 @@ schema = {
   "required" => [ "title" ], "additionalProperties" => false
 }
 
-inspect_tool = RubyLLM::Browser::Inspect.new(context: context)
-extract_tool = RubyLLM::Browser::Extract.new(context: context, schema: schema)
+inspect_tool, extract_tool = RubyLLM::Browser.tools(context: context, schema: schema)
 
 puts inspect_tool.execute(url: "https://docs.example.com/")[:status] # => ok
 puts extract_tool.execute(url: "https://docs.example.com/")[:data]   # => {"title"=>"Example"}
@@ -54,6 +53,23 @@ instances on a configured RubyLLM chat. The host should select the context and s
 the model supplies only the URL, optional instruction, and an optional positive
 `max_bytes` limit.
 
+## Register the Read-only Pair
+
+Once your host has a context and schema, register both tools in one call:
+
+```ruby
+chat.with_tools(*RubyLLM::Browser.tools(context: context, schema: schema))
+```
+
+The factory returns fresh Inspect and Extract instances in that order. Both use the
+same context; Extract keeps its own immutable schema copy. It never includes Act,
+loads credentials, or starts an operation. A missing context or schema is rejected
+by the existing constructors. Schema contents are checked by policy when Extract
+runs, before a session starts.
+
+You can still construct either tool separately with `Inspect.new(context:)` or
+`Extract.new(context:, schema:)`. That remains useful when a chat needs only one tool.
+
 ## Inspect a Page
 
 `Inspect` navigates to one approved URL and asks the backend for observations. It does

data/docs/_data/navigation.yml

@@ -8,5 +8,7 @@
   url: /api-reference/
   collections:
     - reference
+- title: "What's New"
+  url: /whats-new-in-0-2/
 - title: Releases
   url: https://github.com/yorzi/ruby_llm-browser/releases