ruby_llm-browser 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6184d0ab1ce52e3a77ed427ff4e083790a7d573a51b5ea07ddffeab034b356e
-  data.tar.gz: c08d7fd335590fa99341551ce77ca6a8f8ec61662b3e63903308f56ea9ff05d6
+  metadata.gz: 20b730312da9ae14b8e3a17d386ecaa0034a38b1ac87515e89d2c6a4aa29e8d7
+  data.tar.gz: 7f27467a067bbf8e8712cfffe1a855ce85a21e563765658a142ca7c468297929
 SHA512:
-  metadata.gz: 3f671bfe311dea830346ce657373b81f514c227eac636576f76fb962a4690a0e688fecb476d36ef83a288d02cdc28e0bd2f8fece092b00cd8925e57cae6b3509
-  data.tar.gz: 0f11137930c35dc67cf7642db5152864fa5b101bb957bba24edeab974279c66f33e728766bb5005c29bb331b37989f09edbbaee70f461acf419ea31db9b4a209
+  metadata.gz: ec5d0517a3b4fa4b4fbd2a440fd52d59b173b2f2adb4674c96f9e667bbaa57276984f09f1292865adb662fc1595f9f73b63c32509b9bd9269a058366bfa24ce0
+  data.tar.gz: 13fea67455f9bdd9b49864752e69731b527958fbf06bd7ca0325a167345eaf115190cff9778247e8e526518fdef0b17c1fcb46f60346ab5c09508ca490f8cb35

data/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project aims to
 follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-10-19
+
+### Added
+
+- `RubyLLM::Browser.tools(context:, schema:)` builds fresh Inspect and Extract
+  instances for `chat.with_tools(*tools)`. It never includes Act or dispatches work.
+- Agent validation commands, an offline development workbench, and desktop/mobile
+  Chrome workflows with fixture screenshots. Browser libraries are development-only.
+
+### Changed
+
+- Doctor reports `mode: :offline`, `:live`, or `:unconfigured`. FakeBackend checks
+  skip Stagehand SDK and provider environment checks. Custom backends no longer
+  receive unrelated Stagehand credential warnings. Stagehand remains blocked.
+
 ## [0.1.0] - 2026-10-18
 
 ### Fixed

data/CONTRIBUTING.md

@@ -19,17 +19,24 @@ Thanks for helping. This is an unofficial community extension for
 
 ```bash
 bin/setup          # bundle install
+bin/check          # offline suite, lint, alternate bundles, and examples
 bundle exec rake   # specs + rubocop
 bundle exec rspec  # specs only
 bundle exec bundle-audit check --update
 bundle exec rubocop -A   # autocorrect style
 ```
 
+For the offline workbench, real Chrome tests, screenshots, and installed-package
+checks, follow [development and testing](docs/_advanced/development-and-testing.md).
+
 ## Changing behaviour
 
 - Add a failing spec first, including the negative/denial case.
 - Update `CHANGELOG.md` under `Unreleased`.
-- Update `docs/SECURITY_MODEL.md` or `README.md` if a boundary or public API moved.
+- Update the relevant site guide in `docs/` when a boundary or public API changes.
+  Record breaking changes in `docs/_reference/upgrading.md`. Keep the README brief;
+  use [the documentation index](docs/README.md) for source locations and
+  [the roadmap](docs/_reference/roadmap.md) for proposed release scope.
 - Keep runnable examples and the package's local links green in
   `spec/integration/documentation_spec.rb`.
 - Run both alternate bundles in `gemfiles/` when changing Tool or Rails integration.

data/README.md

@@ -1,41 +1,31 @@
 # ruby_llm-browser
 
