@reclaimprotocol/agent 0.1.17 → 0.1.20

package/skill/SKILL.builder.md

@@ -1,16 +1,4 @@
-# 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.
-
-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.
+<!-- common: header -->
 
 ## Getting authenticated
 
@@ -26,11 +14,7 @@ The 2-day token is cached in `~/.reclaim/config.json` and reused on later runs (
 
 ## The loop
 
-1. **Attach.** Call `attach_chrome`. If it returns `needsChoice: true`, ask the dev:
-   - `dedicated` — agent auto-launches Chrome with a dedicated profile under `~/.reclaim/chrome-profile`. Easiest 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`.
-
-   Re-call with the chosen `attachMode`.
+<!-- common: step-attach -->
 
 2. **Pick a tab and start a capture.** Call `list_tabs` and pick a tab (if one is already on the right origin use it; otherwise the first is usually fine). Then call `start_capture(tabId)` — it returns a **`captureId`** that is your session handle for the rest of the flow: `navigate`, `eval_in_page`, `wait_for_page`, `get_cookies`, `list_requests`, `find_requests_containing`, `propose_provider` all take it as their first argument. Capturing from the start is harmless (it just also records the login navigation). Then `navigate(captureId, url)` to the site you inferred from the dev's request (e.g. "GitHub username" → `https://github.com`). Don't ask the dev to navigate.
 
@@ -53,18 +37,9 @@ The 2-day token is cached in `~/.reclaim/config.json` and reused on later runs (
 
 5. **Trigger the request.** Capture has been live since step 2, so just make the relevant API call fire: issue a reload with `eval_in_page(captureId, "location.reload()")`. For some pages you may need to click a specific element or call a SPA route — use `eval_in_page` to do that programmatically rather than asking the dev to click.
 
-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).
-
-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`).
+<!-- common: step-identify-value -->
 
-   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.
+<!-- common: step-find-request -->
 
 8. **Decide whether to OPRF the value** (privacy from the attestor). Before calling `propose_provider`, decide if the captured value should be hashed end-to-end so the attestor never sees it in cleartext. Four options:
    - **No hash** (default). Value travels via `paramValues` + `{{name}}` template; attestor sees the cleartext substring. Simplest, fewest moving parts. Right call for non-sensitive values (public IPs from `ifconfig.me`, public usernames the dev is happy to expose, public repo names).
@@ -83,6 +58,8 @@ The 2-day token is cached in `~/.reclaim/config.json` and reused on later runs (
 
    **Hard constraint:** OPRF-hashed values are capped at **62 bytes**. If the value is longer and the dev picks any hash, surface that and propose either a tighter `target` (e.g. just the email local-part) or no hash. `propose_provider` will return a clean error if you try anyway.
 
+   **Hard constraint: OPRF and the request URL are mutually exclusive for the same value.** The entire point of `hash` is that the attestor never sees the value in cleartext — but any value templated into the request URL (`{{name}}`, `{{context.<name>}}`, or left literal) is always signed into the attestor's context in the clear, regardless of hashing. So if the target's value ALSO appears anywhere in the request URL, hashing it is not just pointless, it doesn't verify. Check this before requesting `hash` for a target: if that value shows up in the captured URL too, either drop `hash` for that target or capture a different request whose URL doesn't carry the value. `propose_provider` throws a clean error if you try anyway — same as the byte cap above.
+
 9. **Draft.** Call `propose_provider`. It returns a **`draftId`** (the handle you pass to `replay_request` and `run_proof`), the secret-free `provider`, and `secretRefs`. The recipe **and the captured secret values** are held server-side under that `draftId` — the secret values never enter the transcript, so you carry the `draftId`, not the provider JSON, into replay/prove.
 
    **Extracting MORE THAN ONE value?** Prefer a **single request whose response contains ALL of them**, and draft them together — the provider gets one `responseMatches` + `responseRedactions` entry per value. First locate that request: run `find_requests_containing` for each value and pick a `requestId` that appears for all. Then pass a `targets` array — one entry per value, each with its `value` (exactly as it appears) and a distinct `name` (its parameter):
@@ -106,16 +83,16 @@ The 2-day token is cached in `~/.reclaim/config.json` and reused on later runs (
 
    ```json
    {
-   	"responseMatches": [
-   		{ "type": "contains", "value": "\"login\":\"{{username}}\"" }
-   	],
-   	"responseRedactions": [
-   		{
-   			"xPath": "//script[@id=\"client-env\"]",
-   			"regex": "\"login\":\"(?<username>[A-Za-z0-9_-]+)\""
-   		}
-   	],
-   	"paramValues": { "username": "Scratch-net" }
+       "responseMatches": [
+           { "type": "contains", "value": "\"login\":\"{{username}}\"" }
+       ],
+       "responseRedactions": [
+           {
+               "xPath": "//script[@id=\"client-env\"]",
+               "regex": "\"login\":\"(?<username>[A-Za-z0-9_-]+)\""
+           }
+       ],
+       "paramValues": { "username": "Scratch-net" }
    }
    ```
 
@@ -123,28 +100,21 @@ The 2-day token is cached in `~/.reclaim/config.json` and reused on later runs (
 
    ```json
    {
-   	"responseMatches": [
-   		{ "type": "contains", "value": "\"login\":\"{{username}}\"" }
-   	],
-   	"responseRedactions": [
-   		{
-   			"xPath": "//script[@id=\"client-env\"]",
-   			"regex": "\"login\":\"(?<username>[A-Za-z0-9_-]+)\"",
-   			"hash": "oprf-raw"
-   		}
-   	],
-   	"paramValues": { "username": "Scratch-net" }
+       "responseMatches": [
+           { "type": "contains", "value": "\"login\":\"{{username}}\"" }
+       ],
+       "responseRedactions": [
+           {
+               "xPath": "//script[@id=\"client-env\"]",
+               "regex": "\"login\":\"(?<username>[A-Za-z0-9_-]+)\"",
+               "hash": "oprf-raw"
+           }
+       ],
+       "paramValues": { "username": "Scratch-net" }
    }
    ```
 
-   **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.
-
-   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.
+<!-- common: rewrite-shape-block -->
 
 10. **Parameterize user-specific URL segments** so the provider isn't user-specific at the URL level. The matcher already populates `paramValues` with the _captured value_ (e.g. `{username: "Scratch-net"}` for a username target). If the URL ALSO contains user-identifying segments, those are **consumer-supplied context params** — at verification time their values come from the Consumer's session `context`, not from extraction. They use a namespaced placeholder, and the namespace differs by mode:
 
@@ -153,7 +123,13 @@ replace with `{{context.<name>}}`. E.g. `https://github.com/Scratch-net/repos`
 - Generic segments (`/api/v3`, `/users`, `/repos`) stay literal.
 - If the URL has no user-identifying segments (e.g. `/settings/profile`), leave it untouched — the matcher already handled the value via paramValues.
 
-**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.
+**Marking a value secret:** name ANY param with `SECRET` anywhere in the key (case-insensitive) — a bare `{{SECRET_x}}` (e.g. a value extracted earlier in a multi-request flow) just as much as a consumer-supplied `{{context.SECRET_apiKey}}` — and it's routed to `secretParams.paramValues` (`classifyParamName`/`splitSecretParamValues`), same naming convention `reclaim-inapp-sdk`/`reclaim-portal` use for their `paramValues`. The `context.` prefix is a BUILDER-only namespace (consumer-supplied vs extracted-from-traffic); the attestor itself just looks up `{{whatever}}` in `paramValues`/`secretParams.paramValues` and doesn't care about the prefix. Headers are secret by the OPPOSITE rule — an ALLOWLIST, not a name check: any header not in 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`).
+
+A secret value CAN be used in the URL or `geoLocation` — write-redaction genuinely hides it there, but only up to a small character budget, and that budget is a TOTAL summed across every secret value used in that URL, not a per-value allowance (`secretUrlCharBudget`): 2 characters under `key-update` (the default), 12 under `zk`. Over budget, the value is effectively still visible to the attestor no matter how it's marked. Since the actual value doesn't exist until a verification session supplies one, this can only be checked once that value is known — at verification time, not at publish time (`assertSecretParamValuesFitUrlBudget` in `verify/run.ts`); a captured secret HEADER whose value happens to also sit in the URL gets the same budget check at DRAFT time instead, since its value is already known then (`assertNoSecretUrlConflict`). Using longer than limit secrets in url actually causes the claim creation from attestor to fail.
+
+The value of any parameter marked secret is not included in the final proof, omitted from it. 
+
+<!-- common: no-rename-param -->
 
 **How the verification client resolves these at runtime**:
 
@@ -180,20 +156,7 @@ replace with `{{context.<name>}}`. E.g. `https://github.com/Scratch-net/repos`
 
     **Missing signing credential (`errorKind: "missing-owner-key"`)** — the dev hasn't set up an eth proof-owner key yet. Tell them what's happening, then drive the bootstrap yourself: call `resolve_owner_key`; if it returns no key, ask once _"shall I mint a fresh eth key via `issue_credentials` (or `import_credentials` if you already hold one)? It's written to the project `.env` (mode 0600, gitignored) for this and future sessions."_; on yes, call `issue_credentials` (or `import_credentials`) and retry the same `run_proof` call. **No restart needed** — the key is read live from `.env` on each `run_proof`, and the existing `draftId` from `propose_provider` is still valid.
 
-    **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)
-
-    **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 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 right now; backup hostnames (`attestor-2.*`, etc.) **do not exist**. `attestorUrl` is only for when the dev explicitly supplies a 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.
+<!-- common: prove-tail -->
 
 13. **Publish the proved provider.** `provider` is the exact JSON from step 9 with the step-10 URL parameterisation applied, and `initialUrl` is the page where the user logs in / the value is displayed (e.g. `https://github.com/Syed`) — **not** the API endpoint URL inside the provider.
 
