@reclaimprotocol/agent 0.1.2 → 0.1.4

package/lib/old/tools/build.js

@@ -1,16 +1,18 @@
 import { authenticateTool } from "./authenticate.js";
 import { getMeProvidersTool } from "./me-providers.js";
 import { createVersionFromCaptureTool } from "./publish.js";
+import { sessionAnalyticsLogsTool } from "./session-analytics-logs.js";
 /**
  * The backend-facing tools for OLD-devtools mode. Mirrors
  * `buildCredentialTools` / `buildAgentTools`: returns a flat `RegisteredTool`
- * list for `registerToolList`. These three replace the builder credential +
- * publish tools and the (disabled) generated provider tools.
+ * list for `registerToolList`. These replace the builder credential + publish
+ * tools and the (disabled) generated provider tools.
  */
 export function buildOldBackendTools(client) {
     return [
         authenticateTool(client),
         createVersionFromCaptureTool(client),
         getMeProvidersTool(client),
+        sessionAnalyticsLogsTool(client),
     ];
 }

package/lib/old/tools/publish.js

@@ -43,10 +43,15 @@ function rethrowOwnershipError(err, providerId) {
 export function createVersionFromCaptureTool(client) {
     return defineTool({
         name: 'create_provider_version_from_capture',
-        description: 'Publish a drafted ReclaimProvider to the OLD devtools backend. ' +
+        description: 'Publish drafted ReclaimProvider(s) to the OLD devtools backend. ' +
             'Pass the `provider` object from propose_provider VERBATIM and the ' +
             '`initialUrl` the user landed on (the login/landing page, NOT the ' +
             'API url). \n\n' +
+            'For a MULTI-REQUEST provider, pass `providers: [...]` (each entry a ' +
+            'proven draft from propose_provider) — every entry becomes one ' +
+            '`requestData` entry on the SAME version, and all are verified ' +
+            'together. Pass a single `provider` for the one-request case ' +
+            '(provide exactly one of `provider` / `providers`). \n\n' +
             'Omit `providerId` to REGISTER A NEW provider (creates it + version ' +
             '1.0.0; re-running creates a duplicate). Pass `providerId` (from ' +
             'get_me_providers) to add a NEW VERSION to that existing provider ' +
@@ -61,7 +66,8 @@ export function createVersionFromCaptureTool(client) {
             properties: {
                 provider: {
                     type: 'object',
-                    description: 'The `provider` object from propose_provider, verbatim.',
+                    description: 'A single `provider` object from propose_provider, verbatim. ' +
+                        'For multiple requests use `providers` instead.',
                     properties: {
                         name: { type: 'string' },
                         url: { type: 'string' },
@@ -74,6 +80,28 @@ export function createVersionFromCaptureTool(client) {
                     },
                     required: ['name', 'url', 'method', 'responseMatches'],
                 },
+                providers: {
+                    type: 'array',
+                    description: 'Multiple proven drafts → one multi-request version (each ' +
+                        'becomes a parallel `requestData` entry, all verified ' +
+                        'together). Each item has the same shape as `provider`. Pass ' +
+                        'this OR `provider`, not both.',
+                    minItems: 1,
+                    items: {
+                        type: 'object',
+                        properties: {
+                            name: { type: 'string' },
+                            url: { type: 'string' },
+                            method: { type: 'string' },
+                            headers: { type: 'object' },
+                            body: { type: 'string' },
+                            responseMatches: { type: 'array' },
+                            responseRedactions: { type: 'array' },
+                            paramValues: { type: 'object' },
+                        },
+                        required: ['name', 'url', 'method', 'responseMatches'],
+                    },
+                },
                 initialUrl: {
                     type: 'string',
                     description: 'The website URL the user landed on to trigger the request ' +
@@ -105,9 +133,18 @@ export function createVersionFromCaptureTool(client) {
                         'chars or a default is used).',
                 },
             },
-            required: ['provider', 'initialUrl'],
+            required: ['initialUrl'],
         },
     }, async (args) => {
+        // Exactly one of `provider` / `providers` — normalize to an array so a
+        // multi-request capture publishes every request, not just the first.
+        const hasMany = Array.isArray(args.providers) && args.providers.length > 0;
+        const hasOne = !!args.provider;
+        if (hasMany === hasOne) {
+            throw new Boom('Pass exactly one of `provider` (a single draft) or `providers` ' +
+                '(an array of 1+ drafts).', { statusCode: 400 });
+        }
+        const providers = hasMany ? args.providers : [args.provider];
         const opts = { initialUrl: args.initialUrl };
         if (args.description !== undefined) {
             opts.description = args.description;
@@ -121,11 +158,9 @@ export function createVersionFromCaptureTool(client) {
         if (args.providerType !== undefined) {
             opts.providerType = args.providerType;
         }
-        // Non-blocking advisory — never alters or blocks the publish; the
-        // author keeps full control. Attaches under `_notes` when relevant.
-        const notes = matchRedactionWarnings([
-            countsFor('Request', args.provider),
-        ]);
+        // Non-blocking advisory per request — never alters or blocks the
+        // publish; the author keeps full control. Attaches under `_notes`.
+        const notes = matchRedactionWarnings(providers.map((p, i) => countsFor(`Request ${i + 1}`, p)));
         const withNotes = (result) => {
             if (notes.length && result && typeof result === 'object') {
                 return { ...result, _notes: notes };
@@ -134,7 +169,7 @@ export function createVersionFromCaptureTool(client) {
         };
         // New provider.
         if (!args.providerId) {
-            const body = providerToRegisterBody(args.provider, opts);
+            const body = providerToRegisterBody(providers, opts);
             return withNotes(await client.registerProvider(body));
         }
         // New version of an existing provider — pick the next patch above
@@ -148,7 +183,7 @@ export function createVersionFromCaptureTool(client) {
             const versionInfo = args.notes && args.notes.trim().length >= 10
                 ? args.notes.trim()
                 : DEFAULT_VERSION_INFO;
-            const body = providerToConfigBody(args.provider, opts, version, versionInfo);
+            const body = providerToConfigBody(providers, opts, version, versionInfo);
             return withNotes(await client.updateProviderConfig(providerId, body));
         }
         catch (err) {

package/lib/old/tools/session-analytics-logs.d.ts

@@ -0,0 +1,9 @@
+import { type RegisteredTool } from '../../mcp/server.ts';
+import type { ReclaimOldClient } from '../client.ts';
+/**
+ * Fetch analytics logs for a verification session from the OLD-devtools logs
+ * service (`GET https://logs.reclaimprotocol.org/api/analytics-logs/session/
+ * :sessionId`). Old mode only — useful for diagnosing why a session failed or
+ * stalled. The logs service is a separate host from the devtools API.
+ */
+export declare function sessionAnalyticsLogsTool(client: ReclaimOldClient): RegisteredTool;

package/lib/old/tools/session-analytics-logs.js

@@ -0,0 +1,25 @@
+import { defineTool } from "../../mcp/server.js";
+/**
+ * Fetch analytics logs for a verification session from the OLD-devtools logs
+ * service (`GET https://logs.reclaimprotocol.org/api/analytics-logs/session/
+ * :sessionId`). Old mode only — useful for diagnosing why a session failed or
+ * stalled. The logs service is a separate host from the devtools API.
+ */
+export function sessionAnalyticsLogsTool(client) {
+    return defineTool({
+        name: 'session_analytics_logs',
+        description: 'Fetch analytics logs for a verification session by id from the '
+            + 'old-devtools logs service — use to diagnose what happened in a '
+            + 'session (matches, claims, failures). Pass the `sessionId`.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sessionId: {
+                    type: 'string',
+                    description: 'The verification session id to fetch logs for.',
+                },
+            },
+            required: ['sessionId'],
+        },
+    }, async (args) => client.getSessionAnalyticsLogs(args.sessionId));
+}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@reclaimprotocol/agent",
 	"title": "Reclaim Agent",
-	"version": "0.1.2",
+	"version": "0.1.4",
 	"description": "Reclaim Protocol agent — SDK, CLI, and MCP server in one package. SDK + CLI talk to the builder backend; MCP server adds Chrome CDP capture, provider synthesis, replay, and zkTLS proof.",
 	"type": "module",
 	"main": "./lib/index.js",
@@ -26,8 +26,7 @@
 		"./mcp/register": {
 			"types": "./lib/mcp/register.d.ts",
 			"import": "./lib/mcp/register.js"
-		},
-		"./skill": "./skill/SKILL.md"
+		}
 	},
 	"bin": {
 		"reclaim": "./lib/cli.js",

package/skill/{SKILL.md → SKILL.builder.md}

@@ -1,8 +1,3 @@
----
-name: reclaim-provider
-description: Activate when the developer asks how to verify a value from a website (e.g. "create a provider for X", "verify my GitHub username", "prove my X follower count"). Drives the reclaim-agent MCP server to capture browser traffic, draft a Reclaim provider JSON, replay it, and run an end-to-end zkTLS proof.
----
-
 # Authoring a Reclaim Provider / Verification
 
 > **Terminology note:** "provider" and "verification" refer to the same
@@ -13,27 +8,8 @@ description: Activate when the developer asks how to verify a value from a websi
 
 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.
 
-## Modes
-
-This MCP server targets one of two backends. Detect which from the tools available to you:
-
-- **Old devtools (the default).** `get_me_providers` is present; the generated API tools (`get_me`, `create_verification`, `list_orgs`, …) are absent.
-- **Builder.** The generated API tools are present; `get_me_providers` is absent.
-
-Only **authentication** (below), **publishing** (the final step), and the **consumer-supplied param namespace** differ between modes: values the Consumer supplies at verification time are templated `{{context.<name>}}` on builder vs `{{context_<name>}}` on old devtools (no dotted interpolation there) — see step 10. The capture → draft → replay → prove loop in between is identical, and OPRF is optional and supported in both.
-
 ## Getting authenticated
 
-### Old devtools mode
-
-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.
-
-### Builder mode
-
 **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:
@@ -150,15 +126,14 @@ The 2-day token is cached in `~/.reclaim/config.json` and reused on later runs (
 
 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:
 
-- **Builder 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).
-- **Old devtools mode:** same idea, but the legacy backend doesn't support dotted interpolation — use `{{context_<name>}}` and `paramValues: { ..., "context_username": "Scratch-net" }`.
+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.
 - 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.
 
-**How the verification client resolves these at runtime** (builder mode — use this to make the context-vs-bare call):
+**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, …).
@@ -198,16 +173,8 @@ The 2-day token is cached in `~/.reclaim/config.json` and reused on later runs (
 
     **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.
 
-13. **Publish the proved provider.** This is the step that differs by mode (see [Modes](#modes)). In both, `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.
-
-    **Old devtools mode** — call `create_provider_version_from_capture`:
-    - **New verification:** 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 verification:** pass its `providerId` — the patch is auto-bumped above the highest existing version. Pass `notes` (≥10 chars) as the change note.
-    - `get_me_providers({ searchQuery? })` lists the verifications you own — use it to find a `providerId` or to confirm the result. It's the only provider-listing tool 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.
+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.
 
-    **Builder mode:**
     1. **Create the verification if it doesn't exist:** `create_verification(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.
     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.:

package/skill/SKILL.old.md

@@ -0,0 +1,221 @@
+# Authoring a Reclaim Provider / Verification
+
+> **Terminology note:** "provider" and "verification" refer to the same
+> thing. The API and tool parameters use **provider** / **providerId**
+> (the technical term). Conversations with developers prefer
+> **verification** (the user-facing term). Either is acceptable — never
+> correct the developer for using one or the other.
+
+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.
+
+## 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
+
+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`.
+
+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.
+
+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`).
+
+   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.
+
+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.
+
+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?)
+
+   **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'`):
+
+   ```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" }
+   }
+   ```
+
+   **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.
+
+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 user-specific segments with `{{context_<name>}}` and `paramValues: { ..., "context_username": "Scratch-net" }`.
+- Query parameters 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.
+
+**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.
+
+`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:
+
+- `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 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.
+
+- 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.
+
+    **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.
+
+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 verification:** 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 verification:** pass its `providerId` — the patch is auto-bumped above the highest existing version. Pass `notes` (≥10 chars) as the change note.
+    - `get_me_providers({ searchQuery? })` lists the verifications you own — use it to find a `providerId` or to confirm the result. It's the only provider-listing tool 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`.
+
+## 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.
+
+## 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.
+- **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.
+
+## 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.
+
+**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.
+
+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.
+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.
+- **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.
+
+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.
+
+## Out of scope (v0)
+
+If the dev needs a provider for a flow that requires multiple sequential requests (CSRF preflight, refresh-token chains), tell them: "multi-request providers are v1. For now, we can produce a single-request provider for the target value — let's see if one exists in this capture."

package/skill/builder-mode.md

@@ -10,4 +10,6 @@ This server targets the Reclaim BUILDER backend. It exposes three tool layers: g
 
 **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.
 
+**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.

package/skill/old-mode.md

@@ -4,12 +4,14 @@ This server is running against the LEGACY Reclaim devtools backend (temporary, w
 
 1. `reclaim_authenticate` — by default opens the dashboard in Chrome, waits for you to sign in, captures the token automatically, and closes the tab (or paste a `token` / pass an eth `ethAddress` to skip the browser). Do this once before publishing or listing.
 2. `attach_chrome` → `start_capture` → drive the page (`navigate`, `wait_for_page`) → inspect (`list_requests`, `get_request`, `find_requests_containing`).
-3. `propose_provider` to draft a provider, `replay_request` to pre-flight, `run_proof` to verify with the attestor. OPRF/`hash` redactions are optional and supported.
-4. `create_provider_version_from_capture` to publish. With NO `providerId` it REGISTERS A NEW provider (re-running creates a duplicate); pass a `providerId` from `get_me_providers` to add a new version to an existing provider instead.
+3. `propose_provider` to draft a provider, `replay_request` to pre-flight, `run_proof` to verify with the attestor. OPRF/`hash` redactions are optional and supported. When the data spans MULTIPLE requests (e.g. a landing call + a details call), propose + `run_proof` EACH request to get one proven draft per request.
+4. `create_provider_version_from_capture` to publish. With NO `providerId` it REGISTERS A NEW provider (re-running creates a duplicate); pass a `providerId` from `get_me_providers` to add a new version to an existing provider instead. For a MULTI-REQUEST provider, pass `providers: [draftA, draftB, …]` (every proven draft) so EACH becomes a parallel `requestData` entry on the one version — passing a single `provider` saves only that one request.
 5. `get_me_providers` lists the providers you own (the only provider-listing tool available in this mode).
 
 **Editing / new versions (ownership):** you can only add a version to a provider **you own** — the `providerId` must come from `get_me_providers`. Trying to version a public provider you don't own fails with a permission error; that is expected. To publish your own version of such a site, re-run `create_provider_version_from_capture` **without** `providerId` to register your own copy (a separate provider you own). If versioning a provider you *do* own fails, confirm you authenticated as the account that created it.
 
 Only GET/POST endpoints can be captured into providers here. There is no organization, credential-linking, or public-review workflow in this mode.
 
+**Diagnosing a session:** `session_analytics_logs` fetches the analytics logs for a verification session by id (from the logs service) — use it to see what happened in a session (matches, claims, failures).
+
 **Templating:** bare `{{name}}` placeholders are provider params (values extracted from the response). Values the CONSUMER must supply at verification time (e.g. a username in the URL path) use the `{{context_<name>}}` form — this backend does not support the dotted `{{context.<name>}}` interpolation the new builder uses.