@reclaimprotocol/agent 0.1.36 → 0.1.38

package/skill/SKILL.common.md

@@ -28,45 +28,37 @@ already names it.
 - [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
-> person whose account it is, say?
-
-That answer decides half the list, and a developer can answer it without knowing
-what CDP is. Only then offer the matching pair, call `attach_browser` ONCE with
-the `mode` they pick, and never pick for them or assume last session's choice
-still applies.
-
-**They're doing it themselves** — no link, no Docker, nothing to install:
-
-| mode | what it is | needs |
+**Default: call `attach_browser()` with no arguments. Don't ask anything
+first.** It opens a visible browser on the developer's own machine with the
+persistent Reclaim profile (`~/.reclaim/chrome-profile`), so a site they sign
+in to stays signed in. It uses installed Chrome, then Chromium, then Edge. If
+none is installed, or the installed one won't start, it downloads Chrome for
+Testing once into `~/.reclaim/browsers` and uses that. When the result says
+Chrome for Testing was used, tell the developer in one line.
+
+**Side note on sharing.** Tell the developer once, in passing, that if a
+volunteer is helping them sign in, you can set up a shareable link to the
+browser (`container` mode and `share_browser_view`). Don't ask about it, and
+don't set it up unless they ask.
+
+**Other modes are opt-in.** Pass `mode` only when the developer explicitly asks
+for one of these, or when `attach_browser()` fails even with Chrome for
+Testing (for example, no display on Linux). In that case, use `container` if
+Docker is running and say why in one line. Otherwise don't offer them, list
+them, or pick one yourself, and don't reuse a mode from an earlier session.
+
+| mode | when the developer asks for | needs |
 | --- | --- | --- |
-| `dedicated` | Chrome the agent launches with its own profile (`~/.reclaim/chrome-profile`), which persists, so a site stays signed in. The default choice. | nothing |
-| `attach` | The Chrome they already have open, with its tabs, extensions and logins. | `port` (default 9222) |
-
-Neither can be shared, and neither needs to be: the browser is on their screen.
-
-**Someone else has to sign in, or the site only works on a phone** — these two
-are the only modes that produce a link another person can open:
-
-| mode | what it is | needs | costs |
-| --- | --- | --- | --- |
-| `container` | The Reclaim runtime in Docker, on their machine. `share_browser_view` turns its viewer into a public link. | Docker running | free — their Docker and bandwidth |
-| `builder` | A browser in Reclaim's cloud. The link comes back immediately, with nothing to install. Also the only way to browse from a **specific country**. | Builder auth, `orgId` | **chargeable** — billed against the org's quota |
-
-**Say which one costs money.** They are otherwise interchangeable from the
-developer's point of view, so price and "do you have Docker" are the whole
-decision. Do not quietly pick the billed one.
-
-`custom` (any `ws://`/`wss://` CDP endpoint they supply) exists for someone who
-was handed an endpoint and knows why. Don't offer it unprompted; it cannot be
-shared either.
+| `attach` | The Chrome they already have open, with its tabs, extensions, and logins | `port` (default 9222) |
+| `container` | Someone else signs in, or a phone-only site. The Reclaim runtime runs in Docker on their machine; `share_browser_view` turns its viewer into a public link | Docker running |
+| `builder` | A browser hosted by Reclaim, or browsing from a specific country. **Billed** against the org's quota; say so before you call it | Builder auth, `orgId` |
+| `custom` | A `ws://` or `wss://` CDP endpoint they supply | `cdpUrl` |
 
 **`attach` gotcha (Chrome 136 and later):** the developer's Chrome must be
 started with BOTH `--remote-debugging-port=9222` AND
 `--user-data-dir=<non-default-path>`. The debug flag is silently ignored on the
-default profile. If `attach` fails, say this verbatim and offer `dedicated`.
+default profile. If `attach` fails, say this verbatim. The default call with no
+`mode` always works without it.
 
 **`builder` specifics:**
 
@@ -81,9 +73,7 @@ default profile. If `attach` fails, say this verbatim and offer `dedicated`.
   the suggested country, a country the site must be seen from, or skipping geo
   entirely (`skipCountry: true`, the deployment's default egress). The country
   is **fixed for the session's lifetime** and can't be changed after allocation.
-  When a site is geo-restricted or a recipe pins a `geoLocation`, recommend a
-  remote browser in that country rather than working around it locally. If the
-  deployment has no proxy configured the browser is still allocated, just
+  If the deployment has no proxy configured the browser is still allocated, just
   without the requested country.
 - Costs one VERIFICATION-pool use under the org's normal plan restrictions.
 - Return the FULL `liveViewUrl` to the developer **verbatim, on its own line** —
@@ -129,8 +119,8 @@ If they say yes:
 
 - **`container` is the only mode this applies to.** `builder` returns a hosted
   `liveViewUrl` from `attach_browser` — relay that instead, full and verbatim.
-  `dedicated`, `attach`, and `custom` have no view to share at all; if someone
-  else needs to see the browser, say so and offer `container`.
+  `dedicated`, `attach`, and `custom` have no view to share at all. If the
+  developer asks to let someone else in, re-attach with `mode: "container"`.
 - **The URL is the ONLY credential.** The hostname Cloudflare hands out is the
   whole secret: there is no token and no login behind it, so whoever learns the
   URL has the browser, as the signed-in user. Give it to one person, say plainly
@@ -141,8 +131,8 @@ If they say yes:
 - **It shows the whole browser, not one tab.** A sign-in that opens a separate
   window is visible too.
 - **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.
+  pinch-zoom and the soft keyboard. That is why `container` suits a site that
+  only works on mobile, when the developer asks for it.
 - **Stop a cloudflared process you started as soon as they're done.** If they
   started it, tell them to stop it. The browser keeps running. `dispose_browser` and `reset_session` stop the
   container itself, but not your cloudflared process.
@@ -181,18 +171,30 @@ If they say yes:
 - A container left over from a crashed run is **reused if it is still serving**,
   and replaced if it is not — a second attach does not need a different port.
 
-**When a local attach errors or `waitForCdpReady` reports a dead port**, walk
-these before retrying:
-
-- **Chrome binary not found** (the error lists the paths it tried). Set
-  `RECLAIM_AGENT_CHROME_PATH` to the real binary — on Windows
-  `setx RECLAIM_AGENT_CHROME_PATH "C:\path\to\chrome.exe"` (`setx`, not `$env:`,
-  so future shells inherit it); on macOS/Linux `export` it. **Then fully restart
-  Claude Code** — MCP servers snapshot env vars at launch.
+**When the default local launch fails**, the error names the reason. Act on
+it rather than switching modes:
+
+- **No display** (Linux, neither `WAYLAND_DISPLAY` nor `DISPLAY` set). The MCP
+  server was started outside the desktop session. Ask the developer to add the
+  variable to the MCP server's environment (for example `DISPLAY=:0`, or
+  `WAYLAND_DISPLAY=wayland-0` with `XDG_RUNTIME_DIR`) and restart the agent.
+- **Exited with code N**, followed by the browser's own stderr. Read the
+  stderr: it usually names the cause (a missing library, a sandbox error).
+  Chrome for Testing was already tried as a fallback when the error mentions
+  it.
+- **Profile in use by a running browser (PID N).** A browser on
+  `~/.reclaim/chrome-profile` is open without the debugging port. Ask the
+  developer to close that window, then retry. Stale locks left by a crashed
+  browser are cleared automatically.
+- **Did not answer CDP within 30000ms.** Retry once; a first start on a slow
+  disk can be slow. If it repeats, quote the stderr in the error.
+- **Wrong browser picked.** Set `RECLAIM_AGENT_CHROME_PATH` to the binary — on
+  Windows `setx RECLAIM_AGENT_CHROME_PATH "C:\path\to\chrome.exe"` (`setx`, not
+  `$env:`, so future shells inherit it); on macOS/Linux `export` it. **Then
+  fully restart the agent** — MCP servers snapshot env vars at launch.
 - **Pre-existing `chrome.exe` hijacks the launch (Windows).** A new launch with
   `--remote-debugging-port` gets delegated to the running process group and the
   port silently never opens. `taskkill /F /IM chrome.exe`, then retry.
-- **Chrome 136+ default-profile rule** (above) — `dedicated` is always safe.
 
 <!-- section: login-detect -->
 **Check login state, wait if needed.** `eval_in_page(captureId, ...)` with a
@@ -310,9 +312,18 @@ won't help.
 
    Permitted edits: narrowing the `contains` template, a more distinctive
    xPath class/id when the synthesizer's pick is too generic, fixing `name`,
-   adding/removing secret headers. Tempted to rewrite from scratch? Call
+   adding/removing secret headers. Make matcher edits with `update_draft`
+   (never by importing the agent's internals), then confirm them offline with
+   `check_matchers`, which runs the attestor's own redaction and match engine
+   on the captured response. Tempted to rewrite from scratch? Call
    `propose_provider` again with different inputs instead.
 
+   If `propose_provider` says the value has no key name next to it, or that
+   the window holds a number or a neighbouring value, the request can't give
+   a portable matcher (typical of SvelteKit `__data.json` positional arrays).
+   Pick the HTML page or another JSON API where the value sits under its own
+   key.
+
 <!-- section: secrets -->
 ### Protect secret values
 
@@ -393,6 +404,15 @@ supplies are context params.
     `check_attestor` after the developer fixes their network. Do not loop
     retries; one `run_proof` per change.
 
+    **Blocked non-browser clients** (`diagnosis.kind` is
+    `blocked-non-browser-client`: HTTP 403/406/429/503 or a challenge page,
+    often after `replay_request` succeeded): the site blocks clients that
+    aren't a real browser (bot protection or TLS fingerprint). Copying
+    headers or cookies won't help, and `run_proof_via_pod` doesn't change the
+    TLS fingerprint. Try a different endpoint that returns the value (a JSON
+    API the page calls), or stop and report. Run `check_matchers` first so a
+    recipe bug isn't mistaken for blocking.
+
     **Do not auto-retry with a different `attestorUrl`.** There is one live
     public attestor; backup hostnames (`attestor-2.*`, and so on) **do not
     exist**. `attestorUrl` is only for a developer-supplied private/staging URL.
@@ -421,30 +441,30 @@ supplies are context params.
   match — all stop signs. And never accept "the xPath looks too narrow, let me
   write a regex": the synthesizer already pairs the anchor with a
   structure-anchored named-capture regex. If extraction looks wrong, re-run
-  `propose_provider` with a better request/target.
+  `propose_provider` with a better request/target. The permitted narrowing
+  edits go through `update_draft` and `check_matchers`.
 - Never rename or `%CTX%`-prefix the match-template param (see `params`).
 
 <!-- section: credentials -->
 ## Signing credential for the proof
 
-`run_proof` needs an `ownerAddress` — the eth proof-owner key whose private half
-signs the claim. It does **no** resolution itself. The private key is resolved
-locally (`RECLAIM_PRIVATE_KEY` env → a `RECLAIM_PRIVATE_KEY=0x…` line in the
-project `.env` → a file at `RECLAIM_PRIVATE_KEY_FILE`) and never enters the
-conversation.
-
-1. **`resolve_owner_key`** returns only the derived address.
-   - `{ ready: true, address }` → call `run_proof` with it. No prompts.
-   - `{ ready: false }` → ask the developer once: **their own key** →
-     `import_credentials({ keyFile })` (a path to a file holding the key; never
-     ask them to paste it),
-     or **a fresh one** → `issue_credentials({})` (a fine default for test
-     proofs — owner identity doesn't matter). Either writes to the project
-     `.env` (mode 0600, added to `.gitignore`), never to `~/.reclaim`. Then
-     re-run `resolve_owner_key`.
-2. Fully local — no network, no registration. The key is read live from `.env`
-   on every `run_proof`, so **no restart** is needed after issuing/importing,
-   and the existing draftId stays valid.
+`run_proof` signs the claim with the eth proof-owner key. It resolves the key
+itself (`RECLAIM_PRIVATE_KEY` env → a `RECLAIM_PRIVATE_KEY=0x…` line in the
+project `.env` → a file at `RECLAIM_PRIVATE_KEY_FILE`); the private key never
+enters the conversation. Don't pass `ownerAddress` and don't ask the developer
+for a key.
+
+1. **No key yet:** `run_proof` (or `resolve_owner_key`) creates a local test
+   key in the project `.env` (mode 0600, added to `.gitignore`) and returns
+   `source: "generated"` with a `note`. Tell the developer once, after the
+   fact, that you created a local test signing key. Don't ask for approval:
+   owner identity doesn't matter for test proofs.
+2. **Developer wants their own key:** only when they say so,
+   `import_credentials({ keyFile })` (a path to a file holding the key; never
+   ask them to paste it).
+3. Fully local — no network, no registration. The key is read live from `.env`
+   on every `run_proof`, so **no restart** is needed after importing, and the
+   existing draftId stays valid.
 
 - **Advanced:** `RECLAIM_PRIVATE_KEY` in the MCP server env works too, but env
   vars are snapshotted at Claude Code startup — that route needs a full restart,

package/skill/SKILL.old.md

@@ -9,7 +9,7 @@ Copy this checklist and check off each step as you finish it. Read the linked
 topic before a step you aren't already fluent in.
 
 - [ ] 1. `reclaim_authenticate` once. → topic `auth`
-- [ ] 2. `attach_browser` — pick a browser source with the developer.
+- [ ] 2. `attach_browser()` with no arguments — opens a visible local browser.
       → topic `browser`
 - [ ] 3. `list_tabs` → `start_capture(tabId)` ⇒ **`captureId`**, your handle for
       everything below. → topic `capture`
@@ -24,7 +24,7 @@ topic before a step you aren't already fluent in.
 - [ ] 7. Parameterize user-specific URL segments; mark secrets. → topic `params`
 - [ ] 8. `replay_request(captureId, draftId)`, then again with
       `withoutSecrets: true`. → topic `prove`
-- [ ] 9. `run_proof(captureId, draftId, ownerAddress)`.
+- [ ] 9. `run_proof(captureId, draftId)`.
       → topics `prove`, `credentials`
 - [ ] 10. `create_provider_version_from_capture`. → topic `publish`
 
@@ -241,7 +241,7 @@ with no secrets/cookies, as an anonymous visitor.
   session and re-check. If the value only ever appears on public responses, tell
   the developer it can't be proven as an identity claim.
 
-**3. Prove.** `run_proof(captureId, draftId, ownerAddress)`. On
+**3. Prove.** `run_proof(captureId, draftId)`. On
 `verified: true` the full claim is written to
 `~/.reclaim/claims/<timestamp>.json` and you get
 `{verified, extractedValue, extractedParameters, identifier, owner, claimPath, claim}`.

package/skill/builder-mode.md

@@ -17,6 +17,21 @@ Never call a provider a "verification."**
   "Choose the provider".
 - **Intent unclear:** ask one short question.
 
+### Work order
+
+Do the steps that need the developer first: sign in to Builder, attach the
+browser, capture, and prove the provider. They show early whether a proof is
+possible on the site. Write app code after the proof works, or while you wait
+on the developer.
+
+### Asking the developer
+
+When you need an answer or an action from the developer before you can
+continue, end your turn with the question. Don't ask a blocking question
+through a background or asynchronous question tool: the developer may never
+see it. Put every link they need, such as a sign-in or verification URL, in
+that same message.
+
 ### Choose the provider
 
 Default: build a new provider for the claim the developer described. Use an
@@ -49,6 +64,9 @@ check and holds results for you to read. No tunnel or public URL is needed.
 1. Call `read_callback_events`.
 2. `create_verification_session`, then give the developer `verificationUrl`.
 3. Poll `get_verification_session` until it is terminal.
+   `list_verification_events` shows progress. Don't read the hosted
+   verification page for progress: it streams the site as an image, so text
+   and DOM checks of it come back empty.
 4. Call `read_callback_events({ sessionId })` for the verified result.
 
 When you set up a new provider build, call `check_attestor` once. If it fails,
@@ -67,7 +85,8 @@ tell the developer before they spend time on the build.
 
 ## Integrating into an app
 
-Call `start_integration`, then read `how_it_works({ topic: "integration" })`
+Call `start_integration` and follow its order: prove the provider first, then
+write app code. Read `how_it_works({ topic: "integration" })`
 for the HTTP session workflow, the `api=2` boundary, result verification, and
 TEE binding. Edit the app with your file tools. Use the HTTP API
 (`POST /verifications/sessions`, open `verificationUrl`, poll
@@ -122,13 +141,24 @@ script → `find_requests_containing` → `propose_provider` ⇒ `draftId` →
 
 - **Data points:** propose only values the claim needs, usually one or two.
   Never add identity or profile fields. Name each for what it proves.
-- **Browser:** ask who signs in. The developer themselves: `dedicated` or
-  `attach` (local). Someone else, or a phone-only site: `container` (Docker,
-  free, shareable with `share_browser_view`) or `builder` (hosted,
-  **chargeable**). Say which costs money.
+- **Browser:** call `attach_browser()` with no arguments. It opens a visible
+  local browser with the persistent Reclaim profile, and falls back to Chrome
+  for Testing itself when no installed browser can be attached. Don't ask
+  which browser or who signs in. Use another `mode` only when that fails too,
+  or when the developer explicitly asks for it (topic `browser`). Tell the
+  developer once, as a side note, that a shareable link can be set up if a
+  volunteer is helping them sign in; don't ask about it or set it up unless
+  they ask.
 - **Public endpoints:** after `replay_request` succeeds, re-run it with
   `withoutSecrets: true`. If the value still extracts, the endpoint is public
   and the proof binds to nobody. Find an auth-bound request.
+- **Country:** `run_proof` sends the attestor's request from the developer's
+  own IP country, which is what `{{DYNAMIC_GEO}}` becomes when they verify;
+  `egress` in the result says which country. If a site that serves one
+  country (for example, a US airline) blocks the attestor, retry once with
+  `geoLocation: "US"`. If that verifies, pin it with
+  `update_draft({ geoLocation: "US" })` so the published version goes out
+  from there too.
 - **Drafting limits** (topics `draft`, `params`): never `hash` a value that
   also appears in the request URL. A param named with `SECRET` may appear in a
   URL only within a small character budget (2 under `key-update`, 12 under

package/skill/old-mode.md

@@ -24,25 +24,30 @@ 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.
 
+**Ask blocking questions by ending your turn.** When you need an answer or an
+action from the developer before you can continue, end your turn with the
+question and every link they need. Don't use a background or asynchronous
+question tool for it: the developer may never see it.
+
 **Use the guide as needed.** Call `how_it_works({})` for its topic index, then
 fetch only the topic relevant to the next tool call.
 
-**Ask who is doing the signing in, then offer a browser.** "Yourself, or does
-someone else need to log in?" decides half of `attach_browser`'s list. Doing it
-themselves → `dedicated` or `attach`, both local, neither shareable. Someone
-else, or a phone-only site → `container` (the Reclaim runtime in Docker, free,
-shareable with `share_browser_view`) or `builder` (hosted, no install,
-**chargeable**). Say which costs money, and say `container` exists at all:
-nobody guesses it.
-
-**The flow:** `reclaim_authenticate` once → `attach_browser` (ask the developer
-which browser source — local Chrome, the Reclaim runtime in Docker, a remote
-Builder browser, or a CDP URL they supply) → `start_capture` ⇒ **`captureId`** →
+**Open the browser without asking.** Call `attach_browser()` with no
+arguments: it opens a visible browser on the developer's machine with the
+persistent Reclaim profile, and falls back to Chrome for Testing itself when
+no installed browser can be attached. Don't ask which browser or who signs in.
+Use another `mode` only when that fails too, or when the developer explicitly
+asks for it (topic `browser`). Tell the developer once, as a side note, that a
+shareable link can be set up if a volunteer is helping them sign in; don't ask
+about it or set it up unless they ask.
+
+**The flow:** `reclaim_authenticate` once → `attach_browser()` (no arguments: a
+visible local browser) → `start_capture` ⇒ **`captureId`** →
 drive the page (`navigate`,
 `wait_for_page`, `eval_in_page`) → inspect (`list_requests`, `get_request`,
 `find_requests_containing`) → `propose_provider` ⇒ **`draftId`** →
-`replay_request(captureId, draftId)` → `run_proof(captureId, draftId,
-ownerAddress)` → `create_provider_version_from_capture`.
+`replay_request(captureId, draftId)` → `run_proof(captureId,
+draftId)` → `create_provider_version_from_capture`.
 
 `reclaim_authenticate` itself always uses a local Chrome over loopback CDP. It
 never uses the container, remote Builder, custom-CDP, or shared authoring

package/skill/start-integration.md

@@ -2,9 +2,13 @@
 
 Follow this plan end to end. Mark each step done as you go. Do not ask the developer whether to integrate: integrating into this codebase is the goal.
 
+**Order.** Do the steps that need the developer first: sign in to Builder, attach the browser, capture, and prove the provider (step 2). These need the developer at the browser, and they show early whether a proof is possible on this site. Write app code (step 3) after the proof works, or while you wait on the developer. Never spend a long stretch on app code before the developer has signed in and the browser is attached.
+
+**Asking the developer.** When you need an answer or an action from the developer before you can continue, end your turn with the question. Don't use background or asynchronous question tools for blocking questions: the developer may never see them. Put every link the developer needs, such as a sign-in or verification URL, in that same message.
+
 ## 1. Sign in and pick the organization
 
-- [ ] Call `reclaim_authenticate` if you are not signed in. The developer approves in their browser.
+- [ ] Call `reclaim_authenticate` if you are not signed in. Give the developer the returned `signInUrl` to approve in their browser (end your turn first if `browserOpened` is false), then call `wait_for_sign_in`.
 <!-- if:orgId -->
 - [ ] Use organization `{{orgId}}` for every call below.
 <!-- endif -->
@@ -12,64 +16,77 @@ Follow this plan end to end. Mark each step done as you go. Do not ask the devel
 - [ ] Call `list_orgs`. Use the only organization, or ask the developer which one when there are several.
 <!-- endif -->
 
-## 2. Set up the app
-
-Setup does not need the provider, so it runs in parallel with step 3 or before it.
-
-**Delegation.** If you can run subagents, hand this step to one subagent and start step 3 now: step 3 needs the developer at the browser, step 2 does not. Give the subagent a self-contained brief:
-
-```
-Goal: let this app's users prove "{{goal}}" with Reclaim.
-Repository: <absolute path>. Organization: <org ID>.
-Task: do step 2 of the plan below and report the file paths you changed, the
-callback route URL, and the env variable that holds the provider ID.
-Do not build the provider. Never print or commit the org key.
-<paste the step 2 checklist>
-```
-
-Without subagents, do step 2 first.
-
-- [ ] Detect the app's framework and package manager from the repository, and use them. Read `how_it_works({ topic: "integration" })`.
-- [ ] Call `issue_org_token` with the organization, this project's absolute path, and the server env file. It writes the key to that file and never returns it. Never print or commit the key. Confirm the env file is in `.gitignore`.
-- [ ] Add a backend route that creates a verification session (`POST /verifications/sessions`) and returns `verificationUrl`. Read the provider ID from server config (an env variable such as `RECLAIM_PROVIDER_ID`), so the route works before the provider exists.
-- [ ] Add a callback route that verifies each result with `results.receive` from `@reclaimprotocol/client`, then stores only the requested data points. Store every failure on the verification session record and log it server-side: a failure event (`verification_rejected`, `verification_error`, `verification_cancelled`, `session_expired`), or a thrown `ResultVerificationError` (`error.reason` plus each failing proof's `reason`). Respond `error.retryable ? 503 : 200`. A result that failed verification gets 2xx, because retrying can't fix it. Read the exact pattern in `how_it_works({ topic: "integration" })`.
-- [ ] Add a status route the frontend polls. It returns the stored status, data points, and failure reason. While the app has no result, it also reads `GET /verifications/sessions/{sessionId}`, so a session that ended in Builder never stays pending.
-- [ ] Add a frontend Verify button that opens `verificationUrl`, and render every state in "UI states" in `how_it_works({ topic: "integration" })`: idle, waiting in the other tab, verifying, verified (with the data points), failed (plain-language reason and **Try again**), and expired or cancelled (**Try again**). Never leave a spinner as the only feedback.
-- [ ] Start the app. Call `proxy_callback_events({ port, path })` with the callback route's port and path. It forwards the org's verification events to that route on localhost, with no public URL.
-<!-- ifnot:providerIds -->
-- [ ] Call `check_attestor` once. If it fails, tell the developer before they spend time on the provider build: this machine cannot reach the attestor.
-<!-- endif -->
-
-## 3. Get the provider
+## 2. Get the provider and prove it
 
 <!-- if:providerIds -->
 - [ ] Use these existing providers: {{providerIds}}. Read each with `get_provider` and keep only the data points "{{goal}}" needs. Show the developer and use only those; ignore the rest.
-- [ ] If a provider needs any change (a missing data point, inputs the developer didn't ask for, a different value), make your own copy as the server instructions describe ("Choose the provider"). Otherwise skip to step 4.
+- [ ] If a provider needs any change (a missing data point, inputs the developer didn't ask for, a different value), make your own copy as the server instructions describe ("Choose the provider"). Otherwise go on to step 3.
 <!-- endif -->
 <!-- ifnot:providerIds -->
 Build a new organization-private provider for exactly "{{goal}}". Do not search published providers first.
 
+- [ ] Call `check_attestor` once. If it fails, tell the developer before they spend time on the provider build: this machine cannot reach the attestor.
 - [ ] If the site, the account, or the value to prove is unclear, ask one concise question. Otherwise do not ask.
 - [ ] Choose the minimum data points: only the values the claim needs, usually one or two. Add no profile or identity extras.
 - [ ] If the developer names an existing provider, use only the data points they asked for and ignore the rest. If it needs any change, make your own copy: a new version when the organization owns it, otherwise a new organization provider from a copy of its config.
 - [ ] Call `how_it_works` with topics `overview`, `user-script`, `capture`, and `publish` before you start. Do not repeat their detail here.
-- [ ] Call `attach_browser` without `mode`, ask the developer which browser to use, then call it again with their choice. Use `start_capture` on the tab.
+- [ ] Call `attach_browser()` with no arguments. It opens a visible local browser, falling back to Chrome for Testing when no installed browser can be attached; don't ask which browser to use. Use another mode only if that fails too (topic `browser`). Mention once, as a side note, that a shareable link can be set up if a volunteer is helping the developer sign in; don't ask or set it up unless they ask. Use `start_capture` on the tab.
 - [ ] Open the sign-in page with `navigate`. The developer signs in; use `wait_for_login`.
 - [ ] Write the navigation script first. Signed out, it goes to the sign-in page. After sign-in, it visits each data page in order. It must stay correct across reloads.
 - [ ] Test it with `test_user_script` and `keep: true`. The kept script stays installed for every later navigation and is published with the provider version.
 - [ ] While the script drives the browser, find the request that returns each data point (`find_requests_containing`, then `analyze_request_constraints`).
 - [ ] Call `propose_provider` with only the needed data points.
 - [ ] Call `replay_request`, then `replay_request` with `withoutSecrets: true` to confirm the request is auth-bound.
-- [ ] Call `resolve_owner_key`, then `run_proof`.
+- [ ] Call `run_proof`. It creates a local test signing key if none exists; tell the developer once afterwards.
 - [ ] Call `create_provider_version_from_capture`. It publishes the kept script as `jsUserScripts`. Follow its `_notes`, then publish the version.
 - [ ] Call `dispose_browser` after asking the developer.
 <!-- endif -->
 
+## 3. Set up the app
+
+Setup does not need the provider. Start it after step 2 has a working proof, or while you wait on the developer during step 2 (for example, while they sign in to the site). Don't let it delay a step that needs the developer.
+
+**Delegation.** When the workspace already has an app and you can run subagents, hand this step to one subagent as soon as you are signed in, and keep working on step 2: step 2 needs the developer at the browser, step 3 does not. Give the subagent a self-contained brief:
+
+```
+Goal: let this app's users prove "{{goal}}" with Reclaim.
+Repository: <absolute path>. Organization: <org ID>.
+Task: do step 3 of the plan below and report the file paths you changed, the
+callback route URL, and the env variable that holds the provider ID.
+Do not build the provider. Never print or commit the org key.
+<paste the step 3 checklist>
+```
+
+Without subagents, do step 2 first, and fill waits for the developer with this step.
+
+**No app yet?** If the workspace has no app to add verification to (it is empty, or has no backend or frontend), don't write one. Bootstrap from [builder-example](https://github.com/reclaimprotocol/builder-example), a ready-to-run Fastify backend and Vite frontend that already create sessions, verify callbacks, poll status, and render every UI state:
+
+Do this yourself, not in a subagent.
+
+- [ ] Call `create_example_app` with the workspace root you were started in as `projectDir`. It writes the example there and sets its backend to the latest `@reclaimprotocol/client`. Don't clone the repository or create a subdirectory: commands you run inside a clone count as running external code, and permission checks may block them.
+- [ ] Call `issue_org_token` with the same `projectDir` and `envFile: "packages/backend/.env"`.
+- [ ] Only when the developer asks for session binding or encrypted results: call `issue_org_keypair` with the same `projectDir` and `envFile` (add `encryptResults: true` for encrypted results). It writes `RECLAIM_ORG_ETH_PRIVATE_KEY` and registers the public key. Then pass `orgEthPrivateKey: process.env.RECLAIM_ORG_ETH_PRIVATE_KEY` to `reclaim.sessions.create` in `packages/backend/src/routes/verifications.ts` (binding) and to `reclaim.results.receive` in `packages/backend/src/routes/callback.ts` (decryption and TEE proof checks), and add an empty `RECLAIM_ORG_ETH_PRIVATE_KEY=` line to `packages/backend/example.env`.
+- [ ] From the workspace root, run `npm install`, then `npm run dev`. The backend listens on port 3000; the app opens at <http://localhost:5173>. If a permission check blocks either command, don't work around it: end your turn, say which command was blocked and that it installs and runs the Reclaim example app, and ask the developer to approve it.
+- [ ] Call `proxy_callback_events({ port: 3000, path: "/reclaim/callback" })`.
+- [ ] Skip the rest of this step. In step 4, the provider goes in `packages/backend/config.json`: replace the example entry with `{ "id": "<provider ID>", "name": "<what it proves>" }`, then restart the backend, because it reads the file at startup.
+
+**Existing app.** Add verification to it:
+
+- [ ] Detect the app's framework and package manager from the repository, and use them. Read `how_it_works({ topic: "integration" })`.
+- [ ] Call `issue_org_token` with the organization, this project's absolute path, and the server env file. It writes the key to that file and never returns it. Never print or commit the key. Confirm the env file is in `.gitignore`.
+- [ ] Add a backend route that creates a verification session (`POST /verifications/sessions`) and returns `verificationUrl`. Read the provider ID from server config (an env variable such as `RECLAIM_PROVIDER_ID`), so the route works before the provider exists.
+- [ ] Only when the developer asks for session binding or encrypted results: call `issue_org_keypair` with the server env file (`encryptResults: true` for encrypted results), and pass `orgEthPrivateKey` from that env variable to `sessions.create` and `results.receive`.
+- [ ] Add a callback route that verifies each result with `results.receive` from `@reclaimprotocol/client`, then stores only the requested data points. Store every failure on the verification session record and log it server-side: a failure event (`verification_rejected`, `verification_error`, `verification_cancelled`, `session_expired`), or a thrown `ResultVerificationError` (`error.reason` plus each failing proof's `reason`). Respond `error.retryable ? 503 : 200`. A result that failed verification gets 2xx, because retrying can't fix it. Read the exact pattern in `how_it_works({ topic: "integration" })`.
+- [ ] Add a status route the frontend polls. It returns the stored status, data points, and failure reason. While the app has no result, it also reads `GET /verifications/sessions/{sessionId}`, so a session that ended in Builder never stays pending.
+- [ ] Add a frontend Verify button that opens `verificationUrl`, and render every state in "UI states" in `how_it_works({ topic: "integration" })`: idle, waiting in the other tab, verifying, verified (with the data points), failed (plain-language reason and **Try again**), and expired or cancelled (**Try again**). Never leave a spinner as the only feedback.
+- [ ] Start the app. Call `proxy_callback_events({ port, path })` with the callback route's port and path. It forwards the org's verification events to that route on localhost, with no public URL.
+
 ## 4. Wire the provider and test end to end
 
 - [ ] Set the provider ID in the app's server config.
 - [ ] Confirm the callback route is forwarding: `proxy_callback_events` with no `stop` returns its status. If `blocked` is not empty, the app rejected that session's event: read the callback route's response and logs, fix the app, and check again.
 - [ ] Tell the developer exactly how to test: open the app, click Verify, sign in, and see the stored result. Also test one failure, such as cancelling in the verification tab, and confirm the app shows the failed state with **Try again**.
+- [ ] The hosted verification page streams the target site as an image, so text or DOM checks of that page come back empty. Check progress with `list_verification_events` and `get_verification_session`, not by reading the page.
 - [ ] After they click Verify, read the delivered events from `proxy_callback_events` status (`recent`) or `read_callback_events`. If the result did not arrive, or the app shows an unexpected failure, call `list_verification_deliveries` and fix the cause. Repeat until the app shows the stored result.
 - [ ] Ask the developer to set up the production callback. The local listener works only while this coding agent's MCP server runs; once it stops, the deployed app receives no results. Call `create_org_callback_subscription` with the deployed app's public callback route URL for all five session-ending events: `verification_success`, `verification_rejected`, `verification_error`, `verification_cancelled`, and `session_expired`.
 - [ ] If they have no deployed URL yet, tell them: "When you deploy, ask me to run `create_org_callback_subscription` with your public callback URL, or results will not reach the app."

package/skill/verification-client-integration.md

@@ -7,8 +7,18 @@ plan. Don't ask whether to try, integrate, or create an app. Ask one short
 question only when intent is unclear. The steps below are the detail behind
 that plan.
 
-Inspect the app's frontend, backend, package manager, configuration, and
-callback conventions. Complete the integration in its codebase and run its
+Prove the provider before you write app code: sign in to Builder, attach the
+browser, capture, and run the proof first. Those steps need the developer, and
+they show whether a proof is possible on the site. Write the app code after the
+proof works, or while you wait on the developer. When you need the developer
+to answer or act, end your turn with the question and every link they need;
+don't ask through a background or asynchronous question tool.
+
+When the workspace has no app yet, call `create_example_app` to write
+[builder-example](https://github.com/reclaimprotocol/builder-example) into the
+workspace root, as the `start_integration` plan describes, instead of writing a
+new backend and frontend or cloning the repository. Otherwise, inspect the app's frontend, backend, package manager,
+configuration, and callback conventions. Complete the integration in its codebase and run its
 relevant checks. The MCP tools configure Builder resources; your file tools
 edit the app.
 
@@ -27,10 +37,11 @@ server), or migrate to the session flow below. When migrating, remove
    production): register a
    public callback URL with `create_org_callback_subscription`, including
    all five session-ending events. If the
-   app needs encrypted results, register its public key with `set_org_keypair`;
-   keep the private key only in the backend. `set_org_keypair` refuses to
-   replace an existing key unless you pass `replace: true`; pass it only when
-   the developer asks.
+   app needs encrypted results or session binding, call `issue_org_keypair`
+   (`encryptResults: true` for encrypted results). It writes the private key to
+   the backend's env file and registers only the public key. It returns 409
+   when the org already has a different key: ask the developer for that key
+   rather than replacing it.
 3. Org key: reuse the `RECLAIM_ORG_SECRET` the app already has. Otherwise an
    organization owner calls `issue_org_token`. It writes the key to the
    project's env file (default `.env`, variable `RECLAIM_ORG_SECRET`) and
@@ -69,6 +80,10 @@ server), or migrate to the session flow below. When migrating, remove
    from `VerificationClient` in the SDK. Do not send an unregistered URL or
    call a legacy backend for an `api=2` session.
 
+   The hosted verification page streams the target site as an image, so text
+   and DOM checks of that page come back empty. Check a session's progress
+   with `list_verification_events` and `get_verification_session` instead.
+
 The one-time management calls above use the developer's Builder login. The
 consumer backend uses the separate organization token. The SDK's API-only
 entry point, `@reclaimprotocol/client/api`, is available when an application

package/src/authoring/backend.ts

@@ -35,6 +35,10 @@ export interface Draft {
 	/** One entry per extracted value (value + its redaction), so replay can
 	 *  validate each against its own selector. */
 	extractions: Extraction[]
+	/** Outcome of the latest authenticated in-browser replay, recorded by
+	 *  backends that track it. Lets a failed proof tell "the site blocks
+	 *  non-browser clients" apart from a broken recipe. */
+	lastReplay?: { status: number, ok: boolean }
 }
 
 /** A navigation script installed for every later page load of the authoring
@@ -49,10 +53,12 @@ export interface KeptScriptRef {
 	keptScript?: KeptScript
 }
 
-/** Per-session draft store: `propose` puts, `replay`/`run_proof` get by id. */
+/** Per-session draft store: `propose` puts, `replay`/`run_proof` get by id,
+ *  `update_draft` replaces one in place (same id). */
 export interface DraftStore {
 	put(draft: Draft): string
 	get(id: string): Draft | undefined
+	set(id: string, draft: Draft): void
 }
 
 export function makeDraftStore(): DraftStore {
@@ -64,6 +70,9 @@ export function makeDraftStore(): DraftStore {
 			return id
 		},
 		get: (id) => map.get(id),
+		set: (id, draft) => {
+			map.set(id, draft)
+		},
 	}
 }
 
@@ -73,6 +82,8 @@ export function makeDraftStore(): DraftStore {
 export interface ProveOptions {
 	ownerAddress?: string
 	attestorUrl?: string
+	/** ISO country the attestor's request goes out from (local proofs). */
+	geoLocation?: string
 }
 
 /**