@@ -210,33 +173,18 @@ replace with `{{context.<name>}}`. E.g. `https://github.com/Scratch-net/repos`
 
     When done, tell the developer the version is live (PRIVATE) or submitted for review (PUBLIC), and that they can integrate using the `providerId`.
 
-## Concerns the developer should see verbatim
-
-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.
+<!-- common: concerns-section -->
 
 ## Things to never do
 
-- 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.
+<!-- common: never-do-common -->
 - **Never hand-craft `responseMatches` or `responseRedactions`.** If you find yourself typing a regex by hand, OR writing `(?<name>...)`-style patterns by hand, OR copying the captured value literally into the match — stop. The synthesizer in `propose_provider` already produces the canonical shape: `contains` template + paramValues for the match, xPath/jsonPath for the redaction — plus a value-isolating named-capture `regex` (for every xPath/jsonPath anchor — the reveal is a byte range, never the bare value). The named-capture regex in the redaction is the synthesizer's job, not yours.
-- 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 accept "the synthesizer's xPath looks too narrow, let me write a regex" — the synthesizer already pairs the xPath with a structure-anchored named-capture regex (for HTML) that both reveals the element and isolates the value. If extraction still looks wrong, re-run `propose_provider` with a better request/target — don't hand-write patterns.
+- Mark ANY param secret (not just consumer-supplied `context.*` ones) by naming it with `SECRET` (e.g. `{{SECRET_x}}` or `{{context.SECRET_apiKey}}`). It CAN be used in the URL, geoLocation, request body, response match, response redactions — write-redaction hides it there. Any value of a parameter marked secret is not included in the proof. There's also a limitation for secret marked variables secrets in url: only up to a small TOTAL character budget across every secret value in a URL (2 chars under `key-update`, the default; 12 under `zk`). That's checked at verification time against the consumer's real value, not at publish time (see step 10). Headers are secret by allowlist, not by name — anything not on a small fixed public list is secret by default.
 
