@reclaimprotocol/agent 0.1.39 → 0.1.41

package/lib/telemetry/tool-call.js

@@ -0,0 +1,102 @@
+import { isProblemError } from '@reclaimprotocol/client/api';
+import { currentTelemetry } from "./index.js";
+const GOAL_MAX = 300;
+const USER_REQUEST_MAX = 500;
+const DOMAIN_MAX = 200;
+const DATA_POINTS_MAX = 20;
+const DATA_POINT_MAX = 200;
+/**
+ * Times a tool call and records it. Call `end()` once when the call
+ * finishes. It never throws, so it can't change the outcome of the call.
+ */
+export function startToolCall(tool, args) {
+    const startedAt = Date.now();
+    return {
+        end(err) {
+            try {
+                const telemetry = currentTelemetry();
+                if (!telemetry) {
+                    return;
+                }
+                const input = allowlistedInput(tool, args);
+                telemetry.track('tool_call', {
+                    tool,
+                    ok: err === undefined,
+                    ...(err === undefined ? {} : { errorCode: errorCode(err) }),
+                    durationMs: Date.now() - startedAt,
+                    mode: telemetry.mode,
+                    ...(input ? { input } : {}),
+                });
+            }
+            catch {
+                // Telemetry must never affect a tool call.
+            }
+        },
+    };
+}
+/**
+ * A category for the error, such as `http_401`. It's never the message,
+ * because messages can contain URLs, tokens, or file paths.
+ */
+export function errorCode(err) {
+    if (isProblemError(err)) {
+        return `http_${err.output.statusCode}`;
+    }
+    if (isRecord(err) && err.isBoom === true && isRecord(err.output)) {
+        return `http_${String(err.output.statusCode)}`;
+    }
+    if (err instanceof Error) {
+        if (err.name === 'ZodError') {
+            return 'invalid_input';
+        }
+        if (err.name === 'TimeoutError' || err.name === 'AbortError') {
+            return 'timeout';
+        }
+    }
+    return 'error';
+}
+/**
+ * The only arguments Reclaim records, and only for these tools. They are the
+ * developer's own description of what they want to build, which tells us
+ * which providers to add. Every other argument is dropped here, so a new tool
+ * records nothing until you add it to this list on purpose.
+ */
+export function allowlistedInput(tool, args) {
+    if (!isRecord(args)) {
+        return undefined;
+    }
+    switch (tool) {
+        case 'start_integration':
+            return compact({
+                goal: cut(args.goal, GOAL_MAX),
+                userRequest: cut(args.userRequest, USER_REQUEST_MAX),
+            });
+        case 'propose_provider':
+            return compact({ userRequest: cut(args.userRequest, USER_REQUEST_MAX) });
+        case 'discover_resolve': {
+            const query = isRecord(args.query) ? args.query : {};
+            const dataPoints = Array.isArray(query.dataPoints)
+                ? query.dataPoints
+                    .slice(0, DATA_POINTS_MAX)
+                    .map((p) => cut(p, DATA_POINT_MAX))
+                    .filter((p) => p !== undefined)
+                : undefined;
+            return compact({
+                domain: cut(query.domain, DOMAIN_MAX),
+                dataPoints: dataPoints?.length ? dataPoints : undefined,
+            });
+        }
+        default:
+            return undefined;
+    }
+}
+function cut(value, max) {
+    return typeof value === 'string' && value ? value.slice(0, max) : undefined;
+}
+/** Returns the object, or undefined when every field is undefined. */
+function compact(obj) {
+    return Object.values(obj).some((v) => v !== undefined) ? obj : undefined;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@reclaimprotocol/agent",
 	"title": "Reclaim Agent",
-	"version": "0.1.39",
+	"version": "0.1.41",
 	"description": "Reclaim Protocol tools for AI coding agents. Reclaim lets your app verify data points about its users, such as a follower count, an account balance, or an order history. This package is the Reclaim MCP server: it gives your agent the tools to find, build, test, and fix data verification providers by capturing and replaying browser requests, drafting provider recipes, running zkTLS proofs, and publishing provider versions.",
 	"type": "module",
 	"main": "./lib/index.js",
@@ -84,7 +84,7 @@
 		"@noble/hashes": "^2.2.0",
 		"@puppeteer/browsers": "3.2.4",
 		"@reclaimprotocol/attestor-core": "^5.1.6",
-		"@reclaimprotocol/client": "0.1.39",
+		"@reclaimprotocol/client": "0.1.41",
 		"@reclaimprotocol/tls": "^0.1.3",
 		"chrome-remote-interface": "^0.33.0",
 		"domhandler": "^6.0.0",

package/skill/SKILL.builder.md

@@ -68,6 +68,12 @@ immediately with a `code` and `attachUrl` — it does NOT poll.
 The 2-day token is cached in `~/.reclaim/config.json` and reused on later runs
 (`RECLAIM_API_TOKEN` in the server env overrides it).
 
+### Backend mode
+
+`get_devtools_mode` reports the active mode. `set_devtools_mode` persists a
+switch to `~/.reclaim/config.json`, effective on the next server start. An
+explicit `USE_OLD_DEVTOOLS` env var wins.
+
 <!-- topic: devtools-migration -->
 ## Import providers from devtools
 
@@ -316,6 +322,14 @@ with no secrets/cookies, as an anonymous visitor.
 — **show it to the developer as a fenced JSON block at the end**, with the
 provider JSON. That's the final result.
 
+**Country.** `run_proof` sends the attestor's request from the developer's own
+IP country, which is what `{{DYNAMIC_GEO}}` becomes when they verify; `egress`
+in the result names the country. If a site that serves one country (for
+example, a US airline) blocks the attestor, retry once with
+`geoLocation: "US"`. If that verifies, pin it with
+`update_draft({ geoLocation: "US" })` so the published version goes out from
+there too.
+
 **`errorKind: "missing-owner-key"`** → no eth proof-owner key yet. Tell the
 developer what's happening and drive the bootstrap yourself — see topic
 `credentials`. No restart needed, and the existing `draftId` stays valid.
@@ -396,16 +410,17 @@ in, navigate to `initialUrl`; if a user script is present, run
 `test_user_script` with that script and `initialUrl`. When the existing capture
 has enough data, replay and prove every required request. Do not clear
 cookies or force another sign-in. Treat an unavailable or inconclusive retest as
-advisory and do not block publication. Ask whether the developer wants to keep
-the session for further edits; call `dispose_browser` only after they confirm.
-A `builder` session is quota-accounted, so don't leave it idle.
+advisory and do not block publication. Don't ask whether to close the
+browser. Mention once in the final summary that it stays open for provider
+changes and you can close it on request; call `dispose_browser` only when the
+developer says so. A `builder` session is quota-accounted, so close it as soon
+as they say the work is done.
 
 <!-- topic: discover -->
 ## Discover and resolve existing providers
 
-Use this flow only when the developer asks to reuse existing providers or
-doesn't know what a site supports. Otherwise build a new provider (server
-instructions, "Choose the provider").
+Use this flow only when the developer asks to reuse existing providers, names
+one, or doesn't know what a site supports. Otherwise build a new provider.
 
 1. Ask which website their users prove data from.
 2. `discover_data_points({ domain })` → what's verifiable there. Confirm the
