@reclaimprotocol/agent 0.1.23 → 0.1.25

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

@@ -466,7 +466,7 @@ export const MCP_TOOLS = {
 		}),
 	},
 	"CreateProvider": {
-		description: "Create a provider\n\nCreate a new Reclaim provider. Use this only after `providers` returned nothing useful for the domain. The caller must be an active member of the target organization.\nCreates a new provider in the specified organization. `visibility` is coerced to `PRIVATE` at creation regardless of what's sent; the author may toggle to `PUBLIC` later via `PATCH /providers/{id}`. While `PRIVATE`, versions go to the go live freely; once `PUBLIC`, non-admin versions need admin review. See `Provider.visibility`.\nThe server also seeds an initial `0.1.0` version on the `draft` branch in the same transaction so the provider is immediately editable. Its `initialUrl` defaults to `https://<domain>`; all other version fields fall back to their schema-declared defaults (a `structured` verificationType, empty requests, empty web settings). `Provider.latestVersion` stays `null` until the draft is promoted to the live channel.",
+		description: "Create a provider\n\nCreate a new Reclaim provider. Use this only after `providers` returned nothing useful for the domain. The caller must be an active member of the target organization.\nCreates a new provider in the specified organization. `visibility` is coerced to `PRIVATE` at creation regardless of what's sent; the author may toggle to `PUBLIC` later via `PATCH /providers/{id}`. While `PRIVATE`, versions go live freely; once `PUBLIC`, non-admin versions need admin review. See `Provider.visibility`.\nThe server also seeds an initial `0.1.0` version on the `draft` branch in the same transaction so the provider is immediately editable. Its `initialUrl` defaults to `https://<domain>`; all other version fields fall back to their schema-declared defaults (a `structured` verificationType, empty requests, empty web settings). `Provider.latestVersion` stays `null` until the draft is promoted to the live channel.",
 		inputSchema: toZod({
 			"type": "object",
 			"properties": {
@@ -497,7 +497,7 @@ export const MCP_TOOLS = {
 							"format": "uuid"
 						},
 						"domain": {
-							"description": "Canonical root domain (e.g. `github.com`). No scheme, no port, no path.",
+							"description": "Canonical root domain (for example, `github.com`). No scheme, no port, no path.",
 							"type": "string",
 							"format": "hostname",
 							"minLength": 1,
@@ -558,12 +558,12 @@ export const MCP_TOOLS = {
 								"brandUrl": {
 									"type": "string",
 									"format": "uri",
-									"description": "Canonical homepage of the brand (e.g. `https://google.com`). Used in brand-link cards and JSON-LD.",
+									"description": "Canonical homepage of the brand (for example, `https://google.com`). Used in brand-link cards and JSON-LD.",
 									"maxLength": 2000
 								},
 								"primaryDataPoint": {
 									"type": "string",
-									"description": "Headline data point — the single most-important variable this provider can verify (e.g. `subscriber count`). Used in the provider's SEO title.",
+									"description": "Headline data point — the single most-important variable this provider can verify (for example, `subscriber count`). Used in the provider's SEO title.",
 									"maxLength": 200
 								},
 								"dataPoints": {
@@ -670,10 +670,11 @@ export const MCP_TOOLS = {
 								},
 								"branch": {
 									"type": "string",
-									"description": "Branch (lifecycle stage) of this provider version.\n\n- `ai`: changes authored by the AI assistant live on this branch.\n\n- `draft`: a human is actively editing the version.\n\n- `in_review`: the author has submitted the version to be made\n  public and it is awaiting review. On approval the branch tag\n  is cleared (the version is promoted to the live channel and becomes\n  public).\n\n- `rejected`: review concluded with a rejection. When the author\n  addresses the feedback the branch transitions back to\n  `in_review`.",
+									"description": "Branch (lifecycle stage) of this provider version.\n\n- `ai`: changes authored by the AI assistant live on this branch.\n\n- `draft`: a human is actively editing the version.\n\n- `fixed`: a proven AI repair. It remains pinned to its explicit\n  version and does not replace the live trunk version.\n\n- `in_review`: the author has submitted the version to be made\n  public and it is awaiting review. On approval the branch tag\n  is cleared (the version is promoted to the live channel and becomes\n  public).\n\n- `rejected`: review concluded with a rejection. When the author\n  addresses the feedback the branch transitions back to\n  `in_review`.",
 									"enum": [
 										"ai",
 										"draft",
+										"fixed",
 										"in_review",
 										"rejected"
 									]
@@ -811,7 +812,7 @@ export const MCP_TOOLS = {
 										"items": {
 											"type": "object",
 											"additionalProperties": false,
-											"description": "Which portions to select from a response. These are selected in order, xpath => jsonPath => regex * These redactions are done client side and only the selected portions are sent to the attestor. The attestor will only be able to see the selected portions alongside the first line of the HTTP response (i.e. \"HTTP/1.1 200 OK\")",
+											"description": "Which portions to select from a response. These are selected in order, xpath => jsonPath => regex * These redactions are done client side and only the selected portions are sent to the attestor. The attestor will only be able to see the selected portions alongside the first line of the HTTP response (that is, \"HTTP/1.1 200 OK\")",
 											"properties": {
 												"xPath": {
 													"type": "string",
@@ -819,7 +820,7 @@ export const MCP_TOOLS = {
 												},
 												"jsonPath": {
 													"type": "string",
-													"description": "expect a JSON response, retrieve the item at this path using dot notation for e.g. 'email.addresses.0'"
+													"description": "expect a JSON response, retrieve the item at this path using dot notation, for example 'email.addresses.0'."
 												},
 												"regex": {
 													"type": "string",
@@ -964,7 +965,7 @@ export const MCP_TOOLS = {
 										"items": {
 											"type": "object",
 											"additionalProperties": false,
-											"description": "Which portions to select from a response. These are selected in order, xpath => jsonPath => regex * These redactions are done client side and only the selected portions are sent to the attestor. The attestor will only be able to see the selected portions alongside the first line of the HTTP response (i.e. \"HTTP/1.1 200 OK\")",
+											"description": "Which portions to select from a response. These are selected in order, xpath => jsonPath => regex * These redactions are done client side and only the selected portions are sent to the attestor. The attestor will only be able to see the selected portions alongside the first line of the HTTP response (that is, \"HTTP/1.1 200 OK\")",
 											"properties": {
 												"xPath": {
 													"type": "string",
@@ -972,7 +973,7 @@ export const MCP_TOOLS = {
 												},
 												"jsonPath": {
 													"type": "string",
-													"description": "expect a JSON response, retrieve the item at this path using dot notation for e.g. 'email.addresses.0'"
+													"description": "expect a JSON response, retrieve the item at this path using dot notation, for example 'email.addresses.0'."
 												},
 												"regex": {
 													"type": "string",
@@ -1029,8 +1030,8 @@ export const MCP_TOOLS = {
 							"properties": {
 								"geoLocation": {
 									"type": "string",
-									"description": "Geographic location (e.g. ISO country code or {{DYNAMIC_GEO}} to use user's geo location) the verification should appear to originate from.",
-									"maxLength": 15,
+									"description": "Geographic location the verification should appear to originate from: a 2-letter ISO country code, or a parameter the attestor resolves at proof time. `{{DYNAMIC_GEO}}` and `{{DYNAMIC_GEO_SECRET}}` are the Verification Client's standard names for the end-user's own country — the `_SECRET` one is delivered as a secret param, so the attestor never learns which country the proof egressed from.",
+									"maxLength": 64,
 									"default": "{{DYNAMIC_GEO}}"
 								},
 								"clientOptions": {
@@ -1438,7 +1439,7 @@ export const MCP_TOOLS = {
 		}),
 	},
 	"DeleteProviderVersion": {
-		description: "Delete a provider version\n\nSoft-archives a version on the `draft`, `ai`, or `rejected` branch — sets `status` to `ARCHIVED` so history is preserved. Trunk (live) and `in_review` versions cannot be archived this way; archive the parent provider instead. Supports optimistic concurrency via `If-Match`.",
+		description: "Delete a provider version\n\nSoft-archives a version on the `draft`, `ai`, or `rejected` branch — sets `status` to `ARCHIVED` so history is preserved. `fixed`, trunk (live), and `in_review` versions cannot be archived this way; archive the parent provider instead. Supports optimistic concurrency via `If-Match`.",
 		inputSchema: toZod({
 			"type": "object",
 			"properties": {
@@ -1774,7 +1775,7 @@ export const MCP_TOOLS = {
 		}),
 	},
 	"GetProviderVersion": {
-		description: "Get a specific provider version",
+		description: "Get a specific provider version\n\nFetches one exact canonical version. Trunk is public when the provider is public. Non-trunk versions are visible to admins and members of the provider's organization. A member of the organization that paid for a successful AI repair may also read only the exact `fixed` version created by that repair.",
 		inputSchema: toZod({
 			"type": "object",
 			"properties": {
@@ -2151,7 +2152,7 @@ export const MCP_TOOLS = {
 		}),
 	},
 	"ListProviderVersions": {
-		description: "List a provider's versions\n\nLists versions visible to the caller. Non-public branches (`ai`, `draft`, `in_review`, `rejected`) are only visible to members of the provider's owning organization.",
+		description: "List a provider's versions\n\nLists versions visible to the caller. Non-public branches (`ai`, `draft`, `fixed`, `in_review`, `rejected`) are only visible to members of the provider's owning organization.",
 		inputSchema: toZod({
 			"type": "object",
 			"properties": {
@@ -2306,7 +2307,7 @@ export const MCP_TOOLS = {
 		}),
 	},
 	"Providers": {
-		description: "Search providers\n\nSearch published Reclaim providers by domain or data point. A provider is the recipe an end-user follows to prove something about themselves (e.g. \"I have N followers on Twitter\"). Returns a list of matches. Call this BEFORE `create_provider` — most popular domains already have a public provider you can reuse.\nCatalog page listing all providers. Returns a paginated list of providers the caller can see. Public providers are visible to everyone; private providers are only visible to org members.",
+		description: "Search providers\n\nSearch Reclaim providers by domain or data point. A provider is the recipe an end-user follows to prove something about themselves, such as \"I have N followers on Twitter\".\nCall this BEFORE `create_provider` — most popular domains already have a public provider you can reuse, and creating another one just stacks duplicates.\nReturns a paginated list of the providers the caller can see: public providers to everyone, private providers only to members of the owning organization.",
 		inputSchema: toZod({
 			"type": "object",
 			"properties": {
@@ -2677,7 +2678,7 @@ export const MCP_TOOLS = {
 					"properties": {
 						"notes": {
 							"type": "string",
-							"description": "Optional note from the author to reviewers (changelog, areas to focus on, etc.).",
+							"description": "Optional note from the author to reviewers (changelog, areas to focus on, and so on).",
 							"maxLength": 10000
 						}
 					}
@@ -2840,6 +2841,13 @@ export const MCP_TOOLS = {
 							"minLength": 1,
 							"maxLength": 200
 						},
+						"region": {
+							"type": "string",
+							"nullable": true,
+							"description": "Confirm or override the provider's region. Send `null` to clear it so the provider applies to every region. See `Provider.region`.",
+							"pattern": "^[a-z]{2}(-[a-z]{2})?$",
+							"maxLength": 5
+						},
 						"title": {
 							"type": "string",
 							"minLength": 1,
@@ -2892,12 +2900,12 @@ export const MCP_TOOLS = {
 								"brandUrl": {
 									"type": "string",
 									"format": "uri",
-									"description": "Canonical homepage of the brand (e.g. `https://google.com`). Used in brand-link cards and JSON-LD.",
+									"description": "Canonical homepage of the brand (for example, `https://google.com`). Used in brand-link cards and JSON-LD.",
 									"maxLength": 2000
 								},
 								"primaryDataPoint": {
 									"type": "string",
-									"description": "Headline data point — the single most-important variable this provider can verify (e.g. `subscriber count`). Used in the provider's SEO title.",
+									"description": "Headline data point — the single most-important variable this provider can verify (for example, `subscriber count`). Used in the provider's SEO title.",
 									"maxLength": 200
 								},
 								"dataPoints": {
@@ -2933,7 +2941,7 @@ export const MCP_TOOLS = {
 		}),
 	},
 	"UpdateProviderVersion": {
-		description: "Update a provider version\n\nMutable only while the version is on the `draft` or `rejected` branch. Versions on `in_review` or the live channel reject all writes here. Caller must be a member of the provider's owning organization. Supports optimistic concurrency via `If-Match`.",
+		description: "Update a provider version\n\nMutable only while the version is on the `draft` or `rejected` branch. Versions on `fixed`, `in_review`, or the live channel reject all writes here. Caller must be a member of the provider's owning organization. Supports optimistic concurrency via `If-Match`.",
 		inputSchema: toZod({
 			"type": "object",
 			"properties": {
@@ -2975,7 +2983,7 @@ export const MCP_TOOLS = {
 				"body": {
 					"type": "object",
 					"additionalProperties": false,
-					"description": "Partial update of a provider version. Mutable only while the version is on the `draft` or `rejected` branch; versions on `in_review` or the live channel reject all writes here. The semver does not change on update — `build_number` increments instead, giving callers a monotonic revision counter without touching the (major, minor, patch) PK. `verificationType` and `prompt` may be updated; omit either to carry the prior build's value forward.",
+					"description": "Partial update of a provider version. Mutable only while the version is on the `draft` or `rejected` branch; versions on `fixed`, `in_review`, or the live channel reject all writes here. The semver does not change on update — `build_number` increments instead, giving callers a monotonic revision counter without touching the (major, minor, patch) PK. `verificationType` and `prompt` may be updated; omit either to carry the prior build's value forward.",
 					"properties": {
 						"initialUrl": {
 							"type": "string",
@@ -3114,7 +3122,7 @@ export const MCP_TOOLS = {
 										"items": {
 											"type": "object",
 											"additionalProperties": false,
-											"description": "Which portions to select from a response. These are selected in order, xpath => jsonPath => regex * These redactions are done client side and only the selected portions are sent to the attestor. The attestor will only be able to see the selected portions alongside the first line of the HTTP response (i.e. \"HTTP/1.1 200 OK\")",
+											"description": "Which portions to select from a response. These are selected in order, xpath => jsonPath => regex * These redactions are done client side and only the selected portions are sent to the attestor. The attestor will only be able to see the selected portions alongside the first line of the HTTP response (that is, \"HTTP/1.1 200 OK\")",
 											"properties": {
 												"xPath": {
 													"type": "string",
@@ -3122,7 +3130,7 @@ export const MCP_TOOLS = {
 												},
 												"jsonPath": {
 													"type": "string",
-													"description": "expect a JSON response, retrieve the item at this path using dot notation for e.g. 'email.addresses.0'"
+													"description": "expect a JSON response, retrieve the item at this path using dot notation, for example 'email.addresses.0'."
 												},
 												"regex": {
 													"type": "string",
@@ -3264,7 +3272,7 @@ export const MCP_TOOLS = {
 										"items": {
 											"type": "object",
 											"additionalProperties": false,
-											"description": "Which portions to select from a response. These are selected in order, xpath => jsonPath => regex * These redactions are done client side and only the selected portions are sent to the attestor. The attestor will only be able to see the selected portions alongside the first line of the HTTP response (i.e. \"HTTP/1.1 200 OK\")",
+											"description": "Which portions to select from a response. These are selected in order, xpath => jsonPath => regex * These redactions are done client side and only the selected portions are sent to the attestor. The attestor will only be able to see the selected portions alongside the first line of the HTTP response (that is, \"HTTP/1.1 200 OK\")",
 											"properties": {
 												"xPath": {
 													"type": "string",
@@ -3272,7 +3280,7 @@ export const MCP_TOOLS = {
 												},
 												"jsonPath": {
 													"type": "string",
-													"description": "expect a JSON response, retrieve the item at this path using dot notation for e.g. 'email.addresses.0'"
+													"description": "expect a JSON response, retrieve the item at this path using dot notation, for example 'email.addresses.0'."
 												},
 												"regex": {
 													"type": "string",
@@ -3329,8 +3337,8 @@ export const MCP_TOOLS = {
 							"properties": {
 								"geoLocation": {
 									"type": "string",
-									"description": "Geographic location (e.g. ISO country code or {{DYNAMIC_GEO}} to use user's geo location) the verification should appear to originate from.",
-									"maxLength": 15,
+									"description": "Geographic location the verification should appear to originate from: a 2-letter ISO country code, or a parameter the attestor resolves at proof time. `{{DYNAMIC_GEO}}` and `{{DYNAMIC_GEO_SECRET}}` are the Verification Client's standard names for the end-user's own country — the `_SECRET` one is delivered as a secret param, so the attestor never learns which country the proof egressed from.",
+									"maxLength": 64,
 									"default": "{{DYNAMIC_GEO}}"
 								},
 								"clientOptions": {

package/src/mcp/api/to-zod.ts

@@ -6,7 +6,7 @@ import type { JSONSchema } from 'zod/v4/core'
  *
  * The generator (`packages/app/scripts/mcp-tools-gen.ts`) inlines `$ref`s it
  * walks through `properties`/`items`, but it does NOT recurse into `allOf` /
- * `anyOf` / `oneOf`. So a schema composed with `allOf` (e.g.
+ * `anyOf` / `oneOf`. So a schema composed with `allOf` (for example,
  * `RequestSelectionTemplate =
  * allOf[ RequestSelection, { multiple, required } ]`,
  * surfaced by the proof tools' `allowedJsRequests`) can carry a dangling

package/src/mcp/api/tools.ts

@@ -9,7 +9,7 @@ import { MCP_TOOLS } from './operations.gen.ts'
 
 /**
  * The generated `MCP_TOOLS` are keyed by OpenAPI `operationId` (PascalCase,
- * e.g. `GetMe`). MCP tools are conventionally snake_case, matching the
+ * For example, `GetMe`). MCP tools are conventionally snake_case, matching the
  * hand-written tools in this server. Convert the public tool name here while
  * still dispatching to the API with the original operationId — doing this in
  * the (non-generated) registration keeps it from being reverted on regen.

package/src/mcp/instructions.ts

@@ -1,66 +1,140 @@
 /**
- * MCP server instructions shown to the LLM when running in BUILDER mode
- * (`USE_OLD_DEVTOOLS=false`). The prose lives in `skill/builder-mode.md`
- * (published via the `files` array) so it can be edited as markdown without
- * touching code. The path resolves identically from `src/mcp` (dev) and
- * `lib/mcp` (published) — both are two levels below the package root.
- * Old-devtools mode has its own reduced set in `../old/instructions.ts`.
+ * The authoring documentation, assembled from `skill/*.md` at module load.
+ *
+ * Two things are served from here:
+ *  - the always-on MCP server `instructions` (one file per backend mode) —
+ *    deliberately small, since every client pays for them on every turn;
+ *  - the deep authoring guide, split into TOPICS and served on demand by the
+ *    `how_it_works` tool. Nothing here is inlined into a tool schema: a doc
+ *    embedded in an input-schema description is paid for on every request
+ *    whether or not it's ever relevant.
+ *
+ * The prose lives in markdown (published via package.json's `files`) so it
+ * can be edited without touching code. Paths resolve identically from
+ * `src/mcp` (dev) and `lib/mcp` (published) — both are two levels below the
+ * package root.
+ *
+ * Assembly has three steps:
+ *  1. `<!-- common: name -->` splices a shared block out of `SKILL.common.md`
+ *     (delimited there by `<!-- section: name -->`), so the two mode guides
+ *     don't drift on the ~60% of prose that is identical.
+ *  2. `%CTX%` expands to the mode's consumer-param namespace — `context.` on
+ *     the builder, `context_` on old-devtools. That is the only textual
+ *     difference across most shared blocks, so tokenizing it keeps them
+ *     shared.
+ *  3. `<!-- topic: name -->` splits the result into the units `how_it_works`
+ *     serves. Backend-independent topics come from their own files instead.
  */
 import assert from 'node:assert'
 import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 
-export const BUILDER_MODE_INSTRUCTIONS = readFileSync(
-	fileURLToPath(new URL('../../skill/builder-mode.md', import.meta.url)),
-	'utf8',
-).trim()
+function readSkill(file: string): string {
+	const url = new URL(`../../skill/${file}`, import.meta.url)
+	return readFileSync(fileURLToPath(url), 'utf8')
+		// Strip any leading frontmatter defensively.
+		.replace(/^---\n[\s\S]*?\n---\n/, '')
+		.trim()
+}
 
-/**
- * `SKILL.builder.md` and `SKILL.old.md` share a lot of prose (steps that are
- * identical regardless of backend, "never do" rules, common troubleshooting).
- * That shared text lives once in `skill/SKILL.common.md`, split into named
- * `<!-- section: name -->`-delimited blocks; each mode file splices a block
- * back in at `<!-- common: name -->`. Parsed once at module load.
- */
-const COMMON_SECTIONS = parseCommonSections(
-	readFileSync(
-		fileURLToPath(new URL('../../skill/SKILL.common.md', import.meta.url)),
-		'utf8',
-	),
-)
+export const BUILDER_MODE_INSTRUCTIONS = readSkill('builder-mode.md')
+export const OLD_MODE_INSTRUCTIONS = readSkill('old-mode.md')
 
-function parseCommonSections(text: string): Record<string, string> {
-	const sections: Record<string, string> = {}
-	const re = /<!-- section: (\S+) -->\n([\s\S]*?)(?=\n<!-- section: |$)/g
+/** Split `<!-- marker: name -->`-delimited blocks, keeping document order. */
+function splitBlocks(text: string, marker: string): Map<string, string> {
+	const blocks = new Map<string, string>()
+	const re = new RegExp(
+		`<!-- ${marker}: (\\S+) -->\\n([\\s\\S]*?)(?=\\n<!-- ${marker}: |$)`,
+		'g',
+	)
 	for(const match of text.matchAll(re)) {
-		// Trim blank LINES only, not inline indentation — some sections are
+		// Trim blank LINES only, not inline indentation — some blocks are
 		// list-continuation text that's intentionally indented on its first line.
-		sections[match[1]] = match[2].replace(/^\n+/, '').replace(/\n+$/, '')
+		blocks.set(match[1], match[2].replace(/^\n+/, '').replace(/\n+$/, ''))
 	}
 
-	return sections
+	return blocks
 }
 
-/**
- * The full provider-authoring guide — the deep capture→prove→publish workflow,
- * decision frameworks, and troubleshooting. Served on demand by the
- * `how_it_works` MCP tool so every client (not just Claude Code, which
- * auto-loads skills) can pull it. There's a guide PER MODE so an agent is never
- * shown auth/publish tools that don't exist in its backend: the server picks
- * one by `oldMode` (see `mcp/start.ts`). Same `../../skill/` path resolution as
- * the instructions above; any leading frontmatter is stripped defensively.
- */
-function readGuide(file: string): string {
-	const url = new URL(file, import.meta.url)
-	const raw = readFileSync(fileURLToPath(url), 'utf8')
-	const stripped = raw.replace(/^---\n[\s\S]*?\n---\n/, '').trim()
+const COMMON_SECTIONS = splitBlocks(readSkill('SKILL.common.md'), 'section')
+
+/** Topics that read the same on both backends, each its own file. */
+const SHARED_TOPIC_FILES: Record<string, string> = {
+	'user-script': 'user-script.md',
+	'interception': 'interception.md',
+	'hash-validation': 'hash-validation.md',
+}
+
+/** One line per topic, shown in the `how_it_works` index so a caller can pick
+ *  the right one without fetching several. Keyed across both modes; only the
+ *  topics a mode actually has are listed back to it. */
+const TOPIC_SUMMARIES: Record<string, string> = {
+	'overview': 'Terminology, your stance, and the whole loop at a glance.',
+	'auth': 'Signing in to the backend, and which token authorizes what.',
+	'browser': 'Choosing a browser source (local Chrome, the Reclaim runtime in '
+		+ 'Docker, a remote Popcorn browser, or a custom CDP endpoint), '
+		+ 'geolocation, live view, and launch troubleshooting.',
+	'capture': 'Tabs, login detection, driving the page, and picking an '
+		+ 'authenticated request to prove.',
+	'draft': 'The OPRF/privacy decision, propose_provider, and the canonical '
+		+ 'drafted shape.',
+	'params': 'Extracted vs consumer-supplied vs secret params, the URL '
+		+ 'character budget, and runtime resolution.',
+	'prove': 'replay_request, the mandatory auth-bound check, run_proof, and '
+		+ 'diagnosing failures.',
+	'publish': 'Creating/reusing a provider, versions, multi-request providers, '
+		+ 'and going live.',
+	'discover': 'Finding the right providers for a dev\'s app and creating a '
+		+ 'verification session.',
+	'user-script': 'Authoring jsUserScripts / customInjection to drive '
+		+ 'login-gated pages.',
+	'interception': 'injectionType / interceptorType, live interception, the '
+		+ 'document-replay flag, and what to do when a site won\'t load or '
+		+ 'won\'t let the user sign in.',
+	'hash-validation': 'bodySniff, and how verifyProof({ providerId }) gates on '
+		+ 'the declared spec hash.',
+	'credentials': 'The eth proof-owner key run_proof signs with.',
+	'never-do': 'The short list of things that always break a provider.',
+	'troubleshooting': 'Expired drafts, browser problems, and where to look '
+		+ 'next.',
+}
 
-	return stripped.replace(/<!-- common: (\S+) -->/g, (whole, name: string) => {
-		const section = COMMON_SECTIONS[name]
-		assert(section, `${file}: no SKILL.common.md section named "${name}"`)
-		return section
+export interface Guide {
+	/** Topic name → its markdown, in document order. */
+	topics: Map<string, string>
+	/** `{ topic, summary }` for every topic this mode has. */
+	index: Array<{ topic: string, summary: string }>
+	/** Every topic concatenated — the whole guide, as it used to be served. */
+	full: string
+}
+
+function buildGuide(file: string, ctxPrefix: string): Guide {
+	const raw = readSkill(file)
+		.replace(/<!-- common: (\S+) -->/g, (_whole, name: string) => {
+			const section = COMMON_SECTIONS.get(name)
+			assert(section, `${file}: no SKILL.common.md section named "${name}"`)
+			return section
+		})
+		.replaceAll('%CTX%', ctxPrefix)
+
+	const topics = splitBlocks(raw, 'topic')
+	assert(topics.size, `${file}: no <!-- topic: … --> sections found`)
+	for(const [name, path] of Object.entries(SHARED_TOPIC_FILES)) {
+		topics.set(name, readSkill(path))
+	}
+
+	const index = [...topics.keys()].map((topic) => {
+		const summary = TOPIC_SUMMARIES[topic]
+		assert(summary, `${file}: no TOPIC_SUMMARIES entry for "${topic}"`)
+		return { topic, summary }
 	})
+
+	return { topics, index, full: [...topics.values()].join('\n\n') }
 }
 
-export const PROVIDER_GUIDE_BUILDER = readGuide('../../skill/SKILL.builder.md')
-export const PROVIDER_GUIDE_OLD = readGuide('../../skill/SKILL.old.md')
+export const GUIDE_BUILDER = buildGuide('SKILL.builder.md', 'context.')
+export const GUIDE_OLD = buildGuide('SKILL.old.md', 'context_')
+
+export function guideFor(oldMode: boolean): Guide {
+	return oldMode ? GUIDE_OLD : GUIDE_BUILDER
+}

package/src/mcp/start.ts

@@ -11,6 +11,7 @@ import {
 	resolveOldMode,
 	sdkApiUrl,
 } from '../consts.ts'
+import { LOGGER } from '../logger.ts'
 import { ReclaimOldClient } from '../old/client.ts'
 import { resolveInitialIdentity } from '../old/identity.ts'
 import { OLD_MODE_INSTRUCTIONS } from '../old/instructions.ts'
@@ -19,6 +20,7 @@ import { buildOldBackendTools } from '../old/tools/build.ts'
 import { NAME, VERSION } from '../pkg.ts'
 import { registerTools } from './api/tools.ts'
 import {
+	type AgentState,
 	buildAgentState,
 	buildAgentTools,
 	buildBuilderAuthenticationTools,
@@ -27,6 +29,7 @@ import {
 	buildLocalCredentialTools,
 	buildModeTools,
 	buildVerificationTools,
+	disposeAgentState,
 	readSession,
 } from './tools/index.ts'
 import { BUILDER_MODE_INSTRUCTIONS } from './instructions.ts'
@@ -52,6 +55,8 @@ export async function startMcpServer() {
 	// deployments — set RECLAIM_AGENT_DISABLED=1 to register only the API
 	// surface.
 	const agentToolsEnabled = !agentDisabled()
+	/** The agent state this server registered, for shutdown to release. */
+	let agentState: AgentState | undefined
 	const builderClient = new ReclaimClient({
 		baseUrl: apiUrl(),
 		// Builder access is orthogonal to publishing mode. A legacy-devtools
@@ -75,8 +80,9 @@ export async function startMcpServer() {
 		})
 		const sdkClient = new ReclaimSdkClient({ baseUrl: sdkApiUrl() })
 		// Shared with buildAgentTools below so the old-mode publish tool can see
-		// the live attach state (e.g. to flag a still-open browser session).
-		const agentState = buildAgentState()
+		// the live attach state (for example, to flag a still-open browser
+		// session).
+		agentState = buildAgentState()
 
 		registerToolList(server, buildBuilderAuthenticationTools(builderClient))
 		registerToolList(server, buildBuilderOrganizationTools(builderClient))
@@ -105,8 +111,8 @@ export async function startMcpServer() {
 		// Register credential tools for ETH credential management.
 		registerToolList(server, buildCredentialTools(client))
 
-		// Higher-level verification orchestrations (e.g. fetch + decrypt result).
-		// Authenticates with RECLAIM_ORG_SECRET, not the session client.
+		// Higher-level verification orchestrations (for example, fetch + decrypt
+		// result). Authenticates with RECLAIM_ORG_SECRET, not the session client.
 		registerToolList(server, buildVerificationTools())
 
 		// Add auto-generated tools with snake_case wrappers
@@ -114,10 +120,68 @@ export async function startMcpServer() {
 		registerTools(server, client)
 
 		if(agentToolsEnabled) {
-			registerToolList(server, buildAgentTools(client))
+			agentState = buildAgentState()
+			registerToolList(server, buildAgentTools(client, client, agentState))
 		}
 	}
 
+	// Anything the session holds has to be released when the session ends, and
+	// the session can end without a single tool call: the developer closes their
+	// agent, the client kills the server, stdin drops. Nothing ran here before,
+	// which left a container up and — worse — a public tunnel still pointing at a
+	// live browser after the session that made it was gone.
+	if(agentToolsEnabled) {
+		installShutdownHooks(() => agentState)
+	}
+
 	const transport = new StdioServerTransport()
 	await server.connect(transport)
 }
+
+/** How long teardown gets before the process leaves anyway. */
+const SHUTDOWN_GRACE_MS = 10_000
+
+/**
+ * Release the browser on every way out we can observe.
+ *
+ * `SIGTERM`/`SIGINT` is how a client stops us; stdin ending is how a stdio
+ * transport says the other side is gone. A `SIGKILL` cannot be caught at all,
+ * which is why `reapOrphanedContainers` exists as the backstop.
+ */
+function installShutdownHooks(state: () => AgentState | undefined): void {
+	let shuttingDown = false
+	const shutdown = (reason: string) => {
+		if(shuttingDown) {
+			return
+		}
+
+		shuttingDown = true
+		const current = state()
+		if(!current) {
+			process.exit(0)
+		}
+
+		LOGGER.info({ reason }, 'releasing the browser before exit')
+		// Bounded: a wedged `docker stop` must not keep the process alive, but
+		// nor should we skip cleanup that would have finished in a second.
+		const timer = setTimeout(() => {
+			LOGGER.warn({ reason }, 'teardown timed out; exiting anyway')
+			process.exit(0)
+		}, SHUTDOWN_GRACE_MS)
+		timer.unref()
+		void disposeAgentState(current)
+			.catch((err: unknown) => {
+				LOGGER.warn({ err }, 'teardown failed')
+			})
+			.finally(() => {
+				clearTimeout(timer)
+				process.exit(0)
+			})
+	}
+
+	process.once('SIGTERM', () => shutdown('SIGTERM'))
+	process.once('SIGINT', () => shutdown('SIGINT'))
+	// The transport's own end of the conversation.
+	process.stdin.once('end', () => shutdown('stdin ended'))
+	process.stdin.once('close', () => shutdown('stdin closed'))
+}

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

@@ -7,7 +7,11 @@ export function analyzeTool(captures: CaptureStore): RegisteredTool {
 		{
 			name: 'analyze_request_constraints',
 			description:
-				'Flag potential provider-authoring concerns for a captured request.',
+				'Flag provider-authoring concerns for one captured request — signed '
+				+ 'request, CSRF dependency, bot challenge, short-lived token, '
+				+ 'GraphQL. Call it on each top candidate from '
+				+ 'find_requests_containing before drafting, and relay the returned '
+				+ '`concerns` to the developer verbatim.',
 			inputSchema: {
 				type: 'object',
 				properties: {