@reclaimprotocol/agent 0.1.35 → 0.1.37

package/lib/provider/matcher.js

@@ -1,3 +1,5 @@
+import { badRequest } from '@hapi/boom';
+import assert from 'node:assert';
 import { elementAnchor } from "./dom-xpath.js";
 import { normalizeCandidates } from "./normalize.js";
 /** Reclaim attestor caps OPRF-hashed values at 62 bytes (TOPRF marker
@@ -53,6 +55,12 @@ export function synthesizeMatcher(body, contentType, target, paramName, hash) {
             return r;
         }
     }
+    // Inline JSON / JS-object text outside an HTML element (a JS bundle, a
+    // non-JSON text body): anchor on the key name right before the value.
+    const inline = inlineKeyMatcher(body, target, paramName, valueClass, hash);
+    if (inline) {
+        return inline;
+    }
     // No JSON key and no stable xPath anchor: a content-anchored regex, matched
     // by CONTENT so it reproduces regardless of DOM position at proof time (a
     // positional `(//tag)[N]` resolves to the wrong node at proof — see 9fd7770).
@@ -308,7 +316,133 @@ function htmlMatcher(body, target, paramName, valueClass, hash) {
             return keyValueResult(kp.prefix, kp.close, target, paramName, valueClass, { xPath: anchor.xPath, jsonPath }, hash);
         }
     }
-    return elementResult(anchor.xPath, revealSlice, target, paramName, valueClass, hash);
+    // Inline JS-object / JSON text inside the element (a SvelteKit/Next/Nuxt
+    // hydration `<script>` that isn't valid JSON): anchor on the key name
+    // nearest the value (`currentTierDescription:"{{v}}"`), scoped by the xPath.
+    const inline = inlineKeyMatcher(revealSlice, target, paramName, valueClass, hash, anchor.xPath);
+    if (inline) {
+        return inline;
+    }
+    const result = elementResult(anchor.xPath, revealSlice, target, paramName, valueClass, hash);
+    const [left = '', right = ''] = result?.match.value
+        .split(`{{${paramName}}}`) ?? [];
+    const hits = result?.redaction?.regex
+        ? countMatches(revealSlice, result.redaction.regex)
+        : 0;
+    assert(!result || !isGenericWindow(left, right) || hits <= 1, badRequest(`target value "${target}" sits in a <${elementTag(revealSlice)}> `
+        + 'with no key name or markup next to it. The only literal context, '
+        + `"${result?.match.value}", matches ${hits} values in that element, `
+        + 'so it would not pin this one. Pick a request where the value has '
+        + 'a key (for example, a JSON API response) or sits in its own '
+        + 'element.'));
+    return result;
+}
+/** How many times `regex` matches in `text` (0 for an invalid regex). */
+function countMatches(text, regex) {
+    try {
+        return [...text.matchAll(new RegExp(regex, 'g'))].length;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Tag name of the element markup starting `markup` (`script`, `div`, …). */
+function elementTag(markup) {
+    return /^<([A-Za-z][\w-]*)/.exec(markup)?.[1] ?? 'element';
+}
+/** A literal window with no letter or digit on either side (for example,
+ *  `:"{{v}}",`): it pins a value only when the element holds nothing else. */
+function isGenericWindow(left, right) {
+    return !/[A-Za-z0-9]/.test(left + right);
+}
+// ---------------------------------------------------------------------------
+// Inline key: `key:"value"` / `"key":"value"` in JS-object or JSON text
+// ---------------------------------------------------------------------------
+/** How far left of a value to look for its key. */
+const MAX_KEY_LOOKBACK = 128;
+/** The key directly before a value: JSON `"key":`, `'key':`, or a bare JS
+ *  identifier `key:`, then the value's opening quote (if any) at the end. */
+const KEY_BEFORE_VALUE = new RegExp('(?:"([A-Za-z_$][\\w$-]*)"|\'([A-Za-z_$][\\w$-]*)\''
+    + '|(?<![\\w$"\'])([A-Za-z_$][\\w$]*))\\s*:\\s*(["\']?)$');
+/**
+ * Matcher for a value written as `key:"value"` (JS object literal, as SvelteKit
+ * and similar frameworks inline into SSR pages) or `"key":"value"` inside text
+ * that isn't parseable JSON. The window is the key name plus the value's
+ * quotes, so the match pins this field and nothing user-specific:
+ * `currentTierDescription:"{{v}}"`.
+ *
+ * Rejects a key that appears more than once in `scope` with a different value:
+ * the regex would extract the first one, which may not be this field. When the
+ * value has a key but it's ambiguous, throws rather than falling back to a
+ * looser window. Returns undefined when no occurrence has a key before it.
+ */
+function inlineKeyMatcher(scope, target, paramName, valueClass, hash, xPath) {
+    const candidates = [target, ...normalizeCandidates(target)]
+        .filter((c) => c && !c.startsWith('"'));
+    let ambiguous;
+    for (const cand of new Set(candidates)) {
+        for (let idx = scope.indexOf(cand); idx >= 0; idx = scope.indexOf(cand, idx + 1)) {
+            const kv = keyBefore(scope, idx, cand);
+            if (!kv) {
+                continue;
+            }
+            const others = valuesForKey(scope, kv.key)
+                .filter((v) => v !== cand);
+            if (others.length) {
+                ambiguous ?? (ambiguous = { key: kv.key, count: others.length + 1 });
+                continue;
+            }
+            // A single-quoted free-form value must stop at its own quote.
+            const cls = kv.close === '\'' && valueClass === '[^"<>\\n]+'
+                ? '[^\'<>\\n]+'
+                : valueClass;
+            return keyValueResult(kv.prefix, kv.close, cand, paramName, cls, xPath ? { xPath } : {}, hash);
+        }
+    }
+    assert(!ambiguous, badRequest(`target value "${target}" sits under key "${ambiguous?.key}", but that `
+        + `key occurs ${ambiguous?.count} times with different values, so a `
+        + 'match on it would not pin this value. Pick a request where the key '
+        + 'is unique (for example, a JSON API that returns only this object).'));
+    return undefined;
+}
+/** The key + opening-quote prefix directly before the value at `idx`, when the
+ *  value is a complete quoted string (or a bare token) under that key. */
+function keyBefore(scope, idx, value) {
+    const head = scope.slice(Math.max(0, idx - MAX_KEY_LOOKBACK), idx);
+    const m = KEY_BEFORE_VALUE.exec(head);
+    const key = m?.[1] ?? m?.[2] ?? m?.[3];
+    if (!m || !key || key.length < 2) {
+        return undefined;
+    }
+    // A bare key before a bare value (`score: 5`) is prose as often as code;
+    // require a quoted key or a quoted value.
+    const quote = m[4] ?? '';
+    const after = scope[idx + value.length] ?? '';
+    const complete = quote ? after === quote : /^$|[\s,;}\]]/.test(after);
+    if (!complete || (!quote && m[3])) {
+        return undefined;
+    }
+    return { key, prefix: m[0], close: quote };
+}
+/** Every value written under `key` in `scope` (JSON or JS-object syntax),
+ *  raw — quoted strings without their quotes, bare tokens as-is. */
+function valuesForKey(scope, key) {
+    const re = new RegExp(`(?<![\\w$])(["']?)${escapeRegex(key)}\\1\\s*:\\s*`, 'g');
+    const values = [];
+    for (const m of scope.matchAll(re)) {
+        const start = m.index + m[0].length;
+        const quote = scope[start];
+        if (quote === '"' || quote === '\'') {
+            let j = start + 1;
+            while (j < scope.length && scope[j] !== quote) {
+                j += scope[j] === '\\' ? 2 : 1;
+            }
+            values.push(scope.slice(start + 1, j));
+            continue;
+        }
+        values.push(/^[^\s,;}\]]*/.exec(scope.slice(start))?.[0] ?? '');
+    }
+    return values;
 }
 /**
  * `contains` a PORTABLE window of the element around the value, with the value
@@ -547,14 +681,25 @@ function buildContentRegex(body, target, paramName, valueClass) {
             const from = Math.max(0, start);
             const before = escapeRegexFlexWs(body.slice(from, idx));
             const re = `${before}(?<${paramName}>${valueClass})${right}`;
+            let found = false;
             try {
-                if (new RegExp(re).exec(body)?.groups?.[paramName] === cand) {
-                    return re;
-                }
+                found = new RegExp(re).exec(body)?.groups?.[paramName] === cand;
             }
             catch {
                 break;
             }
+            if (found) {
+                const problem = contextProblem(body.slice(from, idx), right ? rawRight : '');
+                assert(!problem, badRequest(`target value "${target}" has no key name or element next to `
+                    + `it; the shortest window that pins it, "${body.slice(from, idx)}`
+                    + `{{${paramName}}}${right ? rawRight : ''}", ${problem}. That `
+                    + 'would pin the provider to this user or match the wrong value. '
+                    + 'This happens with positional arrays such as SvelteKit '
+                    + '`__data.json`. Use a request where the value sits under its '
+                    + 'own key (the HTML page or another JSON API), or stop and '
+                    + 'report.'));
+                return re;
+            }
             if (from === 0) {
                 break;
             }
@@ -562,6 +707,28 @@ function buildContentRegex(body, target, paramName, valueClass) {
     }
     return undefined;
 }
+/** A standalone number token (`33` in `:33},`) — a points balance, count, or
+ *  id that differs per user; not a digit inside a word or class (`mb-2`). */
+const VOLATILE_NUMBER = /(?<![\w.-])\d+(?:\.\d+)?(?![\w.])/;
+/** The closing quote of a string followed by a separator — the end of a
+ *  neighbouring VALUE (keys are followed by `:`), usually user-specific. */
+const NEIGHBOUR_STRING = /"\s*[,\]}]/;
+/** Why a content window around a value isn't portable, or undefined when it
+ *  is: only punctuation (pins nothing), a number next to the value, or a
+ *  neighbouring string value. */
+function contextProblem(left, right) {
+    if (VOLATILE_NUMBER.test(left) || VOLATILE_NUMBER.test(right)) {
+        return 'contains a number next to the value, which is likely '
+            + 'user-specific (for example, a points balance)';
+    }
+    if (NEIGHBOUR_STRING.test(left)) {
+        return 'contains a neighbouring value, which is likely user-specific';
+    }
+    if (!/[A-Za-z]/.test(left + right)) {
+        return 'is only punctuation and matches almost any value';
+    }
+    return undefined;
+}
 /**
  * The literal `contains` template: surrounding structural context with the
  * value replaced by `{{paramName}}`. Whitespace-adjacent context is dropped (a

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@reclaimprotocol/agent",
 	"title": "Reclaim Agent",
-	"version": "0.1.35",
+	"version": "0.1.37",
 	"description": "Reclaim Protocol tools for AI coding agents. Reclaim lets your app verify data points about its users, such as a follower count, an account balance, or an order history. This package is the Reclaim MCP server: it gives your agent the tools to find, build, test, and fix data verification providers by capturing and replaying browser requests, drafting provider recipes, running zkTLS proofs, and publishing provider versions.",
 	"type": "module",
 	"main": "./lib/index.js",
@@ -44,7 +44,7 @@
 		"README.md"
 	],
 	"engines": {
-		"node": ">=22.0.0"
+		"node": ">=22.12.0"
 	},
 	"repository": {
 		"url": "https://github.com/reclaimprotocol/builder",
@@ -82,8 +82,9 @@
 		"@hapi/boom": "^9.1.4",
 		"@modelcontextprotocol/sdk": "^1.29.0",
 		"@noble/hashes": "^2.2.0",
-		"@reclaimprotocol/attestor-core": "^5.1.5",
-		"@reclaimprotocol/client": "0.1.35",
+		"@puppeteer/browsers": "3.2.4",
+		"@reclaimprotocol/attestor-core": "^5.1.6",
+		"@reclaimprotocol/client": "0.1.37",
 		"@reclaimprotocol/tls": "^0.1.3",
 		"chrome-remote-interface": "^0.33.0",
 		"domhandler": "^6.0.0",
@@ -92,6 +93,7 @@
 		"parse5-htmlparser2-tree-adapter": "^8.0.0",
 		"pino": "^9.14.0",
 		"xpath": "^0.0.34",
+		"yauzl": "3.4.0",
 		"zod": "^4.4.3"
 	},
 	"devDependencies": {

package/skill/SKILL.builder.md

@@ -15,6 +15,11 @@ Build a new org-private provider for the claim the developer described. Ask
 one question if the site, account, or value is ambiguous. Copy this checklist
 and check off each step. Read the linked topic before a step you don't know.
 
+Steps 2 through 10 need the developer at the browser, so do them before other
+work, such as app code. When you need the developer to answer or act, end
+your turn with the question and every link they need. Don't use a background
+or asynchronous question tool for a blocking question.
+
 - [ ] 1. Name the data points: only the values the claim must prove, usually
       one or two. No identity or profile fields.
 - [ ] 2. `attach_browser`, then `list_tabs` → `start_capture(tabId)` ⇒
@@ -34,7 +39,7 @@ and check off each step. Read the linked topic before a step you don't know.
       → topic `params`
 - [ ] 9. `replay_request(captureId, draftId)`, then again with
       `withoutSecrets: true`. → topic `prove`
-- [ ] 10. `run_proof(captureId, draftId, ownerAddress)`.
+- [ ] 10. `run_proof(captureId, draftId)`.
       → topics `prove`, `credentials`
 - [ ] 11. `create_provider` (or a new version of a provider your org owns) →
       `create_provider_version_from_capture` (publishes the kept script as
@@ -303,7 +308,7 @@ with no secrets/cookies, as an anonymous visitor.
   `viewer`/`currentUser` API) 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/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
@@ -75,9 +94,17 @@ TEE binding. Edit the app with your file tools. Use the HTTP API
 `@reclaimprotocol/client`. The only exception is `results.receive` on the
 callback, or when the developer asks for the client package.
 
+The app's frontend renders every state and every failure, never only a
+spinner. Follow "UI states" in `how_it_works({ topic: "integration" })`. The
+callback route responds `error.retryable ? 503 : 200` for a thrown
+`ResultVerificationError`; a result that failed verification gets 2xx.
+
 For local development, call `proxy_callback_events({ port, path })` to forward
 events to the app's callback route on localhost. The local listener works only
-while this MCP server runs. Production needs a webhook:
+while this MCP server runs. It keeps events in order per session and retries
+a session the app rejects with backoff, so other sessions keep flowing. When
+its status lists `blocked` sessions, read that session's callback route
+response and logs, and fix the app. Production needs a webhook:
 `create_org_callback_subscription` with the deployed app's public URL. Without
 one, session creation returns 409.
 
@@ -114,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