-## Common first-time issues — surface these proactively
-
-If `attach_chrome` 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.
+<!-- common: first-time-issues-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.
+<!-- common: credential-intro -->
 
 1. **Call `resolve_owner_key`.** It checks `RECLAIM_PRIVATE_KEY` (MCP env) → the project `.env` → `RECLAIM_PRIVATE_KEY_FILE`, and returns only the derived address.
    - `{ ready: true, address }` → call `run_proof(captureId, draftId, address)`. No prompts.
@@ -245,9 +193,9 @@ If `attach_chrome` errors, times out, or `waitForCdpReady` reports the port isn'
      - **Create a new one** → `issue_credentials({})`. (Fine default for test proofs — owner identity doesn't matter.)
      - Either way the key is written to the project `.env` (mode 0600; `.env` is added to `.gitignore`) — never to `~/.reclaim`.
    - Then call `resolve_owner_key` again and `run_proof` with the returned address.
-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.
+<!-- common: credential-step2 -->
 - **Advanced:** setting `RECLAIM_PRIVATE_KEY` directly in the MCP server's env also works, but env vars are snapshotted at Claude Code startup, so that route needs a full restart (which invalidates every `draftId`). The `.env` flow above avoids that — prefer it.
-- **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.
+<!-- common: mcp-config-bullet -->
 
 If `replay_request` or `run_proof` errors with `unknown draftId` (or `no capture`):
 

package/skill/SKILL.common.md

@@ -0,0 +1,102 @@
+<!-- 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.
+
+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. Obtain an `orgId` with `list_builder_organizations` in old-devtools mode or the generated `list_orgs` tool in Builder mode. If Builder answers 401, authenticate with `authenticate_builder` in old-devtools mode or the existing `authenticate` flow in Builder mode, then retry. Return the `liveViewUrl` to the dev so they can 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 and shared.
+
+   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: 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.
+
+   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: 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.
+
+<!-- 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)
+
+    **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 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 right now; backup hostnames (`attestor-2.*`, etc.) **do not exist**. `attestorUrl` is only for when the dev explicitly supplies a 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.
+
+<!-- section: concerns-section -->
+## Concerns the developer should see verbatim
+
+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: 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.

