@reclaimprotocol/agent 0.1.23 → 0.1.25

package/skill/SKILL.common.md

@@ -1,111 +1,414 @@
-<!-- section: header -->
-# Authoring a Reclaim Provider
-
-> **Terminology note:** A **provider** is the recipe you author here — the
-> instructions for extracting a data point from a website (the
-> `responseMatches` / `responseRedactions` spec, identified by a
-> `providerId`). Always call it a **provider**; never call a provider a
-> "verification." A **verification** (or **verification session**) is the
-> separate runtime act in which an end-user proves a data point *using* a
-> provider — reserve that word for the session/result, never for the recipe.
-> If a developer calls the recipe a "verification," gently use "provider"
-> yourself rather than correcting them.
-
-> **Terminology note:** "JS injection", "custom injection", "user script",
-> and "web script" all refer to the SAME thing when talking about a
-> provider — the plain browser JS that runs before every page load to drive
-> navigation for data gated behind login/routing. Builder's schema field is
-> `jsUserScripts`; old-devtools' equivalent field is `customInjection`
-> (identical semantics, different name). Prefer **"user script"** in your
-> own prose regardless of which backend you're on; see `injection-api.md`
-> for the full field-level reference.
-
-You drive the browser through the capture → draft → replay → prove loop using the `reclaim-agent` MCP server. **Your default stance is driver, not orchestrator.** Only pause to ask the dev for things that genuinely require a human: typing credentials, completing 2FA, solving a captcha, confirming an ambiguous value. Navigation, reloads, DOM inspection, request capture — all yours.
-
-<!-- section: step-attach -->
-1. **Attach.** Call `attach_browser`. If it returns `needsChoice: true`, ask the dev which browser source they want:
-   - `dedicated` — agent auto-launches Chrome with a dedicated profile under `~/.reclaim/chrome-profile`. Easiest local path; works out of the box.
-   - `attach` — connect to a Chrome the dev is already running. **Important Chrome 136+ gotcha:** the dev's Chrome must be launched with BOTH `--remote-debugging-port=9222` AND `--user-data-dir=<some-non-default-path>`. Since Chrome 136 (May 2025), the debug-port flag is silently ignored when the default user profile is in use. If `attach` fails, tell them this verbatim and offer to switch to `dedicated`.
-   - `builder` — allocate a quota-accounted remote Popcorn browser. If Builder answers 401, authenticate with `authenticate_builder` in old-devtools mode or the existing `authenticate` flow in Builder mode, then retry. You can omit `orgId` and call `attach_browser` directly: it auto-resolves to the account's only organization, or — if the account belongs to more than one — comes back with `needsChoice: true` and an `organizations` list; **ask the dev which one to use** (don't guess or default to the first) and re-call `attach_browser` with that `orgId`. (`list_builder_organizations` in old-devtools mode / `list_orgs` in Builder mode still work directly if you want the list up front instead.) Return the FULL `liveViewUrl` to the dev verbatim — on its own line, never abbreviated, elided, or wrapped in prose that truncates it — so it stays one clean, copy-pasteable string; they'll share it with the volunteer operating the browser. This works in both publishing modes and consumes one VERIFICATION-pool use under the chosen organization's normal plan restrictions.
-   - `custom` — connect to a `ws://` or `wss://` CDP URL supplied by the dev. The URL is a credential: never repeat it, log it, or persist it. An optional `liveViewUrl` may be returned — if so, share it FULL and verbatim, same as `builder` above.
-
-   Re-call with the chosen `mode` and its required fields.
-
-<!-- section: step-identify-value -->
-6. **Identify the value from the DOM.** `eval_in_page` to read the displayed value (e.g. the logged-in username from `meta[name="user-login"]`'s `content` attribute). If the value is unambiguous, proceed without asking. Only confirm with the dev when there are multiple plausible interpretations (e.g. the page shows both a display name "John Doe" and a handle "@jdoe" and you need to pick which to prove).
-
-<!-- section: step-find-request -->
-7. **Find the request.** Call `find_requests_containing(captureId, value)`. For each top candidate (limit ≤ 5), call `analyze_request_constraints` and surface its `concerns` to the dev verbatim. Skip candidates flagged `signedRequest` or `botChallenge` unless none others are available. Concerns flagged `csrfDependency`, `shortLivedToken`, or `graphql` are informational — surface them and proceed.
-
-   **Strongly prefer authenticated, user-specific endpoints over public pages.** A proof against a public endpoint (e.g. `https://github.com/<username>`) attests only that "this URL returned this value at this time" — anyone in the world could fetch the same URL and prove the same thing. The proof says nothing about who the prover _is_. To prove a fact about the dev, the captured request needs to be one whose **response varies with authentication** — typically an API endpoint that returns the logged-in user's data (e.g. `GET https://api.github.com/user`, `https://twitter.com/i/api/.../UserByScreenName?...&forCurrentUser=true`).
-
-   When ranking candidates from `find_requests_containing`, prefer ones that:
-   - Have `Cookie`, `Authorization`, or other secret headers (analyze_request_constraints will surface these via `splitSecrets`).
-   - Have URL paths suggesting authenticated data: `/me`, `/user`, `/settings`, `/api/...`, `/graphql` with viewer queries.
-   - Return JSON keyed to the dev's identity (login/username/id fields next to the target value).
-
-   If the only candidates are public-page HTML responses, tell the dev: "The value appears on a public page, so a proof against this endpoint won't bind to your identity — anyone could prove the same fact. I can still build it if you just want to attest the value, but for an identity-bound proof we need to capture an authenticated request. Want to keep digging, or proceed anyway?" Then wait for their call.
+<!-- section: terminology -->
+> **provider** = the recipe you author (the `responseMatches`/`responseRedactions`
+> spec behind a `providerId`). **verification** = the runtime act of an end-user
+> proving a data point *using* a provider. Never call a provider a
+> "verification". If the developer does, use "provider" yourself.
+>
+> **user script** = the plain browser JS that runs before every page load
+> ("JS injection", "custom injection", "web script" all mean this). Builder's
+> field is `jsUserScripts`; old-devtools' is `customInjection`. Same thing.
+
+**Your stance is driver, not orchestrator.** Navigation, reloads, DOM
+inspection, request capture — all yours. Pause only for what needs a human:
+typing credentials, 2FA, captchas, confirming a genuinely ambiguous value.
+
+**When you're stuck, read before you guess.** Every failure mode here has a
+topic. Pull the matching one with `how_it_works({ topic })` and offer the
+developer what it says — a site that won't load points at `interception`, a
+failing proof at `prove`, a dead browser at `browser`, an expired draft at
+`troubleshooting`. Inventing a cause wastes their time; the guide usually
+already names it.
+
+<!-- section: browser -->
+## Choosing a browser
+
+- Choosing one — ask who signs in, then offer the matching pair
+- Sharing the container's live view with someone remote
+- What happens when the session ends
+- 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 |
+| --- | --- | --- |
+| `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, their bandwidth. 432 MB the first time, about 2 GB of RAM, 7 to 17 seconds to start |
+| `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` gotcha (Chrome 136+, May 2025):** 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`.
+
+**`builder` specifics:**
+
+- 401 → authenticate first (`authenticate_builder` in old-devtools mode, the
+  native `authenticate` flow in Builder mode), then retry.
+- `orgId` may be omitted: it auto-resolves when the account has exactly one org,
+  otherwise comes back `needsChoice` with an `organizations` list — **ask the
+  developer which one**, don't guess or take the first.
+- **Geolocation is optional.** Omitting `countryCode` returns `needsChoice` with
+  a `suggestedCountryCode` (the developer's own country, from their public IP)
+  and costs nothing — no browser is allocated. Offer the developer three things:
+  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
+  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** —
+  never abbreviated, elided, or wrapped in prose that truncates it.
+- Close it when the work is done (`dispose_browser`) so the quota isn't wasted —
+  but only after the developer confirms, never unprompted.
+
+**`custom` specifics:** the `cdpUrl` is a credential — never repeat, log, or
+persist it. If a `liveViewUrl` comes back, share it full and verbatim.
+
+### Sharing the container's live view (`share_browser_view`)
+
+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
+complete, or a colleague watching a capture.
+
+**Offer it whenever a login is coming and the developer is not the one holding
+the credentials.** Nobody asks for a feature they have no way of knowing exists.
+Ask plainly:
+
+> Do you want a link to this browser? You can open it yourself, or send it to
+> 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 URL verbatim, on
+its own line.**
+
+- **`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`.
+- **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
+  what it grants, and stop the share when they are done rather than leaving it
+  open. Tell them the watcher sees everything typed into that browser, including
+  a password — so if the point is for the DEVELOPER to log in, they should do it
+  before you share, not after.
+- **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.
+- **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**, the tunnel may not have registered with
+  Cloudflare — the hostname exists before the route does. Have them reload after
+  10 seconds; if it still fails, `stop_browser_view` then `share_browser_view`
+  again, since a quick tunnel does occasionally fail to come up. A
+  `propagating: true` in the result is that case, and `cloudflaredLog` carries
+  the reason.
+- **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. Say so when it happens — it's a 37 MB download onto their
+  machine. `RECLAIM_CLOUDFLARED_PATH` points at their own copy instead.
+
+### 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.
+- **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.
+- **A second session working at the same time gets its own container.** They
+  cannot share one: the live view streams the whole screen, so two sessions in
+  one container would see each other's browsing, and two browsers on one profile
+  corrupt the cookie jar they share. Each concurrent session therefore has its
+  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.
+
+### When the container will not start
+
+- **Docker is not running.** The error says so and names the other browser
+  modes. Docker is not something you can install for them.
+- **Apple Silicon.** The image is amd64 and cannot be built for arm64, so it
+  runs translated. OrbStack does this itself; Docker Desktop needs "Use Rosetta
+  for x86/amd64 emulation" turned on. Under QEMU instead of Rosetta, Chromium
+  crashes on launch.
+- **First run looks stuck.** It is downloading 432 MB. Say that rather than
+  letting it look hung.
+- 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.
+- **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
+site-specific check.
+
+**Combine a positive signal (element present only when logged in) with a
+negative one (login button absent), AND them together.** Single signals are too
+prone to false positives — `<meta>` tags in particular exist on every page
+regardless of login state; only their `.content` is populated, so
+`!!document.querySelector('meta[name="user-login"]')` is true when logged out.
+Never use existence-only checks on meta tags or other persistent-but-empty
+elements.
+
+- GitHub: `(document.querySelector('meta[name="user-login"]')?.content?.length || 0) > 0 && !document.querySelector('a.HeaderMenu-link[href="/login"]')`
+- X / Twitter: `!!document.querySelector('[data-testid="AppTabBar_Profile_Link"]') && !document.querySelector('[data-testid="loginButton"]')`
+- Generic: `<logged-in-only-element> && !<logged-out-only-element>`
+
+Truthy → move on. Falsy → **navigate to the login URL yourself** so the
+developer lands on the form (`https://<host>/login`, `/signin`,
+`https://<host>/i/flow/login` for X). Tell them once: _"I've opened the login
+page on `<site>` — please log in (2FA included). I'll detect when you're
+done."_ Then `wait_for_page(captureId, expression="<same expression>",
+timeoutMs=180000)`; it polls every second. **Never** say "tell me when you're
+done" — wait with the tool.
+
+**Self-check:** if your detector says "already logged in" on a freshly launched
+dedicated profile, the detector is wrong — a new profile has an empty cookie
+jar. Rewrite the expression.
+
+<!-- section: identify-value -->
+**Identify the value from the DOM.** `eval_in_page` to read what's displayed
+(for example, the username from `meta[name="user-login"]`'s `content`).
+Unambiguous → proceed silently. Only ask the developer when there are genuinely
+multiple readings (the page shows both "John Doe" and "@jdoe" and you must pick
+one).
+
+<!-- section: find-request -->
+**Find the request.** `find_requests_containing(captureId, value)`. For each top
+candidate (≤5) call `analyze_request_constraints` and surface its `concerns` to
+the developer **verbatim** — don't paraphrase or omit; they're the developer's
+signal that a provider is worth pursuing. Skip candidates flagged
+`signedRequest` or `botChallenge` unless nothing else exists; `csrfDependency`,
+`shortLivedToken` and `graphql` are informational — surface and proceed.
+
+**Strongly prefer authenticated, user-specific endpoints over public pages.** A
+proof against `https://github.com/<username>` attests only "this URL returned
+this value at this time" — anyone could produce it, so it says nothing about who
+the prover is. Rank candidates that:
+
+- carry `Cookie`, `Authorization`, or other secret headers;
+- have auth-shaped paths (`/me`, `/user`, `/settings`, `/api/...`, a `viewer`
+  GraphQL query);
+- return JSON keyed to the developer's identity (login/username/id next to the
+  value).
+
+If every candidate is a public HTML page, tell the developer: _"The value
+appears on a public page, so a proof against this endpoint won't bind to your
+identity — anyone could prove the same fact. I can still build it if you only
+want to attest the value, but an identity-bound proof needs an authenticated
+request. Keep digging, or proceed anyway?"_ Then wait for their call.
+
+<!-- section: oprf -->
+**Decide whether to OPRF the value** (privacy from the attestor) before calling
+`propose_provider`:
+
+- **No hash** (default) — value travels in `paramValues` + `{{name}}`; the
+  attestor sees the cleartext substring. Right for non-sensitive values (public
+  IPs, public usernames, public repo names).
+- **`oprf-raw`** — server-side OPRF. **The only variant that runs on Windows /
+  without external deps.** Weakest privacy of the three (the attestor still
+  participates) — say so honestly.
+- **`oprf`** — client-side ZK OPRF using gnark. Strongest. Needs a gnark install
+  (Linux/macOS in practice). Don't suggest it on Windows.
+- **`oprf-mpc`** — TEE-based MPC. Niche; only if the developer raises it.
+
+**Skip the question** when the value is clearly non-sensitive, and default to
+no hash. When it is or could be sensitive (email, real name, private id —
+anything the developer wouldn't post publicly), put the four options to them.
+
+**Hard limits:**
+
+1. OPRF-hashed values cap at **62 bytes**. Longer → propose a tighter `target`
+   (for example, only the email local-part) or no hash.
+2. **OPRF and the request URL are mutually exclusive for the same value.** Any
+   value templated into the request URL is signed into the attestor's context in
+   the clear regardless of hashing, so hashing it doesn't just fail to help — it
+   doesn't verify. If the target's value also appears in the captured URL, drop
+   `hash` or capture a request whose URL doesn't carry it.
+3. Never pass `hash` for a free-form target (unicode / spaces / punctuation).
+
+`propose_provider` throws a clean error on all three — retrying the same call
+won't help.
 
 <!-- section: rewrite-shape-block -->
-   **Do NOT rewrite the shape.** The synthesizer's output is the canonical Reclaim shape — `contains` template + paramValues + xPath/jsonPath redaction (optionally + regex+hash). Specifically:
-   - Do not replace the `contains` template with a hand-crafted regex.
-   - Do not hand-write a named-capture regex unless `hash` was requested AND the synthesizer's output doesn't already have one. (It will, for any digit/slug/email-shaped target.)
-   - Do not remove `paramValues` — that's how the template resolves at proof time.
-   - The redaction's xPath/jsonPath is what the prover reveals; the match's template is what the attestor verifies post-substitution. They serve different purposes — don't conflate them.
-   - Do not prefix the match-template's param with `context.`/`context_` — that namespace is reserved for consumer-supplied URL/body params (step 10). Match templates are extraction params and stay bare.
+   **Do NOT rewrite the shape.** The synthesizer's output IS the canonical
+   Reclaim shape — `contains` template + paramValues + xPath/jsonPath redaction
+   (+ regex/hash). Specifically:
+
+   - Don't replace the `contains` template with a hand-written regex.
+   - Don't hand-write a named-capture regex unless `hash` was requested AND the
+     synthesizer didn't already emit one (it does, for any digit/slug/email
+     target).
+   - Don't remove `paramValues` — that's how the template resolves at proof
+     time.
+   - The redaction's xPath/jsonPath is what the prover *reveals*; the match's
+     template is what the attestor *verifies* post-substitution. Different
+     jobs — don't conflate them.
+   - Don't prefix the match template's param with `%CTX%` — that namespace is
+     for consumer-supplied URL/body params only. Match templates are extraction
+     params and stay bare.
+
+   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
+   `propose_provider` again with different inputs instead.
 
