@reclaimprotocol/agent 0.1.39 → 0.1.40

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@reclaimprotocol/agent",
 	"title": "Reclaim Agent",
-	"version": "0.1.39",
+	"version": "0.1.40",
 	"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.40",
 		"@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.

package/skill/start-integration.md

@@ -4,7 +4,7 @@ Follow this plan end to end. Mark each step done as you go. Do not ask the devel
 
 **Order.** Do the steps that need the developer first: sign in to Builder, attach the browser, capture, and prove the provider (step 2). These need the developer at the browser, and they show early whether a proof is possible on this site. Write app code (step 3) after the proof works, or while you wait on the developer. Never spend a long stretch on app code before the developer has signed in and the browser is attached.
 
-**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 use background or asynchronous question tools for blocking questions: the developer may never see them. Put every link the developer needs, such as a sign-in or verification URL, in that same message.
+**Asking the developer.** When you need an answer or an action, end your turn with the question. Don't use background or asynchronous question tools: the developer may never see them. Put every link they need in that same message. Ask each question once.
 
 ## 1. Sign in and pick the organization
 
@@ -15,6 +15,7 @@ Follow this plan end to end. Mark each step done as you go. Do not ask the devel
 <!-- ifnot:orgId -->
 - [ ] Call `list_orgs`. Use the only organization, or ask the developer which one when there are several.
 <!-- endif -->
+- [ ] Call `get_org_keypair`. If the org has a key pair (any `canEncryptResult`), the app's callback must pass `orgEthPrivateKey` to `results.receive`: it decrypts encrypted results and verifies TEE-bound proofs. In the same message as any other step 1 question, ask the developer to choose one: reuse the existing key (they put its private key in the app's server env file as `RECLAIM_ORG_ETH_PRIVATE_KEY` themselves, never in chat), or rotate it (`issue_org_keypair` with `replace: true`; other apps holding the old key stop working with new results). If `canEncryptResult` is true, they can also turn encryption off with `update_org_keypair({ orgId, canEncryptResult: false })`, which keeps the key. Name the exact action in your question. Act on the answer in step 3.
 
 ## 2. Get the provider and prove it
 
@@ -39,7 +40,7 @@ Build a new organization-private provider for exactly "{{goal}}". Do not search
 - [ ] Call `replay_request`, then `replay_request` with `withoutSecrets: true` to confirm the request is auth-bound.
 - [ ] Call `run_proof`. It creates a local test signing key if none exists; tell the developer once afterwards.
 - [ ] Call `create_provider_version_from_capture`. It publishes the kept script as `jsUserScripts`. Follow its `_notes`, then publish the version.
-- [ ] Call `dispose_browser` after asking the developer.
+- [ ] Don't ask whether to close the browser. Mention once in your 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.
 <!-- endif -->
 
 ## 3. Set up the app
@@ -65,21 +66,23 @@ Do this yourself, not in a subagent.
 
 - [ ] Call `create_example_app` with the workspace root you were started in as `projectDir`. It writes the example there and sets its backend to the latest `@reclaimprotocol/client`. Don't clone the repository or create a subdirectory: commands you run inside a clone count as running external code, and permission checks may block them.
 - [ ] Call `issue_org_token` with the same `projectDir` and `envFile: "packages/backend/.env"`.