package/skill/SKILL.old.md

@@ -1,16 +1,4 @@
-# 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.
-
-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.
+<!-- common: header -->
 
 ## Getting authenticated
 
@@ -22,11 +10,7 @@ Call `reclaim_authenticate({})` with no arguments. It opens the Reclaim dashboar
 
 ## The loop
 
-1. **Attach.** Call `attach_chrome`. If it returns `needsChoice: true`, ask the dev:
-   - `dedicated` — agent auto-launches Chrome with a dedicated profile under `~/.reclaim/chrome-profile`. Easiest 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`.
-
-   Re-call with the chosen `attachMode`.
+<!-- common: step-attach -->
 
 2. **Pick a tab and open the site yourself.** Call `list_tabs`. If there's already a tab on the right origin, use it. Otherwise pick any tab (the first one is usually fine) and call `navigate(tabId, url)` to send it to the site you've inferred from the dev's request (e.g. "GitHub username" → `https://github.com`). Don't ask the dev to navigate.
 
@@ -49,18 +33,9 @@ Call `reclaim_authenticate({})` with no arguments. It opens the Reclaim dashboar
 
 5. **Start capture, then trigger the request.** Call `start_capture(tabId)` first. Then issue a reload so the relevant API call fires while capture is live: `eval_in_page(tabId, "location.reload()")`. For some pages you may need to click a specific element or call a SPA route — use `eval_in_page` to do that programmatically rather than asking the dev to click.
 
