ruby_llm-browser 0.1.0 → 0.2.0

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/whats-new-in-0-2.md

@@ -0,0 +1,47 @@
+---
+layout: default
+title: What's New in 0.2
+redirect_from:
+  - /whats-new/
+nav_order: 4
+description: Use the read-only tool factory and backend-aware diagnostics in this release.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+
+After reading this guide, you will know:
+
+- How to register the read-only tool pair.
+- How to distinguish offline diagnostics from live-backend checks.
+- Where to verify changes locally before upgrading.
+
+## Read-only Tool Factory
+
+You can register the read-only tools in one call:
+
+```ruby
+chat.with_tools(*RubyLLM::Browser.tools(context: context, schema: schema))
+```
+
+The host still supplies context and schema. The factory returns Inspect and Extract
+instances and never registers Act. Individual constructors remain supported. Read
+[Inspecting and extracting]({% link _core_features/inspect-extract.md %}) for a complete
+offline example and the validation behavior.
+
+## Backend-aware Diagnostics
+
+Doctor adds a `mode` field while preserving `ok`, `summary`, and `checks`. FakeBackend
+reports `offline` mode and skips provider environment and SDK checks. Stagehand
+reports `live` mode and remains blocked. Custom backends no longer receive unrelated
+Stagehand warnings. Read [Checking Configuration]({% link _core_features/diagnostics.md %}).
+
+## Development Verification
+
+Use `bin/check` for offline contracts, lint, alternate bundles, and examples. Use
+`bin/check-browser` for desktop/mobile workflows and fixture screenshots. The
+[development guide]({% link _advanced/development-and-testing.md %}) explains setup,
+package verification, and the limits of this evidence.
+
+Stagehand and live Act remain unsupported. This release remains offline-only.

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,188 @@
+---
+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#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.
+
+## 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,14 @@ 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.2.0]({% link _getting_started/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 %}).

data/docs/_reference/roadmap.md

