@reclaimprotocol/agent 0.1.38 → 0.1.40

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
 

package/skill/verification-client-integration.md

@@ -22,26 +22,44 @@ configuration, and callback conventions. Complete the integration in its codebas
 relevant checks. The MCP tools configure Builder resources; your file tools
 edit the app.
 
-If the app depends on `@reclaimprotocol/js-sdk`, ask the developer first:
-keep it (`set_devtools_mode({ mode: "old" })`, then they restart the MCP
-server), or migrate to the session flow below. When migrating, remove
-`@reclaimprotocol/js-sdk` and replace its `ReclaimProofRequest` and
-`verifyProof` calls.
+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, remove `@reclaimprotocol/js-sdk`, and
+  replace its `ReclaimProofRequest` and `verifyProof` calls with the session
+  flow below.
 
 1. `get_devtools_mode` confirms Builder mode. `get_me` or `authenticate` signs
    in the developer. Find the organization with `list_orgs`; call `create_org`
    only when they want a new one.
 2. Receive callbacks. Local development: call
    `proxy_callback_events({ port, path })` to forward the org's events to the
-   app's callback route on localhost; no public URL. Deployed app (required for
-   production): register a
+   app's callback route on localhost; no public URL. 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. Deployed app (required
+   for production): register a
    public callback URL with `create_org_callback_subscription`, including
    all five session-ending events. If the
    app needs encrypted results or session binding, call `issue_org_keypair`
    (`encryptResults: true` for encrypted results). It writes the private key to
    the backend's env file and registers only the public key. It returns 409
-   when the org already has a different key: ask the developer for that key
-   rather than replacing it.
+   when the org already has a different key. Check `get_org_keypair` first;
+   when the org has a key pair, the app must pass `orgEthPrivateKey` to
+   `results.receive`, with or without encryption: it decrypts results and
+   verifies TEE-bound proofs. Ask the developer to choose: reuse the key (they
+   put its private key in the backend's server env file as
+   `RECLAIM_ORG_ETH_PRIVATE_KEY` themselves, never in chat), rotate it with
+   `issue_org_keypair` and `replace: true` (apps holding the old key stop
+   working with new results; the old key is saved to `<envFile>.backup`, so
+   tell the developer that path), or turn encryption off with
+   `update_org_keypair({ orgId, canEncryptResult: false })`, which keeps the
+   key. Name the exact action when you ask.
 3. Org key: reuse the `RECLAIM_ORG_SECRET` the app already has. Otherwise an
    organization owner calls `issue_org_token`. It writes the key to the
    project's env file (default `.env`, variable `RECLAIM_ORG_SECRET`) and
@@ -254,6 +272,18 @@ Builder snapshots the organization's most recently updated active theme. A
 localized consent block tells supported clients to show consent before the
 first provider. Branding and theme data don't affect proof trust.
 
+## 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.
+4. Call `read_callback_events({ sessionId })` for the verified result.
+
 ## Call the direct Builder API
 
 In `api=2` mode, send the registered client UUID in `x-reclaim-vc-id` on every

package/src/mcp/api/operations.gen.ts

@@ -1,5 +1,5 @@
 // AUTO-GENERATED by packages/app/scripts/mcp-tools-gen.ts
-// from packages/app/openapi.yaml (spec v0.1.0, source sha256:96339e8dff91).
+// from packages/app/openapi.yaml (spec v0.1.0, source sha256:ecdb0ee6d82e).
 // The hash catches drift the version misses (a spec can change without a
 // version bump) — do not remove it as "redundant" with the version.
 // Run `npm run openapi:gen --workspace=packages/app` to regenerate. Do not edit by hand.