-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).
-
-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`).
+<!-- common: step-identify-value -->
 
-   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.
+<!-- common: step-find-request -->
 
 8. **Decide whether to OPRF the value** (privacy from the attestor). Before calling `propose_provider`, decide if the captured value should be hashed end-to-end so the attestor never sees it in cleartext. Four options:
    - **No hash** (default). Value travels via `paramValues` + `{{name}}` template; attestor sees the cleartext substring. Simplest, fewest moving parts. Right call for non-sensitive values (public IPs from `ifconfig.me`, public usernames the dev is happy to expose, public repo names).
@@ -79,6 +54,8 @@ Call `reclaim_authenticate({})` with no arguments. It opens the Reclaim dashboar
 
    **Hard constraint:** OPRF-hashed values are capped at **62 bytes**. If the value is longer and the dev picks any hash, surface that and propose either a tighter `target` (e.g. just the email local-part) or no hash. `propose_provider` will return a clean error if you try anyway.
 
+   **Hard constraint: OPRF and the request URL are mutually exclusive for the same value.** The entire point of `hash` is that the attestor never sees the value in cleartext — but any value templated into the request URL (`{{name}}`, `{{context_<name>}}`, or left literal) is always signed into the attestor's context in the clear, regardless of hashing. So if the target's value ALSO appears anywhere in the request URL, hashing it is not just pointless, it doesn't verify. Check this before requesting `hash` for a target: if that value shows up in the captured URL too, either drop `hash` for that target or capture a different request whose URL doesn't carry the value. `propose_provider` throws a clean error if you try anyway — same as the byte cap above.
+
 9. **Draft.** Call `propose_provider(captureId, requestId, target, name, hash?)`. Pass `hash` only if the dev opted in. Inspect the returned provider:
    - Is the right header marked secret? (cookies, Authorization, X-\* tokens)
    - Is `responseMatches[0].value` a `contains` with a `{{name}}` template (matching the captured value's structural context)?
@@ -115,14 +92,7 @@ Call `reclaim_authenticate({})` with no arguments. It opens the Reclaim dashboar
    }
    ```
 
-   **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.
-
-   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.
+<!-- common: rewrite-shape-block -->
 
 10. **Parameterize user-specific URL segments** so the provider isn't user-specific at the URL level. The matcher already populates `paramValues` with the _captured value_ (e.g. `{username: "Scratch-net"}` for a username target). If the URL ALSO contains user-identifying segments, those are **consumer-supplied context params** — at verification time their values come from the Consumer's session `context`, not from extraction. They use a namespaced placeholder, and the namespace differs by mode:
 
@@ -131,7 +101,11 @@ Call `reclaim_authenticate({})` with no arguments. It opens the Reclaim dashboar
 - Generic segments (`/api/v3`, `/users`, `/repos`) stay literal.
 - If the URL has no user-identifying segments (e.g. `/settings/profile`), leave it untouched — the matcher already handled the value via paramValues.
 
-**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.
+**Marking a value secret:** name ANY param with `SECRET` anywhere in the key (case-insensitive) — a bare `{{SECRET_x}}` (e.g. a value extracted earlier in a multi-request flow) just as much as a consumer-supplied `{{context_SECRET_apiKey}}` — and it's routed to `secretParams.paramValues` (`classifyParamName`/`splitSecretParamValues`), same naming convention `reclaim-inapp-sdk`/`reclaim-portal` use for their `paramValues`. The `context_` prefix is a namespace convention (consumer-supplied vs extracted-from-traffic); the attestor itself just looks up `{{whatever}}` in `paramValues`/`secretParams.paramValues` and doesn't care about the prefix. Headers are secret by the OPPOSITE rule — an ALLOWLIST, not a name check: any header not in 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`).
+
+A secret value CAN be used in the URL, geoLocation, request body, response match, or response redactions — write-redaction hides it there. The value of any parameter marked secret is omitted from the final proof entirely. There's still a limitation specific to the URL: only up to a small TOTAL character budget summed across every secret value used in that URL (`secretUrlCharBudget`), not a per-value allowance — 2 characters under `key-update` (the default), 12 under `zk`. Using a longer-than-budget secret in the URL causes the attestor's claim creation to fail outright.
+
+<!-- common: no-rename-param -->
 
 `propose_provider` returns `verificationWarnings` for the calls only an author can make (currently: a captured value baked literally into the URL, needing the `{{context_<name>}}`-vs-bare-vs-re-capture decision). They are advisory, never blocking — **surface each warning to the dev verbatim** and resolve it before publishing.
 
@@ -150,20 +124,7 @@ Call `reclaim_authenticate({})` with no arguments. It opens the Reclaim dashboar
 
     **Missing signing credential (`errorKind: "missing-owner-key"`)** — the dev hasn't set up an eth proof-owner key yet. Tell them what's happening, then drive the bootstrap yourself: call `resolve_owner_key`; if it returns no key, ask once _"shall I mint a fresh eth key via `issue_credentials` (or `import_credentials` if you already hold one)? It's written to the project `.env` (mode 0600, gitignored) for this and future sessions."_; on yes, call `issue_credentials` (or `import_credentials`) and retry the same `run_proof` call. **No restart needed** — the key is read live from `.env` on each `run_proof`, and the existing `secretParamsRef` from `propose_provider` is still valid.
 
-    **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)
-
-    **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 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 right now; backup hostnames (`attestor-2.*`, etc.) **do not exist**. `attestorUrl` is only for when the dev explicitly supplies a 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.
+<!-- common: prove-tail -->
 
 13. **Publish the proved provider.** `provider` is the exact JSON from step 9 with the step-10 URL parameterisation applied, and `initialUrl` is the page where the user logs in / the value is displayed (e.g. `https://github.com/Syed`) — **not** the API endpoint URL inside the provider.
 