-   Permitted edits: narrowing the `contains` template, picking a more distinctive xPath class/id if the synthesizer's pick is too generic, fixing the `name` field, adding/removing secret headers. If you're tempted to rewrite the provider from scratch, call `propose_provider` again with different inputs instead.
+<!-- section: secrets -->
+**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`
+(`classifyParamName`/`splitSecretParamValues`), the same convention
+`reclaim-inapp-sdk`/`reclaim-portal` use. **A secret param's value never appears
+in the final proof.**
+
+**Headers work by the OPPOSITE rule — an allowlist, not a name check.** Any
+header not on a small fixed public list (`user-agent`, `accept`,
+`accept-language`, `accept-encoding`, `sec-fetch-*`, `origin`,
+`x-requested-with`, `sec-ch-ua*`) is secret by default, including
+`Cookie`/`Authorization` and anything custom (`classifyHeader`/`splitSecrets`).
+
+**The URL character budget.** A secret value CAN be used in the URL,
+`geoLocation`, body, matches and redactions — write-redaction genuinely hides
+it. But in the URL it only holds up to a small **TOTAL** budget summed across
+every secret value in that URL (`secretUrlCharBudget`), not a per-value
+allowance: **2 characters under `key-update`** (the default), **12 under `zk`**.
+Over budget the value is effectively visible to the attestor no matter how it's
+marked, and claim creation fails outright. Since the real value doesn't exist
+until a verification session supplies one, this is checked at **verification**
+time (`assertSecretParamValuesFitUrlBudget`), not publish time — except for a
+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 -->
-**Do not rename the match-template param.** The synthesizer's `{{name}}` in `responseMatches[].value` is an _extraction_ template (the attestor pulls the value out of the response) — it stays bare and never gets the `context.` prefix. Only URL/body placeholders whose values the Consumer must supply are context params.
+**Do not rename the match-template param.** The synthesizer's `{{name}}` in
+`responseMatches[].value` is an _extraction_ template — it stays bare and never
+takes the `%CTX%` prefix. Only URL/body placeholders whose values the consumer
+supplies are context params.
 
 <!-- section: prove-tail -->
-    **On any `verified: false` response, the result includes (inline):**
-    - `error` — the SDK's thrown error message verbatim
-    - `sentParams` — the exact `params` object the SDK saw, post-template substitution (lets you spot mutation / substitution surprises)
+    **On any `verified: false` the result includes, inline:** `error` (the SDK's
+    thrown message verbatim) and `sentParams` (the exact `params` the SDK saw,
+    post-substitution — this is where you spot mutation surprises).
+
+    **The attestor is reliable. If it errors, the cause is the provider, the
+    network, or prover-side code — not "the attestor can't handle this site".**
+    Do not invent failure modes like "the HTML is too large", "TLS records are
+    chunked", "it matches against gzipped bytes" (it doesn't —
+    `propose_provider` always sets `Accept-Encoding: identity`), or "xPath
+    doesn't work on this DOM". They're wrong and they waste the developer's
+    time. Instead: (1) show `error` verbatim; (2) if `sentParams` differs from
+    what you expected, surface that; (3) only then hypothesize, tied to that
+    evidence.
 
-    **Deeper tracing (opt-in).** If the dev launches Claude Code with `RECLAIM_AGENT_TRACE=1` in the MCP server's env, `run_proof` ALSO captures the SDK's full pino log stream into `result.attestorLogs` and persists a per-call dump to `~/.reclaim/proof-runs/<timestamp>.json` (surfaced as `runLogPath`). Off by default because the trace stream is verbose. Suggest turning it on when investigating a recurring proof failure.
+    **Deeper tracing (opt-in).** With `RECLAIM_AGENT_TRACE=1` in the MCP
+    server's env, `run_proof` also captures the SDK's full pino stream into
+    `result.attestorLogs` and dumps `~/.reclaim/proof-runs/<timestamp>.json`
+    (`runLogPath`). Off by default — suggest it for a recurring failure.
 
-    **The attestor is reliable. If it errors, the cause is in the provider, the network, or the prover-side code — not "the attestor can't handle this site".** Do not invent failure modes like "HTML is too large", "TLS records are chunked", "the attestor matches against gzipped bytes" (it doesn't if the provider has `Accept-Encoding: identity`, which `propose_provider` always sets), or "xPath doesn't work on this DOM". These are wrong and they waste the dev's time. Instead:
-    1. Show the `error` field to the dev verbatim.
-    2. If `sentParams` differs from what you expected — e.g. `{{name}}` substituted to the wrong value, headers got mutated, redactions look different from `propose_provider`'s output — surface that.
-    3. Only then propose a hypothesis, and tie it to that evidence. If the diagnosis is unclear, suggest the dev set `RECLAIM_AGENT_TRACE=1` and rerun for full attestor logs.
+    **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.
 
-    **Do not auto-retry with a different `attestorUrl`.** There is one live public attestor right now; backup hostnames (`attestor-2.*`, etc.) **do not exist**. `attestorUrl` is only for when the dev explicitly supplies a private/staging URL.
+    **"ZK circuit resources are missing"** (points at a `circuit.wasm` path) —
+    the npm postinstall didn't run (`--ignore-scripts`, or corp policy). Tell
+    the developer to run `npm run download:zk-files` from the project root and
+    retry `run_proof`. No re-capture, no server restart.
 
-    **Missing ZK circuit files:** if the error says "ZK circuit resources are missing" and points at a `circuit.wasm` path, the npm postinstall didn't run (commonly because the dev used `npm install --ignore-scripts` or a corp policy disabled it). Tell the dev to run `npm run download:zk-files` from the project root and then retry `run_proof` — no need to redo capture or propose. The MCP server doesn't need a restart either; the next `run_proof` call will see the files.
+<!-- section: never-do-common -->
+- Never echo a raw `Authorization`, `Cookie`, or `X-*-Token` value back to the
+  developer or write one to a file. `list_requests`,
+  `find_requests_containing`, `propose_provider` and every draft/replay/proof
+  result are secret-free by construction. `get_request` is the one exception —
+  it returns the request's RAW headers so you can inspect them. Read them,
+  never repeat them.
+- Never call `run_proof` before `replay_request` succeeds. Attestor calls are
+  expensive.
+- Never pretend a proof succeeded when `verified: false`. Show the error and
+  iterate.
+- Never write a literal value into `responseMatches.value` — that bakes the
+  original user into the provider. The synthesizer always emits `{{name}}` +
+  paramValues.
+- **Never hand-craft `responseMatches`/`responseRedactions`.** Typing a regex by
+  hand, writing `(?<name>...)` by hand, or copying the captured value into the
+  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.
+- Never rename or `%CTX%`-prefix the match-template param (see `params`).
 
-<!-- section: concerns-section -->
-## Concerns the developer should see verbatim
+<!-- section: credentials -->
+## Signing credential for the proof
 
-When `analyze_request_constraints` returns concerns, repeat each `message` to the dev exactly. Don't paraphrase, don't omit. These are the dev's signal that a provider is or isn't worth pursuing.
+`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.
 
