@reclaimprotocol/agent 0.1.33 → 0.1.34

package/skill/SKILL.builder.md

@@ -11,32 +11,38 @@ Builder.
 
 ## The loop, at a glance
 
-Copy this checklist and check off each step as you finish it. Read the linked
-topic before a step you aren't already fluent in.
-
-- [ ] 1. `attach_browser` — pick a browser source with the developer.
-      → topic `browser`
-- [ ] 2. `list_tabs` → `start_capture(tabId)` ⇒ **`captureId`**, your handle for
-      everything below. → topic `capture`
-- [ ] 3. Drive the page: `navigate`, `wait_for_page`, `eval_in_page`,
-      `get_cookies`. Detect login, land on the page showing the value, trigger
-      the request. → topic `capture`
-- [ ] 4. `find_requests_containing` → `analyze_request_constraints` → pick an
-      **authenticated** request. → topic `capture`
-- [ ] 5. `propose_provider(captureId, requestId, …)` ⇒ **`draftId`** (recipe +
-      captured secrets, held server-side — secrets never enter the transcript).
-      → topic `draft`
-- [ ] 6. Parameterize user-specific URL segments; mark secrets. → topic `params`
-- [ ] 7. `replay_request(captureId, draftId)`, then again with
+Build a new org-private provider for the claim the developer described. Ask
+one question if the site, account, or value is ambiguous. Copy this checklist
+and check off each step. Read the linked topic before a step you don't know.
+
+- [ ] 1. Name the data points: only the values the claim must prove, usually
+      one or two. No identity or profile fields.
+- [ ] 2. `attach_browser`, then `list_tabs` → `start_capture(tabId)` ⇒
+      **`captureId`**. → topics `browser`, `capture`
+- [ ] 3. Open the sign-in page and wait for the developer to sign in
+      (`wait_for_page`). → topic `capture`
+- [ ] 4. Write the navigation script: sign-in redirect, then each data
+      point's page in order. → topic `user-script`
+- [ ] 5. `test_user_script({ script, keep: true })`. Fix and retest until it
+      reaches every page, also after a reload.
+- [ ] 6. Capture by letting the script navigate: `find_requests_containing` →
+      `analyze_request_constraints` → pick an **authenticated** request per
+      data point. → topic `capture`
+- [ ] 7. `propose_provider(captureId, requestId, …)` ⇒ **`draftId`**
+      (`targets` = the data points). → topic `draft`
+- [ ] 8. Parameterize user-specific URL segments; mark secrets.
+      → topic `params`
+- [ ] 9. `replay_request(captureId, draftId)`, then again with
       `withoutSecrets: true`. → topic `prove`
-- [ ] 8. `run_proof(captureId, draftId, ownerAddress)`.
+- [ ] 10. `run_proof(captureId, draftId, ownerAddress)`.
       → topics `prove`, `credentials`
-- [ ] 9. Resolve a `providerId` (**reuse before create**) →
-      `create_provider_version_from_capture` → `publish_provider_version` or
+- [ ] 11. `create_provider` (or a new version of a provider your org owns) →
+      `create_provider_version_from_capture` (publishes the kept script as
+      `webSettings.jsUserScripts`) → `publish_provider_version` or
       `submit_provider_version_for_review`. → topic `publish`
 
-Multi-request provider? Run steps 5–8 once per request, then publish every
-proven draft in one call. See topic `publish`.
+Data points on different requests? Run steps 7-10 once per request, then
+publish every proven draft in one call. See topic `publish`.
 
 <!-- topic: contributions -->
 
@@ -84,7 +90,7 @@ integration. Prefer Builder for new integrations.
 2. **Pick a tab and start the capture.** `list_tabs`, then
    `start_capture(tabId)` ⇒ a **`captureId`**: the session handle every browser
    and inspect tool takes as its first argument (`navigate`, `eval_in_page`,
-   `wait_for_page`, `get_cookies`, `list_requests`, `find_requests_containing`,
+   `wait_for_page`, `list_requests`, `find_requests_containing`,
    `propose_provider`). If a tab is already on the right origin use it,
    otherwise the first is usually fine. Capturing from the start is harmless —
    it also records the login navigation. Then `navigate(captureId, url)` to
@@ -93,13 +99,18 @@ integration. Prefer Builder for new integrations.
 
 3. <!-- common: login-detect -->
 