@@ -180,33 +141,18 @@ Call `reclaim_authenticate({})` with no arguments. It opens the Reclaim dashboar
 
     When done, tell the developer the version is live (PRIVATE) or submitted for review (PUBLIC), and that they can integrate using the `providerId`.
 
-## Concerns the developer should see verbatim
-
-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.
+<!-- common: concerns-section -->
 
 ## Things to never do
 
-- 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.
+<!-- common: never-do-common -->
 - **Never hand-craft `responseMatches` or `responseRedactions`.** If you find yourself typing a regex by hand, OR writing `(?<name>...)`-style patterns by hand, OR copying the captured value literally into the match — stop. The synthesizer in `propose_provider` already produces the canonical shape: `contains` template + paramValues for the match, xPath/jsonPath (optionally + regex+hash when `hash` is passed) for the redaction. The named-capture regex in the redaction is the synthesizer's job, not yours.
-- 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 accept "the synthesizer's xPath looks too narrow, let me write a regex" — the xPath is fine, the attestor will reveal the whole matched element which is naturally ≥16 bytes.
+- Mark ANY param secret (not just consumer-supplied `context_*` ones) by naming it with `SECRET` (e.g. `{{SECRET_x}}` or `{{context_SECRET_apiKey}}`). It CAN be used in the URL, geoLocation, request body, response match, response redactions — write-redaction hides it there. Any value of a parameter marked secret is not included in the proof. There's also a limitation for secret-marked values used in a URL: only up to a small TOTAL character budget across every secret value in that URL (2 chars under `key-update`, the default; 12 under `zk`). That's checked at verification time against the real value, not at publish time (see step 10). Headers are secret by allowlist, not by name — anything not on a small fixed public list is secret by default.
 
-## Common first-time issues — surface these proactively
-
-If `attach_chrome` 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.
+<!-- common: first-time-issues-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.
+<!-- common: credential-intro -->
 
 1. **Call `resolve_owner_key`.** It checks `RECLAIM_PRIVATE_KEY` (MCP env) → the project `.env` → `RECLAIM_PRIVATE_KEY_FILE`, and returns only the derived address.
    - `{ ready: true, address }` → call `run_proof({ provider, ownerAddress: address, … })`. No prompts.
