@mercuryo-ai/agentbrowse 0.2.60 → 0.2.63

package/docs/api-reference.md

@@ -97,21 +97,211 @@ Captures a screenshot of the current page.
 
 Closes the browser session.
 
-## Stable Error Code Arrays
+### `match(subject, options)`
 
-The root package exports stable top-level error code arrays for command
-branching:
+Decides which caller-supplied candidate value fits an observed target or
+fillable form. Pure and local — does not call the network and does not
+mutate browser state. See
+[Match / Resolve / Fill Guide](./match-resolve-fill.md) for the full
+mental model.
 
-- `ACT_ERROR_CODES`
-- `ATTACH_ERROR_CODES`
-- `CLOSE_ERROR_CODES`
-- `EXTRACT_ERROR_CODES`
-- `LAUNCH_ERROR_CODES`
-- `NAVIGATE_ERROR_CODES`
-- `OBSERVE_ERROR_CODES`
-- `SCREENSHOT_ERROR_CODES`
+```ts
+function match(
+  subject: TargetDescriptor | ProtectedFillForm,
+  options: AgentbrowseMatchOptions,
+): Promise<AgentbrowseMatchResult>;
+
+interface AgentbrowseMatchOptions {
+  from: AgentbrowseMatchSource;
+  host?: string;
+  protectedTargetRefs?: ReadonlySet<string>;
+}
+```
+
+### `resolve(plan, options)`
+
+Turns one or many `needs_resolution` plans into ready match results
+through a caller-supplied adapter. `ready` results pass through
+untouched. Overloaded for single plan and batch arrays.
+
+```ts
+function resolve(
+  plan: AgentbrowseMatchResult,
+  options: AgentbrowseResolveOptions,
+): Promise<AgentbrowseMatchResult>;
+
+function resolve(
+  plans: ReadonlyArray<AgentbrowseMatchResult>,
+  options: AgentbrowseResolveOptions,
+): Promise<AgentbrowseMatchResult[]>;
+
+interface AgentbrowseResolveOptions {
+  with: AgentbrowseMatchResolver;
+}
+```
+
+### `fill(session, subject, plan, options?)`
+
+Applies a match result to the browser. Dereferences the opaque
+value/artifact ref internally and hands off to the standard `act(...)`
+path (single targets) or `resolver.fill(...)` (grouped protected forms).
+
+```ts
+function fill(
+  session: BrowserCommandSession,
+  subject: Pick<TargetDescriptor, 'ref'> | ProtectedFillForm,
+  plan: AgentbrowseMatchResult,
+  options?: AgentbrowseFillOptions,
+): Promise<AgentbrowseFillResult>;
+
+interface AgentbrowseFillOptions {
+  resolver?: AgentbrowseMatchResolver;
+}
+```
+
+`fill(...)` can run `resolve` inline when you pass a `resolver` for a
+plan that still needs resolution — equivalent to the two-call form. See
+[match-resolve-fill.md → Walk-through 3](./match-resolve-fill.md#walk-through-3--collapsing-to-one-call).
 
-These arrays back the exported `*ErrorCode` types.
+## Result Shape
+
+All main commands share the same top-level pattern.
+
+```ts
+// success
+{ success: true, ...commandSpecificFields }
+
+// failure
+{
+  success: false,
+  error: <ErrorCode>,
+  outcomeType: <OutcomeType>,
+  message: string,
+  reason: string,
+  ...commandSpecificFields,
+}
+```
+
+- `error` — stable top-level code from the per-command table below.
+  Branch on this, not on `reason` or `message`.
+- `outcomeType` — stable outcome category (e.g. `binding_stale`,
+  `blocked`). Same vocabulary per command as the `*_OUTCOME_TYPES`
+  exports.
+- `message` — human-readable short message.
+- `reason` — detailed reason string. Usually a lower-level error code,
+  a truncation detail, or an explanation; see the sticky-owner note
+  below for one common special case.
+
+The root package exports stable arrays backing the `*ErrorCode` and
+`*OutcomeType` types for every command: `ACT_ERROR_CODES`,
+`ACT_OUTCOME_TYPES`, `ATTACH_ERROR_CODES`, `CLOSE_ERROR_CODES`,
+`EXTRACT_ERROR_CODES`, `EXTRACT_OUTCOME_TYPES`, `LAUNCH_ERROR_CODES`,
+`NAVIGATE_ERROR_CODES`, `OBSERVE_ERROR_CODES`, `OBSERVE_OUTCOME_TYPES`,
+`SCREENSHOT_ERROR_CODES`, `SCREENSHOT_OUTCOME_TYPES`.
+
+### Cross-command codes
+
+Any command that drives an already-open browser session may surface:
+
+| `error` | When | Action |
+| --- | --- | --- |
+| `browser_connection_failed` | AgentBrowse could not reach the browser. | Check `reason`. A common special value is `sticky_owner_unrecoverable` — the prior browser session is lost; launch or attach a fresh session before retrying. |
+
+### Error codes by command
+
+#### `launch`
+
+| `error` | When | Action |
+| --- | --- | --- |
+| `browser_launch_failed` | The managed browser could not be started. | Inspect `reason`/`message`; verify the host can run the browser. |
+
+#### `attach`
+
+| `error` | When | Action |
+| --- | --- | --- |
+| `browser_attach_failed` | Could not attach to the provided CDP URL. | Verify the CDP URL is reachable and exposes the protocol. |
+
+#### `navigate`
+
+| `error` | When | Action |
+| --- | --- | --- |
+| `browser_connection_failed` | See Cross-command codes. | — |
+| `navigation_failed` | Navigation did not complete. | Retry, or re-observe to see current page state. |
+
+#### `observe`
+
+| `error` | When | Action |
+| --- | --- | --- |
+| `browser_connection_failed` | See Cross-command codes. | — |
+| `observe_failed` | Page inspection failed (DOM or assistive runtime error). | Retry; if persistent, check the assistive runtime. |
+| `protected_observe_blocked` | The page is under active protected exposure; observation is blocked. | Complete or cancel the protected step first. |
+
+#### `act`
+
+| `error` | When | Action |
+| --- | --- | --- |
+| `act_failed` | Generic action failure not covered by a specific code. | Check `reason`/`message`. |
+| `action_not_allowed_for_target` | The requested action (`click`/`fill`/`type`/`select`/`press`) is not valid for this target kind. | Use an action compatible with the target's capability. |
+| `browser_connection_failed` | See Cross-command codes. | — |
+| `no_observable_progress` | The action ran but no DOM/UI change was detected within the wait window. | Re-observe; the target may need a different interaction. |
+| `stale_target` | The target binding is stale at execution time. | Re-observe and rebind. |
+| `stale_target_ref` | The passed `targetRef` no longer maps to an observed element. | Re-observe. |
+| `target_disabled` | Element is present but disabled. | Wait for enablement or resolve the blocker. |
+| `target_gated` | Element is gated behind an intermediate step. | Resolve the gating step first. |
+| `target_not_actionable` | Element exists but cannot be actioned (visibility or position). | Scroll/expand the owning scope, then re-observe. |
+| `target_readonly` | Element is read-only; `fill`/`type` are not allowed. | Use a different action or a different target. |
+| `target_surface_inactive` | The owning scope is currently inactive (e.g. a closed modal). | Activate or expand the scope first. |
+| `target_surface_not_live` | The owning scope is no longer live on the page. | Re-observe. |
+| `target_surface_unavailable` | The owning scope is not currently available. | Re-observe after any UI transition. |
+| `unknown_target_ref` | The `targetRef` was not issued by a prior `observe(...)`. | Never synthesise refs — pass back what `observe` returned. |
+| `validation_blocked` | The target accepted the input, but page-level validation blocks continuation. | Resolve the validation error and re-observe. |
+
+#### `extract`
+
+| `error` | When | Action |
+| --- | --- | --- |
+| `browser_connection_failed` | See Cross-command codes. | — |
+| `expired_extract_scope` | The scope ref expired (page moved past its lifetime). | Re-observe and use the new scope. |
+| `extract_failed` | Extraction failed at runtime. | Check `reason`/`message` and retry. |
+| `extract_output_truncated` | The assistive runtime returned a structured output that was cut off. | Raise `maxOutputTokens` in your adapter. |
+| `invalid_extract_schema` | The passed schema is not a supported shape. | See [Extraction Schema Rules](#extraction-schema-rules). |
+| `invalid_extract_scope` | The scope ref was provided but is not valid. | Verify the ref came from `observe(...)`. |
+| `stale_extract_scope` | The scope ref is stale against the current DOM. | Re-observe. |
+| `unknown_scope_ref` | The scope ref was not issued by a prior `observe(...)`. | Never synthesise refs. |
+
+#### `screenshot`
+
+| `error` | When | Action |
+| --- | --- | --- |
+| `browser_connection_failed` | See Cross-command codes. | — |
+| `protected_screenshot_blocked` | The page is under active protected exposure; screenshot is blocked. | Complete or cancel the protected step first. |
+| `screenshot_failed` | The screenshot attempt failed. | Check `reason`/`message`. |
+
+#### `close`
+
+| `error` | When | Action |
+| --- | --- | --- |
+| `browser_close_failed` | The browser session could not be closed cleanly. | Usually cosmetic; the process will eventually clean up. |
+
+#### `fill`
+
+Contract failures from `fill(...)` share a dedicated shape,
+`AgentbrowseFillFailureResult`, with `failureSurface: 'contract'` and
+`action: 'fill'`. Browser-level failures (stale refs, validation,
+connection) flow through the underlying `ActResult` / `resolver.fill`
+result instead — see `act` codes above and
+[protected-fill.md](./protected-fill.md).
+
+| `error` | When | Action |
+| --- | --- | --- |
+| `match_no_match` | `fill` received a `no_match` / `no_match_group` plan, or a subject-shape mismatch (field plan on a form, form plan on a field). | Do not retry with the same input. Re-observe or branch on the match result first. |
+| `match_ambiguous` | `fill` received an `ambiguous` / `ambiguous_group` plan. | Ask the caller to disambiguate before filling. |
+| `match_resolver_required` | Plan needs external resolution and no `resolver` was supplied, or the resolver is missing the required capability (`.resolve` for needs-resolution, `.fill` for grouped). | Provide a resolver adapter that implements the capability. |
+| `match_value_unavailable` | Internal value accessor is gone. Typically means a `ready` result was serialized across a process boundary and the non-enumerable accessor was lost. | Run `resolve` → `fill` inside the same process, or ship the `needs_resolution` plan instead. |
+| `match_artifact_unavailable` | Same failure mode as above, for grouped ready plans. | Same fix. |
+
+See [Protected Fill](./protected-fill.md) for the separate error and
+execution-kind vocabulary used by `fillProtectedForm(...)`.
 
 ## Error Classes
 
@@ -123,13 +313,6 @@ For code paths that want `instanceof` checks instead of string matching on
 - `AssistiveStructuredOutputTruncatedError` — thrown when the assistive
   runtime returns a structured output that was cut off mid-response.
 
-## Core Result Shapes
-
-All main commands use the same top-level pattern:
-
-- success: `{ success: true, ... }`
-- failure: `{ success: false, error, outcomeType, message, reason, ... }`
-
 ## Observe Types
 
 ### `ObserveTarget`
@@ -197,6 +380,115 @@ Fields:
 - `framePath`
 - `source`
 
+## Match / Resolve / Fill Types
+
+The exported types for the `match` / `resolve` / `fill` primitives.
+Read [match-resolve-fill.md](./match-resolve-fill.md) for how they
+compose in practice; this section is lookup-only.
+
+### Candidate sources
+
+- `AgentbrowseMatchSource` — union of `Record<string, AgentbrowseMatchValue>`,
+  `ReadonlyArray<AgentbrowseMatchCandidate>`,
+  `AgentbrowseMatchStore`,
+  `ReadonlyArray<AgentbrowseGroupMatchCandidate>`, or
+  `AgentbrowseGroupMatchStore`. All of these are valid `options.from`
+  values for `match(...)`.
+- `AgentbrowseMatchValue` — `string | number`.
+- `AgentbrowseMatchApplicability` — `{ target: 'global' | 'host'; value?: string }`.
+- `AgentbrowseMatchCandidate` — single-field candidate with optional
+  `candidateRef`, `value`, `type`, `label`, `semanticTags`,
+  `applicability`, `resolve` plan.
+- `AgentbrowseGroupMatchCandidate` — grouped candidate with required
+  `fieldKeys` plus optional `candidateRef`, `itemRef`, `label`,
+  `confidence`, `applicability`, `resolve` plan, `artifact`.
+- `AgentbrowseMatchStore` — `{ entries(), read(candidateRef) }`.
+  Opaque single-field store; values stay behind `read`.
+- `AgentbrowseGroupMatchStore` — `{ entries(), readArtifact(candidateRef) }`.
+  Opaque grouped store; artifacts stay behind `readArtifact`.
+
+### Match result union
+
+`AgentbrowseMatchResult` is a discriminated union over `kind`:
+
+- `AgentbrowseReadyMatchResult` — `kind: 'ready'` (single target).
+- `AgentbrowseNeedsResolutionMatchResult` — `kind: 'needs_resolution'`
+  with `plan: AgentbrowseResolutionPlan`.
+- `AgentbrowseAmbiguousMatchResult` — `kind: 'ambiguous'` with
+  `candidates: string[]`.
+- `AgentbrowseNoMatchResult` — `kind: 'no_match'` with a stable
+  `reason`: `'protected_target' | 'no_candidate' | 'scope_ineligible' | 'incompatible_shape' | 'low_confidence'`.
+- `AgentbrowseReadyGroupMatchResult` — `kind: 'ready_group'`.
+- `AgentbrowseNeedsResolutionGroupMatchResult` — `kind: 'needs_resolution_group'`
+  with `plan: AgentbrowseGroupResolutionPlan`.
+- `AgentbrowseAmbiguousGroupMatchResult` — `kind: 'ambiguous_group'`.
+- `AgentbrowseNoGroupMatchResult` — `kind: 'no_match_group'` with the
+  same `reason` vocabulary.
+
+`AgentbrowseResolvableMatchResult` is the narrower union of
+`'needs_resolution' | 'needs_resolution_group'` — what `resolve(...)`
+actually hands to your adapter.
+
+### Resolution plans
+
+- `AgentbrowseResolutionPlan` — `{ targetRef, candidateRef, fieldKey, type?, resolve }`.
+- `AgentbrowseGroupResolutionPlan` — `{ fillRef, pageRef, scopeRef?, purpose, candidateRef, itemRef?, fieldKeys, resolve }`.
+- `AgentbrowseMatchResolutionRequest` — `{ kind: string; key?: string; params?: Record<string, unknown> }`.
+  The `resolve` field on a candidate or plan. AgentBrowse does not
+  interpret `kind` or `key` — they are opaque to the core and meaningful
+  only to your adapter.
+
+### Resolved resources
+
+- `AgentbrowseResolvedResource` — `AgentbrowseResolvedValueResource | AgentbrowseResolvedArtifactResource`.
+- `AgentbrowseResolvedValueResource` — `{ kind: 'value'; value }`.
+- `AgentbrowseResolvedArtifactResource` — `{ kind: 'artifact'; artifact; itemRef?; requestId?; resolutionPath?; claimedAt? }`.
+- `AgentbrowseReadyGroupFillInput` — the shape `resolver.fill` receives:
+  `{ candidateRef, itemRef?, fieldKeys, artifact, requestId?, resolutionPath?, claimedAt? }`.
+
+### Resolver adapter
+
+Two exported interfaces. The `{ resolver }` slot on `fill(...)` accepts
+either via a union; `resolve(plan, { with })` only accepts the main
+resolver.
+
+```ts
+interface AgentbrowseMatchResolver {
+  resolve(plan): Promise<AgentbrowseResolvedResource>;
+  resolveBatch?(plans): Promise<ReadonlyArray<AgentbrowseResolvedResource>>;
+  fill?(session, subject, ready): Promise<Record<string, unknown> & { success: boolean }>;
+}
+
+interface AgentbrowseGroupFillHandler {
+  fill(session, subject, ready): Promise<Record<string, unknown> & { success: boolean }>;
+}
+```
+
+- `AgentbrowseMatchResolver` — full adapter. `resolve` is required;
+  `resolveBatch` and `fill` are optional. Used by `resolve(plan, { with })`
+  and by `fill(...)` for all plan kinds.
+- `AgentbrowseGroupFillHandler` — narrow handler used only at the
+  `fill(...)` boundary when the plan is `ready_group` and no resolution
+  is needed. A handler is not accepted by `resolve(...)`.
+
+At runtime, `fill(...)` picks the right capability via an internal type
+guard (`hasResolveCapability` / `hasGroupFillCapability`). When a
+capability the current plan needs is missing on the passed object,
+`fill(...)` returns a typed `match_resolver_required` failure instead
+of throwing.
+
+See [match-resolve-fill.md → Resolver Interface](./match-resolve-fill.md#resolver-interface)
+for examples of each shape.
+
+### Fill result
+
+- `AgentbrowseFillResult` — `ActResult | AgentbrowseFillFailureResult | (Record<string, unknown> & { success: boolean })`.
+  Single-target fill returns `ActResult`; grouped fill returns whatever
+  your `resolver.fill` returned; contract failures return
+  `AgentbrowseFillFailureResult`.
+- `AgentbrowseFillFailureResult` — `{ success: false; failureSurface: 'contract'; error; outcomeType; message; reason; targetRef?; fillRef?; action: 'fill' }`.
+  See the [`fill` error table](#fill) above for `error` codes.
+
 ## Ref Glossary
 
 - `ref`

package/docs/assistive-runtime.md

@@ -58,6 +58,9 @@ this usually means:
 
 1. Convert the Zod schema to JSON Schema (e.g. with
    `@browserbasehq/stagehand`'s `toJsonSchema`, or your own helper).
+   `@browserbasehq/stagehand` is a direct dependency of this package, so
+   `toJsonSchema` is available without a separate install. Alternatives
+   like `zod-to-json-schema` work too.
 2. Pass it as `response_format: { type: 'json_schema', json_schema: { ... } }`.
 3. Parse `choices[0].message.content` and return `{ data, usage? }`.
 
@@ -99,6 +102,9 @@ by hand.
 
 ## Recommended Setup
 
+The preferred path is a per-client runtime: pass your runtime into
+`createAgentbrowseClient({ assistiveRuntime })` and reuse that client.
+
 ```ts
 import { createAgentbrowseClient } from '@mercuryo-ai/agentbrowse';
 
@@ -106,16 +112,38 @@ const client = createAgentbrowseClient({
   assistiveRuntime: createOpenAiCompatibleAssistiveRuntime({
     baseUrl: 'https://api.openai.com/v1',
     apiKey: process.env.OPENAI_API_KEY!,
-    model: 'gpt-4.1-mini',
+    // Any OpenAI-compatible model that supports structured outputs.
+    model: process.env.OPENAI_MODEL ?? '<your-model>',
   }),
 });
 ```
 
 This pattern works well when:
 
-- your app is multi-tenant
-- you run parallel tests
-- different consumers in one process need different LLM settings
+- your app is multi-tenant;
+- you run parallel tests;
+- different consumers in one process need different LLM settings.
+
+### Per-client vs global runtime
+
+| Setup | When to use |
+| --- | --- |
+| `createAgentbrowseClient({ assistiveRuntime })` | Default. Keeps the runtime scoped to one client, works with multi-tenant and parallel scenarios. |
+| `configureAgentbrowseAssistiveRuntime(runtime)` | Fallback for small scripts and single-tenant processes — sets one global runtime for the whole process. Not recommended when multiple consumers may coexist. |
+
+Global-runtime shape:
+
+```ts
+import { configureAgentbrowseAssistiveRuntime } from '@mercuryo-ai/agentbrowse';
+
+configureAgentbrowseAssistiveRuntime(
+  createOpenAiCompatibleAssistiveRuntime({
+    baseUrl: 'https://api.openai.com/v1',
+    apiKey: process.env.OPENAI_API_KEY!,
+    model: process.env.OPENAI_MODEL ?? '<your-model>',
+  })
+);
+```
 
 ## OpenAI-Compatible Helper Example
 
@@ -232,21 +260,18 @@ Examples:
 - OpenRouter base URL:
   `https://openrouter.ai/api/v1`
 
-## Small Script Fallback
-
-For small scripts, you can also use:
-
-```ts
-import { configureAgentbrowseAssistiveRuntime } from '@mercuryo-ai/agentbrowse';
-```
-
-This is a convenience fallback, not the preferred embedded pattern.
-
 ## What Happens Without Assistive Runtime
 
-- `extract(...)` cannot run successfully
+- `extract(...)` cannot run successfully.
 - `observe(session, goal)` still runs, but quality may be lower because
-  AgentBrowse falls back to local heuristics instead of LLM-assisted ranking
+  AgentBrowse falls back to local heuristics instead of LLM-assisted
+  ranking.
+- `fillProtectedForm(...)` returns
+  `{ kind: 'unexpected_error', reason: 'assisted_value_resolution_failed' }`
+  for fields that require LLM-assisted resolution (split `full_name` into
+  given/family, localised dropdown values like nationality on a
+  non-English page, or any field pinned to the `llm_assisted` policy).
+  See [Protected Fill Guide](./protected-fill.md#split-fields-and-assistive-runtime).
 
 ## Testing Runtime
 

package/docs/configuration.md

@@ -15,6 +15,12 @@ Most applications can start with this mental model:
 2. keep the returned `session` in memory
 3. pass that `session` into later calls
 
+Both bootstrap the same sticky-owner lifecycle. AgentBrowse may keep that
+owner in-process or in an internal detached host, but consumers do not manage
+that host directly. Detached hosts default to a 30 minute TTL and may be
+recreated on the next browser command if the browser session itself is still
+alive.
+
 You only need more configuration when you want one of these:
 
 - custom LLM integration
@@ -43,6 +49,10 @@ const attached = await attach(remoteCdpUrl, {
 The provider label is metadata only — AgentBrowse treats the connection as
 a generic CDP-attached browser session regardless of the label.
 
+`attach(...)` creates the same sticky-owner metadata as `launch(...)`. Later
+browser commands reuse that owner and only attempt a fresh root attach again
+as a repair path after owner loss.
+
 ## Client Configuration
 
 ```ts
@@ -68,6 +78,9 @@ configuration is the cleaner embedded pattern.
 Persistence is optional. Use it when you want to restore a browser session
 after a process restart.
 
+Persisted session files store browser identity plus versioned sticky-owner
+metadata. They do not serialize a live Playwright connection.
+
 ### Default Store
 
 ```ts
@@ -76,12 +89,12 @@ import { loadBrowserSession, saveBrowserSession, status } from '@mercuryo-ai/age
 saveBrowserSession(session);
 const restored = loadBrowserSession();
 
-// Always check a restored session before using it — the browser it points
-// at may already be gone.
+// `null` means there is no usable persisted session. That includes
+// incompatible reconnect-era records and incomplete owner metadata.
 if (restored) {
   const check = await status(restored);
-  if (!check.success) {
-    // The session is no longer reachable. Discard and relaunch.
+  if (!check.alive) {
+    // The session is no longer reachable. Discard and relaunch or re-attach.
   }
 }
 ```
@@ -90,6 +103,21 @@ Default path:
 
 `~/.agentbrowse/browse-session.json`
 
+If the detached owner host is gone but the underlying browser session is still
+alive, the first command after restore may repair ownership. If the browser is
+gone, AgentBrowse fails closed and you should start a fresh session.
+
+### Sticky Owner TTL
+
+Detached sticky-owner hosts use a bounded lifetime by default:
+
+- default TTL: `30` minutes
+- env override: `AGENTBROWSE_STICKY_OWNER_TTL_MS=<milliseconds>`
+
+This TTL is a resource guard for the detached owner host, not for the browser
+session itself. If the TTL expires and the browser is still reachable, the next
+browser command may bootstrap a fresh owner and continue.
+
 ### Custom Store
 
 For embedded apps, prefer an explicit store root:
@@ -108,6 +136,10 @@ store.delete();
 
 This avoids hidden machine-level coupling to `~/.agentbrowse`.
 
+`store.load()` follows the same contract as `loadBrowserSession()`: it returns
+`null` for missing files, incompatible old records, or unusable sticky-owner
+metadata.
+
 ## Proxy Configuration
 
 The clearest way to use a proxy is to pass it directly to `launch(...)`.

package/docs/getting-started.md

@@ -19,9 +19,18 @@ The normal flow is:
 5. `close(session)` ends the browser session
 
 The `session` is the key object in the whole API. It is the handle that keeps
-the browser connection and runtime state together between calls. A session
-stays valid while the underlying browser connection is live; call
-`status(session)` to check if you need to.
+the browser connection, runtime state, and sticky-owner metadata together
+between calls. Healthy commands reuse that sticky owner instead of issuing a
+fresh root attach on every call. If you persist the session and restart your
+process, the next command may repair the owner while the underlying browser is
+still alive; otherwise the session fails closed and you start fresh. Detached
+sticky owners also have a bounded lifetime, so an idle or expired owner may be
+recreated on the next browser command while the underlying browser session is
+still live.
+
+The sticky owner may live in-process or in an internal detached host. That is
+an implementation detail of AgentBrowse, not a daemon you manage separately.
+Detached hosts default to a 30 minute TTL.
 
 Refs returned by `observe(...)` (target refs, scope refs, fill refs) are
 valid for the page state that produced them, not forever. Any of these
@@ -33,12 +42,14 @@ invalidates them:
 
 After any of the above, call `observe(...)` again and use the new refs.
 
-At a high level, AgentBrowse has three kinds of behavior:
+At a high level, AgentBrowse has four kinds of behavior:
 
 - normal browser execution for `launch`, `navigate`, `observe`, `act`,
   `status`, `screenshot`, and `close`
 - assistive page understanding for `extract` and some goal-based
   `observe(session, goal)` calls
+- deterministic field data-plane for deciding which caller-supplied
+  value belongs in which observed field (`match`, `resolve`, `fill`)
 - protected fill for applying sensitive values you already have through a
   guarded form execution path
 
@@ -116,6 +127,11 @@ Success result includes:
 - current `url`
 - current `title`
 
+`attach(...)` bootstraps the same sticky-owner lifecycle as `launch(...)`.
+After attach succeeds, later browser commands use that owner. A new provider-
+level root attach is only attempted again as an explicit repair path after
+owner loss.
+
 ### `observe(session, goal?)`
 
 Reads the current page and returns what AgentBrowse found.
@@ -141,6 +157,22 @@ serve different intents:
 - `observe(session)` is for general page inspection
 - `observe(session, goal)` is for a focused question
 
+These examples share a shape that works well: each names one control,
+optionally anchored to a surface. A useful goal looks like
+`"find <target> in <surface>"`:
+
+- one target — a single field, button, or grid cell
+- one surface — the active form, the open datepicker, the visible banner
+- one step — the goal describes what the next `act` will target,
+  not the rest of the plan
+
+When the task takes several steps, run one `observe` per step:
+
+1. `observe(session, "find the date picker trigger in the top search form")`
+2. `act(session, trigger.ref, "click")`
+3. `observe(session, "find May 5, 2026 in the open calendar")`
+4. `act(session, cell.ref, "click")`
+
 ### `act(session, targetRef, action, value?)`
 
 Executes a browser action against a `targetRef` returned by `observe(...)`.
@@ -172,12 +204,42 @@ before calling it.
 Returns local browser/runtime diagnostics for an existing session.
 
 Use it when you want to know whether the browser is still reachable and what
-page AgentBrowse believes it is on.
+page AgentBrowse believes it is on. After restoring a persisted session,
+`status(session)` is the cheapest explicit health check before more expensive
+workflows.
 
 ### `close(session)`
 
 Closes the browser session.
 
+This also terminates the internal sticky owner. Repeated closes and already-
+dead owner hosts are treated as idempotent.
+
+### `match` / `resolve` / `fill`
+
+Three primitives for the «key–value pairs into an observed form» problem.
+Instead of calling `act(session, ref, 'fill', value)` by hand, the
+primitives let you hand a source of candidate values to `match(...)`,
+resolve externally stored values through a caller-supplied adapter, and
+apply the result to the browser deterministically — without the values
+passing through LLM prompts or public result objects.
+
+The typical shape is `match → (resolve) → fill`:
+
+```ts
+import { match, resolve, fill } from '@mercuryo-ai/agentbrowse';
+
+const matched = await match(emailTarget, {
+  from: { email: 'traveler@example.com' },
+});
+await fill(session, emailTarget, matched);
+```
+
+See the dedicated [Match / Resolve / Fill Guide](./match-resolve-fill.md)
+for the full mental model, walk-throughs (value in hand, external
+lookup, batch, grouped protected forms), and the design rules (no raw
+values in public results, stable resolved refs, adapter boundary).
+
 ## How To Handle Results
 
 All main commands use the same broad pattern:
@@ -233,6 +295,11 @@ If you want to restore a browser session between process runs, use:
 - `loadBrowserSession()`
 - `createBrowserSessionStore({ rootDir })`
 
+Persisted session records now require restorable sticky-owner metadata.
+Incompatible reconnect-era records are rejected at load time instead of being
+auto-migrated. Treat `loadBrowserSession() === null` as "no usable session",
+not as a recoverable partial state.
+
 See:
 
 - [Configuration Guide](./configuration.md)
@@ -240,6 +307,7 @@ See:
 ## Next Docs
 
 - [API Reference](./api-reference.md)
+- [Match / Resolve / Fill Guide](./match-resolve-fill.md)
 - [Configuration Guide](./configuration.md)
 - [Assistive Runtime Guide](./assistive-runtime.md)
 - [Protected Fill Guide](./protected-fill.md)