@reclaimprotocol/agent 0.1.22 → 0.1.24

package/skill/SKILL.common.md

@@ -1,102 +1,337 @@
-<!-- section: header -->
-# Authoring a Reclaim Provider
+<!-- 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.
 
-> **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.
+**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.
 
-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.
+**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: 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.
+<!-- section: browser -->
+## Choosing a browser
 
-   Re-call with the chosen `mode` and its required fields.
+**Ask the developer which browser they want, then call `attach_browser` ONCE
+with their chosen `mode`.** Never pick for them, and never assume last session's
+choice still applies. You don't need a discovery call — the four options are
+spelled out in the tool's own description (and summarized below). Calling with
+no `mode` returns the same list as `needsChoice: true` + `options`, if you'd
+rather relay it verbatim.
 
-<!-- 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).
+| mode | what it is | needs | live view |
+| --- | --- | --- | --- |
+| `dedicated` | Local Chrome the agent launches with its own profile (`~/.reclaim/chrome-profile`). Easiest local path. | nothing | `share_browser_view` on request |
+| `attach` | A Chrome the developer is already running. | `port` (default 9222) | `share_browser_view` on request |
+| `builder` | Quota-accounted remote Popcorn browser. Only way to browse from a **specific country**. | Builder auth, `orgId` | hosted `liveViewUrl`, returned by `attach_browser` |
+| `custom` | Any CDP websocket the developer supplies. | `cdpUrl` | `share_browser_view` on request |
 
-<!-- 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.
+**Say the live-view column out loud when you offer the choice.** How the
+developer watches the browser is part of picking one, and a local browser looks
+like it can't be shared at all unless you tell them `share_browser_view`
+exists.
 
-   **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`).
+**`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`.
 
-   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).
+**`builder` specifics:**
 
-   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.
+- 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 a local browser (`share_browser_view`)
+
+A `dedicated`, `attach`, or `custom` browser runs on the developer's machine,
+so only they can see it. `share_browser_view` puts the tab behind a public
+HTTPS URL through a cloudflared quick tunnel — use it 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.
+
+- **`builder` mode already has one.** The Popcorn browser returns a hosted
+  `liveViewUrl` from `attach_browser`; share that instead. The tool refuses
+  here rather than opening a second tunnel.
+- **The URL is a credential.** It carries an unguessable token and needs no
+  login, so whoever holds it can see the tab — and, by default, click and type
+  in it as the signed-in user. Give it to one person, and say plainly what it
+  grants.
+- **Return it verbatim, on its own line**, exactly as with `liveViewUrl`.
+- `interactive: false` streams a watch-only view. Prefer it when the developer
+  only needs to see progress.
+- **Call `stop_browser_view` as soon as they're done.** The tunnel stays open
+  until you do. `dispose_browser` and `reset_session` also close it.
+- **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.
+
+**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, 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.
+   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.
+
+<!-- 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).
 
-    **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.
+    **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.
 
-    **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.
+    **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.
 
-    **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.
+    **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.
 
-    **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.
+    **"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.
 
-<!-- section: concerns-section -->
-## Concerns the developer should see verbatim
+<!-- 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`).
 
-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.
+<!-- section: credentials -->
+## Signing credential for the proof
 
-<!-- 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.
+`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({ 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.