@reclaimprotocol/agent 0.1.22 → 0.1.24

package/skill/SKILL.builder.md

@@ -1,211 +1,378 @@
-<!-- common: header -->
-
+<!-- topic: overview -->
+# Authoring a Reclaim provider (Builder backend)
+
+<!-- common: terminology -->
+
+## The loop, at a glance
+
+Copy this checklist and check off each step as you finish it. Read the linked
+topic before a step you aren't already fluent in.
+
+- [ ] 1. `attach_browser` — pick a browser source with the developer.
+      → topic `browser`
+- [ ] 2. `list_tabs` → `start_capture(tabId)` ⇒ **`captureId`**, your handle for
+      everything below. → topic `capture`
+- [ ] 3. Drive the page: `navigate`, `wait_for_page`, `eval_in_page`,
+      `get_cookies`. Detect login, land on the page showing the value, trigger
+      the request. → topic `capture`
+- [ ] 4. `find_requests_containing` → `analyze_request_constraints` → pick an
+      **authenticated** request. → topic `capture`
+- [ ] 5. `propose_provider(captureId, requestId, …)` ⇒ **`draftId`** (recipe +
+      captured secrets, held server-side — secrets never enter the transcript).
+      → topic `draft`
+- [ ] 6. Parameterize user-specific URL segments; mark secrets. → topic `params`
+- [ ] 7. `replay_request(captureId, draftId)`, then again with
+      `withoutSecrets: true`. → topic `prove`
+- [ ] 8. `run_proof(captureId, draftId, ownerAddress)`.
+      → topics `prove`, `credentials`
+- [ ] 9. Resolve a `providerId` (**reuse before create**) →
+      `create_provider_version_from_capture` → `publish_provider_version` or
+      `submit_provider_version_for_review`. → topic `publish`
+
+Multi-request provider? Run steps 5–8 once per request, then publish every
+proven draft in one call. See topic `publish`.
+
+<!-- topic: auth -->
 ## Getting authenticated
 
