@reclaimprotocol/agent 0.1.3 → 0.1.4

package/README.md

@@ -111,13 +111,13 @@ Defaults target the production old-devtools backend, so **no env is needed for t
 
 See [Backends](#backends) for builder mode (`USE_OLD_DEVTOOLS=false`) and the full env-var list.
 
-### Companion skill (optional, recommended)
+### Provider-authoring guide
 
-The MCP server is all you need to start — but installing the companion skill makes the agent markedly better at the capture → prove → publish flow (login detection, choosing auth-bound endpoints, OPRF decisions, troubleshooting). See [Skill](#skill) for install steps.
+The MCP server is all you need — it ships a `how_it_works` tool that returns the full capture → prove → publish guide (login detection, choosing auth-bound endpoints, OPRF decisions, troubleshooting). Any MCP client can call it on demand; there's nothing extra to install.
 
 ## Using it from your agent
 
-Optional but recommended: install the [skill](#skill) so the agent follows the full authoring flow.
+Tip: have your agent call the `how_it_works` tool first so it follows the full authoring flow.
 
 Then just ask in plain language, e.g.:
 
@@ -138,28 +138,9 @@ The agent orchestrates the tools for you:
 
 Your only manual steps are signing in when the browser windows open and confirming the value you want to prove.
 
-## Skill
+## How it works (guide tool)
 
-Optional but recommended. The companion skill (`skill/SKILL.md`) is a Claude Code **Agent Skill** that teaches the agent the full mode-aware authoring flow — it ships inside the npm package and is also in this repo.
-
-```bash
-# macOS / Linux — from a global install of the package
-npm i -g @reclaimprotocol/agent
-mkdir -p ~/.claude/skills/reclaim-provider
-cp "$(npm root -g)/@reclaimprotocol/agent/skill/SKILL.md" ~/.claude/skills/reclaim-provider/SKILL.md
-
-# …or from a checkout of this repo
-cp packages/agent/skill/SKILL.md ~/.claude/skills/reclaim-provider/SKILL.md
-```
-
-```powershell
-# Windows (PowerShell) — from a global install
-npm i -g @reclaimprotocol/agent
-New-Item -ItemType Directory -Force $env:USERPROFILE\.claude\skills\reclaim-provider | Out-Null
-Copy-Item "$(npm root -g)\@reclaimprotocol\agent\skill\SKILL.md" $env:USERPROFILE\.claude\skills\reclaim-provider\SKILL.md
-```
-
-Claude Code auto-loads it once it's in `~/.claude/skills/`. **Other MCP clients** (Cursor, opencode, Antigravity, …) don't read `SKILL.md` automatically — the server's built-in instructions already cover the essentials, and you can paste or adapt the skill's content into that client's rules / system-prompt for the same depth.
+The full, mode-aware authoring guide (`skill/SKILL.md`) is served on demand by the **`how_it_works`** MCP tool — call it from any MCP client (Claude Code, Cursor, opencode, Antigravity, …) to get the deep capture → prove → publish workflow, decision frameworks, and troubleshooting. The server's always-on `instructions` cover the essentials; `how_it_works` is the in-depth version, with nothing to install.
 
 ## Provider-authoring tools
 
@@ -285,18 +266,6 @@ claude mcp add reclaim -- node "$(pwd)/packages/agent/lib/mcp-bin.js"
 
 To target a specific backend while developing, add an `env` block (Claude Code / `.mcp.json`) or `environment` (opencode) — e.g. `"USE_OLD_DEVTOOLS": "false"` for builder mode. See [Backends](#backends).
 
-### Skill
-
-Symlink the source `skill/` folder into `~/.claude/skills/` so edits to `SKILL.md` are picked up live (no re-copy):
-
-```bash
-# macOS / Linux — from the repo root
-ln -s "$(pwd)/packages/agent/skill" ~/.claude/skills/reclaim-provider
-```
-
-```powershell
-# Windows (PowerShell, Developer Mode or elevated) — from the repo root
-New-Item -ItemType SymbolicLink -Path $env:USERPROFILE\.claude\skills\reclaim-provider -Target (Resolve-Path packages\agent\skill)
-```
+### Authoring guide
 
-Claude Code auto-loads it once linked. opencode doesn't read `SKILL.md` automatically — paste or adapt its content into that client's rules / system-prompt for the same depth.
+`skill/SKILL.builder.md` and `skill/SKILL.old.md` are the sources the `how_it_works` tool serves — one per backend, so an agent is never shown tools its mode doesn't have. The server picks by `USE_OLD_DEVTOOLS`. Edit the relevant file and rebuild (`npm run build`) to update what the tool returns.

package/lib/cdp/capture-engine.d.ts

@@ -30,6 +30,13 @@ export interface ResponseReceivedLike {
  *  `:`. Stripping at capture time keeps every downstream consumer
  *  (`get_request`, draft, replay, proof) clean by construction. */
 export declare function stripPseudoHeaders(headers: Record<string, string>): Record<string, string>;
+/** True when the URL's path names a static asset (by file extension; query and
+ *  hash are ignored, so `chunk.js?v=1` still counts). The capture engine drops
+ *  these up front — they never carry JSON/HTML a recipe matches. */
+export declare function isStaticAsset(url: string): boolean;
+/** True when a response Content-Type is a static asset (scripts/styles/fonts/
+ *  images/media). Parameters (`; charset=…`) and case are ignored. */
+export declare function isStaticAssetMime(mimeType: string | undefined): boolean;
 export interface CaptureSession {
     captureId: string;
     requests: Map<string, CapturedRequest>;

package/lib/cdp/capture-engine.js

@@ -25,6 +25,64 @@ export function stripPseudoHeaders(headers) {
     }
     return out;
 }
+/** Extensions for static assets we never prove over — scripts, styles, fonts,
+ *  images, media, source maps. A real page pulls hundreds of these; tracking
+ *  them (and fetching their bodies) just bloats the request map and body store
+ *  with traffic no recipe ever matches. Note: `.json` is deliberately absent —
+ *  that's the API shape recipes care about. */
+const STATIC_ASSET_EXTENSIONS = new Set([
+    'js', 'mjs', 'cjs', 'css', 'map',
+    'png', 'jpg', 'jpeg', 'gif', 'svg', 'webp', 'avif', 'ico', 'bmp',
+    'woff', 'woff2', 'ttf', 'otf', 'eot',
+    'mp4', 'webm', 'mp3', 'ogg', 'wav',
+]);
+/** True when the URL's path names a static asset (by file extension; query and
+ *  hash are ignored, so `chunk.js?v=1` still counts). The capture engine drops
+ *  these up front — they never carry JSON/HTML a recipe matches. */
+export function isStaticAsset(url) {
+    let path;
+    try {
+        path = new URL(url).pathname;
+    }
+    catch {
+        path = url.split(/[?#]/)[0] ?? url;
+    }
+    // Extension of the last path segment only, so `/v1.2/data` isn't misread.
+    const base = path.slice(path.lastIndexOf('/') + 1);
+    const dot = base.lastIndexOf('.');
+    if (dot <= 0) {
+        return false;
+    }
+    return STATIC_ASSET_EXTENSIONS.has(base.slice(dot + 1).toLowerCase());
+}
+/** Response Content-Types for static assets. The URL-extension filter misses
+ *  extension-less bundler/CDN URLs (e.g. `/assets/3b8f1c`), so we also drop by
+ *  MIME at response time. `text/html`, `application/json`, and `text/plain`
+ *  are NOT here — those are the document/API shapes recipes match. */
+const STATIC_ASSET_MIME_EXACT = new Set([
+    'text/css',
+    'application/javascript', 'text/javascript', 'application/x-javascript',
+    'application/ecmascript', 'text/ecmascript',
+    'application/wasm',
+    'application/font-woff', 'application/font-woff2',
+    'application/vnd.ms-fontobject', 'application/x-font-ttf',
+]);
+const STATIC_ASSET_MIME_PREFIXES = ['image/', 'font/', 'audio/', 'video/'];
+/** True when a response Content-Type is a static asset (scripts/styles/fonts/
+ *  images/media). Parameters (`; charset=…`) and case are ignored. */
+export function isStaticAssetMime(mimeType) {
+    if (!mimeType) {
+        return false;
+    }
+    const m = mimeType.toLowerCase().split(';')[0].trim();
+    if (!m) {
+        return false;
+    }
+    if (STATIC_ASSET_MIME_PREFIXES.some((p) => m.startsWith(p))) {
+        return true;
+    }
+    return STATIC_ASSET_MIME_EXACT.has(m);
+}
 export function createCaptureEngine(opts) {
     const captureId = randomUUID();
     const requests = new Map();
@@ -79,6 +137,13 @@ export function createCaptureEngine(opts) {
         pendingResponseExtra.set(requestId, { ...buffered, ...clean });
     }
     function onRequestWillBeSent(p) {
+        // Static assets never match a recipe — never track them (so we don't
+        // fetch their bodies or grow the store). Drop any extra-info that raced
+        // ahead of this event so it can't linger.
+        if (isStaticAsset(p.request.url)) {
+            pendingRequestExtra.delete(p.requestId);
+            return;
+        }
         const f = {
             requestId: p.requestId,
             method: p.request.method,
@@ -100,6 +165,19 @@ export function createCaptureEngine(opts) {
     function onResponseReceived(p) {
         const f = inFlight.get(p.requestId);
         if (!f) {
+            // No in-flight entry → the request was skipped (e.g. a static asset)
+            // or never seen. Discard any buffered response extra-info so a skipped
+            // asset can't leave a dangling entry.
+            pendingResponseExtra.delete(p.requestId);
+            return;
+        }
+        // Second-line asset filter by Content-Type: catches extension-less
+        // bundler/CDN URLs the request-time URL filter can't. Forget the
+        // in-flight entry so it never reaches `requests` and a later
+        // loadingFinished/extra-info for it becomes a no-op.
+        if (isStaticAssetMime(p.response.mimeType)) {
+            inFlight.delete(p.requestId);
+            pendingResponseExtra.delete(p.requestId);
             return;
         }
         const captured = {

package/lib/cdp/capture.d.ts

@@ -6,6 +6,6 @@
  */
 import type CDP from 'chrome-remote-interface';
 import { type CaptureSession, type StartCaptureOptions } from './capture-engine.ts';
-export { stripPseudoHeaders } from './capture-engine.ts';
+export { isStaticAsset, isStaticAssetMime, stripPseudoHeaders, } from './capture-engine.ts';
 export type { CaptureSession, StartCaptureOptions } from './capture-engine.ts';
 export declare function startCapture(tab: CDP.Client, opts?: StartCaptureOptions): Promise<CaptureSession>;

package/lib/cdp/capture.js

@@ -1,5 +1,5 @@
 import { createCaptureEngine, } from "./capture-engine.js";
-export { stripPseudoHeaders } from "./capture-engine.js";
+export { isStaticAsset, isStaticAssetMime, stripPseudoHeaders, } from "./capture-engine.js";
 export async function startCapture(tab, opts = {}) {
     const engine = createCaptureEngine({
         ...(opts.maxBodyBytes !== undefined && { maxBodyBytes: opts.maxBodyBytes }),

package/lib/consts.d.ts

@@ -16,12 +16,12 @@
  * Each var's default/fallback literal is co-located with its getter.
  */
 import { DEFAULT_BASE_URL } from '@reclaimprotocol/client';
-import { DEFAULT_OLD_API_URL } from './old/client.ts';
+import { DEFAULT_OLD_API_URL, DEFAULT_OLD_LOGS_URL } from './old/client.ts';
 /** Public attestor websocket URL — fallback for `RECLAIM_ATTESTOR_URL`. */
 export declare const FALLBACK_ATTESTOR_URL = "wss://attestor.reclaimprotocol.org:444/ws";
 /** The devtools dashboard login page — fallback for `RECLAIM_OLD_LOGIN_URL`. */
 export declare const DEFAULT_LOGIN_URL = "https://dev.reclaimprotocol.org";
-export { DEFAULT_BASE_URL, DEFAULT_OLD_API_URL };
+export { DEFAULT_BASE_URL, DEFAULT_OLD_API_URL, DEFAULT_OLD_LOGS_URL };
 /** Pino log level. Read once at logger construction, so an eager const is
  *  safe (no test mutates LOG_LEVEL at runtime). */
 export declare const LOG_LEVEL: string;
@@ -45,6 +45,8 @@ export declare function chromePath(): string | undefined;
 export declare function agentDisabled(): boolean;
 /** Old-devtools backend base URL. */
 export declare function oldApiUrl(): string;
+/** Old-devtools analytics-logs service base URL (separate host). */
+export declare function oldLogsUrl(): string;
 /** Builder backend base URL. Shared by mcp/start and the verification tool. */
 export declare function apiUrl(): string;
 /** Explicit builder API token (overrides the cached session token). */

package/lib/consts.js

@@ -18,7 +18,7 @@
 import { DEFAULT_BASE_URL } from '@reclaimprotocol/client';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { DEFAULT_OLD_API_URL } from "./old/client.js";
+import { DEFAULT_OLD_API_URL, DEFAULT_OLD_LOGS_URL } from "./old/client.js";
 // ---------------------------------------------------------------------------
 // Default / fallback literals (used only as env fallbacks).
 // ---------------------------------------------------------------------------
@@ -28,7 +28,7 @@ export const FALLBACK_ATTESTOR_URL = 'wss://attestor.reclaimprotocol.org:444/ws'
 export const DEFAULT_LOGIN_URL = 'https://dev.reclaimprotocol.org';
 // Re-export the two non-env-fallback defaults so callers can keep importing
 // their URL defaults from a single place if they wish.
-export { DEFAULT_BASE_URL, DEFAULT_OLD_API_URL };
+export { DEFAULT_BASE_URL, DEFAULT_OLD_API_URL, DEFAULT_OLD_LOGS_URL };
 // ---------------------------------------------------------------------------
 // Logging.
 // ---------------------------------------------------------------------------
@@ -79,6 +79,10 @@ export function agentDisabled() {
 export function oldApiUrl() {
     return process.env.RECLAIM_OLD_API_URL || DEFAULT_OLD_API_URL;
 }
+/** Old-devtools analytics-logs service base URL (separate host). */
+export function oldLogsUrl() {
+    return process.env.RECLAIM_OLD_LOGS_URL || DEFAULT_OLD_LOGS_URL;
+}
 /** Builder backend base URL. Shared by mcp/start and the verification tool. */
 export function apiUrl() {
     return process.env.RECLAIM_API_URL || DEFAULT_BASE_URL;

package/lib/mcp/instructions.d.ts

@@ -1 +1,3 @@
 export declare const BUILDER_MODE_INSTRUCTIONS: string;
+export declare const PROVIDER_GUIDE_BUILDER: string;
+export declare const PROVIDER_GUIDE_OLD: string;

package/lib/mcp/instructions.js

@@ -9,3 +9,19 @@
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 export const BUILDER_MODE_INSTRUCTIONS = readFileSync(fileURLToPath(new URL('../../skill/builder-mode.md', import.meta.url)), 'utf8').trim();
+/**
+ * The full provider-authoring guide — the deep capture→prove→publish workflow,
+ * decision frameworks, and troubleshooting. Served on demand by the
+ * `how_it_works` MCP tool so every client (not just Claude Code, which
+ * auto-loads skills) can pull it. There's a guide PER MODE so an agent is never
+ * shown auth/publish tools that don't exist in its backend: the server picks
+ * one by `oldMode` (see `mcp/start.ts`). Same `../../skill/` path resolution as
+ * the instructions above; any leading frontmatter is stripped defensively.
+ */
+function readGuide(file) {
+    return readFileSync(fileURLToPath(new URL(file, import.meta.url)), 'utf8')
+        .replace(/^---\n[\s\S]*?\n---\n/, '')
+        .trim();
+}
+export const PROVIDER_GUIDE_BUILDER = readGuide('../../skill/SKILL.builder.md');
+export const PROVIDER_GUIDE_OLD = readGuide('../../skill/SKILL.old.md');

package/lib/mcp/start.js

@@ -1,7 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ReclaimClient } from '@reclaimprotocol/client';
-import { agentDisabled, apiToken, apiUrl, oldApiUrl, useOldDevtools, } from "../consts.js";
+import { agentDisabled, apiToken, apiUrl, oldApiUrl, oldLogsUrl, useOldDevtools, } from "../consts.js";
 import { ReclaimOldClient } from "../old/client.js";
 import { resolveInitialIdentity } from "../old/identity.js";
 import { OLD_MODE_INSTRUCTIONS } from "../old/instructions.js";
@@ -30,6 +30,7 @@ export async function startMcpServer() {
         // get_me_providers instead.
         const oldClient = new ReclaimOldClient({
             baseUrl: oldApiUrl(),
+            logsBaseUrl: oldLogsUrl(),
             identity: resolveInitialIdentity(),
         });
         registerToolList(server, buildLocalCredentialTools());

package/lib/mcp/tools/agent/build.js

@@ -14,6 +14,7 @@ import { attachTool } from "./attach.js";
 import { captureTools } from "./capture.js";
 import { browserTools } from "./eval.js";
 import { findTool } from "./find.js";
+import { howItWorksTool } from "./how-it-works.js";
 import { proofTool } from "./proof.js";
 import { makeSecretStore, proposeTool, } from "./propose.js";
 import { createVersionFromCaptureTool } from "./publish.js";
@@ -35,6 +36,9 @@ export function buildAgentTools(client) {
     const state = buildAgentState();
     ensureAttestorCrypto();
     const tools = [];
+    // Stateless docs tool — serve the mode-specific authoring guide to any
+    // client. No `client` ⇒ old-devtools mode (see `mcp/start.ts`).
+    tools.push(howItWorksTool(!client));
     tools.push(attachTool(state.attach));
     for (const t of captureTools(state.attach, state.captures)) {
         tools.push(t);

package/lib/mcp/tools/agent/how-it-works.d.ts

@@ -0,0 +1,11 @@
+import { type RegisteredTool } from '../../server.ts';
+/**
+ * Serves the full provider-authoring guide on demand. The MCP server's
+ * always-on `instructions` are a terse tool-flow reference; this tool returns
+ * the deep version (workflow, decision frameworks, gotchas, "never do" rules)
+ * so any MCP client — not just Claude Code, which alone auto-loads skills — can
+ * pull it. `oldMode` selects the backend-specific guide so the agent is never
+ * told to call auth/publish tools that aren't registered in its mode.
+ * Stateless: callable before `attach_chrome`.
+ */
+export declare function howItWorksTool(oldMode: boolean): RegisteredTool;

package/lib/mcp/tools/agent/how-it-works.js

@@ -0,0 +1,24 @@
+import { PROVIDER_GUIDE_BUILDER, PROVIDER_GUIDE_OLD, } from "../../instructions.js";
+import { defineTool } from "../../server.js";
+/**
+ * Serves the full provider-authoring guide on demand. The MCP server's
+ * always-on `instructions` are a terse tool-flow reference; this tool returns
+ * the deep version (workflow, decision frameworks, gotchas, "never do" rules)
+ * so any MCP client — not just Claude Code, which alone auto-loads skills — can
+ * pull it. `oldMode` selects the backend-specific guide so the agent is never
+ * told to call auth/publish tools that aren't registered in its mode.
+ * Stateless: callable before `attach_chrome`.
+ */
+export function howItWorksTool(oldMode) {
+    const guide = oldMode ? PROVIDER_GUIDE_OLD : PROVIDER_GUIDE_BUILDER;
+    return defineTool({
+        name: 'how_it_works',
+        description: 'Return the full Reclaim provider-authoring guide for THIS server: '
+            + 'the capture → draft → replay → prove → publish workflow, decision '
+            + 'frameworks (login detection, OPRF privacy, context vs bare params), '
+            + 'multi-request handling, troubleshooting, and what never to do. '
+            + 'Call this BEFORE building a provider unless you are already '
+            + 'fluent in the flow.',
+        inputSchema: { type: 'object', properties: {} },
+    }, async () => ({ guide }));
+}

package/lib/old/client.d.ts

@@ -2,6 +2,9 @@
  *  `/api` route prefix itself, so this is the bare origin. Override with
  *  `RECLAIM_OLD_API_URL`. */
 export declare const DEFAULT_OLD_API_URL = "https://devapi.reclaimprotocol.org";
+/** Default origin of the OLD-devtools analytics-logs service — a SEPARATE host
+ *  from the devtools API. Override with `RECLAIM_OLD_LOGS_URL`. */
+export declare const DEFAULT_OLD_LOGS_URL = "https://logs.reclaimprotocol.org";
 /**
  * Externally-supplied caller identity. We do NOT mint these — the dev
  * provides one:
@@ -53,8 +56,10 @@ export interface MyProvidersQuery {
 export declare class ReclaimOldClient {
     #private;
     readonly baseUrl: string;
+    readonly logsBaseUrl: string;
     constructor(opts?: {
         baseUrl?: string;
+        logsBaseUrl?: string;
         identity?: OldIdentity;
         fetch?: typeof fetch;
     });
@@ -66,5 +71,10 @@ export declare class ReclaimOldClient {
     registerProvider(body: RegisterProviderBody): Promise<unknown>;
     updateProviderConfig(providerId: string, body: UpdateProviderConfigBody): Promise<unknown>;
     listVersions(providerId: string): Promise<unknown>;
+    /** Analytics logs for a verification session, from the logs service (a
+     *  DIFFERENT host than the devtools API — hence its own fetch, not
+     *  `#request`). Attaches the caller identity when one is set; queried
+     *  anonymously otherwise. */
+    getSessionAnalyticsLogs(sessionId: string): Promise<unknown>;
     getMyProviders(query?: MyProvidersQuery): Promise<unknown>;
 }

package/lib/old/client.js

@@ -4,6 +4,9 @@ import { NAME, VERSION } from "../pkg.js";
  *  `/api` route prefix itself, so this is the bare origin. Override with
  *  `RECLAIM_OLD_API_URL`. */
 export const DEFAULT_OLD_API_URL = 'https://devapi.reclaimprotocol.org';
+/** Default origin of the OLD-devtools analytics-logs service — a SEPARATE host
+ *  from the devtools API. Override with `RECLAIM_OLD_LOGS_URL`. */
+export const DEFAULT_OLD_LOGS_URL = 'https://logs.reclaimprotocol.org';
 /**
  * Minimal REST client for the OLD devtools Express backend (base `/api`).
  * Deliberately NOT a clone of `@reclaimprotocol/client`'s operationId
@@ -16,10 +19,13 @@ export const DEFAULT_OLD_API_URL = 'https://devapi.reclaimprotocol.org';
  */
 export class ReclaimOldClient {
     baseUrl;
+    logsBaseUrl;
     #identity;
     #fetch;
     constructor(opts = {}) {
         this.baseUrl = (opts.baseUrl || DEFAULT_OLD_API_URL).replace(/\/+$/, '');
+        this.logsBaseUrl = (opts.logsBaseUrl || DEFAULT_OLD_LOGS_URL)
+            .replace(/\/+$/, '');
         this.#identity = opts.identity;
         this.#fetch = opts.fetch ?? fetch;
     }
@@ -43,6 +49,27 @@ export class ReclaimOldClient {
     listVersions(providerId) {
         return this.#request('GET', `/providers/${encodeURIComponent(providerId)}/versions`, { auth: true });
     }
+    /** Analytics logs for a verification session, from the logs service (a
+     *  DIFFERENT host than the devtools API — hence its own fetch, not
+     *  `#request`). Attaches the caller identity when one is set; queried
+     *  anonymously otherwise. */
+    async getSessionAnalyticsLogs(sessionId) {
+        const url = `${this.logsBaseUrl}/api/analytics-logs/session/`
+            + encodeURIComponent(sessionId);
+        const headers = {
+            Accept: 'application/json',
+            'User-Agent': `${NAME}/${VERSION}`,
+        };
+        if (this.#identity) {
+            headers[this.#authHeaderName()] = this.#authHeaderValue();
+        }
+        const res = await this.#fetch(url, { method: 'GET', headers });
+        const json = await this.#parseBody(res);
+        if (!res.ok) {
+            throw this.#asBoom(res, json);
+        }
+        return json;
+    }
     getMyProviders(query = {}) {
         // Every one of these query params is REQUIRED by the backend
         // validator (missing/invalid → 400), so default them all here.

package/lib/old/tools/build.d.ts

@@ -3,7 +3,7 @@ import type { ReclaimOldClient } from '../client.ts';
 /**
  * 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 declare function buildOldBackendTools(client: ReclaimOldClient): RegisteredTool[];

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/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.3",
+	"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/old-mode.md

@@ -12,4 +12,6 @@ This server is running against the LEGACY Reclaim devtools backend (temporary, w
 
 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.

package/src/cdp/capture-engine.ts

@@ -55,6 +55,73 @@ export function stripPseudoHeaders(
 	return out
 }
 
+/** Extensions for static assets we never prove over — scripts, styles, fonts,
+ *  images, media, source maps. A real page pulls hundreds of these; tracking
+ *  them (and fetching their bodies) just bloats the request map and body store
+ *  with traffic no recipe ever matches. Note: `.json` is deliberately absent —
+ *  that's the API shape recipes care about. */
+const STATIC_ASSET_EXTENSIONS = new Set([
+	'js', 'mjs', 'cjs', 'css', 'map',
+	'png', 'jpg', 'jpeg', 'gif', 'svg', 'webp', 'avif', 'ico', 'bmp',
+	'woff', 'woff2', 'ttf', 'otf', 'eot',
+	'mp4', 'webm', 'mp3', 'ogg', 'wav',
+])
+
+/** True when the URL's path names a static asset (by file extension; query and
+ *  hash are ignored, so `chunk.js?v=1` still counts). The capture engine drops
+ *  these up front — they never carry JSON/HTML a recipe matches. */
+export function isStaticAsset(url: string): boolean {
+	let path: string
+	try {
+		path = new URL(url).pathname
+	} catch{
+		path = url.split(/[?#]/)[0] ?? url
+	}
+
+	// Extension of the last path segment only, so `/v1.2/data` isn't misread.
+	const base = path.slice(path.lastIndexOf('/') + 1)
+	const dot = base.lastIndexOf('.')
+	if(dot <= 0) {
+		return false
+	}
+
+	return STATIC_ASSET_EXTENSIONS.has(base.slice(dot + 1).toLowerCase())
+}
+
+/** Response Content-Types for static assets. The URL-extension filter misses
+ *  extension-less bundler/CDN URLs (e.g. `/assets/3b8f1c`), so we also drop by
+ *  MIME at response time. `text/html`, `application/json`, and `text/plain`
+ *  are NOT here — those are the document/API shapes recipes match. */
+const STATIC_ASSET_MIME_EXACT = new Set([
+	'text/css',
+	'application/javascript', 'text/javascript', 'application/x-javascript',
+	'application/ecmascript', 'text/ecmascript',
+	'application/wasm',
+	'application/font-woff', 'application/font-woff2',
+	'application/vnd.ms-fontobject', 'application/x-font-ttf',
+])
+
+const STATIC_ASSET_MIME_PREFIXES = ['image/', 'font/', 'audio/', 'video/']
+
+/** True when a response Content-Type is a static asset (scripts/styles/fonts/
+ *  images/media). Parameters (`; charset=…`) and case are ignored. */
+export function isStaticAssetMime(mimeType: string | undefined): boolean {
+	if(!mimeType) {
+		return false
+	}
+
+	const m = mimeType.toLowerCase().split(';')[0].trim()
+	if(!m) {
+		return false
+	}
+
+	if(STATIC_ASSET_MIME_PREFIXES.some((p) => m.startsWith(p))) {
+		return true
+	}
+
+	return STATIC_ASSET_MIME_EXACT.has(m)
+}
+
 export interface CaptureSession {
 	captureId: string
 	requests: Map<string, CapturedRequest>
@@ -173,6 +240,14 @@ export function createCaptureEngine(opts: CaptureEngineOptions): CaptureEngine {
 	}
 
 	function onRequestWillBeSent(p: RequestWillBeSentLike) {
+		// Static assets never match a recipe — never track them (so we don't
+		// fetch their bodies or grow the store). Drop any extra-info that raced
+		// ahead of this event so it can't linger.
+		if(isStaticAsset(p.request.url)) {
+			pendingRequestExtra.delete(p.requestId)
+			return
+		}
+
 		const f: InFlight = {
 			requestId: p.requestId,
 			method: p.request.method,
@@ -197,6 +272,20 @@ export function createCaptureEngine(opts: CaptureEngineOptions): CaptureEngine {
 	function onResponseReceived(p: ResponseReceivedLike) {
 		const f = inFlight.get(p.requestId)
 		if(!f) {
+			// No in-flight entry → the request was skipped (e.g. a static asset)
+			// or never seen. Discard any buffered response extra-info so a skipped
+			// asset can't leave a dangling entry.
+			pendingResponseExtra.delete(p.requestId)
+			return
+		}
+
+		// Second-line asset filter by Content-Type: catches extension-less
+		// bundler/CDN URLs the request-time URL filter can't. Forget the
+		// in-flight entry so it never reaches `requests` and a later
+		// loadingFinished/extra-info for it becomes a no-op.
+		if(isStaticAssetMime(p.response.mimeType)) {
+			inFlight.delete(p.requestId)
+			pendingResponseExtra.delete(p.requestId)
 			return
 		}
 

package/src/cdp/capture.ts

@@ -11,7 +11,11 @@ import {
 	type StartCaptureOptions,
 } from './capture-engine.ts'
 
-export { stripPseudoHeaders } from './capture-engine.ts'
+export {
+	isStaticAsset,
+	isStaticAssetMime,
+	stripPseudoHeaders,
+} from './capture-engine.ts'
 export type { CaptureSession, StartCaptureOptions } from './capture-engine.ts'
 
 export async function startCapture(

package/src/consts.ts

@@ -18,7 +18,7 @@
 import { DEFAULT_BASE_URL } from '@reclaimprotocol/client'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
-import { DEFAULT_OLD_API_URL } from './old/client.ts'
+import { DEFAULT_OLD_API_URL, DEFAULT_OLD_LOGS_URL } from './old/client.ts'
 
 // ---------------------------------------------------------------------------
 // Default / fallback literals (used only as env fallbacks).
@@ -32,7 +32,7 @@ export const DEFAULT_LOGIN_URL = 'https://dev.reclaimprotocol.org'
 
 // Re-export the two non-env-fallback defaults so callers can keep importing
 // their URL defaults from a single place if they wish.
-export { DEFAULT_BASE_URL, DEFAULT_OLD_API_URL }
+export { DEFAULT_BASE_URL, DEFAULT_OLD_API_URL, DEFAULT_OLD_LOGS_URL }
 
 // ---------------------------------------------------------------------------
 // Logging.
@@ -96,6 +96,11 @@ export function oldApiUrl(): string {
 	return process.env.RECLAIM_OLD_API_URL || DEFAULT_OLD_API_URL
 }
 
+/** Old-devtools analytics-logs service base URL (separate host). */
+export function oldLogsUrl(): string {
+	return process.env.RECLAIM_OLD_LOGS_URL || DEFAULT_OLD_LOGS_URL
+}
+
 /** Builder backend base URL. Shared by mcp/start and the verification tool. */
 export function apiUrl(): string {
 	return process.env.RECLAIM_API_URL || DEFAULT_BASE_URL

package/src/mcp/instructions.ts

@@ -13,3 +13,21 @@ export const BUILDER_MODE_INSTRUCTIONS = readFileSync(
 	fileURLToPath(new URL('../../skill/builder-mode.md', import.meta.url)),
 	'utf8',
 ).trim()
+
+/**
+ * The full provider-authoring guide — the deep capture→prove→publish workflow,
+ * decision frameworks, and troubleshooting. Served on demand by the
+ * `how_it_works` MCP tool so every client (not just Claude Code, which
+ * auto-loads skills) can pull it. There's a guide PER MODE so an agent is never
+ * shown auth/publish tools that don't exist in its backend: the server picks
+ * one by `oldMode` (see `mcp/start.ts`). Same `../../skill/` path resolution as
+ * the instructions above; any leading frontmatter is stripped defensively.
+ */
+function readGuide(file: string): string {
+	return readFileSync(fileURLToPath(new URL(file, import.meta.url)), 'utf8')
+		.replace(/^---\n[\s\S]*?\n---\n/, '')
+		.trim()
+}
+
+export const PROVIDER_GUIDE_BUILDER = readGuide('../../skill/SKILL.builder.md')
+export const PROVIDER_GUIDE_OLD = readGuide('../../skill/SKILL.old.md')

package/src/mcp/start.ts

@@ -6,6 +6,7 @@ import {
 	apiToken,
 	apiUrl,
 	oldApiUrl,
+	oldLogsUrl,
 	useOldDevtools,
 } from '../consts.ts'
 import { ReclaimOldClient } from '../old/client.ts'
@@ -49,6 +50,7 @@ export async function startMcpServer() {
 		// get_me_providers instead.
 		const oldClient = new ReclaimOldClient({
 			baseUrl: oldApiUrl(),
+			logsBaseUrl: oldLogsUrl(),
 			identity: resolveInitialIdentity(),
 		})
 

package/src/mcp/tools/agent/build.ts

@@ -17,6 +17,7 @@ import { type AttachState, attachTool } from './attach.ts'
 import { type CaptureStore, captureTools } from './capture.ts'
 import { browserTools } from './eval.ts'
 import { findTool } from './find.ts'
+import { howItWorksTool } from './how-it-works.ts'
 import { proofTool } from './proof.ts'
 import {
 	makeSecretStore,
@@ -52,6 +53,9 @@ export function buildAgentTools(
 	const state = buildAgentState()
 	ensureAttestorCrypto()
 	const tools: RegisteredTool[] = []
+	// Stateless docs tool — serve the mode-specific authoring guide to any
+	// client. No `client` ⇒ old-devtools mode (see `mcp/start.ts`).
+	tools.push(howItWorksTool(!client))
 	tools.push(attachTool(state.attach))
 	for(const t of captureTools(state.attach, state.captures)) {
 		tools.push(t)

package/src/mcp/tools/agent/how-it-works.ts

@@ -0,0 +1,32 @@
+import {
+	PROVIDER_GUIDE_BUILDER,
+	PROVIDER_GUIDE_OLD,
+} from '../../instructions.ts'
+import { defineTool, type RegisteredTool } from '../../server.ts'
+
+/**
+ * Serves the full provider-authoring guide on demand. The MCP server's
+ * always-on `instructions` are a terse tool-flow reference; this tool returns
+ * the deep version (workflow, decision frameworks, gotchas, "never do" rules)
+ * so any MCP client — not just Claude Code, which alone auto-loads skills — can
+ * pull it. `oldMode` selects the backend-specific guide so the agent is never
+ * told to call auth/publish tools that aren't registered in its mode.
+ * Stateless: callable before `attach_chrome`.
+ */
+export function howItWorksTool(oldMode: boolean): RegisteredTool {
+	const guide = oldMode ? PROVIDER_GUIDE_OLD : PROVIDER_GUIDE_BUILDER
+	return defineTool<Record<string, never>>(
+		{
+			name: 'how_it_works',
+			description:
+				'Return the full Reclaim provider-authoring guide for THIS server: '
+				+ 'the capture → draft → replay → prove → publish workflow, decision '
+				+ 'frameworks (login detection, OPRF privacy, context vs bare params), '
+				+ 'multi-request handling, troubleshooting, and what never to do. '
+				+ 'Call this BEFORE building a provider unless you are already '
+				+ 'fluent in the flow.',
+			inputSchema: { type: 'object', properties: {} },
+		},
+		async() => ({ guide }),
+	)
+}

package/src/old/client.ts

@@ -6,6 +6,10 @@ import { NAME, VERSION } from '../pkg.ts'
  *  `RECLAIM_OLD_API_URL`. */
 export const DEFAULT_OLD_API_URL = 'https://devapi.reclaimprotocol.org'
 
+/** Default origin of the OLD-devtools analytics-logs service — a SEPARATE host
+ *  from the devtools API. Override with `RECLAIM_OLD_LOGS_URL`. */
+export const DEFAULT_OLD_LOGS_URL = 'https://logs.reclaimprotocol.org'
+
 /**
  * Externally-supplied caller identity. We do NOT mint these — the dev
  * provides one:
@@ -63,15 +67,19 @@ interface RequestOpts {
  */
 export class ReclaimOldClient {
 	readonly baseUrl: string
+	readonly logsBaseUrl: string
 	#identity?: OldIdentity
 	#fetch: typeof fetch
 
 	constructor(opts: {
 		baseUrl?: string
+		logsBaseUrl?: string
 		identity?: OldIdentity
 		fetch?: typeof fetch
 	} = {}) {
 		this.baseUrl = (opts.baseUrl || DEFAULT_OLD_API_URL).replace(/\/+$/, '')
+		this.logsBaseUrl = (opts.logsBaseUrl || DEFAULT_OLD_LOGS_URL)
+			.replace(/\/+$/, '')
 		this.#identity = opts.identity
 		this.#fetch = opts.fetch ?? fetch
 	}
@@ -113,6 +121,30 @@ export class ReclaimOldClient {
 		)
 	}
 
+	/** Analytics logs for a verification session, from the logs service (a
+	 *  DIFFERENT host than the devtools API — hence its own fetch, not
+	 *  `#request`). Attaches the caller identity when one is set; queried
+	 *  anonymously otherwise. */
+	async getSessionAnalyticsLogs(sessionId: string): Promise<unknown> {
+		const url = `${this.logsBaseUrl}/api/analytics-logs/session/`
+			+ encodeURIComponent(sessionId)
+		const headers: Record<string, string> = {
+			Accept: 'application/json',
+			'User-Agent': `${NAME}/${VERSION}`,
+		}
+		if(this.#identity) {
+			headers[this.#authHeaderName()] = this.#authHeaderValue()
+		}
+
+		const res = await this.#fetch(url, { method: 'GET', headers })
+		const json = await this.#parseBody(res)
+		if(!res.ok) {
+			throw this.#asBoom(res, json)
+		}
+
+		return json
+	}
+
 	getMyProviders(query: MyProvidersQuery = {}): Promise<unknown> {
 		// Every one of these query params is REQUIRED by the backend
 		// validator (missing/invalid → 400), so default them all here.

package/src/old/tools/build.ts

@@ -3,12 +3,13 @@ import type { ReclaimOldClient } from '../client.ts'
 import { authenticateTool } from './authenticate.ts'
 import { getMeProvidersTool } from './me-providers.ts'
 import { createVersionFromCaptureTool } from './publish.ts'
+import { sessionAnalyticsLogsTool } from './session-analytics-logs.ts'
 
 /**
  * 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: ReclaimOldClient,
@@ -17,5 +18,6 @@ export function buildOldBackendTools(
 		authenticateTool(client),
 		createVersionFromCaptureTool(client),
 		getMeProvidersTool(client),
+		sessionAnalyticsLogsTool(client),
 	]
 }

package/src/old/tools/session-analytics-logs.ts

@@ -0,0 +1,33 @@
+import { defineTool, 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 function sessionAnalyticsLogsTool(
+	client: ReclaimOldClient,
+): RegisteredTool {
+	return defineTool<{ sessionId: string }>(
+		{
+			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),
+	)
+}