ruby_llm-browser 0.1.0

data/docs/RAILS.md

@@ -0,0 +1,167 @@
+---
+layout: default
+title: Rails Jobs and Recovery
+description: Run bounded read-only operations with durable state and independently scheduled cleanup.
+---
+
+# 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.

data/docs/README.md

@@ -0,0 +1,16 @@
+# Documentation
+
+Use these guides to configure browser tools and understand their limits.
+
+- [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.
+
+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).

data/docs/RELEASE_ACTION_PLAN.md

@@ -0,0 +1,81 @@
+---
+layout: default
+title: Release Action Plan
+description: Record the offline first-release decision and the automated gem release path.
+llms: false
+---
+
+# Release action plan
+
+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.
+
+## Current position
+
+- Hardening baseline: `0ec34d4`.
+- Expanded remote CI is green: seven test jobs and the package/install/advisory job.
+- 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.
+
+## Release scope
+
+The first version supports offline `FakeBackend` operations. `StagehandBackend` remains in
+the source but cannot start or operate on a live session. The full same-session Act
+protocol is deferred to a later version. H1/H2 approved this scope for handoff against
+exact Q `22d488987517b10dcd96d2713ed3d47e8818b36b`; the approved Specs candidate label
+`0.3.0-draft` is historical provenance. The package and Git release use `0.1.0`.
+
+## Remaining work and ownership
+
+| Gate | What you decide or provide | What the assistant can do |
+| --- | --- | --- |
+| 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. |
+| 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. |
+
+## Provider questions to resolve before live tests
+
+1. Can the actual browser enforce approved destinations and public IP ranges at
+   connection time across navigation, redirect hops, subresources, iframes, popups,
+   WebSockets and DNS rebinding? A Ruby allowlist is insufficient.
+2. Does the actual Stagehand server return a verified final top-level URL? The SDK
+   permits null navigation results; the gem refuses to invent provenance.
+3. How are session TTL and confirmed closure enforced? Is a start with a lost response
+   recoverable by correlation? If not, unknown starts must remain held for host review.
+4. Which provider-side billing controls exist? The gem's `max_cost_usd` field is
+   advisory, not an enforceable currency cap.
+
+If the provider cannot meet a required guarantee, a test passing once is not a substitute.
+Keep the Stagehand backend unsupported until the missing controls have been qualified.
+The current adapter does not accept `egress_isolation: :enforced`; do not add a host
+assertion merely to bypass the preflight gate.
+
+## Authorizing a later live test
+
+Approve the provider/deployment, public test origin you control or have permission to
+use, data to be sent to browser/model services, session/request/time limits, billing
+owner, and spending limit. A hard monetary ceiling requires an actual provider control.
+Use controlled negative fixtures, not genuine cloud-metadata or third-party private
+services. Supply credentials through local secret management, never in chat or commits.
+
+The assistant can first prepare this plan without credentials or paid calls. If required
+network isolation cannot be established, do not proceed with live browsing.
+
+## Provider boundary
+
+The release instruction does not authorize provider calls or live browsing. Keep
+Stagehand and live Act disabled until the missing provider guarantees are separately
+qualified and approved. A Ruby source URL allowlist is not browser-side egress proof.

data/docs/RELEASE_AUDIT.md

