@reclaimprotocol/agent 0.1.33 → 0.1.35

package/skill/builder-mode.md

@@ -1,146 +1,148 @@
 # Builder mode
 
-Reclaim provider-authoring tools run against the Builder backend. They include
-generated Builder API tools, credential and verification helpers, and browser
-authoring tools.
-
-## Claimant-facing Builder sessions
-
-This integration is separate from provider authoring.
-
-**Using a provider.** A provider found with `providers`, `discover_resolve`, or
-another lookup 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 whether they just want
-to try it or want it in an app (skip this if they already said):
-
-> Want to (1) just try it right now, (2) integrate it into an existing backend
-> or frontend (this directory or another path), or (3) create a new app for it?
-
-- **Just try it:** no app or client package, but the same production API the
-  app will use. You need an org API key (`rorg_…`): reuse one the developer
-  already has, else `issue_org_token` (owner only; the key is shown once).
-  Session creation returns 409 while the org has no callback subscription, and
-  the result is only stored for subscriptions to the event the session ends
-  with. If the org has none, register a temporary one for all five ending
-  events with `create_org_callback_subscription` (for example, a tunnel to a
-  local listener that saves the body it receives). Then call
-  `create_verification_session` with `orgToken`, give the developer
-  `verificationUrl` to open, poll `get_verification_session` (with `orgToken`)
-  until it is terminal, and report the outcome: from the body your listener
-  received, or with `get_verification_result` (with `orgToken`), which only
-  works until the callback is delivered. Delete the temporary subscription with
-  `delete_org_callback_subscription` only after that: deleting it also deletes
-  its stored results.
-- **Integrate, or new app:** follow the setup below in the path they named.
-
-**Org API key vs. sign-in.** 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`) are the
-production API a backend calls, so they take the org key as `orgToken`
-(defaulting to this server's `RECLAIM_ORG_SECRET`). Never print the key back to
-the developer.
-
-**Prefer the HTTP API over `@reclaimprotocol/client`** for every option:
-create sessions with `POST /verifications/sessions`, open `verificationUrl`,
-poll `GET /verifications/sessions/{sessionId}`, and take the result on the
-callback. Use the client package only when the developer asks for it — the one
-exception is `results.receive`, to verify the result on your callback.
-
-When integrating into an app, read `how_it_works({ topic: "integration" })`,
-then configure the organization with generated tools (`list_orgs`,
-`create_org`, `create_org_callback_subscription`, and owner-only
-`issue_org_token`) and edit the app's frontend and backend with the coding
-agent's file tools. The guide
-covers the HTTP session workflow, exact `api=2` boundary, result
-verification, request-proof contract, and optional TEE binding. A URL without
-`api=2` stays on its existing legacy path.
-
-**Existing `@reclaimprotocol/js-sdk` projects.** If the app's `package.json`
-depends on `@reclaimprotocol/js-sdk`, ask the developer before doing anything
-else:
+Reclaim provider-authoring tools run against the Builder backend: generated
+Builder API tools, credential and verification helpers, and browser authoring
+tools.
+
+**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
+
+- **"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.
+
+### Choose the provider
+
+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.
+
+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.
+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.
+
+## 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`, then 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.
+
+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. 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 integration
-> (Builder HTTP API)?
-
-- **Keep js-sdk:** call `set_devtools_mode({ mode: "old" })`, then tell them to
-  restart or reconnect the MCP server; the switch applies on the next start. An
-  explicit `USE_OLD_DEVTOOLS` env var overrides it. After the restart, read
-  `get_js_sdk_integration_guide`.
-- **Migrate:** stay in Builder mode. Follow `how_it_works({ topic:
-  "integration" })` to replace `@reclaimprotocol/js-sdk` with the Builder
-  HTTP session flow and update the app's code.
-
-**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 versions are immutable in agent workflows.** 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
-use an in-place provider-version update or archive tool.
+> 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:** ask who signs in. The developer themselves: `dedicated` or
+  `attach` (local). Someone else, or a phone-only site: `container` (Docker,
+  free, shareable with `share_browser_view`) or `builder` (hosted,
+  **chargeable**). Say which costs money.
+- **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.
+- **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`).
 
 ## 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.
-
-**Use the guide as needed.** Call `how_it_works({})` for its topic index, then
-fetch only the topic relevant to the next tool call.
-
-**Authentication:** try `get_me` first. On 401, `authenticate({})` returns a
-device-pairing `code` + `attachUrl` — give the user the URL, then poll
-`authenticate({ code })` until LINKED. Tokens cache ~2 days.
-(→ `how_it_works({ topic: "auth" })`)
-
-**Ask who is doing the signing in, then offer a browser.** "Yourself, or does
-someone else need to log in?" decides half of `attach_browser`'s list. Doing it
-themselves → `dedicated` or `attach`, both local, neither shareable. Someone
-else, or a phone-only site → `container` (the Reclaim runtime in Docker, free,
-shareable with `share_browser_view`) or `builder` (hosted, no install,
-**chargeable**). Say which costs money, and say `container` exists at all:
-nobody guesses it.
-
-**The flow:** `attach_browser` (ask the developer which browser source — local
-Chrome, the Reclaim runtime in Docker, a remote Builder browser, or a CDP URL
-they supply) → `start_capture`
-⇒ **`captureId`** (the handle every browser/inspect tool takes first) → drive
-the page (`navigate`, `wait_for_page`, `eval_in_page`, `get_cookies`) → inspect
-(`list_requests`, `get_request`, `find_requests_containing`) →
-`propose_provider` ⇒ **`draftId`** (recipe + captured secrets, held server-side
-— secrets never enter the transcript) → `replay_request(captureId, draftId)` →
-`run_proof(captureId, draftId, ownerAddress)` → resolve a `providerId` →
-`create_provider_version_from_capture` (lands on the draft branch) →
-`publish_provider_version` (PRIVATE) or `submit_provider_version_for_review`
-(PUBLIC).
-
-**Reuse before create.** `create_provider_version_from_capture` needs a
-`providerId`. Search your existing providers with `providers` (by domain / data
-point) BEFORE calling `create_provider` — routing every run through
-`create_provider` is what stacks duplicates in "My providers".
-
-**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.
-
-**Two hard constraints when drafting** (details in topics `draft` / `params`):
-never `hash`/OPRF a value that also appears in the request URL; any param named
-with `SECRET` may be used in a URL only within a tiny TOTAL character budget (2
-under `key-update`, 12 under `zk`), checked at verification time.
-
-**Backend mode:** this server can instead run against the devtools backend with
-a reduced tool set. `get_devtools_mode` reports the active mode and why;
+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.
+
+**Guide:** `how_it_works({})` lists topics. Fetch only the one for your next
+step.
+
+**Authentication:** call `get_me`. On 401, `authenticate({})` returns `code`
+and `attachUrl`. Give the developer the URL, then poll `authenticate({ code })`
+until LINKED (topic `auth`).
+
+**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 over the
-persisted choice.
+the next server start. An explicit `USE_OLD_DEVTOOLS` env var wins.

package/skill/start-integration.md

@@ -0,0 +1,74 @@
+# Plan: let users prove "{{goal}}" in this app
+
+Follow this plan end to end. Mark each step done as you go. Do not ask the developer whether to integrate: integrating into this codebase is the goal.
+
+## 1. Sign in and pick the organization
+
+- [ ] Call `reclaim_authenticate` if you are not signed in. The developer approves in their browser.
+<!-- if:orgId -->
+- [ ] Use organization `{{orgId}}` for every call below.
+<!-- endif -->
+<!-- ifnot:orgId -->
+- [ ] Call `list_orgs`. Use the only organization, or ask the developer which one when there are several.
+<!-- endif -->
+
+## 2. Set up the app
+
+Setup does not need the provider, so it runs in parallel with step 3 or before it.
+
+**Delegation.** If you can run subagents, hand this step to one subagent and start step 3 now: step 3 needs the developer at the browser, step 2 does not. Give the subagent a self-contained brief:
+
+```
+Goal: let this app's users prove "{{goal}}" with Reclaim.
+Repository: <absolute path>. Organization: <org ID>.
+Task: do step 2 of the plan below and report the file paths you changed, the
+callback route URL, and the env variable that holds the provider ID.
+Do not build the provider. Never print or commit the org key.
+<paste the step 2 checklist>
+```
+
+Without subagents, do step 2 first.
+
+- [ ] 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`.
+- [ ] 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.
+- [ ] Add a callback route that verifies each result with `results.receive` from `@reclaimprotocol/client`, then stores only the requested data points.
+- [ ] Add a frontend Verify button that opens `verificationUrl`, and shows the stored result when it arrives.
+- [ ] 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.
+<!-- ifnot:providerIds -->
+- [ ] Call `check_attestor` once. If it fails, tell the developer before they spend time on the provider build: this machine cannot reach the attestor.
+<!-- endif -->
+
+## 3. Get the provider
+
+<!-- if:providerIds -->
+- [ ] Use these existing providers: {{providerIds}}. Read each with `get_provider` and keep only the data points "{{goal}}" needs. Show the developer and use only those; ignore the rest.
+- [ ] If a provider needs any change (a missing data point, inputs the developer didn't ask for, a different value), make your own copy as the server instructions describe ("Choose the provider"). Otherwise skip to step 4.
+<!-- endif -->
+<!-- ifnot:providerIds -->
+Build a new organization-private provider for exactly "{{goal}}". Do not search published providers first.
+
+- [ ] If the site, the account, or the value to prove is unclear, ask one concise question. Otherwise do not ask.
+- [ ] Choose the minimum data points: only the values the claim needs, usually one or two. Add no profile or identity extras.
+- [ ] If the developer names an existing provider, use only the data points they asked for and ignore the rest. If it needs any change, make your own copy: a new version when the organization owns it, otherwise a new organization provider from a copy of its config.
+- [ ] Call `how_it_works` with topics `overview`, `user-script`, `capture`, and `publish` before you start. Do not repeat their detail here.
+- [ ] Call `attach_browser` without `mode`, ask the developer which browser to use, then call it again with their choice. Use `start_capture` on the tab.
+- [ ] Open the sign-in page with `navigate`. The developer signs in; use `wait_for_login`.
+- [ ] Write the navigation script first. Signed out, it goes to the sign-in page. After sign-in, it visits each data page in order. It must stay correct across reloads.
+- [ ] Test it with `test_user_script` and `keep: true`. The kept script stays installed for every later navigation and is published with the provider version.
+- [ ] While the script drives the browser, find the request that returns each data point (`find_requests_containing`, then `analyze_request_constraints`).
+- [ ] Call `propose_provider` with only the needed data points.
+- [ ] Call `replay_request`, then `replay_request` with `withoutSecrets: true` to confirm the request is auth-bound.
+- [ ] Call `resolve_owner_key`, then `run_proof`.
+- [ ] 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.
+<!-- endif -->
+
+## 4. Wire the provider and test end to end
+
+- [ ] Set the provider ID in the app's server config.
+- [ ] Confirm the callback route is forwarding: `proxy_callback_events` with no `stop` returns its status.
+- [ ] Tell the developer exactly how to test: open the app, click Verify, sign in, and see the stored result.
+- [ ] After they click Verify, read the delivered events from `proxy_callback_events` status (`recent`) or `read_callback_events`. If the result did not arrive, call `list_verification_deliveries` and fix the cause. Repeat until the app shows the stored result.
+- [ ] Ask the developer to set up the production callback. The local listener works only while this coding agent's MCP server runs; once it stops, the deployed app receives no results. Call `create_org_callback_subscription` with the deployed app's public callback route URL for all five session-ending events: `verification_success`, `verification_rejected`, `verification_error`, `verification_cancelled`, and `session_expired`.
+- [ ] If they have no deployed URL yet, tell them: "When you deploy, ask me to run `create_org_callback_subscription` with your public callback URL, or results will not reach the app."

package/skill/user-script.md

@@ -47,6 +47,70 @@ Do not clear cookies or force another sign-in; inconclusive coverage must not
 block publication. This browser check does not emulate a client-specific
 interceptor.
 
+## Write the navigation script first
+
+Write the navigation script as soon as the developer is signed in, or as soon
+as you know the sign-in page. Then capture through it, so authoring, testing,
+and verification follow the same path.
+
+The script does two things:
+
+1. **Signed out:** send the user to the sign-in page.
+2. **Signed in:** visit each page that holds a data point, in order. Data
+   points can live on different pages. Keep a step index in `sessionStorage` so
+   the script survives reloads and repeated runs.
+
+Loop: `test_user_script({ script, keep: true })` → fix → retest. With `keep:
+true` the script stays installed for every later navigation in the authoring
+browser, as it does at verification. `create_provider_version_from_capture`
+publishes it as `webSettings.jsUserScripts` unless you pass your own.
+
+```js
+(() => {
+	const SIGN_IN = '/login'
+	const STEPS = [
+		{ path: '/account', ready: () => document.querySelector('#dob') },
+		{ path: '/settings/profile', ready: () => document.querySelector('#plan') },
+	]
+	const signedIn = () => document.querySelector('[data-user-menu]')
+		&& !document.querySelector('a[href="/login"]')
+	let tries = 0
+	const timer = setInterval(() => {
+		if(++tries > 120) {
+			return clearInterval(timer)
+		}
+
+		if(!signedIn()) {
+			// stay put on the sign-in page; also covers unknown pages
+			if(location.pathname !== SIGN_IN) {
+				clearInterval(timer)
+				location.assign(SIGN_IN)
+			}
+
+			return
+		}
+
+		const i = Number(sessionStorage.getItem('rc-step') || 0)
+		const step = STEPS[i]
+		if(!step) {
+			return clearInterval(timer)
+		}
+
+		if(location.pathname !== step.path) {
+			clearInterval(timer)
+			return location.assign(step.path)
+		}
+
+		if(step.ready()) {
+			sessionStorage.setItem('rc-step', String(i + 1))
+		}
+	}, 500)
+})()
+```
+
+Adapt the selectors to the site. Each new tab starts at the first step, and a
+reload resumes at the current step.
+
 ## `window.Reclaim` — rarely needed
 
 `window.Reclaim` is an optional bridge for a handful of edge cases. Most

package/skill/verification-client-integration.md

@@ -2,31 +2,42 @@
 
 ## Set up an application with the coding agent
 
-When asked to integrate Reclaim into an app, inspect that app's frontend,
-backend, package manager, configuration, and callback conventions. Complete
-the integration in its codebase and run its relevant checks. The MCP tools
-configure Builder resources; the coding agent's file tools edit the app.
+For "add Reclaim to my app", call `start_integration` first and follow its
+plan. Don't ask whether to try, integrate, or create an app. Ask one short
+question only when intent is unclear. The steps below are the detail behind
+that plan.
+
+Inspect the app's frontend, backend, package manager, configuration, and
+callback conventions. Complete the integration in its codebase and run its
+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 (call `set_devtools_mode({ mode: "old" })` and have them restart the MCP
-server), or migrate to the Builder session flow below. When
-migrating, remove `@reclaimprotocol/js-sdk` and replace its
-`ReclaimProofRequest` and `verifyProof` calls with the session flow below.
-
-1. Use `get_devtools_mode` to confirm Builder mode and `get_me` or
-   `authenticate` to sign in as the developer. Find the intended organization
-   with `list_orgs`; call `create_org` only when a new organization is wanted.
-2. Register a callback URL owned by the app's backend with
-   `create_org_callback_subscription`. Include terminal success, rejection,
-   error, cancellation, and expiry events. If the app needs encrypted results,
-   register its public key with `set_org_keypair`; retain the private key only
-   in the backend.
-3. Reuse a `RECLAIM_ORG_SECRET` the app already has. Otherwise an organization
-   owner calls `issue_org_token`; its `orgSecret` is shown once. Write it with
-   your file tools into the backend's env file (for example
-   `RECLAIM_ORG_SECRET=rorg_…` in `.env`) and make sure that file is
-   gitignored. Keep it out of frontend bundles, logs, source control, and the
-   final response.
+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.
+
+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
+   public callback URL with `create_org_callback_subscription`, including
+   all five session-ending events. If the
+   app needs encrypted results, register its public key with `set_org_keypair`;
+   keep the private key only in the backend. `set_org_keypair` refuses to
+   replace an existing key unless you pass `replace: true`; pass it only when
+   the developer asks.
+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
+   returns only the last four characters and the file path. Make sure that file
+   is gitignored. Never print the key, put it in the conversation, or ask the
+   developer to paste it. Keep it out of frontend bundles, logs, and source
+   control.
 4. Prefer plain HTTP from the backend (see [Code to write](#code-to-write)).
    Create sessions with `POST /verifications/sessions`
    (`Authorization: Bearer $RECLAIM_ORG_SECRET`), save each returned session ID
@@ -60,8 +71,7 @@ The MCP session tools (`create_verification_session`,
 `delete_callback_subscription`, `bind_verification_session_tee_nonce`, and
 `get_verification_result`) call these same production endpoints with the org
 key: pass it as `orgToken`, or let them fall back to the MCP server's
-`RECLAIM_ORG_SECRET`. Use them, or `curl` with the key from `.env`, to test the
-integration end to end.
+`RECLAIM_ORG_SECRET`. Use them to test the integration end to end.
 
 ## Code to write
 
@@ -69,10 +79,12 @@ Use the API base URL the developer's Builder runs at (production:
 `https://build.reclaimprotocol.org`). Every call authenticates with
 `authorization: Bearer $RECLAIM_ORG_SECRET`.
 
-Subscribe a callback once (or use `create_org_callback_subscription`). Session
-creation returns 409 while the org has none, and a result is only delivered to
+Deployed apps subscribe a callback once (or use
+`create_org_callback_subscription`); local development uses
+`proxy_callback_events` instead. Session creation returns 409 while the org has
+no subscription, and a result is only delivered to
 subscriptions that include the event the session ends with, so subscribe to all
-five:
+five session-ending events:
 
 ```bash
 curl -X POST https://build.reclaimprotocol.org/verifications/callback-subscriptions \

package/src/authoring/backend.ts

@@ -37,6 +37,18 @@ export interface Draft {
 	extractions: Extraction[]
 }
 
+/** A navigation script installed for every later page load of the authoring
+ *  session. `identifier` is the CDP registration, so it can be removed. */
+export interface KeptScript {
+	script: string
+	identifier?: string
+}
+
+/** Holds the session's kept script, replaced by each `keep` call. */
+export interface KeptScriptRef {
+	keptScript?: KeptScript
+}
+
 /** Per-session draft store: `propose` puts, `replay`/`run_proof` get by id. */
 export interface DraftStore {
 	put(draft: Draft): string
@@ -75,6 +87,9 @@ export interface AuthoringBackend {
 	 * out. Cloud authoring enables this; local MCP keeps its existing
 	 * behavior. */
 	readonly readOnlyPageEval?: boolean
+	/** Where `test_user_script` keeps its script. Absent for hosts that do not
+	 * publish it (the cloud loop synthesizes its own navigation script). */
+	readonly kept?: KeptScriptRef
 	/** Send a raw CDP command scoped to this session's page. */
 	sendCdp(method: string, params?: Record<string, unknown>): Promise<unknown>
 	/** Resolve once `method` (a CDP event) fires on this session's page, or

package/src/authoring/index.ts

@@ -4,6 +4,8 @@ export type {
 	AuthoringBackend,
 	Draft,
 	DraftStore,
+	KeptScript,
+	KeptScriptRef,
 	ProveOptions,
 	SecretParams,
 } from './backend.ts'