-<!-- section: never-do-common -->
-- Never echo a raw `Authorization`, `Cookie`, or `X-*-Token` value back to the dev or write one to any file. The MCP guarantees these don't appear in tool responses — keep that guarantee.
-- Never call `run_proof` before `replay_request` succeeds. Attestor calls are expensive.
-- Never pretend a proof succeeded when `verified: false` came back. Show the error and iterate.
-- Never write a literal value into `responseMatches.value` — the synthesizer always emits `{{name}}` templates with paramValues. A literal value bakes the original user into the provider.
-- Never pass `hash` to `propose_provider` for a free-form (unicode / spaces / punctuation) target — the synthesizer will error, and the right move is either to use a tighter `target` or accept cleartext (no `hash`).
-- Never request `hash` for a target whose value also appears in the request URL — `propose_provider` throws (see step 8); the fix is dropping `hash` or capturing a request whose URL doesn't carry the value, not retrying the same call.
-
-<!-- section: first-time-issues-intro -->
-## Common first-time issues — surface these proactively
-
-If a local `attach_browser` call errors, times out, or `waitForCdpReady` reports the port isn't answering, walk through these in order before retrying:
-
-- **Browser binary not found.** If the error lists candidate paths it tried (Program Files Chrome, LOCALAPPDATA Chrome, Edge), every one missed. Either the dev has Chrome installed somewhere unusual, or doesn't have Chrome/Edge at all. Walk them through setting `RECLAIM_AGENT_CHROME_PATH` to the actual binary path:
-  ```powershell
-  setx RECLAIM_AGENT_CHROME_PATH "C:\path\to\chrome.exe"
-  ```
-  `setx` (not `$env:`) writes to the user-level Windows env, so future shells and future Claude Code launches inherit it. **Then fully restart Claude Code** — MCP servers snapshot env vars at launch, so the running reclaim-agent has the old empty value. After restart, the new MCP process picks up the env. On macOS/Linux: `export RECLAIM_AGENT_CHROME_PATH=/path/to/chrome` in the shell, then restart Claude Code from that same shell so the var propagates.
-- **Pre-existing `chrome.exe` processes hijack the new launch (Windows).** If any Chrome is already running, a new launch with `--remote-debugging-port` gets delegated to the existing process group and the debug port silently doesn't open. Tell the dev to kill all `chrome.exe` first (`taskkill /F /IM chrome.exe` in cmd/PowerShell, or via Task Manager), then retry. Affects both `attach` and `dedicated` modes when the existing instance was launched with the same profile dir.
-- **Chrome 136+ silently disables remote debugging on the default user profile.** Already noted in step 1, but worth raising again here: the only fix is a non-default `--user-data-dir`. `dedicated` mode is always safe; `attach` mode needs the dev to have launched with both flags.
-
-<!-- section: credential-intro -->
-**Credential for signing the proof.** `run_proof` requires an `ownerAddress` — the eth proof-owner key whose private half signs the claim. It does **no** resolution itself; get the address from `resolve_owner_key` first. 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.
-
-<!-- section: credential-step2 -->
-2. All fully local — no network, no server registration. The key is read live from `.env` on each `run_proof`, so no restart is needed after issuing/importing.
-
-<!-- section: mcp-config-bullet -->
-- **Multiple MCP config files exist on Windows.** `~/.claude.json` takes precedence over `~/.claude/mcp.json`. When advising config edits, point them at the right file or tell them to use `claude mcp list` / `claude mcp add --scope user` rather than editing JSON by hand.
+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({ privateKey: "0x…" })` (a `keyFile` path also works),
+     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.
+
+- **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,
+  which invalidates every draftId. Prefer the `.env` flow.
+- **Multiple MCP config files exist on Windows.** `~/.claude.json` takes
+  precedence over `~/.claude/mcp.json`. Point developers at `claude mcp list` /
+  `claude mcp add --scope user` rather than hand-editing JSON.