@@ -415,13 +430,17 @@ instructions, "Choose the provider").
    any `uncovered` points (author those with the checklist in topic
    `overview`, then re-resolve).
 4. Use only the data points the developer confirmed: show and read only those
-   and ignore the rest. A provider that needs any change gets your own copy
-   (server instructions, "Choose the provider"). Otherwise it's usable as-is;
-   don't capture, replay, or prove it unless the developer asks.
+   and ignore the rest. A provider that needs any change (a missing data point, extra inputs, a different extraction) gets your own copy
+   (`create_provider_version` when your org owns it; otherwise
+   `create_provider`, then `create_provider_version` from a copy of its
+   config, trimmed to the requested data points). Otherwise it's published and
+   usable as-is; don't capture, replay, or prove it unless the developer asks.
+   When a requirement (site, account, or value) is ambiguous, ask one concise
+   question; don't guess.
 5. To try them: `create_verification_session({ providers: [{ providerId }, …],
    context, verificationClientUrl })` with EVERY resolved provider id and the
-   collected context. The server instructions ("Try a provider without an
-   app") cover the callback and polling. To integrate: topic `integration`.
+   collected context. Topic `integration` ("Try a provider without an app")
+   covers the callback and polling, and the integration steps.
 
 `merge.mergeable` only signals the set *could* collapse into one provider. Pass
 them all; the Builder runs them in one session.

package/skill/SKILL.old.md

@@ -74,6 +74,14 @@ and are NOT interchangeable.
 `reclaim_authenticate` ran earlier, the old-devtools token has expired — re-run
 it. Don't assume `authenticate_builder` fixes it.
 
+### Backend mode
+
+The BUILDER backend (generated API tools, orgs, verification sessions, public
+review) is one switch away. `get_devtools_mode` reports the active mode and
+why; `set_devtools_mode` persists a switch to `~/.reclaim/config.json`,
+effective on the NEXT server start. An explicit `USE_OLD_DEVTOOLS` env var wins
+over the persisted choice.
+
 <!-- topic: browser -->
 <!-- common: browser -->
 
@@ -320,8 +328,17 @@ applies them.
 There's no create-then-version step and no org / public-review workflow here.
 When done, tell the developer the version is live, then ask once how they want
 to use it — try it now, integrate it into an existing backend or frontend, or
-create a new app — unless they already said (see "Using a provider" in the
-server instructions).
+create a new app — unless they already said:
+
+> Want to (1) try it right now here, (2) integrate it into an existing backend
+> or frontend (this directory or another path), or (3) create a new app for it?
+
+Try it now → `scaffold_reclaim_demo_server` with its `providerId`. Integrate,
+or new app → `get_js_sdk_integration_guide`, then work in the path they named.
+
+A provider found with `get_me_providers` or `get_provider_info` is published
+and usable as-is. Don't capture, `replay_request`, or `run_proof` against it
+unless the developer asks you to check or test it.
 
 **If the response includes `_notes` for an attached browser, follow them for an
 optional authenticated-state retest.** Only when its profile is still signed in,
@@ -329,9 +346,10 @@ navigate to `initialUrl`; if `customInjection` is present, run
 `test_user_script` with that script and `initialUrl`. When the existing capture
 has enough data, replay and prove every required request. Do not clear
 cookies or force another sign-in. Treat an unavailable or inconclusive retest as
-advisory and do not block the completed provider. Ask whether the developer
-wants to keep the session for further edits; call `dispose_browser` only after
-they confirm.
+advisory and do not block the completed provider. Don't ask whether to close the
+browser. Mention once in the final summary that it stays open for provider
+changes and you can close it on request; call `dispose_browser` only when the
+developer says so.
 
 <!-- topic: never-do -->
 ## Things to never do

package/skill/builder-mode.md

@@ -1,186 +1,51 @@
 # Builder mode
 
-Reclaim provider-authoring tools run against the Builder backend: generated
-Builder API tools, credential and verification helpers, and browser authoring
-tools.
+Provider-authoring and verification tools for the Builder backend.
 
-**A provider is a recipe for extracting a data point from a site. A
-verification is an end-user session that proves a data point with a provider.
-Never call a provider a "verification."**
+**A provider is a recipe for extracting a data point from a site. A verification is an end-user session that proves a data point with a provider. Never call a provider a "verification."**
 
-## What the developer wants
+## Routing
 
-- **"Add Reclaim to my app" or similar:** call `start_integration` first and
-  follow the plan it returns. Don't ask what they want to do with the result.
-- **A claim they describe** (for example, "prove the user is over 18 on
-  example.com"): build a new org-private provider for exactly that claim. See
-  "Choose the provider".
-- **Intent unclear:** ask one short question.
+- "Add Reclaim to my app" or similar: call `start_integration` first and follow its plan. Don't ask what they want to do with the result.
+- A claim they describe (for example, "prove the user is over 18 on example.com"): build a new org-private provider for exactly that claim. Use an existing provider only when they name one or ask to reuse one (topic `discover`).
+- Intent unclear: ask one short question.
 
-### Work order
+## Authoring rules
 
-Do the steps that need the developer first: sign in to Builder, attach the
-browser, capture, and prove the provider. They show early whether a proof is
-possible on the site. Write app code after the proof works, or while you wait
-on the developer.
+- Do the steps that need the developer first (sign in, attach the browser, capture, prove). Write app code after the proof works, or while you wait.
+- Call `attach_browser()` with no arguments. Don't ask which browser to use.
+- Propose only the data points the claim needs.
+- Provider versions are immutable: every change creates a new version.
 
-### Asking the developer
+## Asking the developer
 
-When you need an answer or an action from the developer before you can
-continue, end your turn with the question. Don't ask a blocking question
-through a background or asynchronous question tool: the developer may never
-see it. Put every link they need, such as a sign-in or verification URL, in
-that same message.
+- When you need an answer or an action, end your turn with the question. Don't use a background or asynchronous question tool: the developer may never see it.
+- Put every link they need, such as a sign-in or verification URL, in that same message.
+- Ask each question once. Act on the answer; don't ask again.
 
-### Choose the provider
+## Permission blocks
 
-Default: build a new provider for the claim the developer described. Use an
-existing provider only when they name one or ask to reuse one.
+When a permission check blocks a tool call or command:
 
-With an existing provider, use only the data points the developer asked for.
-Show the developer only those, collect only the inputs they need, and read
-only those from results. Ignore the provider's other data points.
-
-Make your own copy when it needs any change, for example it lacks a requested
-data point, requires inputs the developer didn't ask for, or extracts a value
-differently:
-
-- Your org owns it: create a new provider version.
-- Another org owns it: `create_provider`, then `create_provider_version` from a
-  copy of its config, trimmed to the requested data points.
-
-Requirement ambiguous (site, account, or value): ask one concise question.
-Don't guess.
-
-A provider used as-is is published and ready. Don't capture, `replay_request`,
-or `run_proof` against it unless the developer asks.
-
-### Try a provider without an app
-
-Session creation returns 409 while the org has no callback subscription.
-`read_callback_events` creates the org's pull listener, which satisfies that
-check and holds results for you to read. No tunnel or public URL is needed.
-
-1. Call `read_callback_events`.
-2. `create_verification_session`, then give the developer `verificationUrl`.
-3. Poll `get_verification_session` until it is terminal.
-   `list_verification_events` shows progress. Don't read the hosted
-   verification page for progress: it streams the site as an image, so text
-   and DOM checks of it come back empty.
-4. Call `read_callback_events({ sessionId })` for the verified result.
-
-When you set up a new provider build, call `check_attestor` once. If it fails,
-tell the developer before they spend time on the build.
+1. Don't retry it or work around it.
+2. In one message, name the blocked tool or command, what it does, and what approving it means.
+3. Ask for approval in words that name that exact action, for example: "Approve running `npm run dev` to start the example app?" A vague question doesn't cover it.
 
 ## Secrets
 
-- Never print, echo, or ask the developer to paste an org key (`rorg_…`) or
-  private key.
-- `issue_org_token` writes the key to the project's env file
-  (`RECLAIM_ORG_SECRET`) and returns only its last four characters. Session
-  and org-token tools use that key when you omit `orgToken`.
-- `issue_credentials` and `import_credentials({ keyFile })` write the proof
-  owner key to the env file. Use these tools, not shell commands that read
-  secret files.
-
-## Integrating into an app
-
-Call `start_integration` and follow its order: prove the provider first, then
-write app code. Read `how_it_works({ topic: "integration" })`
-for the HTTP session workflow, the `api=2` boundary, result verification, and
-TEE binding. Edit the app with your file tools. Use the HTTP API
-(`POST /verifications/sessions`, open `verificationUrl`, poll
-`GET /verifications/sessions/{sessionId}`, read the callback) rather than
-`@reclaimprotocol/client`. The only exception is `results.receive` on the
-callback, or when the developer asks for the client package.
-
-The app's frontend renders every state and every failure, never only a
-spinner. Follow "UI states" in `how_it_works({ topic: "integration" })`. The
-callback route responds `error.retryable ? 503 : 200` for a thrown
-`ResultVerificationError`; a result that failed verification gets 2xx.
-
-For local development, call `proxy_callback_events({ port, path })` to forward
-events to the app's callback route on localhost. The local listener works only
-while this MCP server runs. It keeps events in order per session and retries
-a session the app rejects with backoff, so other sessions keep flowing. When
-its status lists `blocked` sessions, read that session's callback route
-response and logs, and fix the app. Production needs a webhook:
-`create_org_callback_subscription` with the deployed app's public URL. Without
-one, session creation returns 409.
-
-Management tools (`list_orgs`, `create_org_callback_subscription`,
-`issue_org_token`) use the developer's sign-in. Session tools
-(`create_verification_session`, `get_verification_session`,
-`list_verification_events`, `list_verification_deliveries`,
-`retry_verification_callback`, `read_callback_events`,
-`proxy_callback_events`) are the production API and use the org key.
-
-**Existing `@reclaimprotocol/js-sdk` projects.** If `package.json` depends on
-`@reclaimprotocol/js-sdk`, ask first:
-
-> This project uses `@reclaimprotocol/js-sdk`. Keep it (I switch this MCP
-> server to legacy devtools mode), or migrate to the Builder HTTP API?
-
-- **Keep:** `set_devtools_mode({ mode: "old" })`, then tell them to restart or
-  reconnect the MCP server. An explicit `USE_OLD_DEVTOOLS` env var overrides
-  it. After the restart, read `get_js_sdk_integration_guide`.
-- **Migrate:** stay in Builder mode and follow topic `integration`.
-
-## Authoring a provider
-
-Provider versions are immutable. Every change creates a new semantic version
-(default: patch bump; larger only when the developer directs). Never use an
-in-place update or archive tool.
-
-**The flow:** `attach_browser` → `start_capture` ⇒ `captureId` → sign in →
-navigation script (`test_user_script` with `keep: true`) → capture through the
-script → `find_requests_containing` → `propose_provider` ⇒ `draftId` →
-`replay_request` → `run_proof` → `create_provider_version_from_capture` →
-`publish_provider_version` (private) or `submit_provider_version_for_review`
-(public). Get the checklist from `how_it_works({ topic: "overview" })`.
-
-- **Data points:** propose only values the claim needs, usually one or two.
-  Never add identity or profile fields. Name each for what it proves.
-- **Browser:** call `attach_browser()` with no arguments. It opens a visible
-  local browser with the persistent Reclaim profile, and falls back to Chrome
-  for Testing itself when no installed browser can be attached. Don't ask
-  which browser or who signs in. Use another `mode` only when that fails too,
-  or when the developer explicitly asks for it (topic `browser`). Tell the
-  developer once, as a side note, that a shareable link can be set up if a
-  volunteer is helping them sign in; don't ask about it or set it up unless
-  they ask.
-- **Public endpoints:** after `replay_request` succeeds, re-run it with
-  `withoutSecrets: true`. If the value still extracts, the endpoint is public
-  and the proof binds to nobody. Find an auth-bound request.
-- **Country:** `run_proof` sends the attestor's request from the developer's
-  own IP country, which is what `{{DYNAMIC_GEO}}` becomes when they verify;
-  `egress` in the result says which country. If a site that serves one
-  country (for example, a US airline) blocks the attestor, retry once with
-  `geoLocation: "US"`. If that verifies, pin it with
-  `update_draft({ geoLocation: "US" })` so the published version goes out
-  from there too.
-- **Drafting limits** (topics `draft`, `params`): never `hash` a value that
-  also appears in the request URL. A param named with `SECRET` may appear in a
-  URL only within a small character budget (2 under `key-update`, 12 under
-  `zk`).
+- Never print, echo, or ask the developer to paste an org key (`rorg_…`) or private key.
+- `issue_org_token` writes the org key to the project's env file (`RECLAIM_ORG_SECRET`) and returns only its last four characters. `issue_credentials` and `import_credentials({ keyFile })` write the proof-owner key there. Use these tools, not shell commands that read secret files.
 
 ## Evidence contract
 
-Tool results are the source of truth. Never say a browser attached, a user
-signed in, a request was captured, a proof passed, or a version was created or
-published unless a tool result says so.
+Tool results are the source of truth. Never say a browser attached, a user signed in, a request was captured, a proof passed, or a version was created or published unless a tool result says so.
 
-Treat every ID, version, URL, and value as opaque: copy it from the latest tool
-result. Never invent or reconstruct one. When state is unclear, call the
-relevant get/list tool or `how_it_works`. State uncertainty plainly.
+Treat every ID, version, URL, and value as opaque: copy it from the latest tool result. Never invent or reconstruct one. When state is unclear, call the relevant get/list tool or `how_it_works`. State uncertainty plainly.
 
-**Guide:** `how_it_works({})` lists topics. Fetch only the one for your next
-step.
+## Guide
 
-**Authentication:** call `get_me`. On 401, `authenticate({})` returns `code`
-and `attachUrl`. Give the developer the URL, then poll `authenticate({ code })`
-until LINKED (topic `auth`).
+`how_it_works({})` lists topics. Fetch only the one for your next step:
 
-**Backend mode:** `get_devtools_mode` reports the active mode.
-`set_devtools_mode` persists a switch to `~/.reclaim/config.json`, effective on
-the next server start. An explicit `USE_OLD_DEVTOOLS` env var wins.
+- `overview`: authoring checklist; `prove`, `publish`, `browser`: the details behind each step.
+- `integration`: app integration, trying a session without an app, existing `@reclaimprotocol/js-sdk` projects.
+- `auth`: sign-in (`get_me`, then `authenticate` on 401) and backend mode.

package/skill/old-mode.md

@@ -1,100 +1,45 @@
-Reclaim provider-authoring tools, running against the OLD DEVTOOLS backend —
-intentionally reduced: no generated API tools, no organizations, no public
-review flow. Only GET/POST requests can be captured into providers.
+# Legacy devtools mode
 
-**A `provider` is a recipe for extracting a data point from a site. A
-`verification` is an end-user session that proves a data point using one. Never
-call a provider a "verification."**
+Provider-authoring tools for the old devtools backend. The tool surface is reduced: no generated API tools, no organizations, no public review. Only GET and POST requests can be captured.
 
-**Provider versions are immutable.** Every recipe or configuration change
-creates a new semantic version. Default to a patch bump; use a major/minor bump
-or exact higher version when the user directs it. Never edit an existing
-version.
+**A `provider` is a recipe for extracting a data point from a site. A `verification` is an end-user session that proves a data point with a provider. Never call a provider a "verification."**
+
+## Routing
+
+- A provider found with `get_me_providers` or `get_provider_info` is published and usable as-is. Don't capture, replay, or prove it unless the developer asks.
+- Before using a provider, found or just created, ask once how they want to use it (try it, integrate it, or build a new app), unless they already said. Topic `publish` has the options.
+- Call `attach_browser()` with no arguments. Don't ask which browser to use.
+
+## Asking the developer
+
+- When you need an answer or an action, end your turn with the question and every link they need. Don't use a background or asynchronous question tool: the developer may never see it.
+- Ask each question once. Act on the answer; don't ask again.
+
+## Permission blocks
+
+When a permission check blocks a tool call or command:
+
+1. Don't retry it or work around it.
+2. In one message, name the blocked tool or command, what it does, and what approving it means.
+3. Ask for approval in words that name that exact action, for example: "Approve running `npm run dev` to start the demo server?"
+
+## Authoring rules
+
+- Provider versions are immutable: every change creates a new version, default a patch bump. Never edit an existing version.
+- Publishing without `providerId` registers a new provider. Check `get_me_providers` first to avoid duplicates.
+- `reclaim_authenticate` authorizes this mode. On an auth error, run it again (topic `auth`).
 
 ## Evidence contract
 
-Tool results are the source of truth. Never say that a browser attached, a user
-logged in, a request was captured, a proof passed, or a version was created or
-published unless the corresponding tool result says it happened. A planned tool
-call is not a completed action.
-
-Treat every ID, semantic version, URL, request value, and error as opaque: copy
-it from the latest tool result exactly. Never invent, autocomplete, reconstruct,
-shorten, or reuse one from memory. When state is missing or ambiguous, inspect
-it with the relevant get/list/status tool or call `how_it_works` before
-answering. State uncertainty plainly instead of guessing.
-
-**Ask blocking questions by ending your turn.** When you need an answer or an
-action from the developer before you can continue, end your turn with the
-question and every link they need. Don't use a background or asynchronous
-question tool for it: the developer may never see it.
-
-**Use the guide as needed.** Call `how_it_works({})` for its topic index, then
-fetch only the topic relevant to the next tool call.
-
-**Open the browser without asking.** Call `attach_browser()` with no
-arguments: it opens a visible browser on the developer's machine with the
-persistent Reclaim profile, and falls back to Chrome for Testing itself when
-no installed browser can be attached. Don't ask which browser or who signs in.
-Use another `mode` only when that fails too, or when the developer explicitly
-asks for it (topic `browser`). Tell the developer once, as a side note, that a
-shareable link can be set up if a volunteer is helping them sign in; don't ask
-about it or set it up unless they ask.
-
-**The flow:** `reclaim_authenticate` once → `attach_browser()` (no arguments: a
-visible local browser) → `start_capture` ⇒ **`captureId`** →
-drive the page (`navigate`,
-`wait_for_page`, `eval_in_page`) → inspect (`list_requests`, `get_request`,
-`find_requests_containing`) → `propose_provider` ⇒ **`draftId`** →
-`replay_request(captureId, draftId)` → `run_proof(captureId,
-draftId)` → `create_provider_version_from_capture`.
-
-`reclaim_authenticate` itself always uses a local Chrome over loopback CDP. It
-never uses the container, remote Builder, custom-CDP, or shared authoring
-browser; those choices begin only at `attach_browser` after dashboard sign-in.
-
-**Publishing and ownership:** with NO `providerId`, publish REGISTERS A NEW
-provider — re-running creates a duplicate. Pass a `providerId` from
-`get_me_providers` (the only provider-listing tool here) to add a version to an
-existing provider instead; you can only version a provider you own. For a
-multi-request provider pass `providers: [draftA, draftB, …]` so each becomes a
-parallel `requestData` entry on the one version.
-
-**Using a provider.** A provider found with `get_me_providers` or
-`get_provider_info` is published and usable as-is. Don't capture,
-`replay_request`, or `run_proof` against it unless the developer asks you to
-check or test it. Before using a provider, found or just created, ask once how
-they want to use it (skip this if they already said):
-
-> Want to (1) try it right now here, (2) integrate it into an existing backend
-> or frontend (this directory or another path), or (3) create a new app for it?
-
-Try it now → `scaffold_reclaim_demo_server` with its `providerId`. Integrate,
-or new app → `get_js_sdk_integration_guide`, then work in the path they named.
-
-**Two independent auth systems — don't confuse them.** `reclaim_authenticate`
-authorizes everything in this mode; its Firebase token is short-lived (~1h), so
-an auth error on publish or `get_me_providers` means re-run it.
-`authenticate_builder` covers only two Builder-exclusive features: allocating a
-remote browser (`attach_browser mode="builder"`) and
-`list_builder_organizations`. It authorizes nothing else. `get_devtools_mode`
-reports both.
-
-**Never prove a public endpoint.** After `replay_request` succeeds, re-run it
-with `withoutSecrets: true`. If the value still extracts, the endpoint is public
-and the proof binds to nobody — find an auth-bound request instead.
-
-**Templating:** bare `{{name}}` placeholders are extracted from the response.
-Values the CONSUMER supplies at verification time use `{{context_<name>}}` —
-this backend does NOT support the builder's dotted `{{context.<name>}}` form.
-
-**Diagnosing a session:** `session_analytics_logs` returns a session's
-milestone events; `session_logs` returns the log entries the SDK emitted, each
-with its event type — that is where a failed match, redaction, or claim shows
-up. Both take a `sessionId`; see topic `troubleshooting` for how to read them.
-
-**Backend mode:** the BUILDER backend (generated API tools, orgs, verification
-sessions, public review) is one switch away. `get_devtools_mode` reports the
-active mode and why; `set_devtools_mode` persists a switch to
-`~/.reclaim/config.json`, effective on the NEXT server start. An explicit
-`USE_OLD_DEVTOOLS` env var wins over the persisted choice.
+Tool results are the source of truth. Never say a browser attached, a user logged in, a request was captured, a proof passed, or a version was created or published unless a tool result says so. A planned call is not a completed action.
+
+Treat every ID, version, URL, request value, and error as opaque: copy it from the latest tool result. Never invent, reconstruct, or reuse one from memory. When state is unclear, call the relevant get/list/status tool or `how_it_works`. State uncertainty plainly.
+
+## Guide
+
+`how_it_works({})` lists topics. Fetch only the one for your next step:
+
+- `overview`: the authoring checklist.
+- `auth`: sign-in, and backend mode (switching to Builder).
+- `publish`: ownership, multi-request providers, using a provider.
+- `troubleshooting`: `session_analytics_logs` and `session_logs` for a failed session.