@@ -5116,7 +5116,7 @@ export const MCP_TOOLS = {
 		annotations: {"destructiveHint":true,"idempotentHint":true,"openWorldHint":false},
 	},
 	"DeleteOrgKeypair": {
-		description: "Clear the organization's encryption keypair\n\nRemoves the organization's result encryption public key. Results are then delivered unencrypted until you set a new key. Run it only when the developer asks.",
+		description: "Clear the organization's encryption keypair\n\nRemoves the organization's result encryption public key. Results are then delivered unencrypted until you set a new key. Run it only when the developer asks. To rotate the key, use `issue_org_keypair` with `replace: true` instead of deleting first.",
 		inputSchema: toZod({
 			"type": "object",
 			"properties": {
@@ -6700,7 +6700,7 @@ export const MCP_TOOLS = {
 		annotations: {"destructiveHint":true,"idempotentHint":true,"openWorldHint":false},
 	},
 	"SetOrgKeypair": {
-		description: "Set (or rotate) the organization's encryption keypair\n\nRegisters the organization's result encryption public key and turns on encrypted result delivery. Send only the public key; the private key stays with the developer. If the organization already has a different key, the call returns 409 unless you pass replace: true. Pass it only when the developer asked to rotate the key, because results encrypted to the old key can no longer be decrypted. Setting the same key again succeeds.",
+		description: "Set (or rotate) the organization's encryption keypair\n\nRegisters the organization's result encryption public key and turns on encrypted result delivery. Send only the public key; the private key stays with the developer. If the organization already has a different key, the call returns 409 unless you pass replace: true. Pass it only when the developer asked to rotate the key, because results encrypted to the old key can no longer be decrypted. Setting the same key again succeeds. To generate and store the private key in the project, use `issue_org_keypair` instead.",
 		inputSchema: toZod({
 			"type": "object",
 			"properties": {
@@ -6985,6 +6985,54 @@ export const MCP_TOOLS = {
 		}),
 		annotations: {"openWorldHint":false},
 	},
+	"UpdateOrgKeypair": {
+		description: "Turn result encryption on or off\n\nTurns result encryption on or off for the organization's existing key pair without changing the key. Use it when the developer asks to turn encryption on or off. When on, the app's callback needs `orgEthPrivateKey` to decrypt results. Returns 404 when the organization has no key pair; create one with `issue_org_keypair`.",
+		inputSchema: toZod({
+			"type": "object",
+			"properties": {
+				"params": {
+					"type": "object",
+					"properties": {
+						"orgId": {
+							"type": "string",
+							"format": "uuid"
+						}
+					},
+					"required": [
+						"orgId"
+					],
+					"additionalProperties": false
+				},
+				"query": {
+					"type": "object",
+					"properties": {
+
+					}
+				},
+				"body": {
+					"type": "object",
+					"additionalProperties": false,
+					"description": "Body for `PATCH /orgs/{orgId}/keypair`.",
+					"required": [
+						"canEncryptResult"
+					],
+					"properties": {
+						"canEncryptResult": {
+							"type": "boolean",
+							"description": "Set to true to encrypt results to the organization's public key. Set to false to deliver results as plaintext."
+						}
+					}
+				}
+			},
+			"required": [
+				"params",
+				"query",
+				"body"
+			],
+			"additionalProperties": false
+		}),
+		annotations: {"openWorldHint":false},
+	},
 	"UpdateProvider": {
 		description: "Update a provider\n\nUpdates a provider's metadata, such as title, description, or tags. Partial update — pass only the fields to change. Requires active membership. To change the recipe (initialUrl or requests), cut a new version with create_provider_version instead.",
 		inputSchema: toZod({

package/src/mcp/instructions.ts

@@ -59,7 +59,8 @@ const TOPIC_SUMMARIES: Record<string, string> = {
 	'overview': 'Terminology, your stance, and the authoring checklist.',
 	'contributions': 'Contributing a public provider as a volunteer: the '
 		+ 'candidate-and-review workflow and the extra rules it adds.',
-	'auth': 'Signing in to the backend, and which token authorizes what.',
+	'auth': 'Signing in to the backend, which token authorizes what, and '
+		+ 'the backend mode (Builder or legacy devtools).',
 	'devtools-migration': 'Importing a public legacy provider with the same '
 		+ 'UUID.',
 	'browser': 'The default local browser, the opt-in modes (attach, the '
@@ -71,15 +72,16 @@ const TOPIC_SUMMARIES: Record<string, string> = {
 		+ 'drafted shape.',
 	'params': 'Extracted vs consumer-supplied vs secret params, the URL '
 		+ 'character budget, and runtime resolution.',
-	'prove': 'replay_request, the mandatory auth-bound check, run_proof, and '
-		+ 'diagnosing failures.',
+	'prove': 'replay_request, the mandatory auth-bound check, run_proof '
+		+ '(including the egress country), and diagnosing failures.',
 	'publish': 'Creating a provider, provider versions, multi-request '
 		+ 'providers, and going live.',
-	'discover': 'Reusing existing providers: finding, resolving, and '
-		+ 'creating a verification session.',
-	'integration': 'After start_integration: org key, callback (local '
-		+ 'proxy_callback_events or deployed webhook), frontend and backend '
-		+ 'over the HTTP session API; `api=2` and result verification.',
+	'discover': 'Reusing existing providers: finding, resolving, copying one '
+		+ 'that needs changes, and creating a verification session.',
+	'integration': 'After start_integration: org key and keypair, callback '
+		+ '(local proxy_callback_events or deployed webhook), frontend and '
+		+ 'backend over the HTTP session API, js-sdk projects, trying a '
+		+ 'session without an app; `api=2` and result verification.',
 	'user-script': 'The navigation script (jsUserScripts): sign-in redirect, '
 		+ 'multi-page walk, test_user_script with keep.',
 	'interception': 'injectionType / interceptorType, live interception, the '