@@ -215,9 +161,9 @@ If `attach_chrome` errors, times out, or `waitForCdpReady` reports the port isn'
      - **Create a new one** → `issue_credentials({})`. (Fine default for test proofs — owner identity doesn't matter.)
      - Either way the key is written to the project `.env` (mode 0600; `.env` is added to `.gitignore`) — never to `~/.reclaim`.
    - Then call `resolve_owner_key` again and `run_proof` with the returned address.
-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.
+<!-- common: credential-step2 -->
 - **Advanced:** setting `RECLAIM_PRIVATE_KEY` directly in the MCP server's env also works, but env vars are snapshotted at Claude Code startup, so that route needs a full restart (which invalidates every `secretParamsRef`). The `.env` flow above avoids that — prefer it.
-- **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.
+<!-- common: mcp-config-bullet -->
 
 If `replay_request` or `run_proof` errors with `unknown secretParamsRef`:
 

package/skill/builder-mode.md

@@ -2,14 +2,16 @@ This server targets the Reclaim BUILDER backend. It exposes three tool layers: g
 
 **Authentication:** try `get_me` first. On 401, `authenticate({})` opens a device-pairing session — give the user the `attachUrl`, then poll `authenticate({ code })` until LINKED. Tokens are cached ~2 days.
 
-**Provider-authoring flow:** `attach_chrome` → `start_capture(tabId)` ⇒ a **`captureId`** (the session handle every browser/inspect tool takes as its first arg) → drive the page (`navigate`, `wait_for_page`, `eval_in_page`, `get_cookies`) → inspect (`list_requests`, `get_request`, `find_requests_containing`) → `propose_provider` ⇒ a **`draftId`** (the recipe + captured secrets held server-side; secrets never enter the transcript) → `replay_request(captureId, draftId)` → `run_proof(captureId, draftId, ownerAddress)` → resolve a `providerId` (**Reuse before create**, below) → `create_provider_version_from_capture` (lands on the draft branch) → `publish_provider_version` (PRIVATE) or `submit_provider_version_for_review` (PUBLIC).
+**Provider-authoring flow:** `attach_browser` (local, Builder remote, or custom CDP) → `start_capture(tabId)` ⇒ a **`captureId`** (the session handle every browser/inspect tool takes as its first arg) → drive the page (`navigate`, `wait_for_page`, `eval_in_page`, `get_cookies`) → inspect (`list_requests`, `get_request`, `find_requests_containing`) → `propose_provider` ⇒ a **`draftId`** (the recipe + captured secrets held server-side; secrets never enter the transcript) → `replay_request(captureId, draftId)` → `run_proof(captureId, draftId, ownerAddress)` → resolve a `providerId` (**Reuse before create**, below) → `create_provider_version_from_capture` (lands on the draft branch) → `publish_provider_version` (PRIVATE) or `submit_provider_version_for_review` (PUBLIC).
 
 **Reuse before create (avoid duplicates):** `create_provider_version_from_capture` requires a `providerId`. Before minting a new one with `create_provider`, search your existing providers with `providers` (by domain / data point) — a site you've already built will be there. If one matches, pass its `providerId` so the capture lands as a NEW VERSION on that provider. Only `create_provider` (then use its returned id) when none exists. Re-running the flow against `create_provider` each time is what stacks duplicate providers in "My providers".
 
 **Multiple requests & login-gated data:** one version can carry many requests — `propose_provider` + `run_proof` each target request individually, then publish them together via `create_provider_version_from_capture({ providers: [draftA, draftB, …] })` (every entry is required at verification; the single-`provider` form still works for the one-request case). For data gated behind login/navigation, supply `jsUserScripts` — plain page JavaScript if needed that drives login/waits for user to login/waits for user to do multifactor auth/navigation with standard browser APIs (`window.location`, clicking elements, submitting forms) so the target request fires (page requests are intercepted automatically; `window.Reclaim` is only for rare edge cases) — and/or `allowedJsRequests` (extra requests the script may fire, e.g. pagination). NOTE: the builder verification client installs `jsUserScripts` to run before every page load (before navigating to `initialUrl`), matching the old-devtool `customInjection`; `window.Reclaim` itself is not yet exposed there, so prefer plain browser JS.
 
-**Templating:** bare `{{name}}` placeholders are provider params (values extracted from the response by the attestor). Values the CONSUMER must supply at verification time (e.g. a username in the URL path) are templated `{{context.<name>}}` and declared on the version as `requiredContext` — a JSON Schema set via `update_provider_version` while the version is on draft. The Builder validates every session-create's `context` against it (400 on mismatch; extra context fields are always allowed). `requiredContext` is optional — skip it when the recipe has no `{{context.*}}` placeholders. At verification time, requests are matched by exact origin+path: `{{context.<name>}}` segments match the consumer-sent value only, bare `{{name}}` values are extracted from the live traffic (plain-text alignment — works for JSON, XML, HTML, form-encoded, any text). Extract selectors apply client-side in spec order xPath → jsonPath → regex, each to the prior selection, so only the first selector constrains the full response; responses that cannot satisfy it (or miss a required match) are skipped. `propose_provider` returns advisory `verificationWarnings` for author-only decisions — surface them to the dev before publishing.
+**Templating:** bare `{{name}}` placeholders are provider params (values extracted from the response by the attestor). Values the CONSUMER must supply at verification time (e.g. a username in the URL path) are templated `{{context.<name>}}` and declared on the version as `requiredContext` — a JSON Schema set via `update_provider_version` while the version is on draft. The Builder validates every session-create's `context` against it (400 on mismatch; extra context fields are always allowed). `requiredContext` is optional — skip it when the recipe has no `{{context.*}}` placeholders. At verification time, requests are matched by exact origin+path: `{{context.<name>}}` segments match the consumer-sent value only, bare `{{name}}` values are extracted from the live traffic (plain-text alignment — works for JSON, XML, HTML, form-encoded, any text). Extract selectors apply client-side in spec order xPath → jsonPath → regex, each to the prior selection, so only the first selector constrains the full response; responses that cannot satisfy it (or miss a required match) are skipped. `propose_provider` returns advisory `verificationWarnings` for author-only decisions — surface them to the dev before publishing. **Two hard limitations:** (1) never `hash`/OPRF a target whose value also appears in the request URL — URL param values are always signed into context in the clear, so `propose_provider` throws rather than shipping a draft that can't verify; (2) ANY param — bare `{{SECRET_x}}` or consumer-supplied `{{context.SECRET_apiKey}}` alike — named with `SECRET` routes to `secretParams.paramValues` and CAN be used in the URL/geoLocation, but only up to a small TOTAL character budget summed across every secret value in that URL — 2 chars under `key-update` (default), 12 under `zk` — checked at verification time against the real value, since it doesn't exist yet at publish time. See `how_it_works` for the full reasoning.
 
 **Discover & resolve (find providers for the user's app):** when a dev wants to add verification but doesn't know which providers to use, run the same flow the Discover UI does. Ask which website their users prove data from, then `discover_data_points({ domain })` to list what's verifiable there. Confirm the data points with the dev, then `discover_resolve({ domain, dataPoints })` → the smallest provider set (`providers`, greedy combine), the `requiredContext` inputs to collect from the dev, and any `uncovered` points (author those with the provider-authoring flow above, then re-resolve). Create the session with `create_verification_session({ providers: [{ providerId }, …], context, verificationClientUrl })`, passing EVERY resolved provider id and the collected context. `merge.mergeable` only signals the set could collapse into one provider — you still pass them all; the Builder runs them in one session.
 
 **Verification sessions:** consumers authenticate with a per-org token (`rorg_…`, issued in the dashboard via `POST /orgs/{orgId}/token`) and create sessions via `POST /verifications/sessions`. Results are ECIES-encrypted (secp256k1 + AES-256-GCM) to the org's eth public key when its `canEncryptResult` is enabled — set via `PUT /orgs/{orgId}/keypair` with an eth public key — and delivered to the org's callback subscriptions (plaintext otherwise). Use the org/session tools (`get_verification_session`, `list_verification_events`, `list_org_verification_sessions`) to troubleshoot.
+
+**Backend mode:** this server can alternatively run against the devtools backend with a reduced tool set (no generated API tools, no orgs/review flows). `get_devtools_mode` reports the active mode and why it's in effect; `set_devtools_mode` persists a switch to `~/.reclaim/config.json` — it takes effect on the NEXT server start (restart/reconnect), and an explicit `USE_OLD_DEVTOOLS` env var overrides the persisted choice.