@fangorn-network/westmarch 0.0.1-dev

package/docs/app-to-agent.md

@@ -0,0 +1,351 @@
+# From app to agent: registering and discovering a runtime-free backend
+
+This walks one static site from nothing to "any agent can find it and use it":
+
+1. The site exposes WebMCP tools and an A2A agent card.
+2. You claim a Fangorn app and point it at that card.
+3. You register the card as an ERC-8004 agent, which makes it publicly searchable.
+4. Someone who has never heard of it discovers it, verifies it, and drives it.
+
+It runs on Arbitrum Sepolia. Steps 1–5 and 7 were run against the live chain (step 6's
+publish commands are from the CLI's help and have not been run for Kingsfoil yet); [Kingsfoil](#reference-kingsfoil) is the worked example, and its real values are
+at the end.
+
+```
+ ERC-8004 identity registry ──(A2A endpoint)──┐
+   (searchable on 8004scan)                   ▼
+                                  https://your.site/.well-known/agent-card.json
+ Fangorn AppRegistry ──(agent_uri)────────────▲   │
+   AppAgentChanged log = the app directory        │ card names appId, fromBlock,
+                                                  │ namespaces, views, WebMCP tools
+                                                  ▼
+                  https://your.site/tools-page  ← a browser, or fangorn-mcp driving Chrome
+                  document.modelContext tools, static shards, no server
+```
+
+## What you need
+
+- Node 22, and the SDK/CLI: `npm i -g @fangorn-network/sdk@2026.9.22-dev` (gives `fangorn`)
+- A wallet on Arbitrum Sepolia with a little ETH. **It owns the app forever**; use the
+  wallet that will publish the data.
+- A Pinata JWT. ERC-8004 registration pins a registration file to IPFS.
+- A static host that serves `/.well-known/` and custom headers (Cloudflare Pages does both).
+- `@fangorn/westmarch` for the card generator and the discovery helpers.
+
+Configure the CLI once:
+
+```sh
+fangorn init          # writes ~/.fangorn/config.json: key, Pinata JWT, gateway
+fangorn wallet        # confirm which address will sign
+```
+
+> The config file wins over `ETH_PRIVATE_KEY` in the environment. If `fangorn wallet`
+> shows the wrong address, that's why.
+
+## 1. Expose tools with WebMCP
+
+The site's agent surface is a function that registers tools on `document.modelContext`.
+Guard it, since most browsers don't have WebMCP yet:
+
+```js
+// app/agent.js
+import { search, getRow } from "@fangorn/westmarch/tools";
+
+const ok = (o) => ({ content: [{ type: "text", text: JSON.stringify(o) }] });
+
+export function registerAgent(ctx) {
+    const mc = document.modelContext;
+    if (!mc?.registerTool) return 0;
+    mc.registerTool({
+        name: "search-rows",
+        description: "Search the corpus by meaning. Call this first.",
+        inputSchema: { type: "object", properties: { query: { type: "string" } } },
+        execute: async ({ query }) => ok(search(ctx.rows(), query, ctx.roles(), { qv: await ctx.queryVector(query) })),
+    });
+    // …more tools
+}
+```
+
+Call it only once the data the tools read has loaded, not at module top level. A human
+clicks after the page has settled; an agent calls the moment a tool appears, and a tool
+that answers before its data exists answers wrong without erroring. (Kingsfoil's first
+search routed to zero areas until its tools waited for `routes.json`.)
+
+```js
+const data = await loadIndex();   // whatever the tools read
+registerAgent(ctxOver(data));
+```
+
+`@fangorn/westmarch/tools` holds verbs that work on any corpus (describe, search, browse,
+facet, get, neighbours). Add a domain verb only when the generic ones can't express it.
+
+## 2. Generate the agent card
+
+A WebMCP tool only exists inside a loaded tab, so the card is the only machine-readable
+record that the tools exist. Don't write the tool list by hand. `captureTools` runs your
+register function against a recording stub, so the card lists exactly what the browser
+registers. No `execute` runs during capture.
+
+```js
+// pipeline/agent-card.mjs — run at build time, after the site is built
+import { writeFileSync, mkdirSync } from "node:fs";
+import { agentCard, captureTools } from "@fangorn/westmarch/agent-card";
+import { registerAgent } from "../app/agent.js";
+
+const tools = await captureTools(() => registerAgent({}));
+const card = agentCard({
+    name: "My App",
+    description: "What a stranger gets from this, in two sentences.",
+    url: "https://my-app.pages.dev/tools.html", // the page that REGISTERS the tools, not just the site
+    version: "2026-09-22",
+    tools,
+    tags: ["my-app"],
+    fangorn: {
+        app: "my-app",                          // the name you will claim in step 4
+        fromBlock: 311671082,                   // see below
+        namespaces: ["my-app"],                 // where your data is published
+        views: ["https://my-app.pages.dev/v1"], // baked quickbeam views, if any
+    },
+});
+
+mkdirSync("site/.well-known", { recursive: true });
+writeFileSync("site/.well-known/agent-card.json", JSON.stringify(card, null, 1));
+// Discovery runs in other sites' tabs: without CORS the browser won't hand over the card.
+writeFileSync("site/_headers", "/.well-known/agent-card.json\n  Access-Control-Allow-Origin: *\n");
+```
+
+The `fangorn` block becomes an A2A extension (`https://fangorn.network/a2a/app/v1`) holding
+the chain, the registry addresses (taken from the SDK, so they can't drift), your appId,
+`fromBlock`, `namespaces` and `views`. `agentCard` validates these fields the same way
+readers will, so a bad card fails your build, not someone else's discovery.
+
+**`fromBlock`** is where readers start scanning for your data. Set it to the current block
+**before** you claim the app:
+
+```sh
+node -e 'const {createPublicClient,http}=require("viem");const {arbitrumSepolia}=require("viem/chains");
+createPublicClient({chain:arbitrumSepolia,transport:http()}).getBlockNumber().then(String).then(console.log)'
+```
+
+Too early is only slow: readers query logs 1000 blocks per call. Leave it at 0 and a reader
+makes hundreds of thousands of calls.
+
+**Hard-code these values once the app is claimed.** A rebuild that drops the extension
+publishes a card that every reader rejects.
+
+## 3. Deploy and check the card
+
+```sh
+npx wrangler pages deploy site --project-name my-app
+curl -sD - https://my-app.pages.dev/.well-known/agent-card.json -o /dev/null | grep -iE "^HTTP|content-type|access-control"
+# HTTP/2 200 · content-type: application/json · access-control-allow-origin: *
+```
+
+The card has to be live before step 5, because the CLI fetches it.
+
+## 4. Claim the app
+
+```sh
+fangorn --app my-app app info     # "unclaimed", and the wallet you expect
+fangorn --app my-app app claim    # first come, first served; permanent
+```
+
+With no flags, `claim` uses placeholder terms. Publish real ones later with
+`fangorn app terms <hash> <uri>`; anyone who joined under the old terms has to accept again.
+`--fee <wei>` sets a join fee.
+
+## 5. Register the agent and bind the card
+
+```sh
+fangorn --app my-app app agent https://my-app.pages.dev/.well-known/agent-card.json
+# Agent ID:  421614:226
+# Card:      https://my-app.pages.dev/.well-known/agent-card.json
+# Tx:        0x…
+```
+
+This command does two things:
+
+1. **ERC-8004.** It builds a registration file from the card (name, description, A2A
+   endpoint = the card URL, trust = reputation, x402 only if a skill is tagged `x402`),
+   pins it to Pinata, and mints an agent in the identity registry at
+   `0x8004A818BFB912233c491871b3d84c89A494BD9e`. That's the same address as on Ethereum
+   and Base Sepolia. [8004scan](https://8004scan.io) indexes it within minutes.
+2. **Fangorn.** It calls `setAppAgentUri(cardUrl)`, which emits `AppAgentChanged`. That log
+   is the app directory: westmarch's `listApps` reads it.
+
+`--skip-register` does only the second step, e.g. to move a card that's already registered
+to a new URL.
+
+## 6. Publish data into the app
+
+The owner is the app's first publisher, but still needs global standing:
+
+```sh
+fangorn --app my-app register
+fangorn --app my-app repo init my-app
+fangorn --app my-app commit graph.json -m "first bake" --replace
+fangorn --app my-app push
+```
+
+`graph.json` is `{ vertices: [{id, tag, payload}], edges?: [{rel, from, to}] }`.
+`westmarch/publish/graph.js` builds one from a file tree.
+
+## 7. Discover it
+
+Every route below ends in `discoverApp(cardUrl)`, which accepts a card only if:
+
+- the card carries the Fangorn extension for **this** chain and **this** AppRegistry, and
+- `appAgentUri(card.appId)` on chain is **exactly** the card URL.
+
+The registry and the index are where you look. The on-chain binding is what you trust.
+
+`example/discover.mjs` runs all three routes:
+
+```sh
+node example/discover.mjs card   https://kingsfoil.pages.dev/.well-known/agent-card.json
+node example/discover.mjs chain  311637349          # every app bound since this block
+node example/discover.mjs search Kingsfoil          # the public ERC-8004 index
+```
+
+```
+Kingsfoil  https://kingsfoil.pages.dev/.well-known/agent-card.json
+  app 0x3069…c8ca  data from block 311671082  namespaces kingsfoil
+  open https://kingsfoil.pages.dev — WebMCP tools: list-areas, search-trials, get-trial, …
+```
+
+**From a card URL** (someone handed it to you):
+
+```js
+import { Fangorn, FangornConfig } from "@fangorn-network/sdk";
+import { generatePrivateKey } from "viem/accounts";
+// Fangorn.create needs a signer; a throwaway key is fine for reading.
+const fangorn = Fangorn.create({ privateKey: generatePrivateKey(), config: FangornConfig });
+const { card, appId, fromBlock, namespaces } = await fangorn.discoverApp(cardUrl);
+```
+
+**From the chain** (every Fangorn app; no index, no server):
+
+```js
+import { listApps } from "@fangorn/westmarch/apps";
+const { apps, rejected } = await listApps(fangorn, { fromBlock: 311637349n });
+// apps: [{ name, appId, card, url, views, namespaces, fromBlock }]
+// rejected: [{ card, why }]: unreachable or not bound, reported rather than dropped
+```
+
+`sourcesFromChain` in `@fangorn/westmarch/directory` turns that into `findCorpora` sources,
+so an agent can rank every app's corpora against a question without downloading a shard.
+In the example page, `?fromBlock=311637349` does the same thing in a browser.
+
+**From ERC-8004** (general-purpose agents that know nothing about Fangorn):
+
+```js
+const api = "https://8004scan.io/api/v1/agents";
+const { items } = await (await fetch(`${api}?chain_id=421614&search=Kingsfoil`)).json();
+const detail = await (await fetch(`${api}/421614/${items[0].token_id}`)).json();
+const found = await fangorn.discoverApp(detail.services.a2a.endpoint);
+```
+
+Without the index, read it straight from the registry: `tokenURI(agentId)` returns the
+registration file's `ipfs://` URI, and its `A2A` endpoint is the card.
+
+### Use it
+
+- **An agent:** open `card.url` in Chrome 150+ with `--enable-features=WebMCP` (headless
+  works) and call the tools the card lists as `webmcp` skills. Queries run in that tab, and
+  nothing reaches a server. WebMCP is not a network MCP server: the tools exist only inside
+  a loaded tab, so an agent outside the browser (Claude Code, a script) needs something
+  that drives the tab for it. `card.url` must be the page that registers the tools, not
+  just the site's root. `fangorn-mcp` is that driver, for every app at once. Register it
+  once:
+
+  ```sh
+  claude mcp add fangorn -- npx -y -p @fangorn/westmarch fangorn-mcp
+  ```
+
+  or, for any MCP client:
+
+  ```json
+  { "mcpServers": { "fangorn": {
+      "command": "npx", "args": ["-y", "-p", "@fangorn/westmarch", "fangorn-mcp"],
+      "env": { "FANGORN_MCP_CDP": "ws://your-browser:9222" } } } }
+  ```
+
+  Drop `env` to use the local Chrome.
+
+  It starts with three tools. `list-apps` reads the apps off the chain and keeps the ones
+  whose cards verify. `open-app kingsfoil` verifies that app's card, opens `card.url` in a
+  tab of one shared Chrome with WebMCP on, and adds the page's tools as
+  `kingsfoil__search-trials` and so on. `call-app-tool` reaches the same tools for clients
+  that don't refresh their tool list. A new app needs no new registration: it shows up in
+  `list-apps` once its card is bound on chain.
+
+  **Where the browser comes from.** Anything that speaks the Chrome DevTools Protocol and
+  has WebMCP will do: a headless Chromium service, a hosted browser, or the local Chrome.
+
+  | setting | browser |
+  |---|---|
+  | `FANGORN_MCP_CDP=http://host:9222` (or `--cdp`) | a running browser's DevTools address |
+  | `FANGORN_MCP_CDP=ws://host:9222/devtools/browser/…` | a browser WebSocket endpoint, which is what hosted services hand out |
+  | neither | the local Chrome 150+ (`CHROME=/path` if it isn't `google-chrome`), headless (`--headed` to watch) |
+
+  A remote browser is never closed. Only the tabs the server opened are. A local Chrome is
+  shared by every session on the machine and closes when the last one exits. Its profile
+  (`~/.cache/westmarch-mcp/`) keeps page downloads such as an embedding model.
+  `--from-block <n>` points the server at another deployment.
+
+- **Without a browser:** the views are plain HTTP (`<view>/cdn/catalog`, then the shards it
+  names). Point `westmarch/consume/shard.js` at `views[i]`.
+- **The committed data itself:**
+
+```js
+fangorn.setAppId(appId);
+const timelines = await fangorn.appNamespaces({ namespace: namespaces[0], fromBlock });
+const { contents } = await fangorn.readNamespace(timelines[0].owner, namespaces[0]);
+```
+
+## What the binding proves, and what it doesn't
+
+- **Proves:** whoever owns the app on chain chose this card URL. Anyone can serve a card
+  claiming any appId, and `discoverApp` rejects it unless the app points back at that exact
+  URL. This is tested (`src/discover-app.test.ts`, `src/app-agent.e2e.test.ts`).
+- **Doesn't prove:** that the page behind `card.url` behaves as described, or that the card
+  wasn't changed after binding. The card is live HTTP, not content-addressed, and the
+  binding is to the URL. That's deliberate: the card is mostly endpoints, which change, and
+  pinning each version would cost a transaction for nothing. The data's integrity comes
+  from the commits, not from the card.
+
+## Gotchas
+
+| symptom | cause |
+|---|---|
+| `not bound to app … on-chain agent_uri is …` | URLs must match exactly. A trailing slash, `http` vs `https`, or a different path counts as a different card. |
+| card rejected after a rebuild | the build dropped the `fangorn` block or changed `fromBlock`/`url`; hard-code them |
+| discovery works in Node, fails in a browser | no `Access-Control-Allow-Origin` on the card |
+| `listApps` takes forever | `fromBlock` is too early; the scan is 1000 blocks per RPC call |
+| a log scan misses a transaction you just sent | fixed in the SDK (uncached head block); upgrade to ≥ 2026.9.22-dev |
+| IPFS reads return "switching to a service worker gateway" | ipfs.io stopped serving raw content; use a Pinata gateway |
+| `app agent` signs as the wrong wallet | `~/.fangorn/config.json` beats `ETH_PRIVATE_KEY` |
+| an agent opens the page and finds no tools | `card.url` is the site root, but the tools register on another page |
+| an agent's first call returns empty, later calls work | the tools registered before their data loaded (step 1) |
+| `fangorn-mcp`: "this browser has no WebMCP" | the browser at `FANGORN_MCP_CDP` (or the local Chrome) lacks `document.modelContext`; it needs Chrome 150+ with `--enable-features=WebMCP`, or a build with it on |
+| `fangorn-mcp`: "no browser: cannot launch google-chrome" | no local Chrome; set `FANGORN_MCP_CDP` |
+| the page isn't listed as a "Web" service on 8004scan | agent0-sdk has no web endpoint type; agents find the page through the card's `url` |
+
+## Reference: Kingsfoil
+
+| | |
+|---|---|
+| site | https://kingsfoil.pages.dev |
+| tools page (`card.url`) | https://kingsfoil.pages.dev/provider.html (the root is the patient view, with no tools) |
+| card | https://kingsfoil.pages.dev/.well-known/agent-card.json |
+| app | `kingsfoil` = `0x3069aaab9c73b01fb147a97106c7e595534850af5cab0e0ff7f2a55554d5c8ca` |
+| owner | `0x7a7849231cF7Ab1EA003BcF0063CB89704D7Cce9` |
+| fromBlock | 311671082 |
+| claim tx | `0x881a88e4775c6360f799503b098f00ef470806278f7b282045d6cc881df3cf72` |
+| ERC-8004 | agent `421614:226`, registration `ipfs://bafkreigmy2ubgzrsp55fnf77fykabapuv4y42nk6peq4ko3oi3w2x7u7ay` |
+| bind tx | `0xc7d8726d31bb9698ba2bfae3bc107a6111062d4b7e26526301a984638ab94c9f` |
+| card script | `kingsfoil/pipeline/agent-card.mjs` |
+
+Deployment (Arbitrum Sepolia, 421614): AppRegistry `0x11d228c4774af3d9cae3b4b6874a12576a1a83ec`,
+DataRegistry `0x775026e905d7b58b34d16bcbd385fa630ee36c26`, earliest AppRegistry event at block
+311637349.

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@fangorn-network/westmarch",
+  "version": "0.0.1-dev",
+  "description": "Publisher and consumer surfaces for a Fangorn app: shape a graph, publish it, read it back as a searchable, agent-drivable catalog",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    "./graph": "./publish/graph.js",
+    "./envelope": "./publish/envelope.js",
+    "./enrich": "./publish/enrich.js",
+    "./shard": "./consume/shard.js",
+    "./embed": "./consume/embed.js",
+    "./rank": "./consume/rank.js",
+    "./apps": "./consume/apps.js",
+    "./agent-card": "./publish/agent-card.js",
+    "./roles": "./consume/roles.js",
+    "./directory": "./consume/directory.js",
+    "./taste": "./consume/taste.js",
+    "./corpora": "./consume/corpora.js",
+    "./ui": "./consume/ui.js",
+    "./lint": "./consume/lint.js",
+    "./terms": "./publish/terms.js",
+    "./reactions": "./publish/reactions.js",
+    "./cohort": "./publish/cohort.js",
+    "./vault": "./publish/vault.js",
+    "./taste-doc": "./consume/taste-doc.js",
+    "./settle": "./publish/settle.js",
+    "./manifest": "./publish/manifest.js",
+    "./demand": "./publish/demand.js",
+    "./steam": "./consume/steam.js",
+    "./tools": "./consume/tools.js",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "test": "node publish/terms.js && node publish/reactions.js && node publish/cohort.js && node publish/vault.js && node publish/graph.js && node publish/envelope.js && node publish/demand.js && node publish/settle.js && node publish/manifest.js && node publish/agent-card.js && node publish/cli.js --selfcheck && node publish/enrich.js && node consume/embed.js && node consume/rank.js && node consume/apps.js && node consume/mcp.js --selfcheck && node consume/roles.js && node consume/shard.js && node consume/directory.js && node consume/taste.js && node consume/steam.js && node consume/taste-doc.js && node consume/corpora.js && node consume/ui.js && node consume/lint.js && node consume/tools.js",
+    "lint": "node consume/lint.js"
+  },
+  "peerDependencies": {
+    "@huggingface/transformers": "^4.2.0",
+    "viem": "^2.55.1",
+    "@fangorn-network/sdk": "^2026.9.22-dev",
+    "@noble/curves": "^1.9.1"
+  },
+  "peerDependenciesMeta": {
+    "@huggingface/transformers": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@huggingface/transformers": "^4.2.0",
+    "viem": "^2.56.3",
+    "@fangorn-network/sdk": "^2026.9.22-dev",
+    "@noble/curves": "^1.9.1"
+  },
+  "bin": {
+    "westmarch-publish": "./publish/cli.js",
+    "fangorn-mcp": "./consume/mcp.js"
+  },
+  "files": [
+    "consume",
+    "publish",
+    "docs/app-to-agent.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/publish/agent-card.js

@@ -0,0 +1,134 @@
+// The A2A agent card for a runtime-free backend: `/.well-known/agent-card.json`.
+//
+// A WebMCP tool lives on `document.modelContext` inside a loaded tab. There is
+// no endpoint to crawl, so the card is the only machine-readable trace of the
+// tools: a discovering agent learns the verbs exist from here or not at all.
+//
+// The tools are CAPTURED, not transcribed. The page's own register function is
+// run against a stub `document.modelContext` that records what it registers.
+// Registration only builds descriptors, and no `execute` fires, so the card is
+// generated from the same declarations the browser sees. Add a tool and it
+// appears on the next build; there is no second list to drift.
+//
+// The Fangorn extension is what makes the card an APP rather than a web page.
+// It names the app, where its data starts on chain, and which namespaces and
+// views hold it. It only counts once the app owner binds the card's URL on
+// chain (`setAppAgentUri`). `discoverApp` refuses a card whose app does not
+// point back at it, so writing someone else's appId here gets you nothing.
+
+import { FANGORN_APP_EXTENSION, FangornConfig, appId as hashAppId } from "@fangorn-network/sdk";
+
+/** Run `register` against a recording `document.modelContext`; return what it
+ *  registered. `register` is whatever the page calls at load. */
+export async function captureTools(register) {
+    const tools = [];
+    const had = "document" in globalThis, prev = globalThis.document;
+    globalThis.document = { modelContext: { registerTool: (t) => tools.push(t) } };
+    try { await register(); } finally {
+        if (had) globalThis.document = prev; else delete globalThis.document;
+    }
+    if (!tools.length) throw new Error("no tools captured — does register() call document.modelContext.registerTool?");
+    return tools;
+}
+
+const HEX32 = /^0x[0-9a-fA-F]{64}$/;
+
+/**
+ * The card.
+ *
+ * `fangorn` is optional: without it this is a plain A2A card for a page with
+ * tools. With it, `{app, fromBlock, namespaces, views, config}`:
+ *   app        the app's name or its bytes32 id
+ *   fromBlock  a block at or before the app's registration. The reader's log
+ *              scan starts here; leave it at 0 and a reader makes one RPC call
+ *              per 1000 blocks of chain history.
+ *   views      view bases (quickbeam) holding the baked data. Read by
+ *              westmarch's directory; the SDK ignores it.
+ *   config     the deployment; defaults to the SDK's, so the addresses in the
+ *              card cannot drift from the ones `discoverApp` checks.
+ */
+export function agentCard({ name, description, url, version = "0.0.0", tools = [], tags = [], skills = [], fangorn, ...rest }) {
+    if (!name || !url) throw new Error("agentCard: name and url are required");
+    const card = {
+        protocolVersion: "0.3.0",
+        name, description: description ?? "", url, version,
+        capabilities: { streaming: false, pushNotifications: false, stateTransitionHistory: false },
+        defaultInputModes: ["application/json"],
+        defaultOutputModes: ["application/json"],
+        ...rest,
+        skills: [
+            // `webmcp` is how a caller knows it needs a browser it can drive.
+            ...tools.map((t) => ({
+                id: t.name,
+                name: t.name.replace(/-/g, " ").replace(/^./, (c) => c.toUpperCase()),
+                description: t.description ?? "",
+                tags: [...tags, "webmcp"],
+            })),
+            ...skills,
+        ],
+    };
+    if (fangorn) card.capabilities.extensions = [fangornExtension(fangorn)];
+    return card;
+}
+
+/** The params `discoverApp` reads, validated the same way it validates them.
+ *  A malformed card should fail the build, not the first reader. */
+export function fangornExtension({ app, fromBlock, namespaces = [], views = [], config = FangornConfig }) {
+    if (!app) throw new Error("fangorn.app is required");
+    const id = HEX32.test(app) ? app : hashAppId(app);
+    const from = String(fromBlock ?? "");
+    if (!/^\d+$/.test(from)) throw new Error(`fangorn.fromBlock must be a non-negative integer, got ${fromBlock}`);
+    if (!namespaces.every((n) => typeof n === "string")) throw new Error("fangorn.namespaces must be strings");
+    for (const v of views) {
+        const u = new URL(v);   // throws on garbage
+        if (u.protocol !== "https:" && u.protocol !== "http:") throw new Error(`fangorn.views: not http(s): ${v}`);
+    }
+    return {
+        uri: FANGORN_APP_EXTENSION,
+        description: "The Fangorn app this agent fronts.",
+        required: false,
+        params: {
+            chainId: config.caip2,
+            appRegistry: config.appRegistryContractAddress,
+            dataRegistry: config.dataRegistryContractAddress,
+            appId: id, fromBlock: from, namespaces, views,
+        },
+    };
+}
+
+// ── self-check: `node publish/agent-card.js` ────────────────────────────────
+if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}`) {
+    const eq = (a, b, m) => { if (JSON.stringify(a) !== JSON.stringify(b)) throw new Error(`${m}: ${JSON.stringify(a)} != ${JSON.stringify(b)}`); };
+    const throws = (f, re, m) => { try { f(); } catch (e) { if (re.test(e.message)) return; throw e; } throw new Error(`must throw: ${m}`); };
+
+    const { APP_EXTENSION } = await import("../consume/apps.js");
+    eq(APP_EXTENSION, FANGORN_APP_EXTENSION, "consume/apps.js's copy of the extension uri");
+
+    let fired = 0;
+    const tools = await captureTools(() => {
+        document.modelContext.registerTool({ name: "search-rows", description: "Search.", execute: () => fired++ });
+        document.modelContext.registerTool({ name: "get-row", description: "One row.", execute: () => fired++ });
+    });
+    eq(tools.map((t) => t.name), ["search-rows", "get-row"], "captured tools");
+    if (fired) throw new Error("capture must not execute tools");
+    if ("document" in globalThis) throw new Error("stub document must not leak");
+    await captureTools(() => {}).then(() => { throw new Error("empty capture must throw"); }, () => {});
+
+    const plain = agentCard({ name: "X", url: "https://x.test", tools, tags: ["x"] });
+    eq(plain.skills.map((s) => [s.id, s.name, s.tags]), [["search-rows", "Search rows", ["x", "webmcp"]], ["get-row", "Get row", ["x", "webmcp"]]], "skills");
+    if (plain.capabilities.extensions) throw new Error("no fangorn → no extension");
+
+    const card = agentCard({ name: "X", url: "https://x.test", tools, fangorn: { app: "kingsfoil", fromBlock: 5n, namespaces: ["kingsfoil"], views: ["https://x.test/v1"] } });
+    const [ext] = card.capabilities.extensions;
+    eq(ext.uri, FANGORN_APP_EXTENSION, "extension uri");
+    eq(ext.params.appId, hashAppId("kingsfoil"), "app name hashes to the id the registry uses");
+    eq([ext.params.chainId, ext.params.appRegistry, ext.params.fromBlock], [FangornConfig.caip2, FangornConfig.appRegistryContractAddress, "5"], "deployment + fromBlock as a decimal string");
+    eq(fangornExtension({ app: ext.params.appId, fromBlock: 0 }).params.appId, ext.params.appId, "a bytes32 id passes through");
+
+    throws(() => fangornExtension({ app: "a", fromBlock: -1 }), /fromBlock/, "negative fromBlock");
+    throws(() => fangornExtension({ app: "a" }), /fromBlock/, "missing fromBlock");
+    throws(() => fangornExtension({ app: "a", fromBlock: 0, views: ["javascript:alert(1)"] }), /views/, "non-http view");
+    throws(() => agentCard({ name: "X" }), /url/, "missing url");
+
+    console.log("agent-card.js self-check ok — tools captured without executing, extension matches the SDK's, bad params fail the build");
+}