-- [ ] Only when the developer asks for session binding or encrypted results: call `issue_org_keypair` with the same `projectDir` and `envFile` (add `encryptResults: true` for encrypted results). It writes `RECLAIM_ORG_ETH_PRIVATE_KEY` and registers the public key. Then pass `orgEthPrivateKey: process.env.RECLAIM_ORG_ETH_PRIVATE_KEY` to `reclaim.sessions.create` in `packages/backend/src/routes/verifications.ts` (binding) and to `reclaim.results.receive` in `packages/backend/src/routes/callback.ts` (decryption and TEE proof checks), and add an empty `RECLAIM_ORG_ETH_PRIVATE_KEY=` line to `packages/backend/example.env`.
-- [ ] From the workspace root, run `npm install`, then `npm run dev`. The backend listens on port 3000; the app opens at <http://localhost:5173>. If a permission check blocks either command, don't work around it: end your turn, say which command was blocked and that it installs and runs the Reclaim example app, and ask the developer to approve it.
-- [ ] Call `proxy_callback_events({ port: 3000, path: "/reclaim/callback" })`.
-- [ ] Skip the rest of this step. In step 4, the provider goes in `packages/backend/config.json`: replace the example entry with `{ "id": "<provider ID>", "name": "<what it proves>" }`, then restart the backend, because it reads the file at startup.
+- [ ] Key pair, by the step 1 answer. No key pair on the org and the developer wants none: skip. Reuse: the developer has put the key in `packages/backend/.env`. Rotate, or no key pair and the developer asks for binding or encrypted results: call `issue_org_keypair` with the same `projectDir` and `envFile` (`encryptResults: true` for encrypted results, `replace: true` to rotate). It writes `RECLAIM_ORG_ETH_PRIVATE_KEY` and backs up a replaced key to `<envFile>.backup`; tell the developer that path (never the key). Turn encryption off with `update_org_keypair`. The example's callback (`packages/backend/src/routes/callback.ts`) passes `RECLAIM_ORG_ETH_PRIVATE_KEY` to `reclaim.results.receive`; if it doesn't, add `orgEthPrivateKey: process.env.RECLAIM_ORG_ETH_PRIVATE_KEY` there. For session binding, also pass it to `reclaim.sessions.create` in `packages/backend/src/routes/verifications.ts`.
+- [ ] From the workspace root, run `npm install`. Then follow the `next` array that `create_example_app` returned for the dev command, ports, log location, notes, and the `proxy_callback_events` call. Don't assume default ports.
+- [ ] Run the dev server in the background with its output redirected to a log file, and read that file for backend output. Don't depend on the shell's own output.
+- [ ] After you restart the backend, its in-memory store is empty. Ask the developer for a new verification; don't retry the old session.
+- [ ] If a permission check blocks a command, follow "Permission blocks" in the server instructions.
+- [ ] Skip the rest of this step. In step 4, the provider goes in `packages/backend/config.json`: replace the example entry with `{ "id": "<provider ID>", "name": "<what it proves>" }`, then restart the backend, because it reads the file at startup. Then ask for a new verification.
 
 **Existing app.** Add verification to it:
 
 - [ ] Detect the app's framework and package manager from the repository, and use them. Read `how_it_works({ topic: "integration" })`.
-- [ ] Call `issue_org_token` with the organization, this project's absolute path, and the server env file. It writes the key to that file and never returns it. Never print or commit the key. Confirm the env file is in `.gitignore`.
+- [ ] Call `issue_org_token` with the organization, this project's absolute path, and the server env file. It writes the key to that file and never returns it; it backs up a replaced value to `<envFile>.backup`, so tell the developer that path. Never print or commit the key. Confirm the env file is in `.gitignore`.
 - [ ] Add a backend route that creates a verification session (`POST /verifications/sessions`) and returns `verificationUrl`. Read the provider ID from server config (an env variable such as `RECLAIM_PROVIDER_ID`), so the route works before the provider exists.
-- [ ] Only when the developer asks for session binding or encrypted results: call `issue_org_keypair` with the server env file (`encryptResults: true` for encrypted results), and pass `orgEthPrivateKey` from that env variable to `sessions.create` and `results.receive`.
+- [ ] Key pair, by the step 1 answer. Reuse: the developer has put the key in the server env file. Rotate, or no key pair and the developer asks for binding or encrypted results: call `issue_org_keypair` with the server env file (`encryptResults: true` for encrypted results, `replace: true` to rotate). It backs up a replaced key to `<envFile>.backup`; tell the developer that path (never the key). Turn encryption off with `update_org_keypair`. Whenever the org has a key pair, pass `orgEthPrivateKey` from `RECLAIM_ORG_ETH_PRIVATE_KEY` to `sessions.create` and `results.receive`.
 - [ ] Add a callback route that verifies each result with `results.receive` from `@reclaimprotocol/client`, then stores only the requested data points. Store every failure on the verification session record and log it server-side: a failure event (`verification_rejected`, `verification_error`, `verification_cancelled`, `session_expired`), or a thrown `ResultVerificationError` (`error.reason` plus each failing proof's `reason`). Respond `error.retryable ? 503 : 200`. A result that failed verification gets 2xx, because retrying can't fix it. Read the exact pattern in `how_it_works({ topic: "integration" })`.
 - [ ] Add a status route the frontend polls. It returns the stored status, data points, and failure reason. While the app has no result, it also reads `GET /verifications/sessions/{sessionId}`, so a session that ended in Builder never stays pending.
 - [ ] Add a frontend Verify button that opens `verificationUrl`, and render every state in "UI states" in `how_it_works({ topic: "integration" })`: idle, waiting in the other tab, verifying, verified (with the data points), failed (plain-language reason and **Try again**), and expired or cancelled (**Try again**). Never leave a spinner as the only feedback.
-- [ ] Start the app. Call `proxy_callback_events({ port, path })` with the callback route's port and path. It forwards the org's verification events to that route on localhost, with no public URL.
+- [ ] Start the app in the background with output redirected to a log file. Call `proxy_callback_events({ port, path })` with the callback route's port and path. It forwards the org's verification events to that route on localhost, with no public URL.
 
 ## 4. Wire the provider and test end to end