ruby_llm-browser 0.1.0 → 0.3.0

data/docs/_advanced/result-delivery.md

@@ -0,0 +1,119 @@
+---
+layout: default
+title: Rails Result Delivery
+nav_order: 2
+description: Persist sanitized background results in your application and recover delivery separately from browser cleanup.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+
+After reading this guide, you will know:
+
+- How to receive a background operation's bounded result.
+- How to store and authorize results in your application.
+- How to recover delivery without repeating browser work.
+
+## Persist a Result
+
+Configure the optional Rails adapter and its context factory first. See
+[Rails jobs and recovery]({% link _advanced/rails-integration.md %}). Register a trusted
+callback in your initializer:
+
+```ruby
+RubyLLM::Browser::Rails.result_delivery = lambda do |operation:, result:|
+  # Your host service persists result.to_h with operation.id, actor_id and run_id.
+  BrowserResults.persist(operation: operation, payload: result.to_h)
+end
+```
+
+`BrowserResults` is your application service. It is not a gem class. The callback
+receives an immutable `Operation` snapshot and the core's sanitized, bounded `Result`.
+Persist `result.to_h` or `result.to_json`, rather than the operation object, which
+contains a provider session ID for trusted bookkeeping.
+
+The callback runs synchronously in the worker after the engine attempts cleanup and
+before the job returns. It receives successful, truncated, error, unknown, and
+cleanup-pending results. Preflight exceptions have no `Result` and do not invoke it.
+Cancellation or a changed fence detected after execution suppresses delivery. A
+missing, already started, or terminal operation does not invoke it either.
+
+The default is `nil`, which preserves the existing job return behavior. Setting the
+hook to a non-callable value raises `InvalidInput`. Callback return values are ignored;
+raise an exception if persistence fails.
+
+## Keep Storage and Access in the Host
+
+Run the disposable, offline host example:
+
+```sh
+bundle exec ruby examples/rails_results.rb
+# RESULT_AFTER_WORKER_EXIT_PASS
+# SCOPED_READS_PASS
+# IDEMPOTENT_WRITE_PASS
+```
+
+It writes a serialized Active Job to a temporary file, executes it in a separate
+worker, waits for exit, and reads the schema-checked extraction from SQLite. Repeating
+the job in another worker starts no browser session. The example's host table accepts
+identical repeated writes and rejects conflicting bodies or actor/run identities.
+Its file queue holds one job and is for demonstration; use a durable queue in your
+application. The temporary database and queue file are removed on completion. Read
+[the example source](https://github.com/yorzi/ruby_llm-browser/blob/main/examples/rails_results.rb).
+
+Use a unique operation ID for idempotent writes. Repeating a write of the same result
+should succeed; reject a conflicting body or actor/run identity. Retrieve with the
+authenticated actor and run in the database query. Never use model-supplied actor IDs
+as authorization. Recheck host revocation and retention rules when serving a result.
+
+The gem creates no result table and adds no migrations. Keep results in your host's
+database or durable storage. Do not rely on an Active Job return value or in-memory
+callback state after a worker exits.
+
+An `ok` extraction passed the pinned schema before redaction and bounding. A truncated
+result can contain a preview instead of the original schema shape. Treat all page
+content as untrusted. Store failures too, without interpreting `cleanup_pending` or
+`unknown` as success. A stored result describes that attempt; a later reaper changes
+session state, not the historical result body.
+
+## Recover Delivery Separately
+
+If the callback raises, the job raises `RubyLLM::Browser::Rails::ResultDeliveryError`
+with code `RESULT_DELIVERY_FAILED`. The original callback exception is not chained,
+so automatic job logs cannot print its potentially sensitive message. The error
+exposes `operation` and `result` to trusted, in-process host recovery code:
+
+```ruby
+# Inside host code that catches ResultDeliveryError while these objects still exist:
+RubyLLM::Browser::Rails.result_delivery.call(
+  operation: error.operation, result: error.result
+)
+```
+
+This retries only your callback. Reauthorize recovery in the host. Keep external side
+effects idempotent and persist the result before sending notifications. For durable
+notification retries, write the result and a host outbox entry in one transaction.
+An exception object does not survive worker exit as durable result storage.
+
+A failed callback does not change the operation's session state or error code. Queue
+redelivery of `OperationJob` does not repeat a started browser operation and does not
+redeliver its result. Keep delivery failures visible in your job monitoring; retrying
+the browser job is not a result-recovery mechanism.
+
+There is no atomic transaction across provider execution, operation bookkeeping, and
+host persistence. A process crash after execution but before persistence can lose the
+result. The hook offers one automatic delivery attempt, not guaranteed or exactly-once
+delivery. If host storage is unavailable, a recovery handler must save the retained
+result to a separate durable destination before it exits. Never recover a lost result
+by replaying an uncertain browser operation automatically.
+
+Cancellation can race after the worker's final check. If your host forbids storing a
+result after revocation, enforce that rule in the persistence transaction as well as
+at read time. A callback failure must not clear cancellation, pending cleanup, or quota.
+
+## Next Steps
+
+Read [the API reference]({% link _reference/api-and-configuration.md %}) for result
+fields and [Rails jobs and recovery]({% link _advanced/rails-integration.md %}) for
+cancellation and reaper behavior.

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.3.0"
+stable_version: "0.3.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-3/
 - title: Releases
   url: https://github.com/yorzi/ruby_llm-browser/releases

data/docs/_getting_started/getting-started.md

@@ -18,7 +18,16 @@ After reading this guide, you will know:
 
 ## Installation
 
-The stable release is `{{ site.version }}`. Add it to your Gemfile:
+{% if site.docs_unreleased %}This guide follows `main` at source version `{{ site.version }}`.
+Install the default branch to use the APIs documented here:
+
+```sh
+bundle add ruby_llm-browser --git https://github.com/yorzi/ruby_llm-browser --branch main
+```
+
+The latest stable release is `{{ site.stable_version }}`; select its documentation
+from the version menu before installing that release.
+{% else %}The stable release is `{{ site.version }}`. Add it to your Gemfile:
 
 ```ruby
 gem "ruby_llm-browser", "~> {{ site.version }}"
@@ -29,6 +38,7 @@ For unreleased development changes, install the default branch instead:
 ```sh
 bundle add ruby_llm-browser --git https://github.com/yorzi/ruby_llm-browser --branch main
 ```
+{% endif %}
 
 Use Ruby 3.2 or later. The gem supports RubyLLM `>= 2.0, < 3` and pins Stagehand to the
 3.21.x series. Rails is optional and is not loaded by the core entry point. See

data/docs/_getting_started/overview.md

@@ -50,3 +50,6 @@ does not click or submit forms.
 * [Getting Started]({% link _getting_started/getting-started.md %}) - install and run the offline example.
 * [Configuration]({% link _getting_started/configuration.md %}) - choose host-owned defaults.
 * [API and configuration reference]({% link _reference/api-reference.md %}) - see options, statuses, and result fields.
+
+Read [Rails Result Delivery]({% link _advanced/result-delivery.md %}) to persist a
+background result in host storage and recover delivery separately from session cleanup.

data/docs/_getting_started/whats-new-in-0-3.md

@@ -0,0 +1,48 @@
+---
+layout: default
+title: What's New in 0.3
+redirect_from:
+  - /whats-new/
+nav_order: 4
+description: Deliver Rails background results to host storage without repeating browser work on delivery failure.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+
+After reading this guide, you will know:
+
+- How to persist the result of a background operation.
+- Which delivery failures your application must recover.
+- Which capabilities remain unsupported.
+
+## Rails Result Delivery
+
+Register a host callback to receive each eligible job's sanitized `Result` after
+execution and cleanup:
+
+```ruby
+RubyLLM::Browser::Rails.result_delivery = lambda do |operation:, result:|
+  BrowserResults.persist(operation: operation, payload: result.to_h)
+end
+```
+
+Your application supplies `BrowserResults`, storage, access checks, retention, and
+idempotent recovery. The gem adds no database tables or runtime dependencies. Read
+[Rails Result Delivery]({% link _advanced/result-delivery.md %}) for the contract.
+
+Run `bundle exec ruby examples/rails_results.rb` for a disposable SQLite host example.
+It executes a serialized job in a separate process, waits for the worker to exit,
+then verifies result retrieval, actor/run isolation, and idempotent persistence.
+
+## Delivery Failure Is Separate from Cleanup
+
+A callback failure raises `Rails::ResultDeliveryError` with the retained operation and
+result. It does not change session state. A duplicate browser job does not rerun the
+operation or redeliver the result. Recover host delivery using the retained result;
+do not enqueue a new browser operation to recover persistence.
+
+The hook cannot guarantee delivery across worker crashes. Stagehand and live Act remain
+unsupported. Review [the roadmap]({% link _reference/roadmap.md %}) for live-backend
+qualification and the remaining 1.0 requirements.

data/docs/_plugins/versioned_docs.rb

@@ -6,9 +6,9 @@
 #   while _config.yml says `released: false`. Pages use it to show the install
 #   command for the default branch. A build of a release tag is never
 #   unreleased, even when that tag forgot to set `released: true`.
-# - A versioned build takes `version` from _data/versions.yml, which
+# - A stable or archive build takes `version` from _data/versions.yml, which
 #   bin/prepare_versions.rb fills in from the tag, so a tag that forgot to bump
-#   `version` still shows the right install command.
+#   `version` still shows the right install command. Next keeps its source version.
 # - An absolute canonical_url on this site becomes a path, so the theme adds
 #   this build's base path (/next/, /v1/) and the page stays in its own
 #   build's llms.txt and sitemap.
@@ -22,7 +22,7 @@ Jekyll::Hooks.register :site, :post_read, priority: :high do |site|
   else
     site.config['docs_unreleased'] = [ 'next', 'Next (unreleased)' ].include?(current)
     release = versions['release'].to_s
-    site.config['version'] = release unless release.empty?
+    site.config['version'] = release unless release.empty? || site.config['docs_unreleased']
   end
 
   origin = site.config['url'].to_s.delete_suffix('/')

data/docs/_reference/api-and-configuration.md

@@ -0,0 +1,203 @@
+---
+layout: default
+title: API and Configuration
+nav_order: 3
+permalink: /api-and-configuration/
+description: Configure trusted host objects and interpret bounded untrusted results.
+---
+
+# 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
+chat.with_tools(*RubyLLM::Browser.tools(context: context, schema: schema))
+```
+
+`Browser.tools` returns fresh Inspect and Extract instances in that order, sharing
+the supplied context. It never includes Act or dispatches an operation. You can also
+construct either tool separately with `Inspect.new(context:)` and
+`Extract.new(context:, schema:)`. Constructors reject missing host bindings; schema
+contents are validated by policy when Extract runs, before a session starts.
+
+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` copies and freezes its strings and nested data. This includes operation ID,
+error code and error message; changes to constructor inputs cannot alter a retained
+result. Duplicate a returned string if host code needs to edit it.
+
+`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.
+
+## Configuration diagnostics
+
+For diagnostics without network requests, use `Doctor.new(backend:).report`. It
+returns `mode`, `ok`, `summary`, and `checks`. See
+[Checking Configuration]({% link _core_features/diagnostics.md %}) for the backend-specific checks.
+
+## 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.
+
+## Rails Result Delivery
+
+After `require "ruby_llm/browser/rails"`, set `Rails.result_delivery` to a callable
+accepting `operation:` and `result:`, or `nil` to disable it. `Rails.reset!` clears the
+hook. The callback runs synchronously after execution and cleanup. Return values are
+ignored; exceptions become `Rails::ResultDeliveryError` (`RESULT_DELIVERY_FAILED`),
+which exposes `operation` and `result` to trusted recovery code. These objects are
+not automatically persisted. Duplicate browser jobs do not retry delivery. Read
+[Rails Result Delivery]({% link _advanced/result-delivery.md %}) for storage, access,
+cancellation, and crash boundaries.
+
+## Next steps
+
+- Read [Rails integration]({% link _advanced/rails-integration.md %}) for durable workers and recovery.
+- Read [security boundaries]({% link SECURITY_MODEL.md %}) before qualifying a live backend.

data/docs/_reference/api-reference.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: API Reference
-nav_order: 1
+nav_order: 4
 guide: false
 description: Find the RubyLLM::Browser classes for tools, policy, results, backends, and Rails jobs.
 ---
@@ -20,10 +20,11 @@ The [generated RDoc reference]({{ '/api/' | relative_url }}) documents classes a
 | Simulate one host-approved action offline | `Act`, `Approval`, `ApprovalStore` |
 | Read a bounded result | `Result` |
 | Use an offline backend | `FakeBackend` |
+| Diagnose configuration without dispatch | `Doctor` ([guide]({% link _core_features/diagnostics.md %})) |
 | Adapt the Stagehand Ruby SDK | `StagehandBackend`, `Capabilities`, `Doctor` |
 | Persist operation or approval state | `OperationStore`, `ApprovalStore` and their implementations |
 | Run Rails background jobs and cleanup | `RubyLLM::Browser::Rails::OperationJob`, `Reaper` |
 
-Start with [Getting Started]({% link _getting_started/getting-started.md %}) for a runnable offline example. The [API and configuration guide]({% link API.md %}) explains inputs, results, limits, and errors.
+Start with [Getting Started]({% link _getting_started/getting-started.md %}) for a runnable offline example. The [API and configuration guide]({% link _reference/api-and-configuration.md %}) explains inputs, results, limits, and errors.
 
 The reference is generated from source comments. Build it locally with `docs/bin/build-api.sh tmp/api`.

data/docs/_reference/release-history.md

@@ -11,13 +11,15 @@ description: Follow release tags and their documentation for RubyLLM::Browser.
 {{ page.description }}
 {: .fs-6 .fw-300 }
 
-{% if site.docs_unreleased %}The current source build follows `main`. The latest stable release is `0.1.0`.
+{% if site.docs_unreleased %}The current source build follows `main`. The latest stable release is `{{ site.stable_version }}`.
 {% else %}This documentation describes the `{{ site.version }}` release. Use the tag and
 release notes to identify the exact source for this version.
 {% endif %}
 
 | Release | Date | Highlights |
 | --- | --- | --- |
+| [0.3.0]({% link _getting_started/whats-new-in-0-3.md %}) | 2026-10-19 | Opt-in Rails result delivery, durable host example, recovery and upgrade verification |
+| [0.2.0]({% link _reference/whats-new-in-0-2.md %}) | 2026-10-19 | Read-only tool factory, backend-aware Doctor, and agent development/browser verification |
 | [0.1.0](https://github.com/yorzi/ruby_llm-browser/releases/tag/v0.1.0) | 2026-10-18 | Offline read-only Inspect and Extract, Rails adapter, and Act simulation; live Stagehand and live Act are unsupported |
 
 For changes to existing applications, follow [Upgrading]({% link _reference/upgrading.md %}).