@@ -0,0 +1,163 @@
+---
+layout: default
+title: Roadmap to 1.0
+nav_order: 8
+description: Plan small releases toward a reliable read-only browser integration for RubyLLM.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+
+After reading this guide, you will know:
+
+- What works today and what still blocks practical live use.
+- Which small features belong in the next release.
+- What must pass before the project releases 1.0.0.
+
+## Start with a Narrow 1.0
+
+The proposed 1.0 supports one complete workflow: your RubyLLM application inspects an
+approved public page or extracts schema-checked data, receives a bounded result with
+provenance, and can account for the browser session through cleanup. It works in plain
+Ruby and through the optional Rails adapter.
+
+Version 0.1.0 introduced the offline foundation: Inspect, Extract, URL policy, bounded
+results, operation bookkeeping, Rails jobs, and Act simulation. It does not provide a
+supported live backend. The current Stagehand adapter refuses live operations. Rails
+jobs track state but do not durably deliver result bodies.
+
+**This is a proposed development sequence, not a list of available features or release
+dates.** Future API names below are proposals. Keep each release small; use patch
+releases for fixes and split a milestone if implementation reveals a larger change.
+
+## Release Sequence
+
+Build convenience on the current offline API first. Complete the Rails result path
+next. Qualify one live deployment before advertising browser support, then use pilot
+feedback to settle the public API.
+
+| Version | Outcome | Release condition |
+| --- | --- | --- |
+| 0.2.0 | Easier tool setup and clearer offline diagnostics | Two additive features, tested with no provider requests |
+| 0.3.0 | Usable Rails result delivery | A host can retrieve a job's result after the worker exits |
+| 0.4.0 | One supported live read-only deployment | Egress, final URL, session expiry and cleanup qualified on that deployment |
+| 0.5.0 | Pilot feedback and recovery hardening | Plain-Ruby and Rails workflows exercised outside the test suite |
+| 1.0.0-rc.1 | Stable API candidate | Feature freeze, complete upgrade instructions, candidate package verified |
+| 1.0.0 | Supported read-only integration | All acceptance criteria below pass on the release candidate |
+
+### 0.2.0: Two Small Features
+
+Version `0.2.0` adds both features below. Later milestones remain proposed scope. See
+[What's New]({% link _getting_started/whats-new-in-0-2.md %}) for usage and
+[development and testing]({% link _advanced/development-and-testing.md %}) for validation.
+
+1. Add the read-only tool factory `RubyLLM::Browser.tools(context:, schema:)`.
+   Return Inspect and Extract instances suitable for `chat.with_tools(*tools)`. Keep
+   the context and extraction schema explicit; never include Act. Reuse the existing
+   constructors and validation instead of creating a second configuration API.
+2. Make Doctor distinguish offline and live-backend checks. FakeBackend diagnostics
+   should not warn that provider credentials are missing. Live-backend reports must
+   keep the unsupported Stagehand reason visible. Preserve the structured report and
+   make clear that a passing local check does not qualify a provider.
+
+Acceptance: exercise the factory through RubyLLM's public tool-registration API on
+both supported RubyLLM versions; reject an invalid schema; verify no Act registration,
+provider request, credential discovery, or Rails load. Test Doctor with fake and
+unsupported live backends. Update the relevant guides and changelog with the features.
+
+Do not add a CLI, a context builder, new database tables, or live support in this slice.
+The factory and Doctor are implemented in separate commits. Local and remote
+validation precede the release tag and publication.
+
+### 0.3.0: Complete the Rails Result Path
+
+Add an opt-in result-delivery hook that lets the host persist the sanitized `Result`
+against its operation ID. Provide a runnable host example that stores and retrieves
+the result after an asynchronous job finishes. The host owns access checks, retention,
+and storage; the gem does not need an admin interface or a general results database.
+
+Acceptance: retrieve a schema-checked extraction after worker exit; refuse cross-actor
+reads in the host example; handle success, truncation, failure, and pending cleanup.
+A delivery failure must be visible and must never cause the browser operation to run
+again. Document delivery semantics, duplicate handling, and recovery separately from
+the operation's session state. Verify generator upgrades preserve existing records.
+
+### 0.4.0: Qualify One Live Read-only Deployment
+
+Begin with a feasibility check of the pinned SDK and a named deployment. Determine
+whether the deployment can enforce every required browser request boundary and report
+verified final URLs and terminal session state. Implement only the missing adapter
+integration needed for that deployment. Keep live Act disabled.
+
+Acceptance requires deployment-specific evidence for redirects, subresources, frames,
+popups, WebSockets, connection-time DNS/IP restrictions, final URLs, session expiry,
+and confirmed cleanup. Exercise timeouts, worker death, and lost start responses with
+controlled fixtures. Unknown sessions retain quota and have an explicit host review
+path; an SDK acknowledgement alone cannot release them.
+
+Prepare the fixtures and opt-in qualification runner offline first. Live runs require
+separate owner authorization for the deployment, data, and spending. Keep default CI
+offline. Report provider billing controls separately from the advisory cost field.
+
+If the deployment cannot meet the required controls, stop this milestone and record
+the gap. Keep live support disabled. Do not replace qualification with a boolean flag
+or promote an offline-only package to 1.0 under this plan.
+
+### 0.5.0: Exercise Real Application Workflows
+
+Run two authorized pilots: a plain-Ruby extraction and a Rails background extraction
+with durable host result retrieval. Record the exact dependency/deployment versions,
+fixture expectations, observed results, failures, and cleanup outcomes. A controlled
+host application is sufficient; customer adoption is not a release prerequisite.
+
+Use pilot findings to improve errors, delivery, cancellation, and recovery. Confirm
+that duplicate jobs do not repeat provider starts, unknown outcomes remain visible,
+and result limits and redaction behave as documented. Resolve public API changes now
+and provide migrations before freezing the API.
+
+### 1.0.0-rc.1: Freeze and Verify
+
+Freeze tool constructors, factory arguments, result fields, error codes, backend/store
+contracts, and Rails schema/delivery hooks. Publish migration instructions for every
+breaking pre-1.0 change. Run the declared Ruby/RubyLLM/Rails matrix, build the gem,
+install the actual artifact in a clean environment, and verify its shipped examples,
+generator, guides, and dependency audit.
+
+Repeat the live qualification against the candidate's exact artifact and deployment.
+Fix defects through further release candidates. Feature requests return to a later
+minor release. A candidate with an unresolved blocker does not advance to 1.0.0.
+
+## 1.0.0 Acceptance Criteria
+
+- **Useful:** both pilot workflows complete, and one named live read-only deployment
+  is supported with reproducible evidence and documented limits.
+- **Controlled:** URL policy, schema validation, result bounds, and redaction pass
+  positive and denial cases. Deployment qualification covers all browser request paths.
+- **Recoverable:** cancellation, duplicate jobs, worker death, unknown starts, and
+  pending cleanup preserve correct state and quota. Host recovery steps are tested.
+- **Retrievable:** a Rails host can persist and authorize result retrieval after a job
+  exits. Delivery failure cannot trigger a repeated browser action.
+- **Stable:** the public API and database upgrade path are documented and covered by
+  compatibility checks. Unsupported databases and backends are identified explicitly.
+- **Distributable:** the release artifact passes the compatibility matrix, clean
+  installation, examples, documentation build, and dependency checks. Version, tag,
+  changelog, and stable documentation agree. The owner authorizes publication.
+
+Live Act, multiple providers, PostgreSQL qualification, authenticated browsing,
+screenshots, downloads, arbitrary JavaScript, a hosted UI, and a cost ledger are not
+required for this 1.0. Keep unsupported capabilities explicit. Consider live Act only
+as a separate feature with same-session approval and target identity guarantees.
+
+## Keep Planning and Documentation Separate
+
+The README introduces the project. Site guides teach supported behavior and provide
+the API reference. This page owns future scope; the changelog records shipped changes.
+Historical release audits remain evidence for their exact versions, not a current
+task queue. Plan changes do not rewrite the approved specification baseline.
+
+Read [API and configuration]({% link _reference/api-and-configuration.md %}),
+[Rails jobs and recovery]({% link _advanced/rails-integration.md %}), and
+[live-backend qualification]({% link _advanced/live-backend-qualification.md %}) for
+the current contracts. Follow [the release checklist]({% link RELEASING.md %}) when a
+milestone is ready to ship.

data/docs/_reference/upgrading.md

@@ -2,32 +2,63 @@
 layout: default
 title: Upgrading
 nav_order: 2
-description: Check the supported upgrade path before moving a RubyLLM::Browser application to a new version.
+description: Upgrade from 0.1.0 while preserving tool registration, diagnostics, and operation data.
 ---
 
 # {{ page.title }}
 
 {{ page.description }}
-{: .fs-6 .fw-300 }
 
 After reading this guide, you will know:
 
-* What changed in the first public release.
-* Where to find migration steps for earlier development snapshots.
-* What evidence must exist before a release tag is treated as supported.
+- How to update an application from 0.1.0.
+- Which tool and diagnostic contracts remain compatible.
+- How to preserve data from earlier development snapshots.
 
-## Public Releases
+## Upgrade from 0.1.0
 
-Version `{{ site.version }}` is the first public release. It has no earlier public version
-to migrate from. Install it with `bundle add ruby_llm-browser --version "~> {{ site.version }}"`.
+Update your Gemfile and bundle:
+
+```ruby
+gem "ruby_llm-browser", "~> {{ site.version }}"
+```
+
+```sh
+bundle update ruby_llm-browser
+```
+
+There is no database migration or new runtime dependency. Keep existing operation and
+approval records. The individual Inspect and Extract constructors remain supported.
+You can optionally replace their registration with:
+
+```ruby
+chat.with_tools(*RubyLLM::Browser.tools(context: context, schema: schema))
+```
+
+The host still supplies the context and extraction schema. The factory never adds Act.
+
+## Read Doctor Reports by Name
+
+Doctor adds `mode` while retaining `ok`, `summary`, and `checks`. Check names now depend
+on the backend. Do not require Stagehand or credential checks in every report, and do
+not rely on check order. FakeBackend diagnostics skip provider environment and SDK
+checks. Stagehand still reports a failure; `mode: :live` does not enable it.
+
+Read [Checking Configuration]({% link _core_features/diagnostics.md %}) for the report
+fields. No live browser provider is supported by this release.
 
 ## Earlier Development Snapshots
 
-If you ran an earlier development Rails generator, do not drop existing operation data
-or rerun a create-table migration. Follow the additive migration instructions under
-"Upgrading an earlier development snapshot" in the [Rails guide]({% link RAILS.md %}). Drain workers during the migration and do not reuse idempotency keys for legacy rows that lack request digests.
+If you used an earlier development Rails generator, preserve operation data and follow
+the additive migration instructions in the
+[Rails guide]({% link _advanced/rails-integration.md %}). Drain workers during migration;
+do not reuse idempotency keys for legacy rows without request digests.
+
+For the previous version's instructions, read the
+[0.1.0 upgrading guide](https://github.com/yorzi/ruby_llm-browser/blob/v0.1.0/docs/_reference/upgrading.md).
 
 ## Next Steps
 
-* Review the [release history]({% link _reference/release-history.md %}) for version records.
-* Review the [release audit]({% link RELEASE_AUDIT.md %}) before enabling a live backend.
+- Read [What's New in 0.2]({% link _getting_started/whats-new-in-0-2.md %}).
+- Review [release history]({% link _reference/release-history.md %}) and
+  [live-backend qualification]({% link _advanced/live-backend-qualification.md %}).

data/docs/index.md

@@ -35,7 +35,7 @@ features:
 
 ## Before You Install
 
-The first release is `0.1.0` and supports only the offline `FakeBackend`. The built-in
+Version `{{ site.version }}` supports only the offline `FakeBackend`. The built-in
 Stagehand adapter is unsupported until provider egress and confirmed cleanup are
 qualified. The full live Act protocol is deferred to a later version.
 
@@ -70,8 +70,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"}
 ```

data/examples/plain_ruby.rb

@@ -23,12 +23,15 @@ context = RubyLLM::Browser::Context.new(
   budget: RubyLLM::Browser::Budget.new(max_seconds: 30, max_steps: 6)
 )
 
-inspect = RubyLLM::Browser::Inspect.new(context: context)
-puts "Inspect: #{inspect.execute(url: "https://docs.example.com/")}"
-
 schema = { "type" => "object", "properties" => { "title" => { "type" => "string" } } }
-extract = RubyLLM::Browser::Extract.new(context: context, schema: schema)
+inspect, extract = RubyLLM::Browser.tools(context: context, schema: schema)
+puts "Inspect: #{inspect.execute(url: "https://docs.example.com/")}"
 puts "Extract: #{extract.execute(url: "https://docs.example.com/", instruction: "the title")}"
 
 blocked = inspect.execute(url: "http://169.254.169.254/latest/meta-data")
 puts "Blocked: #{blocked[:error][:code]}"
+
+report = RubyLLM::Browser::Doctor.new(backend: context.backend).report
+raise "offline diagnostic failed" unless report[:ok] && report[:mode] == :offline
+raise "provider checks ran offline" if report[:checks].any? { |check| check[:name] == :credentials }
+puts "Doctor: #{report[:mode]}"