@reclaimprotocol/agent 0.1.22 → 0.1.24

package/skill/SKILL.old.md

@@ -1,177 +1,362 @@
-<!-- common: header -->
-
+<!-- topic: overview -->
+# Authoring a Reclaim provider (old-devtools 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. `reclaim_authenticate` once. → topic `auth`
+- [ ] 2. `attach_browser` — pick a browser source with the developer.
+      → topic `browser`
+- [ ] 3. `list_tabs` → `start_capture(tabId)` ⇒ **`captureId`**, your handle for
+      everything below. → topic `capture`
+- [ ] 4. 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`
+- [ ] 5. `find_requests_containing` → `analyze_request_constraints` → pick an
+      **authenticated** request. → topic `capture`
+- [ ] 6. `propose_provider(captureId, requestId, …)` ⇒ **`draftId`** (recipe +
+      captured secrets, held server-side — secrets never enter the transcript).
+      → topic `draft`
+- [ ] 7. Parameterize user-specific URL segments; mark secrets. → topic `params`
+- [ ] 8. `replay_request(captureId, draftId)`, then again with
+      `withoutSecrets: true`. → topic `prove`
+- [ ] 9. `run_proof(captureId, draftId, ownerAddress)`.
+      → topics `prove`, `credentials`
+- [ ] 10. `create_provider_version_from_capture`. → topic `publish`
+
+Multi-request provider? Run steps 6–9 once per request, then publish every
+proven draft in one call. See topic `publish`.
+
+**This mode's limits.** Only GET/POST requests can be captured into providers.
+There is no organization management, credential-linking, or public-review
+workflow — the narrow `authenticate_builder` / `list_builder_organizations`
+exception exists only to allocate Builder-hosted authoring browsers.
+`get_me_providers` is the only provider-listing tool here.
+
+**Diagnosing a session:** `session_analytics_logs` fetches a verification
+session's analytics logs by id (matches, claims, failures).
+
+<!-- topic: auth -->
 ## Getting authenticated
 
-Call `reclaim_authenticate({})` with no arguments. It opens the Reclaim dashboard in Chrome, waits for the dev to sign in, reads the token from the page automatically, and closes the tab — a still-valid cached identity is reused first, so it's often instant. Tell the dev once: _"A browser window is opening the Reclaim dashboard — please sign in and I'll continue automatically."_
-
-- Force a fresh login (ignore the cached identity): `reclaim_authenticate({ useBrowser: true })`.
-- Skip the browser: `reclaim_authenticate({ token: "<firebase-id-token>" })`, or `reclaim_authenticate({ ethAddress: "0x..." })` for an already-provisioned eth user.
-- Tokens are short-lived (~1h). If a later call returns 401, call `reclaim_authenticate({})` again.
-
-## The loop
-
-<!-- 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.
-
-3. **Check login state, wait if needed.** Use `eval_in_page(tabId, ...)` 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(tabId, "<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(tabId, 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(tabId, url)`. Don't ask the dev to navigate.
-
-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.
-
-<!-- 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(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)?
-   - Is `paramValues[name]` set to the original captured value?
-   - Does `responseRedactions[0]` carry an `xPath` or `jsonPath` anchor? (And if `hash` was requested, also a `regex` with a named capture and a `hash: oprf-…` field?)
+Call `reclaim_authenticate({})` with no arguments. It opens the Reclaim
+dashboard in Chrome, waits for the developer to sign in, reads the token from
+the page and closes the tab — a still-valid cached identity is reused first, so
+it's often instant. Tell the developer once: _"A browser window is opening the
+Reclaim dashboard — please sign in and I'll continue automatically."_
+
+- Force a fresh login: `reclaim_authenticate({ useBrowser: true })`.
+- Skip the browser: `reclaim_authenticate({ token: "<firebase-id-token>" })`, or
+  `reclaim_authenticate({ ethAddress: "0x…" })` for a provisioned eth user.
+- Tokens are short-lived (~1h). Any later 401 → call `reclaim_authenticate({})`
+  again.
+
+### Two independent auth systems — don't confuse them
+
+`reclaim_authenticate` and `authenticate_builder` log into DIFFERENT backends
+and are NOT interchangeable.
+
+- **`reclaim_authenticate`** authorizes everything in this mode:
+  `create_provider_version_from_capture`, `get_me_providers`, and the rest.
+- **`authenticate_builder`** covers exactly two Builder-exclusive features:
+  allocating a Popcorn remote browser (`attach_browser mode="builder"`) and
+  `list_builder_organizations`. It authorizes nothing else.
+
+`get_devtools_mode` reports the presence of both. If a publish or
+`get_me_providers` call fails with an auth error even though
+`reclaim_authenticate` ran earlier, the old-devtools token has expired — re-run
+it. Don't assume `authenticate_builder` fixes 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.
+
+**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? (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 —
+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.
 
-   **Canonical drafted shape** (no hash):
-
-   ```json
-   {
-   	"responseMatches": [
-   		{ "type": "contains", "value": "\"login\":\"{{username}}\"" }
-   	],
-   	"responseRedactions": [{ "xPath": "//script[@id=\"client-env\"]" }],
-   	"paramValues": { "username": "Scratch-net" }
-   }
-   ```
-
-   **Canonical drafted shape** (with `hash: 'oprf-raw'`):
+<!-- common: rewrite-shape-block -->
 
-   ```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" }
-   }
-   ```
+<!-- topic: params -->
+## Parameters: extracted, consumer-supplied, and secret
 
-<!-- common: rewrite-shape-block -->
+**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** — their values come from the consumer at verification time, not from
+extraction.
 
-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 them with `{{context_<name>}}` and add
+`paramValues: { …, "context_username": "Scratch-net" }`. **This backend does not
+support the dotted `{{context.<name>}}` form the Builder uses**, and there is no
+`requiredContext` declaration here — the convention is the whole mechanism.
 
-- Replace user-specific segments with `{{context_<name>}}` and `paramValues: { ..., "context_username": "Scratch-net" }`.
-- 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 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`).
+<!-- common: secrets -->
 
-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.
+The `context_` prefix is a naming convention (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 -->
 
-`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(provider, secretParamsRef)`. Three outcomes:
+`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.
 
-- `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.
+<!-- topic: prove -->
+## Replay, then prove
 
-**After replay succeeds, run an authentication-bound check.** Call `replay_request(provider)` _without_ the `secretParamsRef` (omit it). This sends the request stripped of all secret headers — the same shape an unauthenticated visitor would send.
+**1. Replay.** `replay_request(captureId, draftId)`:
 
-- If `matchesOriginal: false` (e.g. 401/403, or the value differs) → the endpoint is auth-bound. Good. The proof will actually mean "the holder of these secrets saw this value."
-- If `matchesOriginal: true` with the same value → the endpoint is fully public. Tell the dev verbatim: "I verified this endpoint returns the same value with no authentication — the proof won't prove your identity, only that this URL returned the value. Anyone could generate the same proof. Want to keep digging for an auth-bound endpoint, or proceed anyway?" Wait for their decision before continuing.
-
-12. **Prove.** Call `run_proof(provider, secretParamsRef)`. 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 `secretParamsRef` from `propose_provider` is still valid.
+- `matchesOriginal: true` → proceed.
+- `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 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.
-
-    Call `create_provider_version_from_capture`:
-    - **New provider:** omit `providerId`. It registers a new provider (version 1.0.0). Pass `provider`, `initialUrl`, and optionally `description`, `geoLocation`, `providerType` (`PRIVATE` default | `PUBLIC`).
-    - **New version of an existing provider:** pass its `providerId` — the patch is auto-bumped above the highest existing version. Pass `notes` (≥10 chars) as the change note.
-    - **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 publish all of them together in ONE call by passing `providers: [draftA, draftB, ...]` instead of the single-draft `provider`. Every entry becomes its own parallel `requestData` entry on the SAME version, and all are required at verification time.
-    - `get_me_providers({ searchQuery? })` lists the providers you own — use it to find a `providerId` or to confirm the result. It's the only provider-listing tool in this mode.
-    - **Before adding a version to an EXISTING provider, call `get_provider_version_config(providerId)` first.** This backend has no partial-patch endpoint — a version replaces the WHOLE `providerConfig` — so seeing what's currently live (`customInjection`, `userAgent`, `pageTitle`, `stepsToFollow`, etc.) tells you what you're about to change vs. carry forward before you commit to it, rather than finding out after. (`create_provider_version_from_capture` carries forward anything you omit automatically, but knowing what that IS before publishing beats being surprised after.)
-    - **To rename, redescribe, retag, flip `providerType`, or toggle `isActive` on a provider you own — WITHOUT creating a new version** — use `update_provider_metadata(providerId, {...})` instead. It's a genuine partial update on the provider itself; don't route a pure metadata edit through `create_provider_version_from_capture`.
-    - **To look up any published provider (not just ones you own), or to see exactly what the live verification client would fetch** — use `get_provider_info(providerId, versionNumber?)`. It reads the public production SDK backend directly (no auth needed), separate from everything else in this mode.
-    - There's no separate "create-then-version" step and no org / public-review workflow here.
-    - Consumer-supplied params (step 10) keep the `{{context_<name>}}` form in this mode; there is no `requiredContext` declaration on the legacy backend.
-
-    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.
-
-<!-- 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. It maps to the provider's `loginUrl`.
+
+Call `create_provider_version_from_capture`:
+
+- **New provider:** omit `providerId`. Registers a new provider at version
+  1.0.0. Pass `provider`, `initialUrl`, optionally `description`,
+  `geoLocation`, `providerType` (`PRIVATE` default | `PUBLIC`).
+  ⚠️ Re-running without `providerId` registers ANOTHER provider — that's how
+  duplicates appear. Check `get_me_providers` first.
+- **New version of an existing provider:** pass its `providerId`; the patch is
+  auto-bumped above the highest existing version. Pass `notes` (≥10 chars).
+- **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 a parallel `requestData` entry on the SAME version
+  and **all** are required at verification time.
+- **Login/navigation-gated data:** supply `customInjection` (plain page JS) and
+  `allowedInjectedRequestData` (extra requests the script may fire).
+  → topic `user-script`. Before populating `allowedInjectedRequestData` for a
+  `verifyProof({ providerId })` use case, read topic `hash-validation`.
+
+**Ownership — you can only add a version to a provider YOU own.** The
+`providerId` must come from `get_me_providers`. Versioning a public provider you
+don't own fails with a permission error; that's expected. To publish your own
+version of such a site, re-run **without** `providerId` to register your own
+copy. If versioning a provider you *do* own fails, confirm you authenticated as
+the account that created it.
+
+**Before adding a version to an existing provider, read the current one with
+`get_provider_info(providerId)` — this is not optional.** This backend has no
+partial-patch endpoint: every version replaces the WHOLE `providerConfig` with
+exactly what you pass in THIS call, and the tool carries **nothing** forward.
+Any field you want to survive must be re-supplied here — `customInjection`,
+`userAgent`, `pageTitle`, `allowedInjectedRequestData`, `stepsToFollow`,
+`useIncognitoWebview`, `extensionConfig`, and `requestData` (through
+`provider`/`providers`). Anything omitted is published blank. So to change one
+field: read the live config, then pass the full desired config (existing values
+plus your change) back in.
+
+`allowedInjectedRequestData`, `useIncognitoWebview` and `extensionConfig` take
+effect on add-version only — the register endpoint ignores them, so on a fresh
+register the tool automatically follows up with an add-version call that
+applies them.
+
+**Related tools:**
+
+- `update_provider_metadata(providerId, {…})` — rename, redescribe, retag, flip
+  `providerType`, toggle `isActive`, **without** creating a version. A genuine
+  partial update; don't route a pure metadata edit through a new version.
+- `get_provider_info(providerId, versionNumber?)` — look up ANY published
+  provider (not just yours) and see exactly what the live verification client
+  would fetch. Reads the public production SDK backend directly, no auth.
+
+There's no create-then-version step and no org / public-review workflow here.
+When done, tell the developer the version is live and that they can integrate
+using the `providerId`.
+
+**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.
+
+<!-- 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 (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 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-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({ provider, ownerAddress: 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 `secretParamsRef`). The `.env` flow above avoids that — prefer it.
-<!-- common: mcp-config-bullet -->
-
-If `replay_request` or `run_proof` errors with `unknown secretParamsRef`:
-
-- **The ref is bound to the MCP server process.** Anything that restarts the server (Claude Code restart, `reset_session`, machine reboot) invalidates every previously-issued ref. The fix is always: re-run `start_capture` → interact → `propose_provider` to mint a fresh ref. Don't ask the dev to "re-enter the value" — walk them back through capture.
-- **Exception:** if the drafted provider has empty `secretRefs: []` (no secret headers were captured), you can call `replay_request` and `run_proof` without `secretParamsRef` at all — both tools accept it as optional in that case.
-
-## Recognizing a HAWKEYE / live-interception provider
-
-Everything above builds the STANDARD flow: capture → draft → replay (the backend independently re-sends the request) → prove. There is a second, separate flow — `injectionType: HAWKEYE` (or `MSWJS`/`XHOOK`/`CDP`) plus a `customInjection` script that calls `window.reclaimInterceptor.addResponseMiddleware(...)` to observe the page's REAL responses as they happen, instead of the backend replaying anything. You will not author this flow with the current tools — `create_provider_version_from_capture` only builds the standard one. But you WILL see the fields when reading an existing provider (`get_provider_version_config`, `get_provider_info`): don't assume `injectionType` present-but-not-`NONE` means something is broken — the old backend's own schema DEFAULTS `injectionType` to `HAWKEYE` for every provider, standard-flow ones included; it's inert with no interceptor script installed. `disableRequestReplay` is a NARROWER, separate toggle — it does not gate interception in general (that fires regardless, for every `injectionType` including `CDP`); it only controls whether the current page's own document/navigation request specifically gets pulled through a non-CDP interceptor, and exists as a site-compatibility escape hatch, not an architecture choice. See `injection-api.md` (embedded in the `customInjection` field description) for the full, source-verified breakdown of `injectionType`/`disableRequestReplay`/`bodySniff` before guessing at any of these three.
+- 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.
+
+**Auth errors on publish / `get_me_providers`** → the old-devtools token
+expired. Re-run `reclaim_authenticate` (topic `auth`), not
+`authenticate_builder`.
+
+**`reclaim_authenticate` seems to hang.** On a FRESH Chrome profile the
+dashboard is a large cold download, so the login form can take tens of seconds
+to become usable — that time comes out of the sign-in budget. Tell the
+developer it is loading and that the window is waiting for them, and DON'T
+re-run the tool while it is still waiting: a second call restarts the whole
+wait and is what turns a slow load into an apparent multi-minute hang. If it
+does time out, the error says whether the page ever became interactive —
+"never became interactive" means the load, not the human.
+
+**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`.