-**Check first:** try `get_me`. If it returns the user's profile, you're authenticated — proceed to the loop.
-
-**On 401:** call `authenticate({})` to start a device-pairing session:
-
-1. It returns immediately with a `code` and `attachUrl` — it does NOT poll.
-2. Tell the user: _"Open `<attachUrl>`, sign in, and click 'Authorize this device'."_
-3. After they confirm, call `authenticate({ code: "<code>" })`: `LINKED` → proceed; `PENDING` → wait and call again; `EXPIRED` → start a new session.
-
-The 2-day token is cached in `~/.reclaim/config.json` and reused on later runs (`RECLAIM_API_TOKEN` in the server env overrides it).
-
-## The loop
-
-<!-- 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.
-
-3. **Check login state, wait if needed.** Use `eval_in_page(captureId, ...)` to evaluate a site-specific check.
-
-   **Combine a positive signal (logged-in-only element present) with a negative signal (login button absent), AND them together.** Single signals are too prone to false positives — most notably, `<meta>` tags often exist on every page regardless of login state; only their `.content` attribute is populated. The check `!!document.querySelector('meta[name="user-login"]')` returns true even when logged out — DO NOT use existence-only checks on meta tags or other persistent-but-empty elements.
-
-   Examples (always verify against the live page if these break — sites change selectors):
-   - 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 shape: `<element-present-only-when-logged-in> && !<login-button-present-only-when-logged-out>`
-
-   If the result is truthy, skip to step 4.
-
-   If falsy: **navigate to the site's login URL yourself first**, so the dev lands directly on the login form instead of having to find it. Common patterns: `https://<host>/login`, `https://<host>/signin`, `https://<host>/i/flow/login` (Twitter/X). Pick the one you know works for the site. Call `navigate(captureId, "<login-url>")`. Then tell the dev once: "I've opened the login page on `<site>` — please log in (with 2FA if needed). I'll detect when you're done." Then call `wait_for_page(captureId, expression="<same composite expression>", timeoutMs=180000)`. The MCP polls every second and returns when the expression goes truthy. **Do not** instruct the dev to "tell me when you're done" — just wait via the tool.
-
-   **Self-check before trusting the result:** if your detector says "already logged in" on a freshly-launched Chrome profile (cookies-clean), the detector is wrong. Brand-new profile means brand-new cookie jar — there's no way to be already authenticated. If you see that contradiction, your check is matching something that's present regardless of login (a meta tag, a generic class). Rewrite the expression and re-evaluate.
-
-4. **Navigate to the page that displays the value.** Use what you know about the site to construct the URL. If you need the dev's username, eval it (e.g. on GitHub: `document.querySelector('meta[name="user-login"]')?.content`). Then `navigate(captureId, url)`. Don't ask the dev to navigate.
-
-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.
-
-<!-- common: step-identify-value -->
-
-<!-- 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).
-   - **`oprf-raw`**. Server-side OPRF. **The only variant that runs on Windows / without external deps.** Use this when the dev wants any privacy and you're in a normal dev loop. Privacy is the weakest of the three (attestor still participates in hashing) — surface that honestly.
-   - **`oprf`**. Client-side ZK OPRF via gnark. Strongest privacy. Requires gnark install (Linux/macOS in practice). Don't suggest this on Windows.
-   - **`oprf-mpc`**. TEE-based MPC OPRF. Requires a TEE attestor deployment. Niche; only suggest if the dev brings it up.
-
-   **Default skip-the-question heuristic.** If the value is obviously non-sensitive (public IP, public username, public repo name, public follower/star counts on sites where the captured endpoint is auth-bound), default to **no hash** and proceed without asking. If the value is or could be sensitive (email, real name, private ID, anything the dev wouldn't post publicly), surface the choice verbatim:
-
-   > "Do you want this value kept private from the attestor via OPRF?
-   >
-   > - **No** (default) — value visible to attestor
-   > - **`oprf-raw`** — works on Windows / without extra deps; weakest of the OPRF variants
-   > - **`oprf`** — gnark/ZK; strongest privacy but requires Linux/macOS + gnark install
-   > - **`oprf-mpc`** — TEE-based; requires a TEE attestor"
-
-   **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):
-
-   ```
-   propose_provider(captureId, requestId, name, targets: [
-     { value: "Scratch-net", name: "username" },
-     { value: "Alex",        name: "name" },
-   ])
-   ```
-
-   For a single value, the shorthand `propose_provider(captureId, requestId, target, name, hash?)` still works (one target). Pass `hash` only if the dev opted in (per-target `hash` also works inside `targets`). 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)?
-   - Is `paramValues[name]` set to the original captured value?
-   - Does each `responseRedactions` entry carry an `xPath` or `jsonPath` anchor **plus** a named-capture `regex` that isolates just the value? The synthesizer adds the regex for BOTH cases — an HTML element reveal is the element markup and a jsonPath reveal is the surrounding `"key":"value"`, so neither is the bare value without the regex. (And if `hash` was requested, the regex also carries a `hash: oprf-…` field.)
+**Check first:** call `get_me`. A profile back means you're authenticated —
+proceed.
+
+**On 401:** `authenticate({})` starts a device-pairing session. It returns
+immediately with a `code` and `attachUrl` — it does NOT poll.
+
+1. Tell the user: _"Open `<attachUrl>`, sign in, and click 'Authorize this
+   device'."_
+2. After they confirm, call `authenticate({ code: "<code>" })` —
+   `LINKED` → proceed; `PENDING` → wait and call again; `EXPIRED` → start over.
+
+The 2-day token is cached in `~/.reclaim/config.json` and reused on later runs
+(`RECLAIM_API_TOKEN` in the server env overrides it).
+
+<!-- topic: browser -->
+<!-- common: browser -->
+
+<!-- topic: capture -->
+## Capture
+
+1. **Attach** — topic `browser`.
+
+2. **Pick a tab and start the capture.** `list_tabs`, then
+   `start_capture(tabId)` ⇒ a **`captureId`**: the session handle every browser
+   and inspect tool takes as its first argument (`navigate`, `eval_in_page`,
+   `wait_for_page`, `get_cookies`, `list_requests`, `find_requests_containing`,
+   `propose_provider`). If a tab is already on the right origin use it,
+   otherwise the first is usually fine. Capturing from the start is harmless —
+   it also records the login navigation. Then `navigate(captureId, url)` to
+   the site you inferred from the developer's request ("GitHub username" →
+   `https://github.com`). Don't ask the developer to navigate.
+
+3. <!-- common: login-detect -->
+
+4. **Navigate to the page that displays the value.** Construct the URL from what
+   you know about the site; eval for anything you need (for example, GitHub's
+   `meta[name="user-login"]`'s `content`), then `navigate(captureId, url)`.
+
+5. **Trigger the request.** Capture has been live since step 2, so make the
+   call fire: `eval_in_page(captureId, "location.reload()")`, or click an
+   element / hit a SPA route programmatically. Don't ask the developer to click.
+
+6. <!-- common: identify-value -->
+
+7. <!-- common: find-request -->
+
+<!-- topic: draft -->
+## Draft the provider
+
+<!-- common: oprf -->
+
+**Call `propose_provider`.** It returns a **`draftId`** — the handle for
+`replay_request` and `run_proof` — plus the secret-free `provider` and
+`secretRefs`. The recipe **and the captured secret values** live server-side
+under that `draftId`; the secrets 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 — one `responseMatches` +
+`responseRedactions` pair per value. Find that request by running
+`find_requests_containing` for each value and picking a `requestId` common to
+all. Then pass a `targets` array, each entry with its `value` (exactly as it
+appears) and a distinct `name`:
+
+```
+propose_provider(captureId, requestId, name, targets: [
+  { value: "Scratch-net", name: "username" },
+  { value: "Alex",        name: "name" },
+])
+```
+
+The shorthand `propose_provider(captureId, requestId, target, name, hash?)`
+still works for one target. Per-target `hash` works inside `targets` too.
+
+**Inspect what comes back:**
+
+- 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?
+- Is `paramValues[name]` the original captured value?
+- Does each `responseRedactions` entry carry an `xPath`/`jsonPath` anchor
+  **plus** a named-capture `regex` isolating the value? The synthesizer adds the
+  regex in both cases — an HTML reveal is the element markup and a jsonPath
+  reveal is the surrounding `"key":"value"`, so neither is the bare value
+  without it. (With `hash`, the regex also carries `hash: oprf-…`.)
+
+**Provenance — match the structure, never the bare value.** The `contains`
+template and the redaction regex are always anchored on the value's surrounding
+context — the JSON key (`"login":"{{username}}"`) or the enclosing element
+(`<div class="handle">{{username}}</div>`) — never `{{username}}` alone. That
+ties the proof to *where the value legitimately appears*; a bare-value match
+would let a user surface the same string from any field they control. The
+synthesizer does this for you.
+
+**Canonical drafted shape** (no hash):
+
+```json
+{
+    "responseMatches": [
+        { "type": "contains", "value": "\"login\":\"{{username}}\"" }
+    ],
+    "responseRedactions": [
+        {
+            "xPath": "//script[@id=\"client-env\"]",
+            "regex": "\"login\":\"(?<username>[A-Za-z0-9_-]+)\""
+        }
+    ],
+    "paramValues": { "username": "Scratch-net" }
+}
+```
+
+With `hash: 'oprf-raw'`, the redaction gains `"hash": "oprf-raw"`. Nothing else
+changes.
 
-   **Provenance — match the structure, never the bare value.** The `contains` template and the redaction `regex` are always anchored on the value's surrounding context — the JSON key (`"login":"{{username}}"`) or the enclosing element (`<div class="handle">{{username}}</div>`), never just `{{username}}` or `>{{username}}<`. This ties the proof to *where the value legitimately appears*; a bare-value match would let a user surface the same string from any field they control. The synthesizer does this for you.
-
-   **Canonical drafted shape** (no hash):
-
-   ```json
-   {
-       "responseMatches": [
-           { "type": "contains", "value": "\"login\":\"{{username}}\"" }
-       ],
-       "responseRedactions": [
-           {
-               "xPath": "//script[@id=\"client-env\"]",
-               "regex": "\"login\":\"(?<username>[A-Za-z0-9_-]+)\""
-           }
-       ],
-       "paramValues": { "username": "Scratch-net" }
-   }
-   ```
+<!-- common: rewrite-shape-block -->
 
-   **Canonical drafted shape** (with `hash: 'oprf-raw'`):
+<!-- topic: params -->
+## Parameters: extracted, consumer-supplied, and secret
 
-   ```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" }
-   }
-   ```
+**Parameterize user-specific URL segments** so the provider isn't pinned to one
+user. The matcher already puts the *captured* value in `paramValues`. If the URL
+*also* carries user-identifying segments, those are **consumer-supplied context
+params**: at verification time their values come from the consumer's session
+`context`, not from extraction.
 
-<!-- common: rewrite-shape-block -->
+Replace them with `{{context.<name>}}`, for example
+`https://github.com/Scratch-net/repos` →
+`https://github.com/{{context.username}}/repos`, with `paramValues: { …,
+"context.username": "Scratch-net" }` for replay/proof (the key must match the
+placeholder exactly, dot included).
 
-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:
-
-replace with `{{context.<name>}}`. E.g. `https://github.com/Scratch-net/repos` → `https://github.com/{{context.username}}/repos`, with `paramValues: { ..., "context.username": "Scratch-net" }` for replay/proof (the paramValues key must match the placeholder name exactly, dot included). Declare these in the version's `requiredContext` at publish time (step 13).
-- Query parameters with user-specific values → same treatment.
+- Query params with user-specific values → same treatment.
 - 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.
+- No user-identifying segments (for example, `/settings/profile`) → leave it
+  alone.
 
-**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`).
+Declare them in the version's `requiredContext` at publish time (topic
+`publish`).
 
-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.
+<!-- common: secrets -->
 
-The value of any parameter marked secret is not included in the final proof, omitted from it. 
+The `context.` prefix is a **Builder-only namespace** (consumer-supplied vs
+extracted-from-traffic). The attestor itself only looks up `{{whatever}}` in
+`paramValues`/`secretParams.paramValues` and doesn't care about the prefix.
 
 <!-- common: no-rename-param -->
 
-**How the verification client resolves these at runtime**:
-
-- Requests are matched by **exact origin+path** (query ignored). A `{{context.<name>}}` segment matches **only the value the consumer sent** in the session context (validated by `requiredContext`); a bare `{{name}}` segment matches any one path segment and its value is **auto-extracted from the live traffic**.
-- Interpolation and `contains` matching are **plain text** — they work for any captured content (JSON, XML, HTML, form-encoded bodies, …).
-- 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 (an `xPath`→`jsonPath` chain reads JSON embedded in an HTML page; a jsonPath-first extract needs the whole response to be JSON). Only the selected portions reach the attestor.
-- A matched response that can't satisfy the recipe is **skipped**, not failed: the first selector can't operate on it (e.g. jsonPath-first against the HTML navigation of a URL whose JSON XHR was captured), or a required `contains` match is missing. The VC keeps polling for a satisfying request until timeout.
-- So: choose `{{context.<name>}}` when the consumer knows the value up front and the proof should be **pinned to it**; keep it bare when the value should come from whatever the logged-in user's traffic shows.
-
-`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.
-
-11. **Replay.** Call `replay_request(captureId, draftId)`. Three outcomes:
+### How the verification client resolves these at runtime
+
+- Requests match by **exact origin+path** (query ignored). A
+  `{{context.<name>}}` segment matches **only the value the consumer sent**
+  (validated against `requiredContext`); a bare `{{name}}` segment matches any
+  one path segment and its value is **auto-extracted from live traffic**.
+- Interpolation and `contains` matching are **plain text** — JSON, XML, HTML,
+  form-encoded, anything.
+- Extract selectors apply **client-side in spec order xPath → jsonPath →
+  regex**, each to the prior selection. Only the FIRST selector constrains the
+  full response (an `xPath`→`jsonPath` chain reads JSON embedded in HTML; a
+  jsonPath-first extract needs the whole response to be JSON). Only the selected
+  portions reach the attestor.
+- A matched response that can't satisfy the recipe is **skipped, not failed**
+  (the first selector can't operate on it, or a required `contains` is missing).
+  The client keeps polling until timeout.
+- So: `{{context.<name>}}` when the consumer knows the value up front and the
+  proof should be **pinned** to it; bare when the value should come from
+  whatever the logged-in user's traffic shows.
+
+`propose_provider` returns `verificationWarnings` for calls only an author can
+make (currently: a captured value baked literally into the URL, needing the
+`{{context.<name>}}`-vs-bare-vs-recapture decision). Advisory, never blocking —
+**surface each one verbatim** and resolve it before publishing.
+
+<!-- topic: prove -->
+## Replay, then prove
+
+**1. Replay.** `replay_request(captureId, draftId)`:
 
 - `matchesOriginal: true` → proceed.
-- `matchesOriginal: false` with `hints` mentioning auth/csrf → re-trigger the action yourself: navigate or reload via the tools, then loop to step 5. Don't ask the dev to redo it manually.
-- `matchesOriginal: false` with stable diff (timestamps etc.) → tighten the matcher and retry.
-
-**After replay succeeds, run the authentication-bound check — this is mandatory.** Call `replay_request(captureId, draftId, withoutSecrets: true)`. This re-issues the request with NO secrets/cookies (an anonymous visitor).
-
-- If it FAILS to extract (401/403/redirect, or the value is gone) → the endpoint is auth-bound. Good — the proof genuinely means "the holder of these secrets saw this value."
-- If it STILL extracts the value → the endpoint is **PUBLIC**: anyone gets the same value with no login, so the proof binds to nobody. **Do NOT prove it.** Find a request whose response *depends on the session* (an API keyed to the logged-in user, e.g. `/settings/*` or a `viewer`/`currentUser` API), and re-check. If a value only ever appears on public responses, tell the dev it can't be proven as an identity claim rather than proving a public one.
-
-12. **Prove.** Call `run_proof(captureId, draftId, ownerAddress)`. On `verified: true`, the full claim has been written to `~/.reclaim/claims/<timestamp>.json` and the tool returns `{verified, extractedValue, extractedParameters, identifier, owner, claimPath, claim}`. The `claim` field is a display-ready version of the proof — its huge `request` payload has been stripped and all byte arrays converted to base64, so it renders cleanly. **Show it to the dev as a fenced JSON code block at the end** along with the provider JSON. That's the final result. On `verified: false`, diagnose using the returned error and iterate.
-
-    **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.
+- `false` with `hints` mentioning auth/csrf → re-trigger the action yourself
+  (navigate or reload with the tools) and redraft. Don't ask the developer to
+  redo it.
+- `false` with a stable diff (timestamps, and so on) → tighten the matcher
+  and retry.
+
+**2. The authentication-bound check — mandatory.**
+`replay_request(captureId, draftId, withoutSecrets: true)` re-issues the request
+with no secrets/cookies, as an anonymous visitor.
+
+- FAILS to extract (401/403/redirect, or the value is gone) → the endpoint is
+  auth-bound. Good: the proof genuinely means "the holder of these secrets saw
+  this value."
+- STILL extracts the value → the endpoint is **PUBLIC**; the proof binds to
+  nobody. **Do NOT prove it.** Find a request whose response depends on the
+  session (an API keyed to the logged-in user — `/settings/*`, a
+  `viewer`/`currentUser` API) and re-check. If the value only ever appears on
+  public responses, tell the developer it can't be proven as an identity claim.
+
+**3. Prove.** `run_proof(captureId, draftId, ownerAddress)`. On
+`verified: true` the full claim is written to
+`~/.reclaim/claims/<timestamp>.json` and you get
+`{verified, extractedValue, extractedParameters, identifier, owner, claimPath, claim}`.
+`claim` is display-ready (huge `request` payload stripped, byte arrays base64'd)
+— **show it to the developer as a fenced JSON block at the end**, with the
+provider JSON. That's the final result.
+
+**`errorKind: "missing-owner-key"`** → no eth proof-owner key yet. Tell the
+developer what's happening and drive the bootstrap yourself — see topic
+`credentials`. No restart needed, and the existing `draftId` stays valid.
 
 <!-- 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.
-
-    1. **Create the provider if it doesn't exist:** `create_provider(orgId, domain, slug, title, description)` — find `orgId` via `list_orgs`. `domain` e.g. `github.com`; `slug` e.g. `github-username`; `title` e.g. "GitHub Username". Starts PRIVATE with an empty seed version. Skip if the dev already has a `providerId`.
-    2. **Persist the version:** `create_provider_version_from_capture(providerId, provider, initialUrl, notes)` — `notes` e.g. `"Initial draft from browser capture"`. The version lands on the `draft` branch.
-       - **Multi-request provider** (e.g. a landing-page call plus a details call, or a CSRF-preflight/refresh-token chain): run steps 5–12 ONCE PER REQUEST — a separate `propose_provider` → `replay_request` → `run_proof` cycle for each — then pass `providers: [draftA, draftB, ...]` instead of the single-draft `provider` in this same call. Every entry becomes its own request in the version, and all are required at verification time.
-    3. **`requiredContext` is derived for you.** The publish tool scans the recipe's url/body for `{{context.<name>}}` placeholders (step 10) and emits a JSON Schema requiring each one — the Builder then validates every session-create's `context` against it (a clear 400 instead of a late attestor failure). Extra context fields are always allowed. The derived properties are plain strings; to refine types or add human-readable descriptions, call `update_provider_version` with a `requiredContext` override while the version is on `draft`, e.g.:
-
-       ```json
-       { "requiredContext": { "type": "object", "required": ["username"], "properties": { "username": { "type": "string", "description": "GitHub username to verify" } } } }
-       ```
-    4. **Go live:** PRIVATE → `publish_provider_version`; PUBLIC → `submit_provider_version_for_review(providerId, version)` and tell the dev it's awaiting admin review.
-    5. **Tell the dev how consumers call it:** sessions for this provider must include the context params, e.g. `context: { "username": "..." }` in `POST /verifications/sessions`. Quote the `requiredContext` returned on the created version — a session missing those fields gets a 400, and verification matches the supplied values exactly.
-
-    When done, tell the developer the version is live (PRIVATE) or submitted for review (PUBLIC), and that they can integrate using the `providerId`.
-
-    - **If a browser is still attached**, `create_provider_version_from_capture`'s response carries a `_notes` reminder about it. Surface that to the dev and ask whether they want to keep the session open for further edits — only call `dispose_browser` once they confirm they're done. Never close it unprompted; a `builder`-mode session is quota-accounted, but the dev may still be mid-workflow. Closing remote browsers
-    soon is also important to avoid wasting resources. So as best
-    practise, close remote browser session when not needed anymore.
-
-<!-- common: concerns-section -->
-
+<!-- topic: publish -->
+## Publish
+
+`provider` is the JSON from the draft step with the `params` URL
+parameterization applied. `initialUrl` is the page where the user logs in / the
+value is displayed (for example, `https://github.com/Syed`) — **not** the API
+endpoint URL inside the provider.
+
+**1. Reuse before create — this is how duplicates happen.**
+`create_provider_version_from_capture` requires a `providerId`. Before minting a
+new one, search your existing providers with `providers` (by domain / data
+point) — a site you've already built is there. Match → pass its
+`providerId` and the capture lands as a NEW VERSION on it. Only call
+`create_provider(orgId, domain, slug, title, description)` when none exists
+(`orgId` from `list_orgs`; `domain` such as `github.com`, `slug` such as
+`github-username`, `title` such as "GitHub Username"). It starts PRIVATE with an
+empty seed version. Routing every run through `create_provider` is what stacks
+duplicates in "My providers".
+
+**2. Persist the version.**
+`create_provider_version_from_capture(providerId, provider, initialUrl, notes)`
+— `notes` such as `"Initial draft from browser capture"`. It lands on the
+`draft` branch.
+
+- **Multi-request provider** (landing call + details call, a
+  CSRF-preflight/refresh-token chain, …): run capture→draft→replay→prove ONCE
+  PER REQUEST, then pass `providers: [draftA, draftB, …]` instead of the single
+  `provider`. Each becomes its own request on the version and **all** are
+  required at verification time.
+- **Login/navigation-gated data:** supply `jsUserScripts` (plain page JS that
+  drives login/waits/navigation so the target request fires), or
+  `allowedJsRequests` (extra requests the script may fire, for example,
+  pagination). → topic `user-script`. Before populating `allowedJsRequests` for
+  a `verifyProof({ providerId })` use case, read topic `hash-validation` — a
+  session-unique URL there makes verifyProof reject every real proof.
+
+**3. `requiredContext` is derived for you.** The publish tool scans the recipe's
+url/body for `{{context.<name>}}` placeholders and emits a JSON Schema requiring
+each — the Builder then validates every session-create's `context` against it (a
+clear 400 instead of a late attestor failure). Extra context fields are always
+allowed; it's optional when the recipe has no `{{context.*}}` placeholders.
+Derived properties are plain strings; refine types or add descriptions with
+`update_provider_version` while the version is still on `draft`:
+
+```json
+{ "requiredContext": { "type": "object", "required": ["username"], "properties": { "username": { "type": "string", "description": "GitHub username to verify" } } } }
+```
+
+**4. Go live.** PRIVATE → `publish_provider_version`. PUBLIC →
+`submit_provider_version_for_review(providerId, version)`, then tell the
+developer it's awaiting admin review.
+
+**5. Tell the developer how consumers call it.** Sessions must include the
+context params — for example, `context: { "username": "…" }` in
+`create_verification_session`. Quote the `requiredContext` from the created
+version verbatim — a session missing those fields gets a 400, and verification
+matches the supplied values exactly.
+
+**6. The browser is still open.** The response's `_notes` says so. Surface it
+and ask whether the developer wants to keep the session for further edits — call
+`dispose_browser` only once they confirm. Never close it unprompted; a
+`builder`-mode session is quota-accounted, so don't leave it idle either.
+
+<!-- topic: discover -->
+## Discover and resolve providers for the developer's app
+
+When a developer wants to add verification but doesn't know which providers to
+use, run the same flow the Discover UI does:
+
+1. Ask which website their users prove data from.
+2. `discover_data_points({ domain })` → what's verifiable there. Confirm the
+   data points with the developer.
+3. `discover_resolve({ domain, dataPoints })` → the smallest provider set
+   (`providers`, greedy combine), the `requiredContext` inputs to collect, and
+   any `uncovered` points (author those with the flow above, then re-resolve).
+4. `create_verification_session({ providers: [{ providerId }, …], context,
+   verificationClientUrl })` with 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 `canEncryptResult` is
+enabled (set via `PUT /orgs/{orgId}/keypair`) and delivered to the org's
+callback subscriptions; plaintext otherwise. Troubleshoot with
+`get_verification_session`, `list_verification_events`,
+`list_org_verification_sessions`.
+
+<!-- topic: never-do -->
 ## Things to never do
 
 <!-- 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 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-intro -->
-
-<!-- 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.
-   - `{ ready: false }` → no key exists yet. Ask the dev once how to set one up:
-     - **Provide their own key** → `import_credentials({ privateKey: "0x…" })` (also accepts a `keyFile` path).
-     - **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.
-<!-- 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.
-<!-- common: mcp-config-bullet -->
-
-If `replay_request` or `run_proof` errors with `unknown draftId` (or `no capture`):
-
-- **The draft is bound to its capture, held in the MCP server process.** Anything that restarts the server (Claude Code restart, `reset_session`, machine reboot) drops every capture and its drafts. The fix is always: re-run `start_capture` → interact → `propose_provider` to mint a fresh `draftId`. Don't ask the dev to "re-enter the value" — walk them back through capture.
-- **Auth-bound check:** to replay/prove the request as an unauthenticated visitor (no secret headers), pass `withoutSecrets: true` to `replay_request` — the draft still carries the captured secrets, so you never re-supply them.
-
-## Recognizing a HAWKEYE / live-interception provider
-
-Everything above builds the STANDARD flow: capture → draft → replay → prove. There is a second flow — `webSettings.inapp.interceptorOptions.interceptorType: HAWKEYE` (or `MSWJS`/`CDP`) plus a `jsUserScripts` script that calls `window.reclaimInterceptor.addResponseMiddleware(...)` to observe the page's REAL responses as they happen, instead of an independent replay. `create_provider_version_from_capture` never sets `inapp` at all, so you will not author this flow with the current tools — but you may see these fields on a version someone else published outside this flow. `isDocumentRequestReplayEnabled` is a NARROWER, separate toggle from the interception itself — it does not gate `addResponseMiddleware` in general (that fires for every `interceptorType` including `CDP`); it only controls whether the current page's own document/navigation request specifically gets pulled through a non-CDP interceptor, as a site-compatibility escape hatch. See `injection-api.md` (embedded in the `jsUserScripts` field description) for the source-verified breakdown before guessing at what they mean.
+- Never request `hash` for a target whose value also appears in the request URL
+  (topic `draft`), and never `hash` a free-form target — `propose_provider`
+  throws either way; retrying won't help.
+
+<!-- topic: credentials -->
+<!-- common: credentials -->
+
+<!-- topic: troubleshooting -->
+## Troubleshooting
+
+**`unknown draftId` / `no capture`.** The draft is bound to its capture, held in
+the MCP server process. Anything that restarts the server (Claude Code restart,
+`reset_session`, reboot) drops every capture and its drafts. The fix is always
+`start_capture` → interact → `propose_provider` for a fresh `draftId`. Don't ask
+the developer to "re-enter the value" — walk them back through capture.
+
+**Replaying as an anonymous visitor.** Pass `withoutSecrets: true` to
+`replay_request`; the draft still holds the captured secrets, so you never
+re-supply them.
+
+**Site won't load, won't let the user sign in, or breaks right after
+sign-in.** Check WHICH client the session targets first: on `builder` (the
+default) and `portals` interception happens over CDP, so it is never the
+cause — look for a captcha instead. On `inapp-sdk`, `verifier-app`, or the
+browser extension, suspect interception before the recipe, and bisect: FIRST
+turn
+document replay off and keep the interceptor (`disableRequestReplay: true`, or
+`isDocumentRequestReplayEnabled: false` on builder) — often that alone is what
+breaks the page, and it's the smallest change. Only if that doesn't help, turn
+interception off entirely (`injectionType: NONE`, or omit
+`interceptorOptions`). Full checklist and remedies: topic `interception`.
+
+**Proof failures / attestor errors** → topic `prove`.
+**Browser won't launch or attach** → topic `browser`.
+**Missing signing key** → topic `credentials`.