-4. **Navigate to the page that displays the value.** Construct the URL from what
-   you know about the site; eval for anything you need (for example, GitHub's
-   `meta[name="user-login"]`'s `content`), then `navigate(captureId, url)`.
+4. **Write and keep the navigation script** (topic `user-script`) as soon as
+   the developer is signed in, or the sign-in URL is known. Test it with
+   `test_user_script` and `keep: true`. The script visits each data point's
+   page; build its URLs from what you know about the site and read page state
+   with `eval_in_page` when needed (for example, GitHub's
+   `meta[name="user-login"]`'s `content`).
 
-5. **Trigger the request.** Capture has been live since step 2, so make the
-   call fire: `eval_in_page(captureId, "location.reload()")`, or click an
-   element / hit a SPA route programmatically. Don't ask the developer to click.
+5. **Trigger the requests by letting the script navigate.** Capture has been
+   live since step 2. Reload the page (`eval_in_page(captureId,
+   "location.reload()")`) so the kept script runs from the start. Don't click
+   by hand or ask the developer to; if a request needs an interaction, add it
+   to the script.
 
 6. <!-- common: identify-value -->
 
@@ -126,8 +137,9 @@ integration. Prefer Builder for new integrations.
 under that `draftId`; the secrets never enter the transcript, so you carry the
 `draftId`, not the provider JSON, into replay/prove.
 
-**Extracting more than one value?** Prefer a **single request whose response
-contains all of them** and draft them together — one `responseMatches` +
+**Extracting more than one value?** Add a value only when the claim needs it.
+Prefer a **single request whose response contains all of them** and draft them
+together — one `responseMatches` +
 `responseRedactions` pair per value. Find that request by running
 `find_requests_containing` for each value and picking a `requestId` common to
 all. Then pass a `targets` array, each entry with its `value` (exactly as it
@@ -136,7 +148,7 @@ appears) and a distinct `name`:
 ```
 propose_provider(captureId, requestId, name, targets: [
   { value: "Scratch-net", name: "username" },
-  { value: "Alex",        name: "name" },
+  { value: "2019",        name: "member_since_year" },
 ])
 ```
 
@@ -313,16 +325,13 @@ parameterization applied. `initialUrl` is the page where the user logs in / the
 value is displayed (for example, `https://github.com/Syed`) — **not** the API
 endpoint URL inside the provider.
 
-**1. Reuse before create — this is how duplicates happen.**
-`create_provider_version_from_capture` requires a `providerId`. Before minting a
-new one, search your existing providers with `providers` (by domain / data
-point) — a site you've already built is there. Match → pass its
-`providerId` and the capture lands as a NEW VERSION on it. Only call
-`create_provider(orgId, domain, slug, title, description)` when none exists
-(`orgId` from `list_orgs`; `domain` such as `github.com`, `slug` such as
-`github-username`, `title` such as "GitHub Username"). It starts PRIVATE with an
-empty seed version. Routing every run through `create_provider` is what stacks
-duplicates in "My providers".
+**1. Resolve the `providerId`.** For a new claim, call
+`create_provider(orgId, domain, slug, title, description)` (`orgId` from
+`list_orgs`; `domain` such as `github.com`, `slug` such as `github-username`,
+`title` such as "GitHub Username"). It starts PRIVATE with an empty seed
+version. Use an existing `providerId` only when your org owns the provider and
+you are revising it: the capture lands as a NEW VERSION on it. For another
+org's provider that almost fits, create your own provider and version.
 
 **2. Persist the version.**
 `create_provider_version_from_capture(providerId, provider, initialUrl, notes)`
@@ -339,12 +348,13 @@ or archive an existing version to apply provider changes.
   required at verification time. This proves that every request matched; it
   does not automatically bind a value extracted from one response to another
   request.
-- **Login/navigation-gated data:** supply `jsUserScripts` (plain page JS that
-  drives login/waits/navigation so the target request fires), or
-  `allowedJsRequests` (extra requests the script may fire, for example,
-  pagination). → topic `user-script`. Before populating `allowedJsRequests` for
-  a `verifyRequestProof({ providerId })` use case, read topic `hash-validation` — a
-  session-unique URL there makes verifyRequestProof reject every real proof.
+- **Navigation script:** the script kept with `test_user_script` (`keep: true`)
+  is published as `webSettings.jsUserScripts`. Pass `jsUserScripts` only to
+  override it. → topic `user-script`. For extra requests the script may fire
+  (for example, pagination), pass `allowedJsRequests`. Before populating it for
+  a `verifyRequestProof({ providerId })` use case, read topic
+  `hash-validation`: a session-unique URL there makes `verifyRequestProof`
+  reject every real proof.
 
 **3. `requiredContext` is derived for you.** The publish tool scans the recipe's
 url/body for `{{context.<name>}}` placeholders and emits a JSON Schema requiring
@@ -367,10 +377,8 @@ developer it's awaiting admin review.
 context params — for example, `context: { "username": "…" }` in
 `create_verification_session`. Quote the `requiredContext` from the created
 version verbatim — a session missing those fields gets a 400, and verification
-matches the supplied values exactly. Then ask once how they want to use it —
-try it now here, 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).
+matches the supplied values exactly. Then continue as the server
+instructions say under "What the developer wants".
 
 **6. If the response includes `_notes` for an attached browser, follow them for
 an optional authenticated-state retest.** Only when its profile is still signed
@@ -383,35 +391,30 @@ the session for further edits; call `dispose_browser` only after they confirm.
 A `builder` session is quota-accounted, so don't leave it idle.
 
 <!-- topic: discover -->
-## Discover and resolve providers for the developer's app
+## Discover and resolve existing providers
 
-When a developer wants to add verification but doesn't know which providers to
-use, run the same flow the Discover UI does:
+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").
 
 1. Ask which website their users prove data from.
 2. `discover_data_points({ domain })` → what's verifiable there. Confirm the
    data points with the developer.
 3. `discover_resolve({ domain, dataPoints })` → the smallest provider set
    (`providers`, greedy combine), the `requiredContext` inputs to collect, and
-   any `uncovered` points (author those with the flow above, then re-resolve).
-4. Resolved providers are published and usable as-is: don't capture, replay,
-   or prove them unless the developer asks you to check or test one. Ask once
-   whether they just want to try them or want them in an app — just try it
-   now, integrate into an existing backend or frontend (this directory or
-   another path), or create a new app — unless they already said.
-5. Just try it (no app, callback, or client package) →
-   `create_verification_session({ providers: [{ providerId }, …], context,
-   verificationClientUrl })` with EVERY resolved provider id and the collected
-   context, give them `verificationUrl`, poll `get_verification_session` until
-   it is terminal, and report the outcome with `get_verification_result`
-   (builder-mode instructions cover the org key and temporary callback).
-   Integrate or new app → topic `integration`.
-
-`merge.mergeable` only signals the set *could* collapse into one provider — you
-still pass them all; the Builder runs them in one session.
-
-For client integration, result verification, or TEE binding, read topic
-`integration`.
+   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.
+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`.
+
+`merge.mergeable` only signals the set *could* collapse into one provider. Pass
+them all; the Builder runs them in one session.
 
 <!-- topic: integration -->
 

package/skill/SKILL.common.md

@@ -424,7 +424,8 @@ conversation.
 1. **`resolve_owner_key`** returns only the derived address.
    - `{ ready: true, address }` → call `run_proof` with it. No prompts.
    - `{ ready: false }` → ask the developer once: **their own key** →
-     `import_credentials({ privateKey: "0x…" })` (a `keyFile` path also works),
+     `import_credentials({ keyFile })` (a path to a file holding the key; never
+     ask them to paste it),
      or **a fresh one** → `issue_credentials({})` (a fine default for test
      proofs — owner identity doesn't matter). Either writes to the project
      `.env` (mode 0600, added to `.gitignore`), never to `~/.reclaim`. Then

package/skill/builder-mode.md

@@ -1,146 +1,143 @@
 # 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
+
+Use the production API the app will use. Session creation returns 409 while the
+org has no callback subscription, and results are stored only for subscriptions
+to the event the session ends with.
+
+1. If the org has none, register a temporary subscription for all five ending
+   events with `create_org_callback_subscription` (for example, a tunnel to a
+   local listener that saves the body it receives).
+2. `create_verification_session`, then give the developer `verificationUrl`.
+3. Poll `get_verification_session` until it is terminal. Report the outcome
+   from the listener's body, or with `get_verification_result` (works only
+   until the callback is delivered).
+4. `delete_org_callback_subscription` only after that. Deleting it also
+   deletes its stored results.
+
+## 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.
+
+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 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,49 @@
+# 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. Get a 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 3.
+<!-- 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 -->
+
+## 3. Integrate into this codebase
+
+- [ ] Read `how_it_works({ topic: "integration" })`.
+- [ ] Detect the app's framework and package manager from the repository, and use them.
+- [ ] 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`) for the provider and returns `verificationUrl`.
+- [ ] Add a callback route that verifies each result with `results.receive` from `@reclaimprotocol/client`, then stores only the requested data points.
+- [ ] Call `create_org_callback_subscription` for the result events, pointing at the callback route. Use a tunnel for local development.
+- [ ] Add a frontend Verify button that opens `verificationUrl`, and shows the stored result when it arrives.
+- [ ] Run the app, then tell the developer exactly how to test end to end: open the app, click Verify, sign in, and see the stored result.