@reclaimprotocol/agent 0.1.27 → 0.1.28

package/lib/provider/to-version.d.ts

@@ -1,4 +1,4 @@
-import type { ReclaimClient } from '@reclaimprotocol/client';
+import type { ReclaimClient } from '@reclaimprotocol/client/api';
 import type { CreateProviderVersionRequest, ProviderVersionRef } from '@reclaimprotocol/client/openapi';
 import type { DraftResponseMatch, HttpMethod, OldUrlType, ReclaimProvider, ResponseRedaction, WebCredentials } from './schema.ts';
 /** One entry of the version's `requests[]` (a `RequestSelection`), derived
@@ -50,6 +50,9 @@ export interface AllowedJsRequest extends DraftRequest {
 export interface CreateVersionOptions {
     notes?: string;
     version?: ProviderVersionRef;
+    /** Complete context schema for this new immutable version. When omitted,
+     *  it is derived from `{{context.<name>}}` placeholders. */
+    requiredContext?: CreateProviderVersionRequest['requiredContext'];
     /** JS injected before every page load (`webSettings.jsUserScripts`). */
     jsUserScripts?: string;
     /** Requests the injection script may fire, as `RequestSelectionTemplate`s. */
@@ -74,7 +77,8 @@ export interface CreateVersionOptions {
  * injected requests and the injection script) — mechanical, so a published
  * recipe can never reference a context value the Builder doesn't require.
  * Returns undefined when nothing references context (the field is optional).
- * Authors can refine types/descriptions in the version editor.
+ * Authors can pass a complete schema when creating the new version to refine
+ * types or descriptions. Never edit a version in place after creation.
  *
  * A SECRET-named context param (see `classifyParamName`) is NOT rejected here
  * even when it's templated into the URL/geoLocation — write-redaction can