@@ -0,0 +1,158 @@
+---
+layout: default
+title: Release Audit
+description: Record release fixes, provider limits, and the scope of available evidence.
+---
+
+# Release audit: 2026-10-18
+
+**Audit snapshot before the 0.1.0 release instruction: publication was on hold; the selected first-release scope was offline read-only.**
+
+The original 270-example suite was green, but source review and new negative tests
+found security/lifecycle defects and documentation errors. Those defects are hardened
+in commit `0ec34d4`. A green offline suite does not close the provider, authorization,
+name/license, or specification-governance gates below. Nothing has been published.
+
+## Fixed findings
+
+| Severity | Finding | Correction / evidence |
+| --- | --- | --- |
+| High | A stale reserved copy or duplicate worker could start an operation again. | Atomic `claim_start`, exact fence and legal-transition checks; stale-copy and independent-connection races. |
+| High | Locking existing open rows did not serialize an actor's first concurrent reservations. | Durable actor lock row written before quota checks, including an initially empty actor. |
+| High | Cancellation released a live session's quota and hid it from the reaper. | Cancellation flag plus pending cleanup; quota held until exact-session closure is confirmed. |
+| High | Cancellation during start or a persistence exception could bypass cleanup/session tracking. | Persist returned identity across cancellation; ensure-style close after post-start failures; regressions. |
+| High | Stagehand reconciliation always returned unknown, so the reaper did not close known sessions. | Reaper fences before I/O and attempts known-session cleanup without requiring an active reconciliation response. Failed writes are reported as failed. |
+| High | Model byte requests overrode host limits, operation bytes were not enforced, and cleanup overwrote counters. | Minimum of model/policy/remaining budget; retained accounting; exact encoded-byte bounding. |
+| High | Extraction provider data was not validated; malformed schema shapes could pass or raise untyped errors. | JSON Schema meta-validation plus instance validation before returning data. |
+| High | Nested mutable host objects could change frozen policy/approval/schema objects. | Defensive copies and immutable host bindings. |
+| High | A clean install activated vulnerable Ruby default gems despite a green development lockfile audit. | Explicit patched CGI, DNS resolver, URI and zlib dependency floors; audit both the resolved lockfile and clean runtime. |
+| High | Live Act accepted incomplete grants despite missing same-session/target proof. | Engine now refuses every non-fake Act before start. Production protocol remains a blocker, not a claimed fix. |
+| Medium | SDK response failures/missing identities could be treated as closed or successful; final URL was guessed. | Unknown starts remain reserved; unsuccessful responses are refused; missing final URL fails closed. |
+| Medium | Provider defaults permitted self-healing/CAPTCHA solving and logging; relevant ENV could drift after qualification. | Explicit disabled options; snapshot recheck; remaining-time request timeout; real-SDK HTTP regressions. |
+| Medium | URL/selector progress, parser errors and Active Job arguments exposed avoidable data. | Coarse progress, generic parser/backend failures, URL query redaction, disabled job argument logging. |
+| Medium | Duplicate idempotency keys could select a different queued request; factory could use a different store. | Payload/budget digest binding and job/context store identity checks. |
+| Medium | Durable timestamp precision could reject a valid direct Engine call using a real clock; configured defaults were ignored. | Return canonical stored identities, honor process budget/result defaults, and test both real clocks and configuration. |
+| Medium | Rails generator command did not resolve (`RubyLLM` underscored incorrectly). | Explicit namespace, lookup test, generated migration up/down test. |
+| Medium | README used `egress_isolated`, omitted required `schema:`, passed numeric IDs, and misstated return type. | Runnable offline README plus API/Rails guides and tested snippets. |
+| Medium | Built gem omitted guides/examples linked by the README; dependency range admitted untested Stagehand minors. | Package includes docs/examples; Stagehand restricted to 3.21.x; packaged-link checks. |
+| Low | Changelog implied a release, CI missed the RubyLLM minimum, and Doctor overstated readiness. | Unreleased changelog, compatibility matrix, public Chat API tests across versions, qualification caveat in Doctor. |
+
+The first clean runtime activated CGI 0.4.1 (CVE-2025-27219/27220), Resolv 0.3.0
+(CVE-2026-80212/80213), URI 0.13.1 (CVE-2025-27221/61594), and zlib 3.1.1
+(CVE-2026-27820). The project lockfile did not enumerate all of these default gems.
+Patched runtime dependency floors close this resolution gap. The native interpreter
+and its system libraries still require normal host security updates.
+
+The new audit regressions were first run against the original implementation and
+demonstrated the limit/schema/start/cancellation failures before correction.
+Primary evidence: `spec/security/release_audit_spec.rb`,
+`spec/integration/{concurrent_store,stagehand_http,generator,documentation}_spec.rb`,
+and the existing engine/store/job suites. The source repository's `docs/WORK.md` records the commands and dependency versions.
+
+## Open live-support and publication gates
+
+### P1: Provider-side security and protocol qualification (BR-02; blocks live support)
+
+The gem contains no browser firewall. A custom backend's `egress_isolation: :enforced`
+capability is a declaration, not independent proof. `StagehandBackend` stays
+`:unverified` and disabled. No live provider egress, TTL, billing, or cleanup
+qualification was performed. Stagehand 3.21 allows null navigation results, so final-URL
+reporting must be verified against an actual server. Unknown starts without session IDs
+have no correlation API in this adapter and cannot be automatically proven closed. Local
+time alone never releases their quota. These are provider/host evidence gaps, not
+mock-test tasks.
+
+### P1: Full live Act protocol is not implemented (deferred beyond the first release)
+
+The current Engine starts a new session for each call. Approval operation/session/page
+bindings are optional, and a digest of observed action candidates does not prove DOM
+or target revision. Keyword filters cannot prove semantic safety. Offline single-use
+store behavior is correct, but it is not the required same-session host decision.
+Live Act is disabled instead of presenting this as production-safe. Implement the
+protocol in a later version. No unaudited opt-in flag should bypass this Engine refusal.
+
+### P2: Distribution ownership and approval (BR-03 / BR-04; publication blockers)
+
+The RubyGems API returned 404 for `ruby_llm-browser` on 2026-10-18. It was
+unregistered at that check, not reserved or owned. The signed-in publisher account has
+MFA disabled; this gem requires MFA, so a push will be rejected until the owner enables
+it. Exact name availability, trademark/affiliation wording and owner/distributor
+clearance remain open. The 26-gem runtime license metadata inventory now matches the
+resolved lockfile; the Stagehand source MIT text is pinned in NOTICE. This technical
+inventory is not legal clearance.
+
+Independent H1 is complete and owner H2 approved the offline read-only scope and KPI
+proposal against exact Q `22d488987517b10dcd96d2713ed3d47e8818b36b` on 2026-10-18.
+The approval record is in the OddlyNiche Specs handoff. Baseline registration R and
+implementation receipt remain pending. H2 does not approve RubyGems publication or the
+exact release artifact.
+
+## Limits and follow-up checks
+
+- PostgreSQL remains untested. Local macOS Ruby 3.3.5 and the Linux Ruby 3.2/3.3/3.4
+  CI combinations pass with SQLite. Rails 7 is not a supported target.
+- A global reaper cannot route between backend credential configurations; use one
+  configuration per scoped store until provider identity is durably represented.
+- `max_cost_usd` is advisory. No provider-enforced currency cap or cost ledger exists.
+- Retained-output bounds are not remote-response, browser-memory, or bandwidth caps.
+- Sanitization is not a universal secret/PII detector. Host logs, queue arguments,
+  database contents and authenticated/private content require separate protection.
+- Job return values are not durable result delivery. Hosts need explicit authorized
+  result storage if they want it. Reservation and enqueue are not a transactional outbox.
+- The release hardening changes the development schema. Follow the additive migration
+  guidance; do not discard existing operation/approval records.
+
+## Checks completed
+
+Full offline suites run against RubyLLM 2.0.0 and 2.1.1, Rails components 8.0.5.1 and
+8.1.4, Stagehand 3.21.0, and SQLite 2.10.0 on Ruby 3.3.5: **302 examples, 0 failures**
+in each combination, with **89 Ruby files, no RuboCop offenses**. SDK HTTP requests are stubbed,
+with all other network requests disabled. A fresh ruby-advisory-db check reports no
+known vulnerable dependencies (database commit
+`fa2295251efb3b0d1a300e5ce8ad700ff1f1b485`). This is a point-in-time dependency check,
+not a guarantee of no vulnerabilities. Fresh installation also passes the core/Rails
+examples and installed generator/migration, and the activated clean core runtime is
+checked separately against advisories. Artifact verification is recorded in WORK.
+
+## Submission verification
+
+Commit `0ec34d4` is pushed to the repository. The expanded
+[GitHub Actions run](https://github.com/yorzi/ruby_llm-browser/actions/runs/39086570934)
+passed all seven compatibility jobs (302 examples each) and the build/install/advisory
+job, including `CORE_PACKAGE_PASS`, `CLEAN_RUNTIME_ADVISORIES_PASS`, and
+`RAILS_PACKAGE_PASS`. This closes the expanded-CI follow-up, not the live-provider or
+owner-approval gates. The source repository's `docs/RELEASE_ACTION_PLAN.md` records the owner decisions and follow-up actions.
+
+## Owner scope decision and qualification follow-up (2026-10-18)
+
+The owner selected a read-only first release, deferred the full live Act protocol to a
+later version, and explicitly declined live provider calls for this qualification. The
+built-in `StagehandBackend` now always reports egress as unverified and refuses live
+start, navigation, observation, extraction, and Act calls. The host cannot enable it with
+an `:enforced` assertion. The offline `FakeBackend` remains available.
+
+Browserbase's [Allowed Domains documentation](https://docs.browserbase.com/platform/browser/security/allowed-domains)
+describes top-frame navigation checks and does not establish blocking for iframes or
+subresources. This is insufficient evidence for the required browser-side egress policy.
+The [Update a Session endpoint](https://docs.browserbase.com/reference/api/update-a-session)
+accepts `REQUEST_RELEASE` and may return a session in `PENDING`; the [Get a Session endpoint](https://docs.browserbase.com/reference/api/get-a-session)
+exposes `status` and `endedAt`. Stagehand 3.21's `SessionEndResponse.success` only says
+the request succeeded, and its SDK does not expose that status lookup. The implementation
+therefore sends no Stagehand provider request, including `end_`; cleanup remains
+`cleanup_pending` until future work can verify terminal status. The stubbed HTTP contract
+tests now assert that no cleanup request is dispatched.
+
+No egress, TTL, billing, or cleanup live calls were made. BR-02 remains open for any
+future live backend, but it does not block the offline-only first-release scope. At the
+time of this initial audit snapshot, distribution decisions and the final release
+instruction were pending.
+
+## Owner release instruction (2026-10-18)
+
+After the initial audit snapshot, the owner selected gem version `0.1.0`, requested a
+matching Git tag, instructed RubyGems publication, and requested GitHub Actions automation
+for later version tags. This instruction authorizes the offline-only package release; it
+does not authorize provider calls, make Stagehand supported, or implement live Act. The
+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.

data/docs/RELEASING.md

@@ -0,0 +1,131 @@
+---
+layout: default
+title: Compatibility and Release Checklist
+description: Verify the package and release a version from its matching Git tag.
+---
+
+# Compatibility and release checklist
+
+Build and verify the package before you publish a version. GitHub Actions releases the
+gem from the matching version tag and deploys that version's documentation after success.
+
+After reading this guide, you will know:
+
+- Which combinations were exercised.
+- How to run offline checks and build an artifact.
+- Which evidence the automated release checks require.
+
+## Compatibility evidence
+
+The 2026-10-18 audit runs on Ruby **3.3.5**, arm64 macOS, with Stagehand **3.21.0**,
+JSONSchemer **2.5.0**, and sqlite3 **2.10.0**. Full offline suites cover:
+
+| RubyLLM | Active Record / Active Job | Result |
+| --- | --- | --- |
+| 2.1.1 | 8.1.4 | PASS |
+| 2.0.0 | 8.1.4 | PASS |
+| 2.0.0 | 8.0.5.1 | PASS |
+
+The expanded CI configuration includes Ruby 3.2/3.3/3.4 and RubyLLM 2.0.0/2.1.1,
+plus Rails 8.0. All seven compatibility jobs and the build/install/advisory job passed
+for commit `0ec34d4` in [this CI run](https://github.com/yorzi/ruby_llm-browser/actions/runs/39086570934).
+Do not treat that run as evidence for later code changes or live provider guarantees.
+Rails 7 and MySQL are not supported targets. PostgreSQL must be tested separately.
+
+## Running checks
+
+```bash
+bundle install
+bundle exec rake
+bundle exec bundle-audit check --update
+bundle exec ruby examples/plain_ruby.rb
+bundle exec ruby examples/rails_adapter.rb
+
+BUNDLE_GEMFILE=gemfiles/ruby_llm_2_0.gemfile bundle install
+BUNDLE_GEMFILE=gemfiles/ruby_llm_2_0.gemfile bundle exec rspec
+BUNDLE_GEMFILE=gemfiles/rails_8_0.gemfile bundle install
+BUNDLE_GEMFILE=gemfiles/rails_8_0.gemfile bundle exec rspec
+
+bundle exec rake build
+bundle exec ruby bin/verify-package --rails --audit
+```
+
+The default suite blocks unmocked network calls. HTTP contract tests use the actual
+Stagehand client/serializers with stubbed HTTP, not paid browser sessions. Generator
+tests resolve the documented Rails namespace and migrate the generated schema up/down.
+Documentation/package tests check local links, shipped guides/examples and executable
+offline README examples. These are bounded engineering checks, not a penetration test.
+
+## Verifying the built gem
+
+Use a fresh temporary directory for every install. Install the built gem there, then
+activate it from outside the checkout. Confirm its loaded entrypoint lives under that
+GEM_HOME, not under the source tree. Do not use `--ignore-dependencies` to claim that
+dependency resolution succeeded. A clean network-resolved install is stronger evidence
+than an install that borrows the developer's existing dependencies.
+
+`bin/verify-package` installs without `--ignore-dependencies`, activates the artifact
+outside the checkout, runs shipped examples, and optionally installs Rails and tests
+the shipped generator/migration. `--audit` checks the actually activated core runtime
+gems against the advisory database refreshed by `bundle-audit check --update`. This
+catches default gems that a development lockfile may omit. Logs and a JSON version
+inventory are retained in the temporary evidence directory printed by the command.
+
+Verify all of the following:
+
+- Core require loads no Rails, Active Record, Active Job, or Stagehand client.
+- The optional Rails require loads on demand.
+- The generated migration and all README-linked guides are shipped.
+- Both examples run using the installed artifact.
+- The artifact contains no keys, cookies, dumps, databases, lockfiles, or test fixtures.
+- Dependency/license inventory and known-advisory check match the resolved versions.
+- Record the artifact SHA-256, exact versions, commands and date in the WORK ledger.
+
+## Release boundaries
+
+The first-release scope is offline read-only. `FakeBackend` is the only built-in backend
+supported for operations. `StagehandBackend` refuses live calls, its egress capability
+stays unverified, and cleanup requests are disabled. The full live Act
+protocol is deferred to a later version. No provider calls were run or authorized.
+
+The owner selected version `0.1.0` for this package and instructed its release. H1 and
+H2 approved the product handoff against exact Specs candidate Q
+`22d488987517b10dcd96d2713ed3d47e8818b36b`; the candidate's historical version label is
+`0.3.0-draft`. The later release instruction is separate from H2. See [the audit findings]({% link RELEASE_AUDIT.md %}) for the live-provider limits.
+
+Keep Stagehand unsupported and live Act disabled. Before enabling either in a later
+version, qualify egress across every request path, final URL reporting, TTL, cleanup
+status, unknown-start recovery, and provider billing controls. No live provider call was
+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`.
+
+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
+`0.2.0`:
+
+```bash
+git tag -a v0.2.0 -m "Release 0.2.0"
+git push origin v0.2.0
+```
+
+The `Release Gem` workflow rejects a tag that does not match both the gem and docs
+versions, or has no matching changelog section. It runs the suite, dependency audit and
+isolated package verification before RubyGems publishing through OIDC trusted publishing.
+On success it creates a GitHub Release with the gem, checksum and matching changelog
+section. The Docs workflow then builds the tagged stable docs plus current `main` docs.
+Configure the matching
+pending trusted publisher on RubyGems with owner `yorzi`, repository `ruby_llm-browser`,
+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.