@reclaimprotocol/agent 0.1.29 → 0.1.32

package/skill/SKILL.common.md

@@ -22,6 +22,12 @@ already names it.
 <!-- section: browser -->
 ## Choosing a browser
 
+## Contents
+
+- [Sharing a container browser](#sharing-the-containers-live-view-share_browser_view)
+- [Container lifetime and isolation](#how-containers-are-shared-and-when-they-close)
+- [Container startup problems](#when-the-container-will-not-start)
+
 **Ask one question first, before you list anything:**
 
 > Will you be doing this yourself, or does someone else need to sign in — the
@@ -92,8 +98,8 @@ persist it. If a `liveViewUrl` comes back, share it full and verbatim.
 
 A `container` browser serves its own viewer on loopback, so the developer can
 open it the moment `attach_browser` returns. `share_browser_view` puts that same
-viewer behind a public HTTPS URL through a cloudflared quick tunnel — for when
-the person who has to act is not at that machine: a login or 2FA only they can
+viewer behind a public HTTPS URL through a cloudflared quick tunnel that you
+run — for when the person who has to act is not at that machine: a login or 2FA only they can
 complete, or a colleague watching a capture.
 
 **Offer it whenever a login is coming and the developer is not the one holding
@@ -104,8 +110,17 @@ Ask plainly:
 > whoever holds the login — they can watch and click in it, including from a
 > phone.
 
-If they say yes, call `share_browser_view` and **relay the full returned URL
-verbatim, on its own line.** It includes `liveview.html?magnify=1`.
+If they say yes:
+
+1. Call `share_browser_view` with no arguments. It returns the viewer `port` and
+   the `command` (`cloudflared tunnel --url http://localhost:<port>`). The MCP
+   server does not run cloudflared.
+2. Run `command` yourself in the background. If `cloudflared` is not installed,
+   ask the developer to install it; do not install it without their approval.
+3. Read its output for the `https://<words>.trycloudflare.com` URL. Never guess
+   or reconstruct the hostname.
+4. Call `share_browser_view({ publicUrl })` with that URL. **Relay the returned
+   `url` verbatim, on its own line.** It includes `liveview.html?magnify=1`.
 
 - **`container` is the only mode this applies to.** `builder` returns a hosted
   `liveViewUrl` from `attach_browser` — relay that instead, full and verbatim.
@@ -123,24 +138,16 @@ verbatim, on its own line.** It includes `liveview.html?magnify=1`.
 - **Opening it on a phone lays the page out for that phone**, with touch,
   pinch-zoom and the soft keyboard. That is the reason to reach for `container`
   when a site only works on mobile.
-- **Call `stop_browser_view` as soon as they're done.** That closes the tunnel
-  only — the browser keeps running. `dispose_browser` and `reset_session` stop
-  the container itself.
-- **If the URL will not load**, check `propagating`. The hostname can exist
-  before Cloudflare finishes routing it. Keep the returned share open, wait a
-  few seconds, and reload; don't start a second tunnel while it propagates.
-  `cloudflaredLog` contains bounded diagnostic output. If it still fails after
-  60 seconds, call `stop_browser_view`, then retry `share_browser_view` once.
-- **cloudflared is handled for you.** An existing install on PATH wins;
-  otherwise it's fetched once into `~/.reclaim/bin` on the first share, never at
-  install time. Tell the developer when the download starts.
-  `RECLAIM_CLOUDFLARED_PATH` points at their own copy instead.
+- **Stop the cloudflared process you started as soon as they're done.** The
+  browser keeps running. `dispose_browser` and `reset_session` stop the
+  container itself, but not your cloudflared process.
+- **Expose only the viewer port** that `share_browser_view` returns, never the
+  browser's CDP port.
 
 ### How containers are shared, and when they close
 
-- **Closing the agent releases the browser.** The server stops the container and
-  the tunnel when its connection drops, so a public URL never outlives the
-  session that made it. `dispose_browser` does the same on demand.
+- **Closing the agent releases the browser.** The server stops the container
+  when its connection drops. `dispose_browser` does the same on demand.
 - **Re-attaching in one session reuses the same browser** — under a second,
   rather than the twenty a fresh one costs — so whatever it is signed into is
   still there.
@@ -151,9 +158,10 @@ verbatim, on its own line.** It includes `liveview.html?magnify=1`.
   own profile, and starts out signed in to nothing.
 - **Four at once is the ceiling**, because each is about 2 GB of RAM. Past that,
   `attach_browser` says so and points at `dedicated`.
-- **A crash cannot strand one for long.** A killed session runs no cleanup, so
-  the next `container` attach removes any container whose owning process is gone.
-  One belonging to a session that is still alive is never touched.
+- **A crash cannot strand one for long.** A killed session runs no normal
+  cleanup, so the next `container` attach removes any container whose owning
+  process is gone. Resources belonging to a live session are
+  never touched.
 
 ### When the container will not start
 
@@ -270,6 +278,10 @@ anything the developer wouldn't post publicly), put the four options to them.
    `hash` or capture a request whose URL doesn't carry it.
 3. Never pass `hash` for a free-form target (unicode / spaces / punctuation).
 
+**Disambiguate repeated JSON values.** `propose_provider` rejects a target
+found at multiple JSON paths instead of guessing which field the user meant.
+Choose a target that identifies one field.
+
 `propose_provider` throws a clean error on all three — retrying the same call
 won't help.
 
@@ -297,6 +309,8 @@ won't help.
    `propose_provider` again with different inputs instead.
 
 <!-- section: secrets -->
+### Protect secret values
+
 **Marking a value secret.** Name ANY param with `SECRET` anywhere in the key
 (case-insensitive) — a bare `{{SECRET_x}}` as much as a consumer-supplied
 `{{%CTX%SECRET_apiKey}}` — and it routes to `secretParams.paramValues`
@@ -323,6 +337,8 @@ captured secret *header* whose value also sits in the URL, which is already
 known and so gets checked at draft time (`assertNoSecretUrlConflict`).
 
 <!-- section: no-rename-param -->
+### Hide internal fields from claimant UI
+
 **Keep internal claim-construction fields out of claimant-facing UI.** When a
 named regex group or `{{parameter}}` only helps construct another claim request,
 consider an internal prefix:

package/skill/SKILL.old.md

@@ -109,8 +109,18 @@ it. Don't assume `authenticate_builder` fixes it.
 <!-- topic: draft -->
 ## Draft the provider
 
+## Contents
+
+- [Choose a privacy mode](#choose-a-privacy-mode)
+- [Draft and inspect the request](#draft-and-inspect-the-request)
+- [Preserve the canonical shape](#preserve-the-canonical-shape)
+
+### Choose a privacy mode
+
 <!-- common: oprf -->
 
+### Draft and inspect the request
+
 **Call `propose_provider`.** It returns a **`draftId`** — the handle for
 `replay_request` and `run_proof` — plus the secret-free `provider` and
 `secretRefs`. The recipe **and the captured secret values** live server-side
@@ -171,6 +181,8 @@ field they control. The synthesizer does this for you.
 With `hash: 'oprf-raw'`, the redaction gains `"hash": "oprf-raw"`. Nothing else
 changes.
 
+### Preserve the canonical shape
+
 <!-- common: rewrite-shape-block -->
 
 <!-- topic: params -->
@@ -271,7 +283,7 @@ Call `create_provider_version_from_capture`:
 - **Login/navigation-gated data:** supply `customInjection` (plain page JS) and
   `allowedInjectedRequestData` (extra requests the script may fire).
   → topic `user-script`. Before populating `allowedInjectedRequestData` for a
-  `verifyProof({ providerId })` use case, read topic `hash-validation`.
+  `verifyRequestProof({ providerId })` use case, read topic `hash-validation`.
 
 **Ownership — you can only add a version to a provider YOU own.** The
 `providerId` must come from `get_me_providers`. Versioning a public provider you
@@ -306,8 +318,10 @@ applies them.
   would fetch. Reads the public production SDK backend directly, no auth.
 
 There's no create-then-version step and no org / public-review workflow here.
-When done, tell the developer the version is live and that they can integrate
-using the `providerId`.
+When done, tell the developer the version is live, then ask once how they want
+to use it — try it now, integrate it into an existing backend or frontend, or
+create a new app — unless they already said (see "Using a provider" in the
+server instructions).
 
 **If the response includes `_notes` for an attached browser, follow them for an
 optional authenticated-state retest.** Only when its profile is still signed in,
@@ -365,8 +379,10 @@ turn
 document replay off and keep the interceptor (`disableRequestReplay: true`, or
 `isDocumentRequestReplayEnabled: false` on builder) — often that alone is what
 breaks the page, and it's the smallest change. Only if that doesn't help, turn
-interception off entirely (`injectionType: NONE`, or omit
-`interceptorOptions`). Full checklist and remedies: topic `interception`.
+interception off temporarily to confirm it is the cause (`injectionType: NONE`,
+or omit `interceptorOptions`). If that fixes the provider, keep interception
+off and replace intercepted claims with `window.Reclaim.requestClaim`. Full
+checklist and remedies: topic `interception`.
 
 **A session stalled, matched nothing, or produced no claim.** Read it with
 two tools, coarse to fine. `session_analytics_logs` returns the milestone

package/skill/builder-mode.md

@@ -6,10 +6,55 @@ authoring tools.
 
 ## Claimant-facing Builder sessions
 
-This integration is separate from provider authoring. When it is relevant,
-read `how_it_works({ topic: "integration" })` for the exact `api=2` boundary,
-bridge routes, result verification, legacy-proof contract, and optional TEE
-binding. A URL without `api=2` stays on its existing legacy path.
+This integration is separate from provider authoring.
+
+**Using a provider.** A provider found with `providers`, `discover_resolve`, or
+another lookup is published and usable as-is. Don't capture, `replay_request`,
+or `run_proof` against it unless the developer asks you to check or test it.
+Before using a provider, found or just created, ask once whether they just want
+to try it or want it in an app (skip this if they already said):
+
+> Want to (1) just try it right now, (2) integrate it into an existing backend
+> or frontend (this directory or another path), or (3) create a new app for it?
+
+- **Just try it:** no app, callback, or client package. Create the session the
+  HTTP way (`create_verification_session`, i.e. `POST /verifications/sessions`
+  with the org secret as `Authorization: Bearer`; `issue_org_token` if there is
+  none), give the developer `verificationUrl` to open, then check the session
+  yourself (`get_verification_session`) until it is terminal and report the
+  outcome with `get_verification_result`.
+- **Integrate, or new app:** follow the setup below in the path they named.
+
+**Prefer the HTTP API over `@reclaimprotocol/client`** for every option:
+create sessions with `POST /verifications/sessions`, open `verificationUrl`,
+poll `GET /verifications/sessions/{sessionId}`, and take the result on the
+callback. Use the client package only when the developer asks for it — the one
+exception is `results.receive`, to verify the result on your callback.
+
+When integrating into an app, read `how_it_works({ topic: "integration" })`,
+then configure the organization with generated tools (`list_orgs`,
+`create_org`, `create_org_callback_subscription`, and owner-only
+`issue_org_token`) and edit the app's frontend and backend with the coding
+agent's file tools. The guide
+covers the HTTP session workflow, exact `api=2` boundary, result
+verification, request-proof contract, and optional TEE binding. A URL without
+`api=2` stays on its existing legacy path.
+
+**Existing `@reclaimprotocol/js-sdk` projects.** If the app's `package.json`
+depends on `@reclaimprotocol/js-sdk`, ask the developer before doing anything
+else:
+
+> This project uses `@reclaimprotocol/js-sdk`. Keep it (I switch this MCP
+> server to legacy devtools mode), or migrate to the Builder integration
+> (Builder HTTP API)?
+
+- **Keep js-sdk:** call `set_devtools_mode({ mode: "old" })`, then tell them to
+  restart or reconnect the MCP server; the switch applies on the next start. An
+  explicit `USE_OLD_DEVTOOLS` env var overrides it. After the restart, read
+  `get_js_sdk_integration_guide`.
+- **Migrate:** stay in Builder mode. Follow `how_it_works({ topic:
+  "integration" })` to replace `@reclaimprotocol/js-sdk` with the Builder
+  HTTP session flow and update the app's code.
 
 **A `provider` is a recipe for extracting a data point from a site. A
 `verification` is an end-user session that proves a data point using one. Never
@@ -20,6 +65,19 @@ configuration change creates a new semantic version. Default to a patch bump;
 use a major/minor bump or exact higher version when the user directs it. Never
 use an in-place provider-version update or archive tool.
 
+## Evidence contract
+
+Tool results are the source of truth. Never say that a browser attached, a user
+logged in, a request was captured, a proof passed, or a version was created or
+published unless the corresponding tool result says it happened. A planned tool
+call is not a completed action.
+
+Treat every ID, semantic version, URL, request value, and error as opaque: copy
+it from the latest tool result exactly. Never invent, autocomplete, reconstruct,
+shorten, or reuse one from memory. When state is missing or ambiguous, inspect
+it with the relevant get/list/status tool or call `how_it_works` before
+answering. State uncertainty plainly instead of guessing.
+
 **Use the guide as needed.** Call `how_it_works({})` for its topic index, then
 fetch only the topic relevant to the next tool call.
 

package/skill/community-contributions.md

@@ -5,6 +5,14 @@ enabled. It is a topic guide for `SKILL.builder.md`, not a standalone skill.
 The app workflow and volunteer-facing contract are documented in
 `packages/app/docs/community-contributions.md`.
 
+## Contents
+
+- [Required sequence](#required-sequence)
+- [Generalization gates](#generalization-gates)
+- [Asynchronous attempts](#asynchronous-attempts)
+- [Stop conditions](#stop-conditions)
+- [Uber driver example](#uber-driver-example)
+
 ## Required sequence
 
 Follow this order. Keep the attempt ID, provider ID, field key, and candidate
@@ -60,9 +68,10 @@ attempt.
 
 ## Asynchronous attempts
 
-Treat a reconnect at the active verification URL as the same attempt. Read the latest valid state
-before taking another action. Do not start a second browser session for a
-waiting or retryable attempt. On a terminal failure, preserve the history and
+Treat a reconnect at the active verification URL as the same attempt. Read the
+latest valid state before taking another action. Do not start a second browser
+session for a waiting or retryable attempt. On a terminal failure, preserve
+the history and
 stop until a maintainer changes the requirement or explicitly requests a new
 attempt. Use absolute event timestamps and server-side status; do not infer
 state from the volunteer's timezone or a closed tab.

package/skill/hash-validation.md

@@ -1,10 +1,10 @@
-# Spec hashing: `bodySniff` and `verifyProof({ providerId })`
+# Spec hashing: `bodySniff` and `verifyRequestProof({ providerId })`
 
 ## Contents
 
 - The one fact everything follows from
 - `bodySniff` — when to enable it, how to template a partly dynamic body
-- How `verifyProof(proof, { providerId })` gates a proof
+- How `verifyRequestProof(proof, { providerId })` gates a proof
 - Why `url` is hashed verbatim, and when that makes
   `allowedJsRequests`/`allowedInjectedRequestData` unusable
 - Optional fields, and the `dangerouslyDisableContentValidation` fallback
@@ -83,7 +83,7 @@ match (`(.*)`, including embedded delimiters) instead of the default non-greedy
 body. Strictly a fallback — nothing about the body's structure is pinned by the
 hash anymore (any body at all hashes the same).
 
-## How `verifyProof(proof, { providerId })` gates
+## How `verifyRequestProof(proof, { providerId })` gates
 
 Traced from `@reclaimprotocol/js-sdk`
 (`src/utils/proofValidationUtils.ts`, `src/utils/providerUtils.ts`,
@@ -104,7 +104,7 @@ Traced from `@reclaimprotocol/js-sdk`
    present or absent. **That expansion only touches match/redaction pairs, never
    `url`.**
 4. `assertValidProofsByHash` requires the real proof's hash to equal exactly ONE
-   expected hash. No match → `verifyProof` rejects, even for a perfectly valid,
+   expected hash. No match → `verifyRequestProof` rejects, even for a perfectly valid,
    correctly signed proof whose `responseMatches` are 100% right.
 
 ### `url` is hashed VERBATIM — zero template/regex resolution
@@ -116,7 +116,7 @@ touches `url`. `urlType` is consumed by a different validation path entirely
 (matching a live request against the spec at capture time), never by this hash.
 
 **So, before populating `allowedInjectedRequestData`/`allowedJsRequests` for a
-`verifyProof({ providerId })` use case:** if the real captured URL contains ANY
+`verifyRequestProof({ providerId })` use case:** if the real captured URL contains ANY
 component that varies between two otherwise-identical sessions — a tracking
 nonce, a CSRF token, a cache-busting timestamp, a per-request trace id — the
 hash from your declared spec can NEVER equal any real future proof's, no matter
@@ -126,14 +126,14 @@ regenerates `_x_id`, `_x_csid` and `fp` on every API call, so a captured
 
 Populating the field for such a provider is **actively worse than leaving it
 empty**: it converts "no provider-hash check was attempted" into
-"`verifyProof({ providerId })` rejects every real proof, unconditionally."
+"`verifyRequestProof({ providerId })` rejects every real proof, unconditionally."
 
 **Verify first:** capture the same endpoint twice in two separate sessions
 (ideally two users, or the same user on two days) and diff the full URL byte for
 byte.
 
 - Identical every time → safe to populate (`urlType: CONSTANT`, literal URL).
-- Not identical → do not populate it expecting it to gate `verifyProof`. No
+- Not identical → do not populate it expecting it to gate `verifyRequestProof`. No
   amount of care with `responseMatches`/`responseRedactions`/`body` fixes it on
   either backend; it's a property of the hashing itself.
 
@@ -155,7 +155,7 @@ compatibility rule does not pair the lists generally.
 
 Whether it's an unstable `url`, an unmarked optional field, or any other
 persistent mismatch, the way out is on the VERIFYING side:
-`verifyProof(proof, { dangerouslyDisableContentValidation: true })`. That skips
+`verifyRequestProof(proof, { dangerouslyDisableContentValidation: true })`. That skips
 steps 1–4 entirely and trusts only the attestor's cryptographic signature; it
 does NOT check that the proof's url/method/body/matches/redactions match
 anything you declared. A caller-supplied `{ hashes: [...] }` computed some other
@@ -170,4 +170,4 @@ spec says.
 - `user-script` — `allowedJsRequests` / `allowedInjectedRequestData`, the fields
   this page's `url` constraint applies to.
 - `prove` — `run_proof` and diagnosing a proof that fails before it ever reaches
-  `verifyProof`.
+  `verifyRequestProof`.

package/skill/interception.md

@@ -32,11 +32,11 @@ parameter.
   **`HAWKEYE`, not `NONE`** — harmless for the standard flow, since with no
   interceptor script installed nothing calls `addResponseMiddleware`.
   `create_provider_version_from_capture` exposes it as an author-settable input
-  with no forced default: omit it and the backend default applies; pass an
-  explicit value (including `NONE`) for certainty. When passed, it's sent on both
-  register and add-version, and the tool's always-on add-version follow-up (see
-  `disableRequestReplay` below) reapplies it, so an explicit value is guaranteed
-  correct by the time that version lands.
+  with no forced default: omit it and the backend default applies. Use `NONE`
+  only for a controlled diagnostic after observed behavior suggests interception
+  is breaking the provider. When passed, the value is sent on both register and
+  add-version, and the tool's always-on add-version follow-up (see
+  `disableRequestReplay` below) reapplies it.
 - **builder:** `webSettings.inapp.interceptorOptions.interceptorType`, one of
   `HAWKEYE | MSWJS | CDP`. There is no `NONE` here — **omit
   `interceptorOptions` entirely to disable interception**, and the
@@ -91,16 +91,16 @@ strictest row below as the answer.
 | `portals` | Browser level, over CDP | No |
 | `builder` | Server-side CDP, out of band | No |
 
-`builder` is the row for authoring and for a session created with no
-`verificationClientUrl`. Reaching it means you are diagnosing the authoring
-tool, not what the author's users will hit — which is exactly why you ask
-first.
+A session created with no `verificationClientUrl` runs in `portals`.
+`builder` is the row for authoring and for Builder's own "Test this provider"
+runs. Reaching it means you are diagnosing the authoring tool, not what the
+author's users will hit — which is exactly why you ask first.
 
 The `reclaim-browser-extension` row supports both modes. The extension selects
-the Builder bridge only for the exact `api=2` query and keeps its legacy
+the Builder API only for the exact `api=2` query and keeps its legacy
 interception, `init` / `fromJsonString`, and direct-callback path for missing or
-unknown API versions. In Builder mode, the bridge supplies the session-bound
-attestor authorization; the extension still forwards raw legacy proofs and
+unknown API versions. In Builder mode, Builder supplies the session-bound
+attestor authorization; the extension still forwards raw proofs and
 does not perform client-side `allowedJsRequests` validation.
 
 **If production is only `portals` or `builder`, stop here and look elsewhere.**
@@ -138,13 +138,15 @@ Copy this checklist and work down it:
 - [ ] 2. **Retry the verification.** Reload, then sign in as a real end-user
       would. Works now → stop here. This is the cheapest fix and you keep the
       interceptor.
-- [ ] 3. **Still broken? Turn interception off entirely.** Old-devtools:
+- [ ] 3. **Still broken? Temporarily turn interception off to test it.**
+      Old-devtools:
       publish with `injectionType: NONE`. Builder: omit `interceptorOptions`
       entirely — there is no `NONE` there, and omitting it disables interception.
 - [ ] 4. **Retry again, and compare.** Loads and signs in now → interception
-      itself was the cause; pick a remedy below. Still broken → interception
-      is innocent; go back to the recipe (topic `prove`) or the browser
-      (topic `browser`).
+      itself was the cause; keep interception disabled and replace the
+      intercepted claim path with `window.Reclaim.requestClaim`. Still broken →
+      restore the previous interception setting and investigate the recipe
+      (topic `prove`) or browser (topic `browser`).
 
 If step 2 fixed it, you are done — the interceptor stays and only the document
 request stops being replayed. Note that under `CDP` the flag is inert, so a
@@ -152,35 +154,26 @@ request stops being replayed. Note that under `CDP` the flag is inert, so a
 
 ### Remedies
 
-If it took step 3, take the first remedy that fits — in this order:
-
-1. **Try a different interceptor.** They patch the page in different ways, so
-   a site that rejects one often accepts another — work along the row for your
-   backend before giving up on interception:
-   - old-devtools: `HAWKEYE` → `MSWJS` → `XHOOK` → `CDP`
-   - builder: `HAWKEYE` → `MSWJS` → `CDP`
-
-   `CDP` is the one that cannot be detected — it intercepts below the page's
-   JavaScript, so nothing in the page is patched. Prefer it when the target
-   client supports it; the in-page clients above may not, which is why the
-   JS-level mechanisms are worth cycling through first.
-2. **Ship without it.** Most providers never needed an interceptor: the
-   standard capture-and-replay flow proves the data on its own. Leave it off
-   unless the value genuinely can't be reproduced by an independent replay
-   (see "Which mechanism, and when to use any of them at all").
-3. **Drive the claim yourself.** Where the data only exists in a live page,
-   skip `reclaimInterceptor` and have the user script navigate to the page
-   that shows the value, read what the page already holds, and call
-   `window.Reclaim.requestClaim` with it. Declare anything the script fires in
-   `allowedJsRequests` / `allowedInjectedRequestData` for result verification,
-   and read topic `hash-validation` first — a session-unique URL there makes
-   `verifyProof({ providerId })` reject every real proof.
-
-⚠️ **Remedy 3 needs a client that consumes `window.Reclaim`.** The InApp
-SDK, browser extension, portals, and Builder's built-in client do. The built-in
-client uses the page-supplied request to generate the proof; verification of
-its recipe hash belongs to `verifyProof`/`verifyResultFull`. See topic
-`user-script`.
+If step 3 confirmed interception is the cause, keep it disabled. Most providers
+can use the standard capture-and-replay flow without an interceptor. Where the
+data only exists in a live page, replace `addResponseMiddleware` with a user
+script that navigates to the page holding the value and calls
+`window.Reclaim.requestClaim`. Declare anything the script fires in
+`allowedJsRequests` / `allowedInjectedRequestData` for result verification, and
+read topic `hash-validation` first — a session-unique URL there makes
+`verifyRequestProof({ providerId })` reject every real proof.
+
+If direct `requestClaim` does not fit the client or provider, a different
+interceptor is a fallback, not the first recommendation. The mechanisms patch
+the page differently: old-devtools supports `HAWKEYE`, `MSWJS`, `XHOOK`, and
+`CDP`; Builder supports `HAWKEYE`, `MSWJS`, and `CDP`. `CDP` operates below the
+page's JavaScript but is not supported by every in-page client.
+
+⚠️ **The direct-claim remedy needs a client that consumes `window.Reclaim`.**
+The InApp SDK, browser extension, portals, and Builder's built-in client do. The
+built-in client uses the page-supplied request to generate the proof;
+verification of its recipe hash belongs to `verifyRequestProof`/`verifyResultFull`.
+See topic `user-script`.
 
 ## The document-replay flag
 
@@ -244,6 +237,6 @@ oversight.
 - `user-script` — what the script itself does with intercepted traffic, and how
   Builder's built-in client handles `window.Reclaim.requestClaim`.
 - `hash-validation` — declaring script-fired requests without breaking
-  `verifyProof({ providerId })`.
+  `verifyRequestProof({ providerId })`.
 - `browser` — the modes with a live view (`container`, `builder`), for handing
   a stuck sign-in to a human.

package/skill/old-mode.md

@@ -11,6 +11,19 @@ creates a new semantic version. Default to a patch bump; use a major/minor bump
 or exact higher version when the user directs it. Never edit an existing
 version.
 
+## Evidence contract
+
+Tool results are the source of truth. Never say that a browser attached, a user
+logged in, a request was captured, a proof passed, or a version was created or
+published unless the corresponding tool result says it happened. A planned tool
+call is not a completed action.
+
+Treat every ID, semantic version, URL, request value, and error as opaque: copy
+it from the latest tool result exactly. Never invent, autocomplete, reconstruct,
+shorten, or reuse one from memory. When state is missing or ambiguous, inspect
+it with the relevant get/list/status tool or call `how_it_works` before
+answering. State uncertainty plainly instead of guessing.
+
 **Use the guide as needed.** Call `how_it_works({})` for its topic index, then
 fetch only the topic relevant to the next tool call.
 
@@ -42,6 +55,18 @@ existing provider instead; you can only version a provider you own. For a
 multi-request provider pass `providers: [draftA, draftB, …]` so each becomes a
 parallel `requestData` entry on the one version.
 
+**Using a provider.** A provider found with `get_me_providers` or
+`get_provider_info` is published and usable as-is. Don't capture,
+`replay_request`, or `run_proof` against it unless the developer asks you to
+check or test it. Before using a provider, found or just created, ask once how
+they want to use it (skip this if they already said):
+
+> Want to (1) try it right now here, (2) integrate it into an existing backend
+> or frontend (this directory or another path), or (3) create a new app for it?
+
+Try it now → `scaffold_reclaim_demo_server` with its `providerId`. Integrate,
+or new app → `get_js_sdk_integration_guide`, then work in the path they named.
+
 **Two independent auth systems — don't confuse them.** `reclaim_authenticate`
 authorizes everything in this mode; its Firebase token is short-lived (~1h), so
 an auth error on publish or `get_me_providers` means re-run it.

package/skill/user-script.md

@@ -2,7 +2,8 @@
 
 A provider can inject **plain JavaScript** that runs in the page before every
 page load. Builder stores it as `webSettings.jsUserScripts`; old-devtools stores
-it as `customInjection`. Identical semantics, different field name.
+it as `customInjection`. The injection timing and purpose match; available
+`window.Reclaim` bridge methods depend on the Verification Client.
 
 ## What the script is for
 
@@ -54,7 +55,7 @@ browser APIs above for that.
 
 The Builder verification client drains `window.Reclaim.requestClaim` through
 CDP and uses the page-supplied request to generate the proof. It does not
-authorize the request against `allowedJsRequests`; `verifyProof`/
+authorize the request against `allowedJsRequests`; `verifyRequestProof`/
 `verifyResultFull` validates the resulting proof's recipe hash. The built-in
 client doesn't deliver traffic to
 `reclaimInterceptor.addResponseMiddleware`, so response middleware remains
@@ -69,24 +70,39 @@ them. Do not read cookies in the script or copy a `Cookie` value into public
 parameters; the client supplies it as private claim input.
 
 Don't reach for it by default. When an edge case genuinely requires it, consult
-the authoritative API surface rather than guessing:
-<https://github.com/reclaimprotocol/provider-web-script-dev/blob/main/src/support/env.d.ts>
+the [provider web-script API types](https://github.com/reclaimprotocol/provider-web-script-dev/blob/main/src/support/env.d.ts)
+rather than guessing.
+
+### Portal-only request APIs
+
+The portal client also exposes two methods that the built-in Builder client,
+in-app SDK, and browser extension do not:
+
+- `Reclaim.refetch(request)` sends a bounded request through the portal worker.
+- `Reclaim.browserRequest(actionId, input)` runs a declared same-origin action
+  in an isolated page that shares the portal browser's cookie jar. Declare its
+  action in `browserRequestActions` when creating the provider version. The
+  declaration can set the isolated page's User-Agent or omit a fetch action's
+  automatic Origin header when the target requires it.
+
+Use them only when the provider is explicitly portal-only. For the current
+client matrix, see `docs/verification-client-capabilities.md` in Builder.
 
 ## Declaring the requests the script fires
 
 Requests the script triggers beyond the proven one (for example, pagination) are
 declared as `allowedJsRequests` (Builder) / `allowedInjectedRequestData`
-(old-devtools) for `verifyProof`/`verifyResultFull`. They express the same
+(old-devtools) for `verifyRequestProof`/`verifyResultFull`. They express the same
 policy with different field names.
 
-⚠️ **Before populating them to gate `verifyProof(proof, { providerId })`**, read
+⚠️ **Before populating them to gate `verifyRequestProof(proof, { providerId })`**, read
 topic `hash-validation` — the declared `url` is hashed VERBATIM, so a
-session-unique URL there makes `verifyProof` reject every real proof. Leaving
+session-unique URL there makes `verifyRequestProof` reject every real proof. Leaving
 the field empty is better than populating it wrong.
 
 ## Related topics
 
 - `interception` — `injectionType`/`interceptorType`, live interception, and the
   document-replay flag.
-- `hash-validation` — `bodySniff`, and how `verifyProof({ providerId })` gates
+- `hash-validation` — `bodySniff`, and how `verifyRequestProof({ providerId })` gates
   on the provider's declared spec.