@@ -102,10 +106,18 @@ export declare function deriveRequiredContext(providers: ReclaimProvider[], inje
 export declare function providerToRequestSelection(provider: DraftRequest): RequestSelection;
 export declare function providerToCreateVersionRequest(providers: ReclaimProvider[], initialUrl: string, opts?: CreateVersionOptions): CreateProviderVersionRequest;
 /**
- * Fetch the current versions for a provider and return the next version above
- * the highest existing one (bumping the patch number), or 1.0.0 when the
- * provider has no versions yet. A failed lookup propagates — silently
- * resetting to 1.0.0 would re-publish a v3 provider as v1.0.0.
+ * Fetch every current version and resolve a strictly newer immutable version.
+ * The default bump is patch. Callers can request major/minor/patch or provide
+ * an exact version; an exact version must be higher than every existing one.
+ * A failed lookup propagates — silently resetting to 1.0.0 could collide with
+ * an existing version.
  */
-export declare function nextVersion(client: ReclaimClient, providerId: string): Promise<ProviderVersionRef>;
+export declare function nextVersion(client: ReclaimClient, providerId: string, bump?: VersionBump): Promise<ProviderVersionRef>;
+export type VersionBump = 'major' | 'minor' | 'patch';
+/** Resolve either an explicit version or a requested semantic bump. */
+export declare function resolveNewVersion(client: ReclaimClient, providerId: string, input?: {
+    version?: ProviderVersionRef;
+    bump?: VersionBump;
+}): Promise<ProviderVersionRef>;
+export declare function bumpVersion(versions: ProviderVersionRef[], bump?: VersionBump): ProviderVersionRef;
 export {};

package/lib/provider/to-version.js

@@ -1,3 +1,5 @@
+import { badRequest, conflict } from '@hapi/boom';
+import assert from 'node:assert';
 import { DYNAMIC_GEO, normalizeGeoLocation } from "./schema.js";
 /**
  * Translate a drafted ReclaimProvider into the body for
@@ -21,7 +23,8 @@ const CONTEXT_PARAM_RE = /\{\{context\.([A-Za-z_][A-Za-z0-9_]*)\}\}/g;
  * injected requests and the injection script) — mechanical, so a published
  * recipe can never reference a context value the Builder doesn't require.
  * Returns undefined when nothing references context (the field is optional).
- * Authors can refine types/descriptions in the version editor.
+ * Authors can pass a complete schema when creating the new version to refine
+ * types or descriptions. Never edit a version in place after creation.
  *
  * A SECRET-named context param (see `classifyParamName`) is NOT rejected here
  * even when it's templated into the URL/geoLocation — write-redaction can
@@ -101,11 +104,8 @@ function pickGeoLocation(providers) {
     return DYNAMIC_GEO;
 }
 export function providerToCreateVersionRequest(providers, initialUrl, opts = {}) {
-    const { notes, version, jsUserScripts, allowedJsRequests, interceptorOptions, } = opts;
-    const requiredContext = deriveRequiredContext(providers, {
-        allowedJsRequests,
-        jsUserScripts,
-    });
+    const { notes, version, requiredContext: requestedContext, jsUserScripts, allowedJsRequests, interceptorOptions, } = opts;
+    const requiredContext = requestedContext ?? deriveRequiredContext(providers, { allowedJsRequests, jsUserScripts });
     // Each injected request carries its template flags (default true/true per
     // RequestSelectionTemplate) on top of the shared request shape.
     const allowedJs = (allowedJsRequests ?? []).map((req) => ({
@@ -166,28 +166,70 @@ export function providerToCreateVersionRequest(providers, initialUrl, opts = {})
     };
 }
 /**
- * Fetch the current versions for a provider and return the next version above
- * the highest existing one (bumping the patch number), or 1.0.0 when the
- * provider has no versions yet. A failed lookup propagates — silently
- * resetting to 1.0.0 would re-publish a v3 provider as v1.0.0.
+ * Fetch every current version and resolve a strictly newer immutable version.
+ * The default bump is patch. Callers can request major/minor/patch or provide
+ * an exact version; an exact version must be higher than every existing one.
+ * A failed lookup propagates — silently resetting to 1.0.0 could collide with
+ * an existing version.
  */
-export async function nextVersion(client, providerId) {
-    const list = (await client.call('ListProviderVersions', {
-        params: { providerId },
-        query: {},
-    }));
-    if (!list.items?.length) {
+export async function nextVersion(client, providerId, bump = 'patch') {
+    return bumpVersion(await listVersions(client, providerId), bump);
+}
+/** Resolve either an explicit version or a requested semantic bump. */
+export async function resolveNewVersion(client, providerId, input = {}) {
+    assert(!(input.version && input.bump), badRequest('Pass either `version` or `bump`, not both.'));
+    const versions = await listVersions(client, providerId);
+    if (!input.version) {
+        return bumpVersion(versions, input.bump ?? 'patch');
+    }
+    const highest = highestVersion(versions);
+    assert(!highest || compareVersions(input.version, highest) > 0, conflict(`Version ${formatVersion(input.version)} must be higher than the ` +
+        `current highest version ${highest ? formatVersion(highest) : 'none'}.`));
+    return input.version;
+}
+export function bumpVersion(versions, bump = 'patch') {
+    const highest = highestVersion(versions);
+    if (!highest) {
         return { major: 1, minor: 0, patch: 0 };
     }
-    // Find the highest version and bump its patch
-    let hi = list.items[0].version;
-    for (const item of list.items) {
-        const v = item.version;
-        if (v.major > hi.major ||
-            (v.major === hi.major && v.minor > hi.minor) ||
-            (v.major === hi.major && v.minor === hi.minor && v.patch > hi.patch)) {
-            hi = v;
+    switch (bump) {
+        case 'major':
+            return { major: highest.major + 1, minor: 0, patch: 0 };
+        case 'minor':
+            return { major: highest.major, minor: highest.minor + 1, patch: 0 };
+        case 'patch':
+            return {
+                major: highest.major,
+                minor: highest.minor,
+                patch: highest.patch + 1,
+            };
+    }
+}
+async function listVersions(client, providerId) {
+    const versions = [];
+    let cursor;
+    do {
+        const { data } = await client.call('ListProviderVersions', {
+            params: { providerId },
+            query: { cursor },
+        });
+        versions.push(...data.items.map((item) => item.version));
+        cursor = data.nextPageCursor;
+    } while (cursor);
+    return versions;
+}
+function highestVersion(versions) {
+    let highest;
+    for (const version of versions) {
+        if (!highest || compareVersions(version, highest) > 0) {
+            highest = version;
         }
     }
-    return { major: hi.major, minor: hi.minor, patch: hi.patch + 1 };
+    return highest;
+}
+function compareVersions(a, b) {
+    return a.major - b.major || a.minor - b.minor || a.patch - b.patch;
+}
+function formatVersion(version) {
+    return `${version.major}.${version.minor}.${version.patch}`;
 }

package/lib/tools/registry.d.ts

@@ -38,6 +38,6 @@ export declare function errorAsToolText(err: unknown): string;
  */
 export declare function extendTool(tool: RegisteredTool, extra: {
     description?: string;
-    properties?: Record<string, unknown>;
+    properties?: JSONSchema.ObjectSchema['properties'];
     required?: string[];
 }): RegisteredTool;

package/lib/tools/registry.js

@@ -12,6 +12,7 @@
  * re-exports this primitive for the MCP-side tool files.
  */
 import { isBoom } from '@hapi/boom';
+import { isProblemDetails, isProblemError } from '@reclaimprotocol/client/api';
 import { toZod } from "../mcp/api/to-zod.js";
 /**
  * Define a tool with a single inputSchema (JSON Schema) as the source of truth.
@@ -35,8 +36,12 @@ export function defineTool(definition, handler) {
  * else falls back to the plain message.
  */
 export function errorAsToolText(err) {
+    if (isProblemError(err)) {
+        const detail = err.data.detail;
+        return detail ? `${err.message}: ${detail}` : err.message;
+    }
     if (isBoom(err) && err.output?.statusCode) {
-        const detail = err.data?.detail;
+        const detail = isProblemDetails(err.data) ? err.data.detail : undefined;
         return detail ? `${err.message}: ${detail}` : err.message;
     }
     return err instanceof Error ? err.message : String(err);
@@ -56,9 +61,7 @@ export function extendTool(tool, extra) {
         ...(base.inputSchema.required ?? []),
         ...(extra.required ?? []),
     ];
-    // The merged `properties` spread carries the base's untyped property values,
-    // which don't structurally match ObjectSchema's strict per-property schema
-    // type — assert the merged shape.
+    // Keep the merged schema checked against Zod's JSON Schema representation.
     const inputSchema = {
         ...base.inputSchema,
         properties: {

package/package.json

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

package/skill/SKILL.builder.md

@@ -1,6 +1,20 @@
 <!-- topic: overview -->
 # Authoring a Reclaim provider (Builder backend)
 
+For claimant-facing Builder-client integration, result verification, or optional
+TEE binding, read topic `integration`. Keep URLs without `api=2` on the
+existing legacy path.
+
+<!-- topic: contributions -->
+## Public provider contributions
+
+For an asynchronous volunteer contribution, read
+[community-contributions.md](community-contributions.md) before using Builder.
+It defines the history-first workflow, approved-field allowlist, fixed-US
+egress, privacy boundaries, generalized recipe checks, and candidate review.
+Never modify a published version in place; create a candidate and submit it
+for review.
+
 <!-- common: terminology -->
 
 ## The loop, at a glance
@@ -108,7 +122,7 @@ 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
+**Extracting more than one value?** 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
@@ -171,10 +185,10 @@ changes.
 ## Parameters: extracted, consumer-supplied, and secret
 
 **Parameterize user-specific URL segments** so the provider isn't pinned to one
-user. The matcher already puts the *captured* value in `paramValues`. If the URL
-*also* carries user-identifying segments, those are **consumer-supplied context
-params**: at verification time their values come from the consumer's session
-`context`, not from extraction.
+user. The matcher already puts the *captured* value in `paramValues`. If the
+consumer knows a URL value before verification and the proof must be pinned to
+it, make it a **consumer-supplied context param**. At verification time, its
+value comes from the consumer's session `context`, not from extraction.
 
 Replace them with `{{context.<name>}}`, for example
 `https://github.com/Scratch-net/repos` →
@@ -187,6 +201,12 @@ placeholder exactly, dot included).
 - No user-identifying segments (for example, `/settings/profile`) → leave it
   alone.
 
+Use a bare `{{name}}` only when the value can be observed in the same live
+request. A multi-request recipe does not bind a value extracted from one
+response to a later request. If proving that relationship is required, use a
+request that exposes both values, require the value as consumer context, or
+stop and explain that the current recipe format cannot prove the dependency.
+
 Declare them in the version's `requiredContext` at publish time (topic
 `publish`).
 
@@ -218,6 +238,14 @@ extracted-from-traffic). The attestor itself only looks up `{{whatever}}` in
   proof should be **pinned** to it; bare when the value should come from
   whatever the logged-in user's traffic shows.
 
+Builder-mode Verification Clients include one migration fallback for old
+DevTools providers: when a recipe uses bare `{{name}}` instead of
+`{{context.name}}`, the client seeds a missing `parameters.name` from scalar
+session `context.name`. An explicit parameter wins. Do not rely on this
+fallback for new providers; keep using `{{context.<name>}}` so
+`requiredContext` is derived and validated before the session starts.
+Builder-owned `reclaimSessionId` and `attestationNonce` remain context-only.
+
 `propose_provider` returns `verificationWarnings` for calls only an author can
 make (currently: a captured value baked literally into the URL, needing the
 `{{context.<name>}}`-vs-bare-vs-recapture decision). Advisory, never blocking —
@@ -284,13 +312,18 @@ duplicates in "My providers".
 **2. Persist the version.**
 `create_provider_version_from_capture(providerId, provider, initialUrl, notes)`
 — `notes` such as `"Initial draft from browser capture"`. It lands on the
-`draft` branch.
+`draft` branch. This always creates a new immutable semantic version. Omit
+`version` and `bump` for the default patch bump; set `bump` to `major`, `minor`,
+or `patch`, or pass the exact higher `version` requested by the user. Never edit
+or archive an existing version to apply provider changes.
 
 - **Multi-request provider** (landing call + details call, a
   CSRF-preflight/refresh-token chain, …): run capture→draft→replay→prove ONCE
   PER REQUEST, then pass `providers: [draftA, draftB, …]` instead of the single
   `provider`. Each becomes its own request on the version and **all** are
-  required at verification time.
+  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,
@@ -303,8 +336,9 @@ url/body for `{{context.<name>}}` placeholders and emits a JSON Schema requiring
 each — the Builder then validates every session-create's `context` against it (a
 clear 400 instead of a late attestor failure). Extra context fields are always
 allowed; it's optional when the recipe has no `{{context.*}}` placeholders.
-Derived properties are plain strings; refine types or add descriptions with
-`update_provider_version` while the version is still on `draft`:
+Derived properties are plain strings. To refine types or add descriptions,
+pass the complete `requiredContext` in the same
+`create_provider_version_from_capture` call:
 
 ```json
 { "requiredContext": { "type": "object", "required": ["username"], "properties": { "username": { "type": "string", "description": "GitHub username to verify" } } } }
@@ -320,10 +354,15 @@ context params — for example, `context: { "username": "…" }` in
 version verbatim — a session missing those fields gets a 400, and verification
 matches the supplied values exactly.
 
-**6. The browser is still open.** The response's `_notes` says so. Surface it
-and ask whether the developer wants to keep the session for further edits — call
-`dispose_browser` only once they confirm. Never close it unprompted; a
-`builder`-mode session is quota-accounted, so don't leave it idle either.
+**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
+in, navigate to `initialUrl`; if a user script is present, run
+`test_user_script` with that script and `initialUrl`. When the existing capture
+has enough data, replay and prove every required request. Do not clear
+cookies or force another sign-in. Treat an unavailable or inconclusive retest as
+advisory and do not block publication. Ask whether the developer wants to keep
+the session for further edits; call `dispose_browser` only after they confirm.
+A `builder` session is quota-accounted, so don't leave it idle.
 
 <!-- topic: discover -->
 ## Discover and resolve providers for the developer's app
@@ -344,6 +383,12 @@ use, run the same flow the Discover UI does:
 `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`.
+
+<!-- topic: integration -->
+## Integrate a Builder Verification Client
+
 **Verification sessions.** Consumers authenticate with a per-org token
 (`rorg_…`, issued in the dashboard via `POST /orgs/{orgId}/token`) and create
 sessions via `POST /verifications/sessions`. Results are ECIES-encrypted
@@ -353,6 +398,66 @@ callback subscriptions; plaintext otherwise. Troubleshoot with
 `get_verification_session`, `list_verification_events`,
 `list_org_verification_sessions`.
 
+For a claimant-facing Builder-mode integration, share the returned
+`verificationUrl` (it contains the session id and `api=2`). Append client-owned
+redirect parameters only after session creation. Append `diag=1` only for a
+deliberate troubleshooting launch; it can enable logs containing personal data.
+The registered client resolves its own `x-reclaim-vc-id`; do not invent a
+client token or put callback/redirect fields in the session request. Consumers
+should verify terminal deliveries with `verifyResultFull` and the session's
+trusted issuer.
+
+An optional `themeId` on session creation selects an active theme owned by the
+organization. Omit it to snapshot the organization's most recently updated
+active theme. A theme's localized `consent` block makes supported clients show
+consent before the first provider; no block means no consent screen. Theme and
+branding data never affect proof trust.
+
+**Browser extension.** For the exact `api=2` URL, use
+`reclaimExtensionSDK.fromVerificationUrl` or `initBuilder` with the session's
+`verificationClientId`, then call `startVerification()`. The extension
+generates and persists `claimantClientId` when omitted, resolves recipes from
+bootstrap, runs them sequentially, and sends `x-reclaim-vc-id` to every bridge
+route, including session-bound `attestor-auth`. It forwards raw legacy proofs
+inside the Builder result and does not perform client-side `allowedJsRequests`
+validation. Builder recipes support dotted `{{context.key}}` templates; the
+extension forwards matching session context to claim creation. Builder mode
+skips legacy offscreen session-status calls and uses the Builder bridge for
+session lifecycle updates. It emits `verification_result_submitting` and
+`verification_result_submission_failed` when applicable. It does not send
+terminal success or error as a separate best-effort event; the results request
+makes the bridge record the matching terminal event strongly before signing
+and storing result deliveries. Missing or unknown `api` values stay on the
+existing `init` / `fromJsonString` / direct-callback path.
+
+**Builder client bridge.** In `api=2` mode, the registered client UUID is sent
+in `x-reclaim-vc-id` to these routes:
+
+| Route | Purpose |
+| --- | --- |
+| `GET /api/sdk/builder/v2/sessions/{sessionId}/bootstrap` | Load the session and resolved recipe. |
+| `PATCH /api/sdk/builder/v2/sessions/{sessionId}/claimant` | Update claimant diagnostics. |
+| `POST /api/sdk/builder/v2/sessions/{sessionId}/events` | Report canonical lower-snake-case events. |
+| `POST /api/sdk/builder/v2/sessions/{sessionId}/attestor-auth` | Request session-bound attestor authentication. Do not send a legacy app secret or provider signature. |
+| `POST /api/sdk/builder/v2/sessions/{sessionId}/results` | Submit exact legacy proof objects; the bridge records the matching terminal event strongly before signing and storing result deliveries. |
+
+The bridge preserves each legacy proof and signs only the outer Verification
+Client JWS. `verifyResultFull` validates the issuer, JWS, session, audience,
+and expiry, then passes each exact proof to `verifyProof`. Keep TEE settings in
+the legacy verifier configuration; do not add verification hooks. Treat outer
+`extracted_parameters` and `content_hash` as diagnostics, not trust inputs.
+
+**Optional TEE binding.** A consumer can pass
+`teeAttestation: { appSecret }` to `sessions.create`. The SDK derives the
+hash nonce locally with the pinned `@reclaimprotocol/js-sdk` formula, signs
+the binding payload with EIP-191, and registers it with
+`PUT /verifications/sessions/{sessionId}/tee-nonce` using the organization
+token. The private key stays in the consumer process. Bind before proof
+generation. The binding is idempotent for the same values and immutable
+afterward; this helper registers only `RECLAIM_TEE_NONCE_V1` (`v3`). Legacy
+`verifyProof` accepts the older signature nonce, but this helper does not
+generate or register it.
+
 <!-- topic: never-do -->
 ## Things to never do
 

package/skill/SKILL.common.md

@@ -22,11 +22,6 @@ already names it.
 <!-- section: browser -->
 ## Choosing a browser
 
-- Choosing one — ask who signs in, then offer the matching pair
-- Sharing the container's live view with someone remote
-- What happens when the session ends
-- When the container will not start
-
 **Ask one question first, before you list anything:**
 
 > Will you be doing this yourself, or does someone else need to sign in — the
@@ -51,7 +46,7 @@ are the only modes that produce a link another person can open:
 
 | mode | what it is | needs | costs |
 | --- | --- | --- | --- |
-| `container` | The Reclaim runtime in Docker, on their machine. `share_browser_view` turns its viewer into a public link. | Docker running | free — their Docker, their bandwidth. 432 MB the first time, about 2 GB of RAM, 7 to 17 seconds to start |
+| `container` | The Reclaim runtime in Docker, on their machine. `share_browser_view` turns its viewer into a public link. | Docker running | free — their Docker and bandwidth |
 | `builder` | A browser in Reclaim's cloud. The link comes back immediately, with nothing to install. Also the only way to browse from a **specific country**. | Builder auth, `orgId` | **chargeable** — billed against the org's quota |
 
 **Say which one costs money.** They are otherwise interchangeable from the
@@ -62,7 +57,7 @@ decision. Do not quietly pick the billed one.
 was handed an endpoint and knows why. Don't offer it unprompted; it cannot be
 shared either.
 
-**`attach` gotcha (Chrome 136+, May 2025):** the developer's Chrome must be
+**`attach` gotcha (Chrome 136 and later):** the developer's Chrome must be
 started with BOTH `--remote-debugging-port=9222` AND
 `--user-data-dir=<non-default-path>`. The debug flag is silently ignored on the
 default profile. If `attach` fails, say this verbatim and offer `dedicated`.
@@ -109,8 +104,8 @@ Ask plainly:
 > whoever holds the login — they can watch and click in it, including from a
 > phone.
 
-If they say yes, call `share_browser_view` and **relay the full URL verbatim, on
-its own line.**
+If they say yes, call `share_browser_view` and **relay the full returned URL
+verbatim, on its own line.** It includes `liveview.html?magnify=1`.
 
 - **`container` is the only mode this applies to.** `builder` returns a hosted
   `liveViewUrl` from `attach_browser` — relay that instead, full and verbatim.
@@ -131,16 +126,15 @@ its own line.**
 - **Call `stop_browser_view` as soon as they're done.** That closes the tunnel
   only — the browser keeps running. `dispose_browser` and `reset_session` stop
   the container itself.
-- **If the URL will not load**, the tunnel may not have registered with
-  Cloudflare — the hostname exists before the route does. Have them reload after
-  10 seconds; if it still fails, `stop_browser_view` then `share_browser_view`
-  again, since a quick tunnel does occasionally fail to come up. A
-  `propagating: true` in the result is that case, and `cloudflaredLog` carries
-  the reason.
+- **If the URL will not load**, check `propagating`. The hostname can exist
+  before Cloudflare finishes routing it. Keep the returned share open, wait a
+  few seconds, and reload; don't start a second tunnel while it propagates.
+  `cloudflaredLog` contains bounded diagnostic output. If it still fails after
+  60 seconds, call `stop_browser_view`, then retry `share_browser_view` once.
 - **cloudflared is handled for you.** An existing install on PATH wins;
   otherwise it's fetched once into `~/.reclaim/bin` on the first share, never at
-  install time. Say so when it happens — it's a 37 MB download onto their
-  machine. `RECLAIM_CLOUDFLARED_PATH` points at their own copy instead.
+  install time. Tell the developer when the download starts.
+  `RECLAIM_CLOUDFLARED_PATH` points at their own copy instead.
 
 ### How containers are shared, and when they close
 
@@ -169,8 +163,8 @@ its own line.**
   runs translated. OrbStack does this itself; Docker Desktop needs "Use Rosetta
   for x86/amd64 emulation" turned on. Under QEMU instead of Rosetta, Chromium
   crashes on launch.
-- **First run looks stuck.** It is downloading 432 MB. Say that rather than
-  letting it look hung.
+- **First run looks stuck.** It is downloading the browser image. Say that
+  rather than letting it look hung.
 - A container left over from a crashed run is **reused if it is still serving**,
   and replaced if it is not — a second attach does not need a different port.
 
@@ -329,6 +323,23 @@ captured secret *header* whose value also sits in the URL, which is already
 known and so gets checked at draft time (`assertNoSecretUrlConflict`).
 
 <!-- section: no-rename-param -->
+**Keep internal claim-construction fields out of claimant-facing UI.** When a
+named regex group or `{{parameter}}` only helps construct another claim request,
+consider an internal prefix:
+
+- `REQ_` for request/body/header or other intermediate values.
+- `URL_` for URL path/query values.
+
+Builder data-point and SEO/catalog surfaces, and compatible claimant UIs, omit
+these names case-insensitively. The prefix is presentation metadata, not a
+security boundary: the exact parameter remains in the recipe, proof, and
+proof-time substitution maps. Keep the same full name everywhere it is
+referenced: the named group, template, and `paramValues`; for an
+`allowedJsRequests` template, also use it in `templateParams`. With
+`propose_provider`, pass the prefixed target name and `shortenNames: false`;
+otherwise name shortening drops the prefix. Don't prefix an actual
+consumer-facing result merely to conceal it.
+
 **Do not rename the match-template param.** The synthesizer's `{{name}}` in
 `responseMatches[].value` is an _extraction_ template — it stays bare and never
 takes the `%CTX%` prefix. Only URL/body placeholders whose values the consumer

package/skill/SKILL.old.md

@@ -45,10 +45,12 @@ emitted. Read both from topic `troubleshooting`.
 ## Getting authenticated
 
 Call `reclaim_authenticate({})` with no arguments. It opens the Reclaim
-dashboard in Chrome, waits for the developer to sign in, reads the token from
-the page and closes the tab — a still-valid cached identity is reused first, so
-it's often instant. Tell the developer once: _"A browser window is opening the
-Reclaim dashboard — please sign in and I'll continue automatically."_
+dashboard only in a local Chrome over loopback CDP, waits for the developer to
+sign in, reads the token from the page, and closes the tab. It never uses a
+Builder, container, custom-CDP, or shared browser. A still-valid cached identity
+is reused first, so it's often instant. Tell the developer once: _"A local
+Chrome window is opening the Reclaim dashboard — please sign in and I'll
+continue automatically."_
 
 - Force a fresh login: `reclaim_authenticate({ useBrowser: true })`.
 - Skip the browser: `reclaim_authenticate({ token: "<firebase-id-token>" })`, or
@@ -64,7 +66,7 @@ and are NOT interchangeable.
 - **`reclaim_authenticate`** authorizes everything in this mode:
   `create_provider_version_from_capture`, `get_me_providers`, and the rest.
 - **`authenticate_builder`** covers exactly two Builder-exclusive features:
-  allocating a Popcorn remote browser (`attach_browser mode="builder"`) and
+  allocating a Builder remote browser (`attach_browser mode="builder"`) and
   `list_builder_organizations`. It authorizes nothing else.
 
 `get_devtools_mode` reports the presence of both. If a publish or
@@ -115,7 +117,7 @@ it. Don't assume `authenticate_builder` fixes it.
 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
+**Extracting more than one value?** 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
@@ -256,8 +258,11 @@ Call `create_provider_version_from_capture`:
   `geoLocation`, `providerType` (`PRIVATE` default | `PUBLIC`).
   ⚠️ Re-running without `providerId` registers ANOTHER provider — that's how
   duplicates appear. Check `get_me_providers` first.
-- **New version of an existing provider:** pass its `providerId`; the patch is
-  auto-bumped above the highest existing version. Pass `notes` (≥10 chars).
+- **New version of an existing provider:** pass its `providerId`. Omit
+  `version` and `bump` for the default patch bump; set `bump` to `major`,
+  `minor`, or `patch`, or pass the exact higher `version` requested by the
+  user. Every change creates a new immutable version; never edit an existing
+  version. Pass `notes` (≥10 chars).
 - **Multi-request provider** (landing call + details call, a
   CSRF-preflight/refresh-token chain, …): run capture→draft→replay→prove ONCE
   PER REQUEST, then pass `providers: [draftA, draftB, …]` instead of the single
@@ -304,10 +309,15 @@ There's no create-then-version step and no org / public-review workflow here.
 When done, tell the developer the version is live and that they can integrate
 using the `providerId`.
 
-**The browser is still open.** The response's `_notes` says so. Surface it and
-ask whether the developer wants to keep the session for further edits — call
-`dispose_browser` only once they confirm. Never close it unprompted; a
-`builder`-mode session is quota-accounted.
+**If the response includes `_notes` for an attached browser, follow them for an
+optional authenticated-state retest.** Only when its profile is still signed in,
+navigate to `initialUrl`; if `customInjection` is present, run
+`test_user_script` with that script and `initialUrl`. When the existing capture
+has enough data, replay and prove every required request. Do not clear
+cookies or force another sign-in. Treat an unavailable or inconclusive retest as
+advisory and do not block the completed provider. Ask whether the developer
+wants to keep the session for further edits; call `dispose_browser` only after
+they confirm.
 
 <!-- topic: never-do -->
 ## Things to never do