-An **unofficial community extension** for [RubyLLM](https://rubyllm.com), with an
-experimental adapter for the official [Stagehand Ruby SDK](https://github.com/browserbase/stagehand-ruby).
-It provides read-only `Inspect` and schema-pinned `Extract` tools, operation bookkeeping,
-and an optional Rails 8 adapter. It does not implement a browser engine.
+An unofficial [RubyLLM](https://rubyllm.com) extension for read-only browser inspection
+and schema-checked extraction, with an optional Rails 8 adapter.
 
-The first release supports the offline `FakeBackend` only. `StagehandBackend` is present
-for future qualification, but it refuses live operations until browser-side egress and
-provider cleanup are qualified.
+**0.2.0 supports offline use only.** `FakeBackend` runs without credentials or network
+requests. The experimental Stagehand adapter refuses live operations; `Act` is an
+offline simulation. This project is not maintained or endorsed by RubyLLM or Browserbase.
 
-> **Version 0.1.0 is the offline-only first release.** The built-in Stagehand backend
-> is unsupported, and the full live Act approval protocol is deferred. No live provider
-> calls were made. See the [release audit](docs/RELEASE_AUDIT.md). This project is not
-> maintained or endorsed by RubyLLM or Browserbase.
+[Documentation](https://rubyllm-browser.wangyaodi.com/) ·
+[Getting started](https://rubyllm-browser.wangyaodi.com/getting-started/) ·
+[Roadmap to 1.0](docs/_reference/roadmap.md)
 
 ## Install
 
-Add the gem to your application's Gemfile:
+Use Ruby 3.2+ and RubyLLM 2.x. Add to your Gemfile, then run `bundle install`:
 
 ```ruby
-gem "ruby_llm-browser", "~> 0.1.0"
+gem "ruby_llm-browser", "~> 0.2.0"
 ```
 
-The core requires Ruby 3.2+, RubyLLM `>= 2.0, < 3`, `json_schemer ~> 2.5`, and
-`stagehand ~> 3.21.0`, plus patched DNS/URL/CGI/compression gems (see the
-[dependency reference](docs/API.md)). Requiring `ruby_llm/browser` loads neither Rails nor the Stagehand
-client, discovers no provider credentials, and opens no browser session.
-
 ## Try it offline
 
-This complete example makes no network request and requires no API key:
-
 ```ruby
 # smoke-test: offline
 require "ruby_llm/browser"
 
-# Fake DNS is only for this offline demonstration. Production uses real DNS.
+# Test resolver for this offline example only.
 class OfflineResolver
   def getaddresses(_host) = [ "93.184.216.34" ]
 end
@@ -49,91 +39,30 @@ context = RubyLLM::Browser::Context.new(
   operation_store: RubyLLM::Browser::InMemoryOperationStore.new
 )
 schema = {
-  "type" => "object",
-  "properties" => { "title" => { "type" => "string" } },
+  "type" => "object", "properties" => { "title" => { "type" => "string" } },
   "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"}
 ```
 
-Register these instances on your configured RubyLLM chat with
-`chat.with_tools(inspect_tool, extract_tool)`. Never register `Act` by default.
-The host supplies authenticated **string** actor/run IDs, authorization, consent,
-the pinned extraction schema, budgets, and the backend.
-
-The tools return a **Hash**, not a `Result` object. Direct `Engine` calls return a
-`Result`. Check `status` and `error`; page data is untrusted evidence, not verified truth.
-
-## Safety boundaries
-
-- URL policy checks hosts, schemes, ports, and public DNS/IP addresses. It cannot
-  sandbox a remote browser or control page-triggered requests.
-- No built-in live backend is supported in this release. `StagehandBackend` always
-  reports egress as unverified and refuses live operations. A host assertion cannot
-  enable it.
-- The model cannot increase the host's output limit. Results are redacted, schema-checked
-  for extraction, and bounded by the policy and remaining operation bytes.
-- A durable operation is claimed before start. Duplicate jobs cannot start it again.
-  SDK retries are disabled; uncertain outcomes are never automatically replayed.
-- Cancellation fences workers but cannot undo an in-flight request. Dispatched operations
-  retain quota until cleanup is confirmed. Run a reaper independently of job workers.
-- `max_cost_usd` is advisory metadata, not an enforced billing cap. Provider timeouts and
-  cleanup are also not a promise of zero future charges.
-- `Act` is an offline simulation only. The full same-session live approval protocol is
-  deferred to a later version. Candidate-list hashes and selector keyword filters are
-  not proof of target identity or action safety.
-
-## Rails integration
-
-Add Rails 8's `activerecord` and `activejob` to your host application, then opt in:
+Register these tools on your configured chat with
+`chat.with_tools(inspect_tool, extract_tool)`. The host owns identity, authorization,
+source policy, schema, and budgets. Tool calls return hashes; page data remains untrusted.
 
-```ruby
-require "ruby_llm/browser/rails"
-```
+## Learn more
 
-```bash
-bin/rails generate ruby_llm:browser:install
-bin/rails db:migrate
-```
+Use the [documentation site](https://rubyllm-browser.wangyaodi.com/) for configuration,
+Rails jobs, API details, and security boundaries. The same guides ship as Markdown in
+the gem; [docs/README.md](docs/README.md) indexes their source files.
 
-The adapter provides durable operation/approval stores, actor-scoped jobs, cancellation,
-and a reaper. Follow the [Rails guide](docs/RAILS.md) for the context factory, matching
-budgets, status access, scheduling, and upgrading an earlier development database.
-Only SQLite concurrency is tested locally; PostgreSQL requires its own qualification.
-
-## Documentation
-
-- [Documentation website](https://rubyllm-browser.wangyaodi.com) (GitHub Pages)
-- [Documentation index](docs/README.md)
-- [API, configuration, and result reference](docs/API.md)
-- [Rails jobs and recovery](docs/RAILS.md)
-- [Security model and live qualification](docs/SECURITY_MODEL.md)
-- [Compatibility and release checklist](docs/RELEASING.md)
-- [Audit findings and unresolved blockers](docs/RELEASE_AUDIT.md)
-- [Requirement evidence](docs/WORK.md)
-- [Offline scripts](examples/)
-
-These documents and examples are included in the built gem.
-
-## Development
-
-```bash
-bin/setup
-bundle exec rake
-bundle exec bundle-audit check --update
-bundle exec ruby examples/plain_ruby.rb
-bundle exec ruby examples/rails_adapter.rb
-bundle exec rake build
-bundle exec ruby bin/verify-package --rails --audit
-```
+## Contributing
 
-Tests block unmocked network requests. No paid live call or RubyGems publication is part
-of the default workflow. See [contributing](CONTRIBUTING.md).
+Run `bin/setup`, then `bundle exec rake`. Tests block unmocked network requests.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development and
+[the roadmap](docs/_reference/roadmap.md) for the next iterations.
 
 ## License
 
-MIT. See [LICENSE.txt](LICENSE.txt) and [third-party notices](NOTICE.md).
+[MIT](LICENSE.txt). See [third-party notices](NOTICE.md).

data/docs/API.md

@@ -1,177 +1,10 @@
 ---
-layout: default
-title: API and Configuration
-permalink: /api-and-configuration/
-description: Configure trusted host objects and interpret bounded untrusted results.
+title: API Guide Location
+description: Find the canonical API and configuration guide.
+guide: false
 ---
 
 # API and configuration
 
-Configure trusted host objects and interpret bounded, untrusted results.
-
-After reading this guide, you will know:
-
-- How to register read-only tools.
-- Which inputs belong to the host and which belong to the model.
-- How to configure budgets, schemas, backends, and error handling.
-
-## Creating a context
-
-Use the complete offline example in [Getting Started]({% link _getting_started/getting-started.md %}). `Context.new` requires:
-
-| Keyword | Type and meaning |
-| --- | --- |
-| `actor_id`, `run_id` | Nonempty strings from authenticated host records. Convert numeric database IDs with `to_s`. |
-| `backend` | A `Backend` instance. Use `FakeBackend` for offline tests. |
-| `source_policy` | A host-created `Policy`. |
-| `operation_store` | An `OperationStore`; durable storage is required across restarts or workers. |
-| `approval_store` | Optional `ApprovalStore`, needed only for experimental Act. |
-| `budget` | Optional `Budget`; defaults listed below. |
-| `clock` | Optional callable returning a UTC `Time`. |
-| `logger` | Optional host logger. Do not enable raw provider or tool payload logging. |
-| `consent` | Optional host consent record. The gem records its presence; it does not collect or authenticate consent. |
-| `metadata` | Optional host metadata. Never supply credentials here. |
-
-The host must reauthorize actor/run access when building a context, including background
-jobs. Passing IDs alone is not authentication. The model must never choose a backend,
-credential, schema, source allowlist, consent record, or budget.
-
-## Registering tools
-
-```ruby
-inspect_tool = RubyLLM::Browser::Inspect.new(context: context)
-extract_tool = RubyLLM::Browser::Extract.new(context: context, schema: schema)
-chat.with_tools(inspect_tool, extract_tool)
-```
-
-Both tools expose `url`, optional `instruction`, and optional positive integer
-`max_bytes`. `max_bytes` can only tighten the policy and operation ceilings.
-`Extract` takes its schema in the constructor, not in model arguments.
-
-`Inspect` returns **candidate interactions**, not a screenshot or arbitrary page dump.
-Neither read-only tool dispatches candidates automatically. Pages may still run scripts
-and initiate requests; read-only does not mean browsing has no external effects.
-
-`Tool#execute` and RubyLLM `Tool#call` return a Hash. If you need a `Result` object, use:
-
-```ruby
-engine = RubyLLM::Browser::Engine.new(context: context)
-result = engine.inspect(url: url)
-result = engine.extract(url: url, schema: schema, instruction: "Find the title")
-```
-
-The optional `operation:` Engine keyword accepts a host-reserved operation with the
-same actor/run and budget. Starting it is an atomic reserved-to-starting claim. It is
-not a resume or retry API for active, unknown, or closed operations.
-
-## Source policy
-
-`Policy.new(allowed_hosts: [...])` accepts exact hosts and `*.example.com` subdomains.
-A wildcard does not allow the bare domain. Defaults are HTTP/HTTPS and ports 80/443.
-Keep `verify_dns: true`; `resolver:` is injectable for offline fixtures.
-
-Other options are `allowed_schemes`, `allowed_ports`, `max_result_bytes` (65,536),
-`max_schema_depth` (8), `max_schema_properties` (64 root properties), and
-`max_schema_bytes` (16,384). Browser-side enforcement must also cover explicitly
-approved asset origins, redirects, frames, popups, WebSockets, and subresources.
-
-## Extraction schemas
-
-Schemas must be bounded object JSON Schemas, passed as a Hash, JSON object string, or
-an object/class supporting `to_json_schema`. Supported keywords are `type`,
-`description`, `properties`, `required`, `items`, `enum`, `additionalProperties`,
-`title`, `minimum`, `maximum`, `minLength`, `maxLength`, `minItems`, `maxItems`,
-`format`, and `default`. Remote references and arbitrary schema extensions are refused.
-
-Use `required` and `additionalProperties: false` when an exact shape matters. Provider
-data must satisfy the schema before redaction or truncation. Invalid data returns
-`PROVIDER_ERROR`; it is not returned as a successful extraction. A truncated preview
-or redacted field need not retain the original schema's type. Always check the status.
-
-## Results and errors
-
-`Result#to_h` contains symbol keys: `status`, `operation_id`, `final_url`,
-`captured_at` (UTC ISO 8601), `locator`, `digest`, `truncated`, `data`, and optional
-`error: { code:, message: }`. Locator/data objects use string keys. JSON encodes all
-keys as strings. Credential-like query values are redacted in URL provenance.
-
-Statuses are `ok`, `truncated`, `error`, `unknown`, and `cleanup_pending`.
-`Result#ok?` accepts `ok` and `truncated`; it makes no factual verification claim.
-`digest` is SHA-256 of canonical JSON of the returned, sanitized data. Very small byte
-limits can produce an empty string or scalar preview; `truncated` is authoritative.
-
-Engine preflight denials raise typed errors. Tools convert them into error Hashes.
-After a session starts, the Engine attempts cleanup and returns a failure result.
-Cleanup failure can supersede the original result with `cleanup_pending`; inspect the
-durable operation's `error_code` and arrange host review for unknown effects.
-
-Safe error codes: `INVALID_INPUT`, `NOT_AUTHORIZED`, `UNSUPPORTED_SECURITY_CAPABILITY`,
-`BUDGET_EXHAUSTED`, `SESSION_UNKNOWN`, `CLEANUP_PENDING`, `APPROVAL_REQUIRED`,
-`APPROVAL_STALE`, and `PROVIDER_ERROR`.
-
-## Budgets
-
-`Budget.new` defaults to `max_seconds: 60`, `max_steps: 12`, `max_bytes: 262_144`,
-`max_concurrent: 1`, and `max_cost_usd: nil`.
-
-`RubyLLM::Browser.configure` sets process defaults for `default_budget`,
-`max_result_bytes`, `clock`, and `logger`. New contexts/policies use those defaults;
-existing objects do not change. `configuration.backend` is only a reserved host slot:
-contexts always require an explicitly supplied backend and never use a fallback.
-
-- Steps count navigation, observation, extraction, and action calls, not start/cleanup.
-- Bytes count retained sanitized result data, not all bytes the remote browser receives.
-- Wall-clock checks refuse new calls after expiry. Stagehand request timeouts are bounded
-  by remaining time. Cleanup has a separate timeout and may outlive this budget.
-- Concurrency is scoped to the actor across runs. Unknown/pending cleanup holds a slot.
-- `max_cost_usd` is **advisory only**. There is no cost ledger or provider hard spending
-  cap in this release. Enforce billing limits in the provider/host.
-
-## Stagehand backend status
-
-`StagehandBackend` is unsupported for live operations in this release. It always reports
-`egress_isolation: :unverified` and `act_supported?: false`. `Engine` refuses it before
-the first provider request, and direct start, navigation, observation, extraction, and
-Act calls also fail closed. No constructor option or injected client enables live use.
-
-The adapter remains in the source for future qualification. Its client pins credentials
-and base URL, disables retries, self-healing, CAPTCHA solving, session recording and
-session logging, and requests a provider timeout. These controls do not prove egress,
-TTL, billing, final-URL reporting, or cleanup. `end_session` sends no request in this
-release and returns `false`; the operation remains `cleanup_pending`.
-
-The constructor accepts `server: :remote`, `base_url:`, `timeout: 60.0`,
-`custom_headers_approved: false`, `env: ENV`, and an injected `client:` for internal
-contract tests. A future live implementation must verify all relevant environment
-settings, egress across every browser request path, TTL and closure status, and provider
-billing controls before it can advertise support.
-
-## Dependency security floors
-
-Old Ruby installations can supply vulnerable default gems even when a developer's
-lockfile audit passes. Runtime requirements explicitly exclude those versions:
-`cgi >= 0.4.2, < 1`, `resolv >= 0.7.2, < 1`, `uri >= 1.0.4, < 2`, and
-`zlib >= 3.2.3, < 4`. A fresh install may build native extensions for these gems.
-Use a supported, patched Ruby interpreter as well; these floors do not patch Ruby or
-system libraries. Audit the versions actually activated by your application, including
-default gems, not just a development lockfile.
-
-## Experimental Act
-
-`Act.new(context:)` declares RubyLLM `requires_approval`. Its arguments are `url`,
-`approval_id`, `method`, `selector`, optional `description`, and optional `arguments`.
-The resolver reads the host store without consuming. Consumption immediately before
-dispatch checks actor/run, exact URL/action digest, expiry, and any supplied
-page/operation/session bindings. Revocation and consumption are atomic in the stores.
-
-**Do not use this as a production authorization protocol yet.** Bindings are currently
-optional; a candidate-list digest is not a DOM/target revision, and each Engine action
-opens a fresh session. The same-session host approval flow required by the specification
-is deferred to a later version. The Engine refuses all non-fake Act calls before starting
-a session. Selector/description keyword filters are defense in depth, not semantic proof
-that a click is harmless. The Stagehand adapter does not support Act in this release.
-
-## Next steps
-
-- Read [Rails integration]({% link RAILS.md %}) for durable workers and recovery.
-- Read [security boundaries]({% link SECURITY_MODEL.md %}) before qualifying a live backend.
+The [API and configuration reference](_reference/api-and-configuration.md) is the
+canonical guide. Read it on the [documentation site](https://rubyllm-browser.wangyaodi.com/api-and-configuration/).

data/docs/RAILS.md

@@ -1,167 +1,10 @@
 ---
-layout: default
-title: Rails Jobs and Recovery
-description: Run bounded read-only operations with durable state and independently scheduled cleanup.
+title: Rails Guide Location
+description: Find the canonical Rails jobs and recovery guide.
+guide: false
 ---
 
 # Rails jobs and recovery
 
-Run bounded read-only operations with durable state and independently scheduled cleanup.
-
-After reading this guide, you will know:
-
-- 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.
-
-## Installing the adapter
-
-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"
-```
-
-```bash
-bin/rails generate ruby_llm:browser:install
-bin/rails db:migrate
-```
-
-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.
-
-`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.
-
-## Configuring the trusted context factory
-
-```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.
-
-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
-
-Nothing has been publicly released. If you already ran the earlier generator, 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
-```
-
-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
-
-- Review [the API]({% link API.md %}) for result interpretation and budget semantics.
-- Review [release blockers]({% link RELEASE_AUDIT.md %}) before production deployment.
+The [Rails integration guide](_advanced/rails-integration.md) is the canonical guide.
+Read it on the [documentation site](https://rubyllm-browser.wangyaodi.com/rails-integration/).

data/docs/README.md

@@ -1,16 +1,26 @@
 # Documentation
 
-Use these guides to configure browser tools and understand their limits.
+Read the [documentation site](https://rubyllm-browser.wangyaodi.com/) for the latest
+stable release. The [next-version site](https://rubyllm-browser.wangyaodi.com/next/)
+follows `main`. The Markdown files below are the source for those guides and ship in
+the gem.
 
-- [API reference](API.md): contexts, tools, schemas, results, budgets, and backend options.
-- [Rails integration](RAILS.md): durable stores, jobs, cancellation, recovery, and migrations.
-- [Security model](SECURITY_MODEL.md): trust boundaries and live deployment qualification.
-- [Release checklist](RELEASING.md): compatibility, package verification, and owner approvals.
-- [Release audit](RELEASE_AUDIT.md): findings, fixes, and remaining publication blockers.
-- [Owner action plan](RELEASE_ACTION_PLAN.md): decisions you own and work you can delegate.
-- [WORK ledger](WORK.md): exact commands and offline requirement evidence.
-- [Specification baseline](SPEC_BASELINE.md): product intent and governance boundaries.
+- [Getting started](_getting_started/getting-started.md): installation and an offline example.
+- [Configuration](_getting_started/configuration.md): host inputs and process defaults.
+- [Inspect and Extract](_core_features/inspect-extract.md): tools and result handling.
+- [Rails jobs and recovery](_advanced/rails-integration.md): installation, workers, and cleanup.
+- [API and configuration reference](_reference/api-and-configuration.md): parameters and errors.
+- [Security model](SECURITY_MODEL.md): guarantees and limits.
+- [Roadmap to 1.0](_reference/roadmap.md): proposed versions and acceptance criteria.
 
-Start with the runnable offline example in the [README](../README.md). No guide grants
-authorization to access a source or spend provider credits. Gem releases use the reviewed
-tag workflow in [the release checklist](RELEASING.md).
+## Maintaining these docs
+
+Keep the root README to installation, one example, and links. Put usage and API details
+in the site guides, editing each topic in one place. Link to those source files when
+writing repository Markdown; use Jekyll link tags between site pages. Keep
+[CHANGELOG.md](../CHANGELOG.md) to shipped changes.
+
+Preview with `docs/bin/serve.sh`; build with `docs/bin/build.sh`. See
+[releasing](RELEASING.md) for package checks. The [0.1.0 audit](RELEASE_AUDIT.md),
+[release record](RELEASE_ACTION_PLAN.md), [evidence ledger](WORK.md), and
+[specification baseline](SPEC_BASELINE.md) preserve historical evidence.