@reclaimprotocol/agent 0.1.22 → 0.1.24

package/src/mcp/tools/agent/how-it-works.ts

@@ -1,32 +1,73 @@
-import {
-	PROVIDER_GUIDE_BUILDER,
-	PROVIDER_GUIDE_OLD,
-} from '../../instructions.ts'
+import { guideFor } from '../../instructions.ts'
 import { defineTool, type RegisteredTool } from '../../server.ts'
 
 /**
- * Serves the full provider-authoring guide on demand. The MCP server's
- * always-on `instructions` are a terse tool-flow reference; this tool returns
- * the deep version (workflow, decision frameworks, gotchas, "never do" rules)
- * so any MCP client — not just Claude Code, which alone auto-loads skills — can
- * pull it. `oldMode` selects the backend-specific guide so the agent is never
- * told to call auth/publish tools that aren't registered in its mode.
- * Stateless: callable before `attach_browser`.
+ * Serves the provider-authoring guide on demand, ONE TOPIC AT A TIME. The
+ * server's always-on `instructions` are a terse tool-flow reference; this tool
+ * is the deep version, so any MCP client — not just Claude Code, which alone
+ * auto-loads skills — can pull it.
+ *
+ * Topic-scoped rather than all-at-once because the full guide is ~7k tokens:
+ * paying that to answer "how do I mark a header secret?" crowds out the actual
+ * task, which is exactly what makes an agent slow and prone to inventing
+ * details. Every response carries the topic index, so a caller that guessed
+ * wrong (or called with no topic at all) always learns what else is available
+ * without a second round-trip.
+ *
+ * `oldMode` selects the backend-specific guide, so the agent is never told to
+ * call auth/publish tools that aren't registered in its mode. Stateless:
+ * callable before `attach_browser`.
  */
 export function howItWorksTool(oldMode: boolean): RegisteredTool {
-	const guide = oldMode ? PROVIDER_GUIDE_OLD : PROVIDER_GUIDE_BUILDER
-	return defineTool<Record<string, never>>(
+	const guide = guideFor(oldMode)
+	const names = [...guide.topics.keys()]
+
+	return defineTool<{ topic?: string }>(
 		{
 			name: 'how_it_works',
 			description:
-				'Return the full Reclaim provider-authoring guide for THIS server: '
-				+ 'the capture → draft → replay → prove → publish workflow, decision '
-				+ 'frameworks (login detection, OPRF privacy, context vs bare params), '
-				+ 'multi-request handling, troubleshooting, and what never to do. '
-				+ 'Call this BEFORE building a provider unless you are already '
-				+ 'fluent in the flow.',
-			inputSchema: { type: 'object', properties: {} },
+				'Reclaim provider-authoring guide for THIS server, by topic. Call it '
+				+ 'with no arguments for the overview plus the topic index, then again '
+				+ 'for whichever topic you need. Topics: '
+				+ names.join(', ')
+				+ '. Use `all` for the entire guide at once (large — prefer a topic). '
+				+ 'Read the relevant topic BEFORE acting unless you are already fluent '
+				+ 'in that part of the flow.',
+			inputSchema: {
+				type: 'object',
+				properties: {
+					topic: {
+						type: 'string',
+						// Deliberately NOT an `enum`: schema validation runs before the
+						// handler, so an enum turns a mistyped topic into a validation
+						// error instead of a response carrying the real topic list. A
+						// plain string lets the tool answer the mistake usefully.
+						description:
+							'Which section to return: ' + names.join(', ')
+							+ ', or `all`. Omit for the overview + topic index. An '
+							+ 'unrecognized value comes back with the list, not an error.',
+					},
+				},
+			},
+		},
+		async({ topic }) => {
+			if(topic === 'all') {
+				return { topic: 'all', topics: guide.index, guide: guide.full }
+			}
+
+			const requested = topic ?? 'overview'
+			const section = guide.topics.get(requested)
+			if(!section) {
+				// Not an error: hand back the index so the caller self-corrects in
+				// the same turn rather than retrying blind.
+				return {
+					error: `Unknown topic "${requested}".`,
+					topics: guide.index,
+					guide: guide.topics.get('overview'),
+				}
+			}
+
+			return { topic: requested, topics: guide.index, guide: section }
 		},
-		async() => ({ guide }),
 	)
 }

package/src/mcp/tools/agent/live-view.ts

@@ -0,0 +1,198 @@
+/**
+ * `share_browser_view` / `stop_browser_view` — put the LOCAL attached tab
+ * behind a public URL so someone who is not at this machine can watch it, and
+ * optionally drive it.
+ *
+ * Scoped to the CDP-attached modes (`dedicated`, `attach`, `custom`) on
+ * purpose. A `builder`-mode browser is a Popcorn pod that already ships its
+ * own hosted live view on `attach_browser`'s `liveViewUrl`; tunnelling a
+ * second one would duplicate it and burn a share URL for nothing, so this
+ * refuses and points at the one that exists.
+ *
+ * The share is deliberately explicit and single-instance: one live view per
+ * attached browser, started only when asked for, and torn down by
+ * `stop_browser_view`, `dispose_browser`, or `reset_session`.
+ */
+import { badRequest, conflict } from '@hapi/boom'
+import assert from 'node:assert'
+import { startTunnel, type Tunnel } from '../../../live/tunnel.ts'
+import { type LiveView, startLiveView } from '../../../live/viewer.ts'
+import { LOGGER } from '../../../logger.ts'
+import { defineTool, type RegisteredTool } from '../../server.ts'
+import type { AttachState } from './attach.ts'
+import type { CaptureStore } from './capture.ts'
+
+/** Modes whose browser we reach over our own CDP connection, and which
+ *  therefore have no hosted live view of their own. */
+const SHAREABLE_MODES = new Set(['dedicated', 'attach', 'custom'])
+
+export interface LiveShare {
+	view: LiveView
+	tunnel: Tunnel
+	url: string
+	interactive: boolean
+	startedAt: number
+}
+
+export interface LiveShareRef {
+	current?: LiveShare
+}
+
+/** Tear down whatever share is running. Safe when none is. Exported so the
+ *  session tools can call it from `dispose_browser` / `reset_session`. */
+export async function stopLiveShare(ref: LiveShareRef): Promise<boolean> {
+	const share = ref.current
+	if(!share) {
+		return false
+	}
+
+	ref.current = undefined
+	await share.view.stop().catch((err) => {
+		LOGGER.warn({ err }, 'live view: server stop failed')
+	})
+	await share.tunnel.stop().catch((err) => {
+		LOGGER.warn({ err }, 'live view: tunnel stop failed')
+	})
+	return true
+}
+
+export function liveViewTools(
+	attachRef: { current?: AttachState },
+	captures: CaptureStore,
+	shareRef: LiveShareRef,
+): RegisteredTool[] {
+	return [
+		defineTool<{ tabId?: string, interactive?: boolean }>(
+			{
+				name: 'share_browser_view',
+				description:
+					'Put the attached tab behind a PUBLIC HTTPS URL (a cloudflared '
+					+ 'quick tunnel) so someone elsewhere can watch it live, and by '
+					+ 'default click and type in it. Use it to hand a login or a 2FA '
+					+ 'step to the person who holds the credentials, or to let a '
+					+ 'colleague watch a capture. Returns the URL — relay it to the '
+					+ 'developer VERBATIM, on its own line. '
+					+ 'ONLY for a locally attached browser (attach_browser mode '
+					+ '`dedicated`, `attach`, or `custom`). In `builder` mode the '
+					+ 'Popcorn browser already has a hosted live view: use the '
+					+ '`liveViewUrl` that attach_browser returned instead. '
+					+ 'THE URL IS A CREDENTIAL: anyone holding it can see this tab, '
+					+ 'and with the default `interactive: true` can act in it as the '
+					+ 'signed-in user. Share it only with the person who needs it, and '
+					+ 'call stop_browser_view the moment they are done. Pass '
+					+ '`interactive: false` for a watch-only link. '
+					+ 'Needs cloudflared: an existing install on PATH is used as-is, '
+					+ 'otherwise it is downloaded once to ~/.reclaim/bin on first '
+					+ 'share (never at install time). Set RECLAIM_CLOUDFLARED_PATH to '
+					+ 'point at your own copy instead.',
+				inputSchema: {
+					type: 'object',
+					properties: {
+						tabId: {
+							type: 'string',
+							description:
+								'Tab to stream, from list_tabs. Defaults to the tab the '
+								+ 'active capture is on, else the first tab.',
+						},
+						interactive: {
+							type: 'boolean',
+							description:
+								'Let the viewer click and type in the page. Default true. '
+								+ 'Set false to stream a read-only view.',
+						},
+					},
+				},
+			},
+			async({ tabId, interactive }) => {
+				const attached = attachRef.current
+				assert(attached, badRequest(
+					'No browser attached. Call attach_browser first.',
+				))
+				assert(SHAREABLE_MODES.has(attached.mode), badRequest(
+					`share_browser_view does not apply to \`${attached.mode}\` mode. `
+					+ 'That browser already has a hosted live view — use the '
+					+ '`liveViewUrl` from attach_browser'
+					+ (attached.liveViewUrl ? `: ${attached.liveViewUrl}` : '')
+					+ '.',
+				))
+				assert(!shareRef.current, conflict(
+					'A live view is already running at '
+					+ `${shareRef.current?.url}. Call stop_browser_view first, or `
+					+ 'reuse that URL.',
+				))
+
+				const tabs = tabId || captures.activeTab
+					? []
+					: await attached.handles.listTabs()
+				const target = tabId ?? captures.activeTab ?? tabs[0]?.tabId
+				assert(target, badRequest(
+					'No tab to stream. Open a tab, or call list_tabs to pick one.',
+				))
+
+				const tab = await attached.handles.attachToTab(target)
+				const wantsInput = interactive !== false
+				const view = await startLiveView({
+					tab,
+					interactive: wantsInput,
+					title: `Reclaim — ${attached.mode} browser`,
+				})
+
+				let tunnel: Tunnel
+				try {
+					tunnel = await startTunnel(view.port)
+				} catch(err) {
+					// Don't leave the loopback server behind if the tunnel failed.
+					await view.stop().catch(() => {})
+					throw err
+				}
+
+				const url = `${tunnel.url}${view.path}`
+				const share: LiveShare = {
+					view, tunnel, url, interactive: wantsInput, startedAt: Date.now(),
+				}
+				shareRef.current = share
+				LOGGER.info({ mode: attached.mode, interactive: wantsInput },
+					'live view shared')
+
+				return {
+					url,
+					interactive: wantsInput,
+					tabId: target,
+					...(share.tunnel.binary.source === 'downloaded'
+						? { cloudflaredInstalled: true }
+						: {}),
+					...(share.tunnel.ready ? {} : { propagating: true }),
+					_notes: [
+						...(share.tunnel.binary.source === 'downloaded'
+							? ['cloudflared was not installed, so it was downloaded once '
+								+ 'to ~/.reclaim/bin. Mention that; later shares reuse it.']
+							: []),
+						...(share.tunnel.ready
+							? []
+							: ['The tunnel had not started routing yet — if the URL '
+								+ 'errors, wait a few seconds and reload.']),
+						'Relay `url` to the developer verbatim, on its own line.',
+						'The URL is a credential: it needs no login, and anyone with '
+						+ 'it can see this tab'
+						+ (wantsInput ? ' and act in it as the signed-in user.' : '.'),
+						'Call stop_browser_view when they are done — the tunnel stays '
+						+ 'open until you do.',
+					],
+				}
+			},
+		),
+		defineTool<Record<string, never>>(
+			{
+				name: 'stop_browser_view',
+				description:
+					'Close the public live view opened by share_browser_view: stops '
+					+ 'the screen stream and shuts the tunnel down, so the URL stops '
+					+ 'resolving. Call it as soon as the person you shared with is '
+					+ 'finished. The browser itself stays attached and the capture '
+					+ 'keeps running.',
+				inputSchema: { type: 'object', properties: {} },
+			},
+			async() => ({ stopped: await stopLiveShare(shareRef) }),
+		),
+	]
+}

package/src/mcp/tools/agent/pod-proof.ts

@@ -0,0 +1,90 @@
+/**
+ * Prove a drafted recipe through the Popcorn pod's OWN `/reclaim/prove` — the
+ * remote browser session's own API for creating a proof from that same
+ * session — instead of the local in-process attestor SDK (`run_proof`).
+ * Recommended for any `builder`-mode attach: the pod is the SAME enclave that
+ * holds the browser's TLS session, so proving there reaches the target from
+ * the identical exit IP the browser used — including the country-routed egress
+ * Popcorn applies when the session was allocated with a country. A local SDK
+ * proof runs from the agent's own network instead, which won't match a
+ * country-locked / IP-allowlisted target the remote browser could reach.
+ *
+ * Builder mode only (needs the attach's pod `apiUrl`, from
+ * `CreateAgentBrowserSession`) — throws a clear error otherwise rather than
+ * silently falling back to the local path.
+ */
+import { badRequest } from '@hapi/boom'
+import assert from 'node:assert'
+import type { ConfigStore } from '../../../config/store.ts'
+import { popcornProve } from '../../../proof/pod-prover.ts'
+import { buildHttpParams } from '../../../proof/proof-core.ts'
+import { defineTool, type RegisteredTool } from '../../server.ts'
+import type { AttachState } from './attach.ts'
+import type { CaptureStore } from './capture.ts'
+import { shapeRichProofResult } from './proof.ts'
+
+export function podProofTools(
+	attachRef: { current?: AttachState, config: ConfigStore },
+	captures: CaptureStore,
+): RegisteredTool[] {
+	const tool = defineTool<{ captureId: string, draftId: string }>(
+		{
+			name: 'run_proof_via_pod',
+			description:
+				'Prove the drafted recipe through the Popcorn pod\'s own TEE '
+				+ '(/reclaim/prove) instead of the local attestor SDK — this is '
+				+ 'the remote browser session\'s own api for creating a proof '
+				+ 'from that same session. Use this instead of run_proof '
+				+ 'whenever this capture\'s '
+				+ 'attach mode is "builder": the pod is the same enclave that '
+				+ 'held the browser\'s TLS session (and its country-routed egress, '
+				+ 'if any), so '
+				+ 'the proof reaches the target from the browser\'s own exit IP. '
+				+ 'No ownerAddress needed — the pod signs with the attestor\'s '
+				+ 'own TEE key, not a local credential.',
+			inputSchema: {
+				type: 'object',
+				properties: {
+					captureId: { type: 'string' },
+					draftId: { type: 'string' },
+				},
+				required: ['captureId', 'draftId'],
+			},
+		},
+		async({ captureId, draftId }) => {
+			const apiUrl = attachRef.current?.apiUrl
+			assert(
+				apiUrl,
+				badRequest(
+					'No pod api available for this attach — run_proof_via_pod needs '
+					+ 'mode "builder" (attach_browser), not local/custom CDP.',
+				),
+			)
+
+			const entry = captures.sessions.get(captureId)
+			assert(
+				entry,
+				badRequest(
+					`no capture ${captureId} — call start_capture first `
+					+ '(it has been reset or never started).',
+				),
+			)
+
+			const draft = entry.drafts.get(draftId)
+			assert(draft, badRequest(`no draft ${draftId} in capture ${captureId}`))
+
+			const result = await popcornProve({
+				apiUrl,
+				params: buildHttpParams(draft.provider),
+				secretParams: { headers: draft.secrets },
+			})
+
+			return shapeRichProofResult(result, {
+				provider: draft.provider,
+				hasSecrets: Object.keys(draft.secrets).length > 0,
+			})
+		},
+	)
+
+	return [tool]
+}

package/src/mcp/tools/agent/propose.ts

@@ -23,18 +23,43 @@ export function proposeTool(resolveBackend: ResolveBackend): RegisteredTool {
 				+ 'one match + redaction per target. Returns a draftId + recipe '
 				+ '(never secrets). Prefer a SINGLE request holding ALL values. '
 				+ 'Single-value shorthand: `target` + `name`. Per-target `hash` '
-				+ 'OPRF-hashes that value.',
+				+ 'OPRF-hashes that value. BY DEFAULT each `name` is shortened to '
+				+ 'its last alphanumeric token, lowercased, to form the param key '
+				+ '(for example, "employer_name" → "name") — pick names that stay '
+				+ 'distinct '
+				+ 'after shortening ("firstName"/"surname", not "first_name"/'
+				+ '"last_name"). Pass `shortenNames: false` to use each `name` '
+				+ 'VERBATIM as the param key instead — it becomes both a regex '
+				+ 'capture-group name and a paramValues key, so it must be a plain '
+				+ 'identifier (letters/digits/underscore, not starting with a '
+				+ 'digit); we recommend lower_snake_case (for example, '
+				+ '"employer_name"), '
+				+ 'but you choose the exact name.',
 			inputSchema: objectSchema(
 				{
 					requestId: { type: 'string' },
 					name: { type: 'string' },
+					shortenNames: {
+						type: 'boolean',
+						description:
+							'Default true: shorten each target `name` to its last '
+							+ 'alphanumeric token, lowercased, to form the param key. '
+							+ 'Set false to use `name` verbatim instead (must be a plain '
+							+ 'identifier — lower_snake_case recommended).',
+					},
 					targets: {
 						type: 'array',
 						items: {
 							type: 'object',
 							properties: {
 								value: { type: 'string' },
-								name: { type: 'string' },
+								name: {
+									type: 'string',
+									description:
+										'The param key, or the source of one — see '
+										+ '`shortenNames`. Must stay distinct from other targets\' '
+										+ 'names after whichever treatment applies.',
+								},
 								hash: {
 									type: 'string',
 									enum: ['oprf-raw', 'oprf', 'oprf-mpc'],
@@ -54,6 +79,9 @@ export function proposeTool(resolveBackend: ResolveBackend): RegisteredTool {
 			const requestId = String(args.requestId)
 			const providerName = String(args.name)
 			const defaultHash = args.hash as OprfMode | undefined
+			const shortenNames = typeof args.shortenNames === 'boolean'
+				? args.shortenNames
+				: true
 
 			// Explicit multi-value `targets`, else the single `target` shorthand.
 			const raw = Array.isArray(args.targets) ? args.targets : []
@@ -103,7 +131,7 @@ export function proposeTool(resolveBackend: ResolveBackend): RegisteredTool {
 			}
 
 			const { provider, secretRefs, extractions } = draftProvider(
-				captured, targets, providerName, defaultHash,
+				captured, targets, providerName, defaultHash, { shortenNames },
 			)
 			// Materialize the real secret header values for later replay/prove;
 			// they stay in the server-side draft, never in this result.

package/src/mcp/tools/agent/publish.ts

@@ -1,6 +1,9 @@
 import type { ReclaimClient } from '@reclaimprotocol/client'
 import type { JSONSchema } from 'zod/v4/core'
-import { INJECTION_GUIDE } from '../../../provider/injection-doc.ts'
+import {
+	ALLOWED_REQUESTS_HINT,
+	USER_SCRIPT_HINT,
+} from '../../../provider/injection-doc.ts'
 import {
 	countsFor,
 	matchRedactionWarnings,
@@ -82,7 +85,8 @@ const PROVIDER_SCHEMA: JSONSchema.Schema = {
 	type: 'object',
 	description:
 		'A `provider` object from propose_provider, passed through verbatim — ' +
-		'the tool builds the version body (the requests[] entry etc.) for you.',
+		'the tool builds the version body (the requests[] entry and so on) ' +
+		'for you.',
 	properties: {
 		name: { type: 'string', description: 'Verification name.' },
 		...REQUEST_DRAFT_PROPERTIES,
@@ -95,7 +99,7 @@ const PROVIDER_SCHEMA: JSONSchema.Schema = {
 		paramValues: {
 			type: 'object',
 			description:
-				'Real values for the {{param}} placeholders, e.g. ' +
+				'Real values for the {{param}} placeholders, for example, ' +
 				'{ "username": "Syed" }.',
 		},
 	},
@@ -111,8 +115,8 @@ const ALLOWED_JS_REQUEST_SCHEMA: JSONSchema.Schema = {
 		multiple: {
 			type: 'boolean',
 			description:
-				'Allow the template to match many requests (e.g. pagination). ' +
-				'Default true.',
+				'Allow the template to match many requests (for example, ' +
+				'pagination). Default true.',
 		},
 		required: {
 			type: 'boolean',
@@ -136,8 +140,8 @@ interface PublishArgs {
 	allowedJsRequests?: AllowedJsRequest[]
 	interceptorOptions?: {
 		interceptorType: 'HAWKEYE' | 'MSWJS' | 'CDP'
-		isDocumentRequestReplayEnabled?: boolean
 		interceptorSettings?: string
+		isDocumentRequestReplayEnabled?: boolean
 	}
 }
 
@@ -149,36 +153,21 @@ export function createVersionFromCaptureTool(
 		{
 			name: 'create_provider_version_from_capture',
 			description:
-				'Persist drafted ReclaimProvider(s) as a provider version. ' +
-				'Call this after run_proof succeeds, passing the `provider` ' +
-				'object(s) from propose_provider VERBATIM. This tool builds the ' +
-				'body (the requests[] array, webSettings, etc.) for you — do NOT ' +
-				'hand-construct that shape or call create_provider_version directly. ' +
-				'For a MULTI-REQUEST provider, pass `providers: [...]` (each entry a ' +
-				'proven draft) — every entry becomes one request in the version, and ' +
-				'all are required at verification time. Pass a single `provider` ' +
-				'for the one-request case (exactly one of `provider`/`providers`). ' +
-				'For data gated behind login/navigation, supply `jsUserScripts` (a ' +
-				'page-injection script that drives the page to where the request ' +
-				'fires) and/or `allowedJsRequests` (extra requests the script may ' +
-				'fire, e.g. pagination). ' +
-				'Omit `version` to have the tool auto-select the next available ' +
-				'version (it lists existing versions and bumps past the highest). ' +
-				'The version lands on the draft branch — to go live, call ' +
-				'`publish_provider_version` (PRIVATE) or ' +
-				'`submit_provider_version_for_review` (PUBLIC) afterwards. ' +
+				'Persist drafted ReclaimProvider(s) as a provider version, after ' +
+				'run_proof succeeds. Pass the `provider` object(s) from ' +
+				'propose_provider VERBATIM — this tool builds the version body ' +
+				'(requests[], webSettings, …) for you; do NOT hand-construct that ' +
+				'shape or call create_provider_version directly. Exactly one of ' +
+				'`provider` (one request) or `providers` (a multi-request provider — ' +
+				'every entry is required at verification time). Omit `version` to ' +
+				'auto-bump past the highest existing one. The version lands on the ' +
+				'draft branch: call `publish_provider_version` (PRIVATE) or ' +
+				'`submit_provider_version_for_review` (PUBLIC) to go live. ' +
 				'`requiredContext` is derived from any {{context.<name>}} ' +
-				'placeholders across ALL requests (plus injected requests / script) ' +
-				'and returned on the created version — when present, tell the dev ' +
-				'verbatim which context fields consumers MUST send when creating ' +
-				'sessions (verification matches those values exactly; a missing ' +
-				'field is a 400 at session create). ' +
-				'Refine types/descriptions via `update_provider_version` while ' +
-				'still on draft. ' +
-				'On success, if a browser is still attached, the response\'s ' +
-				'`_notes` reminds you to confirm with the developer before ' +
-				'calling `dispose_browser` — never close it unprompted, they ' +
-				'may want it for further edits.',
+				'placeholders and returned on the created version — relay it to the ' +
+				'dev verbatim, since a session missing those fields is a 400. Always ' +
+				'read the response\'s `_notes`. ' +
+				'Full walkthrough: how_it_works({ topic: "publish" }).',
 			inputSchema: {
 				type: 'object',
 				properties: {
@@ -200,13 +189,15 @@ export function createVersionFromCaptureTool(
 						type: 'string',
 						description:
 							'The website URL the user landed on to trigger the request ' +
-							'(e.g. https://github.com/Syed). The URL the verification ' +
-							'flow opens for end-users — NOT the API URL inside the provider.',
+							'(for example, https://github.com/Syed). The URL the ' +
+							'verification flow opens for end-users — NOT the API URL ' +
+							'inside the provider.',
 					},
 					notes: {
 						type: 'string',
 						description:
-							'Short change note (e.g. "Initial draft from browser capture").',
+							'Short change note (for example, "Initial draft from ' +
+							'browser capture").',
 					},
 					version: {
 						type: 'object',
@@ -223,67 +214,52 @@ export function createVersionFromCaptureTool(
 					jsUserScripts: {
 						type: 'string',
 						description:
-							'Plain JavaScript injected into the provider page before every ' +
-							'page load (stored as webSettings.jsUserScripts). Use standard ' +
-							'browser APIs (window.location, element.click(), forms) to ' +
-							'drive login/navigation so the target request fires — the ' +
-							'client already intercepts page requests, and window.Reclaim ' +
-							'is only for rare edge cases, not navigation. The Builder ' +
-							'verification client installs this to run before every page ' +
-							'load (before navigating to initialUrl), matching old-devtool ' +
-							'customInjection; window.Reclaim itself is not yet exposed ' +
-							'there, so prefer plain browser JS. Guide:\n\n' +
-							INJECTION_GUIDE,
+							USER_SCRIPT_HINT +
+							' Stored as webSettings.jsUserScripts; the Builder ' +
+							'verification client runs it before every page load ' +
+							'(including before navigating to initialUrl), matching ' +
+							'old-devtools customInjection. window.Reclaim is not exposed ' +
+							'there yet, so prefer plain browser JS.',
 					},
 					allowedJsRequests: {
 						type: 'array',
 						description:
-							'Extra requests the injection script is allowed to fire ' +
-							'(e.g. paginated API calls), as RequestSelectionTemplates. ' +
-							'`multiple`/`required` default to true. ' +
-							'⚠️ BEFORE populating this to gate ' +
-							'`verifyProof(proof, { providerId })` (old-devtools calls the ' +
-							'same concept `allowedInjectedRequestData` — same mechanics, ' +
-							'different field name): this whole entry (url, method, body, ' +
-							'responseMatches, responseRedactions) feeds a client-side ' +
-							'hash-equality check, and `url` is hashed VERBATIM — no regex/ ' +
-							'template resolution, even with `urlType: REGEX` or ' +
-							'`TEMPLATE`. If the real captured URL contains ANY per-session ' +
-							'part (a tracking nonce, CSRF token, cache-busting timestamp), ' +
-							'no declared spec can EVER hash-match a real proof — populating' +
-							' this for such a provider makes verifyProof reject every real ' +
-							'proof, which is worse than leaving it empty. Diff the same ' +
-							'endpoint\'s captured URL across two separate sessions before ' +
-							'wiring this up. If provider-hash validation keeps causing ' +
-							'problems (unstable url, or any other persistent mismatch), ' +
-							'the fallback on the verifying side is `verifyProof(proof, { ' +
-							'dangerouslyDisableContentValidation: true })` — trusts only ' +
-							'the attestor\'s signature, skips the hash-equality check ' +
-							'entirely; see the "Provider-hash validation" section of the ' +
-							'injection script\'s guide for the full mechanics and when to ' +
-							'reach for it.',
+							'Extra requests the user script is allowed to fire (for ' +
+							'example, paginated API calls), as ' +
+							'RequestSelectionTemplates. ' +
+							'`multiple`/`required` default to true. Old-devtools calls the ' +
+							'same concept `allowedInjectedRequestData`. ' +
+							ALLOWED_REQUESTS_HINT,
 						items: ALLOWED_JS_REQUEST_SCHEMA,
 					},
 					interceptorOptions: {
 						type: 'object',
 						description:
 							'In-app interception settings, stored as ' +
-							'webSettings.clientOptions.inapp.interceptorOptions. ' +
-							'`isDocumentRequestReplayEnabled` is the INVERSE of ' +
-							'old-devtools\' `disableRequestReplay`: true replays the ' +
-							'main document request via the attestor (default false).',
+							'webSettings.clientOptions.inapp.interceptorOptions — only ' +
+							'needed for a genuine live-interception provider (a real ' +
+							'HAWKEYE/MSWJS script, not the standard capture→replay flow).',
 						properties: {
 							interceptorType: {
 								type: 'string',
 								enum: ['HAWKEYE', 'MSWJS', 'CDP'],
 								description: 'How traffic interception is implemented.',
 							},
-							isDocumentRequestReplayEnabled: { type: 'boolean' },
 							interceptorSettings: {
 								type: 'string',
 								description:
 									'Free-form JSON config for the chosen interceptor.',
 							},
+							isDocumentRequestReplayEnabled: {
+								type: 'boolean',
+								description:
+									'Whether the page\'s own document/navigation request is ' +
+									'genuinely replayed through the interceptor, rather than ' +
+									'constructed locally. Defaults to `false` (disabled) when ' +
+									'omitted. Only meaningful for HAWKEYE/MSWJS — pass `true` ' +
+									'when the target value is embedded in the page\'s own HTML ' +
+									'rather than a separate API call. Inert for CDP.',
+							},
 						},
 						required: ['interceptorType'],
 					},