@fangorn-network/westmarch 0.0.4-dev → 0.0.6-dev

package/README.md

@@ -5,6 +5,9 @@ Everything you need to get started building apps with Fangorn.
 **Start here:** [docs/app-to-agent.md](docs/app-to-agent.md) takes a static site from nothing
 to a Fangorn app and ERC-8004 agent that any agent can discover, verify and drive.
 
+**Just want to query apps from Claude or another MCP client?** [docs/mcp.md](docs/mcp.md)
+installs `fangorn-mcp` in one command.
+
 
 **For Publishers** — shape a tree into a commit graph, describe what's in it, seal and upload the bytes. Needs `fangorn`. Runs anywhere: a script, a server, a browser.
 

package/consume/explore.js

@@ -0,0 +1,243 @@
+// The Fangorn explorer: every verified app, what it is about, and what the
+// ERC-8004 registries say about it — read live, with no bake of its own.
+//
+// Everything here is already published by someone else:
+//   AppRegistry `AppAgentChanged`   which apps exist and where their cards are
+//   each card                       name, tools, views; checked against the chain
+//   each view's catalog             rows, domains, and coverage centroids (what it is about)
+//   ERC-8004 identity `Registered`  the agent minted for the app
+//   ERC-8004 reputation             feedback count and average per agent
+//
+// Both registries answer the whole range in one `eth_getLogs` on Arbitrum
+// Sepolia (39 and ~1.5k logs today), so the page and the MCP tool read the same
+// chain the same way, and a new app shows up on the next read.
+//
+// `client` is a viem PublicClient (getLogs, readContract): passed in, so this
+// runs in a tab and in node, and the self-check needs no chain.
+//
+// ponytail: one getLogs per registry from block 0. An RPC that caps log ranges
+// will refuse it; window the scan then (the SDK's getLogsInWindows).
+
+import { parseAbi, parseAbiItem } from "viem";
+import { APP_EXTENSION } from "./apps.js";
+import { survey, comparable } from "./directory.js";
+import { rankDomains, zFloor, lexScore } from "./rank.js";
+
+export const CHAIN = {
+    chainId: 421614,
+    appRegistry: "0x11d228c4774af3d9cae3b4b6874a12576a1a83ec",
+    identity: "0x8004A818BFB912233c491871b3d84c89A494BD9e",
+    reputation: "0x8004B663056A597Dffe9eCcC1965A193B7388713",
+    scan: (agentId) => `https://8004scan.io/agents/arbitrum-sepolia/${agentId}`,
+};
+
+const APP_AGENT_CHANGED = parseAbiItem("event AppAgentChanged(bytes32 indexed app_id, string agent_uri)");
+const REGISTERED = parseAbiItem("event Registered(uint256 indexed agentId, string agentURI, address indexed owner)");
+const APPS = parseAbi(["function getAppOwner(bytes32) view returns (address)"]);
+const REP = parseAbi([
+    "function getClients(uint256) view returns (address[])",
+    "function getSummary(uint256, address[], string, string) view returns (uint64, int128, uint8)",
+]);
+
+/** A link someone else wrote, shown to a reader: https or nothing. */
+const https = (u) => { try { const x = new URL(String(u)); return x.protocol === "https:" ? x.href : null; } catch { return null; } };
+const slug = (name) => String(name).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-|-$/g, "").slice(0, 24) || "app";
+
+/** A card is listed only if it names this chain's AppRegistry and the app that
+ *  bound it — the checks `discoverApp` makes. The binding itself is the log we
+ *  read it from: we scanned to `latest`, so the last write per app is current. */
+export function verifyCard(card, appId, chain = CHAIN) {
+    const p = card?.capabilities?.extensions?.find((e) => e.uri === APP_EXTENSION)?.params;
+    if (!p) return "no fangorn app extension";
+    if (String(p.appId).toLowerCase() !== appId.toLowerCase()) return "card names another app";
+    if (p.chainId !== chain.chainId || String(p.appRegistry).toLowerCase() !== chain.appRegistry.toLowerCase()) return "card is for another registry";
+    if (!/^\d+$/.test(String(p.fromBlock))) return "bad fromBlock";
+    return null;
+}
+
+/**
+ * The agent an app registered. `fangorn app agent` mints it and then binds the
+ * card, from the owner's wallet, so it is the owner's latest `Registered` at or
+ * before the binding.
+ *
+ * ponytail: paired by owner and block, not by reading the registration file
+ * (IPFS gateways are too slow and flaky for a page load). An owner that
+ * rebinds with --skip-register after minting another app's agent gets that
+ * agent; fetch tokenURI and match its A2A endpoint if that starts happening.
+ */
+export function pairAgent(registered, owner, bindBlock) {
+    let best = null;
+    for (const r of registered) {
+        if (r.owner.toLowerCase() !== owner.toLowerCase() || r.block > bindBlock) continue;
+        if (!best || r.block > best.block || (r.block === best.block && r.agentId > best.agentId)) best = r;
+    }
+    return best?.agentId ?? null;
+}
+
+/** Retried: dropping a verified app over a blip hides it from everyone who
+ *  loads the page in that second. Seen 2026-09-28: headless Chrome in WSL got
+ *  intermittent net::ERR_SSL_PROTOCOL_ERROR from one pages.dev host (curl never
+ *  did); three tries do not always get past that one. */
+async function json(url, timeoutMs = 8000, tries = 3) {
+    try {
+        const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        return await res.json();
+    } catch (e) {
+        if (tries <= 1) throw e;
+        await new Promise((ok) => setTimeout(ok, 600 * (4 - tries)));   // 600ms, then 1.2s
+        return json(url, timeoutMs, tries - 1);
+    }
+}
+
+async function reputation(client, agentId, chain) {
+    try {
+        const clients = await client.readContract({ address: chain.reputation, abi: REP, functionName: "getClients", args: [agentId] });
+        if (!clients.length) return { feedback: 0, average: null };
+        const [count, value, decimals] = await client.readContract({ address: chain.reputation, abi: REP, functionName: "getSummary", args: [agentId, clients, "", ""] });
+        return { feedback: Number(count), average: Number(value) / 10 ** decimals, clients: clients.length };
+    } catch (e) {
+        return { error: e?.shortMessage ?? e?.message ?? String(e) };
+    }
+}
+
+/**
+ * Every verified app, with its 8004 agent, reputation, and catalog.
+ * Unverified apps are dropped, not listed; `dropped` says why, for debugging.
+ */
+export async function readDirectory(client, { chain = CHAIN } = {}) {
+    const [bindLogs, regLogs] = await Promise.all([
+        client.getLogs({ address: chain.appRegistry, event: APP_AGENT_CHANGED, fromBlock: 0n, toBlock: "latest" }),
+        client.getLogs({ address: chain.identity, event: REGISTERED, fromBlock: 0n, toBlock: "latest" }),
+    ]);
+    const registered = regLogs.map((l) => ({ agentId: l.args.agentId, owner: l.args.owner, block: l.blockNumber }));
+    const latest = new Map();   // logs come oldest first: the last write wins
+    for (const l of bindLogs) latest.set(l.args.app_id, { uri: l.args.agent_uri, block: l.blockNumber });
+
+    // Two passes: verify every card (small), then read catalogs (Quorum's is
+    // 1.7 MB, Kingsfoil has 23). Only a card failure drops an app; an owner or
+    // catalog that fails leaves it listed with less to say about it.
+    const dropped = [];
+    const verified = (await Promise.all([...latest].map(async ([appId, { uri, block }]) => {
+        if (!uri) return null;   // unbound on purpose
+        try {
+            if (!/^https:\/\//.test(uri)) throw new Error("card is not https");
+            const card = await json(uri);
+            const why = verifyCard(card, appId, chain);
+            if (why) throw new Error(why);
+            return { appId, uri, block, card };
+        } catch (e) { dropped.push({ card: uri, why: e?.message ?? String(e) }); return null; }
+    }))).filter(Boolean);
+
+    const apps = await Promise.all(verified.map(async ({ appId, uri, block, card }) => {
+        const p = card.capabilities.extensions.find((e) => e.uri === APP_EXTENSION).params;
+        const owner = await client.readContract({ address: chain.appRegistry, abi: APPS, functionName: "getAppOwner", args: [appId] }).catch(() => null);
+        const agentId = owner && pairAgent(registered, owner, block);
+        const { corpora, unreachable } = await survey((p.views ?? []).filter((v) => /^https:\/\//.test(v)));
+        const name = typeof card.name === "string" && card.name.trim() ? card.name.trim() : `App ${appId.slice(0, 10)}`;
+        return {
+            app: slug(name), name, description: typeof card.description === "string" ? card.description : "",
+            site: https(card.url), card: uri, appId, owner,
+            boundAt: Number(block), fromBlock: Number(p.fromBlock),
+            tools: (card.skills ?? []).map((s) => s.id),
+            agent: agentId == null ? null : { id: Number(agentId), scan: chain.scan(agentId) },
+            reputation: agentId == null ? null : await reputation(client, agentId, chain),
+            // null, not 0, when no catalog answered: "0 records" would claim it was counted.
+            rows: corpora.length ? corpora.reduce((n, c) => n + (c.rows || 0), 0) : null,
+            unreachable: unreachable.length,
+            domains: corpora.map((c) => ({ name: c.domain, description: c.description, rows: c.rows, coverage: c.coverage, model: c.model })),
+        };
+    }));
+    apps.sort((a, b) => a.name.localeCompare(b.name));
+    return { apps, dropped };
+}
+
+/** A calibration knob, not a law: nomic-embed-text-v1.5 at 256d, 5 apps
+ *  (2026-09-28). Every on-topic top app scored >= 0.545 ("a cozy game" ->
+ *  Sidequest), every off-topic top <= 0.52 ("bitcoin" -> Audius). Re-measure
+ *  with the explorer's check when the model or the network changes much. */
+export const MIN_AFFINITY = 0.53;
+
+// ponytail: a short English list, enough for questions put to a directory.
+const FILLER = new Set("the and for are was were has have had not but with from that this these those what which where when who whom whose why how can could would should will shall may might must about into onto over under than then there their them they you your our any all some more most much many app apps find show tell learn know want need good best reputable".split(" "));
+
+/**
+ * Rank a directory against a question. An app scores as its best domain's
+ * coverage affinity (what its data is about, not what its blurb says). With no
+ * `qv` (no embedder yet), name and description are matched by words.
+ *
+ * `relevant`: mean + 1σ of this query's scores, and at least MIN_AFFINITY.
+ * Unlike findCorpora the top app is NOT always relevant: "which app has stock
+ * prices" must be able to answer "none", or the explorer vouches for a
+ * government-records app on a finance question.
+ */
+export function rankApps(apps, query, { qv = null, model = null } = {}) {
+    const q = String(query ?? "").trim().toLowerCase();
+    if (!q) return apps.map((a) => ({ ...a, score: null, relevant: null, ranked_by: null }));
+    // Filler dropped, or "where can I learn about X" matches every blurb with "about" in it.
+    const content = q.split(/[^\p{L}\p{N}]+/u).filter((w) => w.length > 2 && !FILLER.has(w)).join(" ");
+    const words = (a) => (content ? lexScore({ text: `${a.name} ${a.description} ${a.domains.map((d) => d.description ?? "").join(" ")}` }, content) : 0);
+    let scored;
+    if (qv) {
+        scored = apps.map((a) => {
+            const doms = rankDomains(a.domains.filter((d) => comparable(d, model)), qv);
+            const best = doms.find((d) => d.affinity != null);
+            // No coverage (its catalog did not answer, or predates coverage):
+            // its own blurb, by words, rather than silently ranking it last.
+            if (!best) return { ...a, score: null, matched: null, ranked_by: "words", wordHit: words(a) > 0 };
+            return { ...a, score: best.affinity, matched: best.name, ranked_by: "meaning" };
+        });
+    } else {
+        scored = apps.map((a) => ({ ...a, score: words(a), ranked_by: "words" }));
+    }
+    scored.sort((a, b) => (b.score ?? -Infinity) - (a.score ?? -Infinity));
+    const s = scored.filter((a) => a.ranked_by === "meaning").map((a) => a.score);
+    const floor = qv ? Math.max(zFloor(s), MIN_AFFINITY) : 1e-9;
+    return scored.map(({ wordHit, ...a }) => ({ ...a, relevant: wordHit ?? (a.score != null && a.score >= floor) }));
+}
+
+/** What a caller sees: the ranking minus the centroids. Quorum alone has 29
+ *  domains, so an app reports how many, and which one matched. */
+export const brief = ({ domains, ...a }) => ({ ...a, domains: domains.length });
+
+// ── self-check: `node consume/explore.js` ──────────────────────────────────
+if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}` && process.argv[1].endsWith("/explore.js")) {
+    const j = (x) => JSON.stringify(x, (_, v) => (typeof v === "bigint" ? `${v}n` : v));
+    const eq = (a, b, m) => { if (j(a) !== j(b)) throw new Error(`${m}: ${j(a)} != ${j(b)}`); };
+    const O = "0x00000000000000000000000000000000000000aa", P = "0x00000000000000000000000000000000000000bb";
+    const reg = [
+        { agentId: 1n, owner: O, block: 10n }, { agentId: 2n, owner: P, block: 11n },
+        { agentId: 3n, owner: O, block: 20n }, { agentId: 4n, owner: O, block: 99n },
+    ];
+    eq(pairAgent(reg, O, 21n), 3n, "owner's latest agent at or before the binding");
+    eq(pairAgent(reg, P.toUpperCase().replace("0X", "0x"), 50n), 2n, "owner compared case-insensitively");
+    eq(pairAgent(reg, O, 5n), null, "no agent before the binding");
+
+    const A = "0x" + "a".repeat(64);
+    const card = (params) => ({ capabilities: { extensions: [{ uri: APP_EXTENSION, params }] } });
+    const good = { appId: A, chainId: CHAIN.chainId, appRegistry: CHAIN.appRegistry.toUpperCase().replace("0X", "0x"), fromBlock: "7" };
+    eq(verifyCard(card(good), A), null, "a good card verifies");
+    eq(verifyCard(card({ ...good, appId: "0x" + "b".repeat(64) }), A), "card names another app", "wrong app");
+    eq(verifyCard(card({ ...good, chainId: 1 }), A), "card is for another registry", "wrong chain");
+    eq(verifyCard({}, A), "no fangorn app extension", "no extension");
+
+    const cov = (v) => ({ vectors: [v] });
+    const apps = [
+        { name: "Tunes", description: "music tracks", domains: [{ name: "tracks", coverage: cov([1, 0, 0]) }] },
+        { name: "Sky", description: "weather alerts", domains: [{ name: "alerts", coverage: cov([0, 1, 0]) }, { name: "old", coverage: null }] },
+        { name: "Law", description: "meetings", domains: [{ name: "minutes", coverage: cov([0, 0, 1]) }] },
+        { name: "Empty", description: "", domains: [] },
+    ];
+    const r = rankApps(apps, "rain", { qv: [0.1, 1, 0] });
+    eq(r.map((a) => a.name), ["Sky", "Tunes", "Law", "Empty"], "ranked by best domain affinity, unscored last");
+    eq([r[0].relevant, r[0].matched, r[3].relevant], [true, "alerts", false], "top is relevant, unscored is not");
+    const blind = rankApps([{ ...apps[1], domains: [] }, apps[0], apps[2]], "weather alerts", { qv: [0.1, 1, 0] });
+    eq(blind.map((a) => [a.name, a.relevant, a.ranked_by]).at(-1), ["Sky", true, "words"], "an app with no coverage still matches on its own words");
+    eq(rankApps([{ ...apps[1], description: "all about the sky", domains: [] }], "where can I learn about music", { qv: [1, 0, 0] })[0].relevant, false, "filler words never match");
+    eq(rankApps(apps, "stock prices", { qv: [-1, -1, -1] }).filter((a) => a.relevant).length, 0, "a question no app covers matches none");
+    eq(rankApps(apps, "music").map((a) => [a.name, a.relevant]).slice(0, 2), [["Tunes", true], ["Sky", false]], "word fallback");
+    eq(rankApps(apps, "").map((a) => a.score), [null, null, null, null], "no query: listed, not ranked");
+    eq([https("javascript:alert(1)"), https("http://x.test"), https("https://x.test/a")], [null, null, "https://x.test/a"], "only https links reach a reader");
+    eq(brief({ name: "x", domains: [{ name: "d", coverage: 1 }] }), { name: "x", domains: 1 }, "brief drops centroids");
+    console.log("explore.js self-check ok — cards verified, agents paired by owner and block, apps ranked by coverage or words");
+}

package/consume/mcp.js

@@ -284,6 +284,11 @@ const META = [
     { name: "list-apps",
       description: "List the Fangorn apps registered on chain whose agent cards verify: name, description, card URL, and the WebMCP tools each page offers. Filter with `query`. Call open-app on one to use its tools.",
       inputSchema: { type: "object", properties: { query: { type: "string", description: "Case-insensitive match on name or description" } } } },
+    { name: "find-apps",
+      description: "Find Fangorn apps for a question, ranked by what their data is about (e.g. \"where can I learn about weather?\", \"music\"). Each app carries its site, agent card, ERC-8004 agent with an 8004scan link, ERC-8004 reputation (feedback count and average), record count and bound block. Only apps whose cards verify on chain. `relevant: true` marks the ones worth opening; the rest are sorted, not relevant. With no query, lists every app. Then open-app.",
+      inputSchema: { type: "object", properties: {
+          query: { type: "string", description: "What the person is looking for, in their words" },
+          limit: { type: "integer", minimum: 1, maximum: 50, default: 10 } } } },
     { name: "open-app",
       description: "Verify an app's card against the chain and add its tools to this server as `<app>__<tool>`. An app that publishes views gets fast data tools (describe, search, get, similar, count, browse) with no browser. `page: true` also opens the app's page in a browser for its own WebMCP tools (slower). `app` is a name from list-apps, an appId, or a card URL.",
       inputSchema: { type: "object", properties: { app: { type: "string" }, page: { type: "boolean", description: "Also load the page's own WebMCP tools in a browser" } }, required: ["app"] } },
@@ -295,6 +300,7 @@ const META = [
 /**
  * The server. `deps` is the outside world, so the self-check can fake it:
  *   findApps()          → { apps: [{ name, desc, card, appId }], rejected }
+ *   exploreApps(query)  → { apps: ranked explore.js entries, ranked_by }
  *   findByName(name)    → { card, appId } | null     (optional: a direct registry read)
  *   resolveCard(url)    → { card, page, verified, views }
  *   viewTools(app)      → { tools, call(name, args) } | null   (no browser)
@@ -377,6 +383,11 @@ export function handlers(deps) {
                 unverified: rejected.length,
             });
         },
+        "find-apps": async ({ query, limit = 10 }) => {
+            const { apps, ranked_by } = await deps.exploreApps(query);
+            return text({ query: query ?? null, ranked_by, apps: apps.slice(0, Math.min(50, Math.max(1, limit)))
+                .map((a) => ({ ...a, open: open.has(a.app) })) });
+        },
         "open-app": async ({ app, page }) => {
             const o = await openApp(app, { page });
             return text({ app: o.slug, name: o.name, verified: o.verified,
@@ -419,6 +430,7 @@ if (process.argv[2] === "--selfcheck") {
     let opened = 0;
     const deps = {
         findApps: async () => ({ apps: [{ name: "Kings Foil", desc: "trials", card: "https://k.test/card", appId: "0xk", tools: ["greet"] }], rejected: [{}] }),
+        exploreApps: async (q) => ({ ranked_by: q ? "meaning" : null, apps: [{ app: "kings-foil", name: "Kings Foil", relevant: true }, { app: "b", name: "B", relevant: false }] }),
         resolveCard: async () => ({ card: { name: "Kings Foil" }, page: "https://k.test/p", verified: true }),
         openTab: async () => (opened++ ? "ev" : "dead"),   // the first tab dies
         tabTools: async () => [{ name: "greet", description: "Hi.", inputSchema: { type: "object" } }],
@@ -435,10 +447,13 @@ if (process.argv[2] === "--selfcheck") {
 
     rpc(1, "initialize", {}); rpc(2, "tools/list"); call(3, "list-apps", { query: "TRIAL" }); call(4, "kings-foil__greet"); await wait();
     assert(res(1).result.capabilities.tools.listChanged, "advertises list_changed");
-    assert(res(2).result.tools.length === 3, "only the meta tools before anything is open");
+    assert(res(2).result.tools.length === 4, "only the meta tools before anything is open");
     assert(body(3).apps[0].app === "kings-foil" && body(3).unverified === 1, "list-apps filters and slugs");
     assert(res(4).result.isError && /not open/.test(res(4).result.content[0].text), "an unopened app's tool is an error");
 
+    call(30, "find-apps", { query: "trials", limit: 1 }); await wait();
+    assert(body(30).ranked_by === "meaning" && body(30).apps.length === 1 && body(30).apps[0].open === false, "find-apps ranks, caps, and says what is open");
+
     call(5, "open-app", { app: "Kings Foil" }); await wait();
     call(6, "open-app", { app: "https://k.test/card" }); await wait();
     assert(body(5).tools[0].name === "greet" && opened === 1, "open once, by name or by card URL");
@@ -490,7 +505,7 @@ const fromBlock = fb >= 0 ? BigInt(argv[fb + 1]) : DEFAULT_FROM_BLOCK;
 const headed = argv.includes("--headed");
 const ci = argv.indexOf("--cdp");
 const cdp = ci >= 0 ? argv[ci + 1] : process.env.FANGORN_MCP_CDP || undefined;
-let found, foundAt = 0;
+let found, foundAt = 0, explored, exploredAt = 0;
 const deps = {
     // ponytail: cached for a minute. The scan is a few RPC calls plus a fetch per card.
     findApps: async () => {
@@ -504,6 +519,19 @@ const deps = {
         }
         return found;
     },
+    // ponytail: cached for a minute, like findApps. Two getLogs, a card and catalog per app.
+    exploreApps: async (query) => {
+        if (!explored || Date.now() - exploredAt > 60_000) {
+            const [ex, { createPublicClient, http }, { arbitrumSepolia }] = await Promise.all([import("./explore.js"), import("viem"), import("viem/chains")]);
+            explored = { ex, dir: await ex.readDirectory(createPublicClient({ chain: arbitrumSepolia, transport: http() })) };
+            exploredAt = Date.now();
+        }
+        const { ex, dir } = explored;
+        const { EMBED_MODEL } = await import("./embed.js");
+        const qv = query?.trim() ? await vt.queryVector(query) : null;
+        const apps = ex.rankApps(dir.apps, query, { qv, model: EMBED_MODEL }).map(ex.brief);
+        return { apps, ranked_by: apps[0]?.ranked_by ?? null };
+    },
     findByName: async (name) => {
         const [f, { appId }] = await Promise.all([fangorn(), import("@fangorn-network/sdk")]);
         const reg = f.getAppRegistry();

package/consume/taste.js

@@ -143,6 +143,42 @@ export function recommend(rows, t, { limit = 10, exclude = new Set(), lambda = 0
         .map(({ row, s }) => ({ row, score: Number(s.toFixed(4)) }));
 }
 
+/** The four knobs a person turns on "For you", each 0–1: [default, what it means].
+ *  Tools publish these descriptions as-is, so a person and an agent turn the same dials. */
+export const KNOBS = {
+    lookahead: [0.35, "how far past what you like, toward where your recent likes are heading (the kernel's drift)"],
+    variety: [0.3, "how different the picks are from each other"],
+    surprise: [0, "how much chance reorders the list; 0 is strict best-first"],
+    reach: [0, "how far out from the closest matches to start: 0 is nearest, 1 skips the nearest ~400"],
+};
+const dial = (x, d) => Math.min(1, Math.max(0, Number.isFinite(Number(x)) ? Number(x) : d));
+
+/**
+ * "For you" with the knobs: the kernel over likes and dislikes (`{ id, title, vector }`,
+ * newest last), then `reach` skips the nearest, `surprise` reorders with seeded Gumbel noise
+ * (same seed, same list), and `variety` sets how hard MMR spreads the picks. What Sidequest
+ * shipped, lifted so every page and its `discover` tool rank the same way.
+ */
+export function discover(rows, likes = [], dislikes = [], { limit = 20, seed = 1, exclude = new Set(), ...k } = {}) {
+    const knobs = Object.fromEntries(Object.entries(KNOBS).map(([n, [d]]) => [n, dial(k[n], d)]));
+    const t = taste(likes, dislikes, { drift: knobs.lookahead });
+    if (!t) return { taste: null, knobs: { ...knobs, seed }, picks: [] };
+    const skip = new Set([...exclude, ...likes.map((x) => x.id), ...dislikes.map((x) => x.id)]);
+    let ranked = rows.filter((r) => r.vector && !skip.has(r.id)).map((row) => ({ row, s: score(row, t) })).sort((a, b) => b.s - a.s);
+    const start = Math.round(knobs.reach * Math.min(400, ranked.length / 4));
+    ranked = ranked.slice(start, start + 300);
+    if (knobs.surprise) {
+        let a = (Number(seed) >>> 0) || 1;
+        const rand = () => { a = (a + 0x6d2b79f5) >>> 0; let x = Math.imul(a ^ (a >>> 15), 1 | a); x ^= x + Math.imul(x ^ (x >>> 7), 61 | x); return ((x ^ (x >>> 14)) >>> 0) / 4294967296; };
+        ranked = ranked.map((p) => ({ ...p, s: p.s + 0.04 * knobs.surprise * -Math.log(-Math.log(rand() * 0.999998 + 1e-6)) })).sort((x, y) => y.s - x.s);
+    }
+    return {
+        taste: { from: t.from, rejected: t.rejected, heading: !!t.v, n: t.n },
+        knobs: { ...knobs, seed },
+        picks: diversify(ranked, { limit, lambda: 1 - 0.6 * knobs.variety }).map(({ row, s }) => ({ row, score: Number(s.toFixed(4)) })),
+    };
+}
+
 /**
  * A taste, small enough to paste.
  *
@@ -346,5 +382,19 @@ if (typeof process !== "undefined" && import.meta.url === `file://${process.argv
         if (twice.n !== 3 || twice.from.join() !== kept.from.join()) throw new Error("a second reload must change nothing");
     }
 
-    console.log(`taste.js self-check ok — mu/v/q, drift leans forward, rejection steers, portable in ${size}B, ranks a pool it never saw, MMR keeps a run of near-duplicates from filling the list, provenance and heading survive the restore collapse and do not drift on reload`);
+    // discover: the knobs move the list, a seed pins it, and nothing voted on comes back.
+    {
+        const pool = Array.from({ length: 40 }, (_, i) => { const a = (i * Math.PI) / 80; return { id: `g${i}`, title: `g${i}`, vector: [Math.cos(a), Math.sin(a)], norm: 1 }; });
+        const likes = [pool[0]], dislikes = [pool[39]];
+        const ids = (o) => o.picks.map((p) => p.row.id).join();
+        const base = discover(pool, likes, dislikes, { limit: 5 });
+        if (base.picks[0].row.id !== "g1") throw new Error(`nearest first by default: ${ids(base)}`);
+        if (base.picks.some((p) => p.row.id === "g0" || p.row.id === "g39")) throw new Error("discover must not return what was voted on");
+        if (discover(pool, likes, [], { limit: 5, reach: 1 }).picks[0].row.id === "g1") throw new Error("reach must skip the nearest");
+        const s1 = discover(pool, likes, [], { limit: 5, surprise: 1, seed: 7 });
+        if (ids(s1) !== ids(discover(pool, likes, [], { limit: 5, surprise: 1, seed: 7 }))) throw new Error("the same seed must give the same list");
+        if (discover(pool, [], [], {}).picks.length) throw new Error("no likes, no picks");
+    }
+
+    console.log(`taste.js self-check ok — discover's knobs, mu/v/q, drift leans forward, rejection steers, portable in ${size}B, ranks a pool it never saw, MMR keeps a run of near-duplicates from filling the list, provenance and heading survive the restore collapse and do not drift on reload`);
 }

package/consume/view-tools.js

@@ -51,7 +51,7 @@ export const warm = ({ cacheDir } = {}) => (embedder ??= (async () => {
 export let warmError = null;
 // A model on disk loads in ~0.5s and is worth the wait. A download is 131MB, so
 // until it lands, search ranks by words and says so, rather than stall ~10s.
-const queryVector = async (q) => {
+export const queryVector = async (q) => {
     if (!ready && downloading) return null;
     return (await warm()) ? embedQueryDirect(q).catch(() => null) : null;
 };

package/dist/ts/eval.js

@@ -3,9 +3,10 @@
 //
 //   westmarch-eval <view> [--golden eval/golden.jsonl] [--base <view>] [--known 200] [--json] [--report out.json]
 //
-// A view is a URL or a directory (westmarch-ship --local writes one), served here as a reader fetches it.
 //   westmarch-eval --selfcheck
 //
+// A view is a URL or a directory (westmarch-ship --local writes one), served here as a reader fetches it.
+//
 // It grades the RECIPE — how records are shaped, which fields are embedded, how rows
 // rank — never the data. New records are facts, and a view is not worse for holding
 // them. So: build a base view (main's recipe) and a candidate (the change) from the
@@ -25,6 +26,16 @@
 //   {"id":"addresses","kind":"records","expect":{"match":{"text":"/\\b\\d{2,6} [A-Z]\\w+ (St|Ave)\\b/"}},"max_pct":0.5,"hard":true}
 //       records: the % of rows that satisfy `expect`, lower is better; `hard`: any rise over the base fails.
 //       `of` (a predicate) narrows which rows count, e.g. only meeting items have a date to miss.
+//   {"id":"basin-towns","kind":"coverage","field":"city","values":["Plover","Stevens Point"],"min":0.9}
+//       coverage: the share of `values` that some row holds in `field`, and the missing ones.
+//       `values` may instead be a path (relative to the golden file) to a JSON list, or to an
+//       object {value: weight} such as each town's population: the share is then by weight, and
+//       the missing are listed heaviest first, so the report names the next places to add.
+//       With a base, any fall fails: a recipe that loses a town has dropped its records.
+//
+// Any check may carry a `goal`: the owner's bet it serves (eval/goals.md says what each one
+// is). The report scores each goal apart, so "trades 0.4, general 0.9" shows which bet the
+// app is losing, instead of one mean that hides it.
 //
 // A predicate is {where?, match?, not?}. `where` is fangorn's own whole-value,
 // case-insensitive match — the filter agents use. `match` maps a field (or several
@@ -36,8 +47,9 @@
 import { existsSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { createServer } from "node:http";
 import { homedir } from "node:os";
+import { dirname, join } from "node:path";
 import { configure, loadShard, trimView } from "@fangorn-network/westmarch/shard";
-import { rolesFrom, textOf, titleOf, subtitleOf } from "@fangorn-network/westmarch/roles";
+import { rolesFrom, textOf, titleOf, subtitleOf, values } from "@fangorn-network/westmarch/roles";
 import { search, matches } from "@fangorn-network/westmarch/tools";
 import { EMBED_MODEL, embedQueryDirect } from "@fangorn-network/westmarch/embed";
 /** A drop below this, in mean precision@k or known@10, is "worse". canton-corpus's number. */
@@ -60,21 +72,31 @@ async function grade(rows, roles, checks, qv, known) {
     const byId = new Map(rows.map((r) => [r.id, r]));
     const out = [];
     for (const c of checks) {
+        const goal = c.goal ? { goal: c.goal } : {};
         if (c.kind === "count") {
             const ok = compile(c.expect);
             const n = rows.filter((r) => matches(r, c.where) && ok(r)).length;
-            out.push({ id: c.id, kind: "count", score: n, pass: n >= (c.min ?? 1) && n <= (c.max ?? Infinity) });
+            out.push({ id: c.id, kind: "count", score: n, pass: n >= (c.min ?? 1) && n <= (c.max ?? Infinity), ...goal });
         }
         else if (c.kind === "records") {
             const of = rows.filter(compile(c.of)), ok = compile(c.expect);
             const pct = of.length ? round((100 * of.filter(ok).length) / of.length) : 0;
-            out.push({ id: c.id, kind: "records", score: pct, pass: pct <= c.max_pct, hard: c.hard });
+            out.push({ id: c.id, kind: "records", score: pct, pass: pct <= c.max_pct, hard: c.hard, ...goal });
+        }
+        else if (c.kind === "coverage") {
+            // The same whole-value, any-case reading `where` uses, so covered means an agent's filter finds it.
+            const held = new Set(rows.filter(compile(c.of)).flatMap((r) => values(r[c.field] ?? "").map((v) => v.toLowerCase())));
+            const w = (v) => c.weights?.[v] ?? 1;
+            const missing = c.values.filter((v) => !held.has(v.toLowerCase())).sort((a, b) => w(b) - w(a));
+            const total = c.values.reduce((a, v) => a + w(v), 0);
+            const score = total ? round(1 - missing.reduce((a, v) => a + w(v), 0) / total) : 1;
+            out.push({ id: c.id, kind: "coverage", score, pass: score >= (c.min ?? 0), top: missing.slice(0, 10), ...goal });
         }
         else {
             const k = c.k ?? 5, ok = compile(c.expect);
             const hits = search(rows, c.q, roles, { qv: await qv(c.q), limit: k }).map((h) => byId.get(h.id));
             const score = round(hits.filter(ok).length / k);
-            out.push({ id: c.id, kind: "search", score, pass: score >= (c.min ?? 0), top: hits.slice(0, 3).map((r) => titleOf(r, roles).slice(0, 90)) });
+            out.push({ id: c.id, kind: "search", score, pass: score >= (c.min ?? 0), top: hits.slice(0, 3).map((r) => titleOf(r, roles).slice(0, 90)), ...goal });
         }
     }
     // ponytail: the pool is each view's own rows, so base and candidate sample different
@@ -97,6 +119,18 @@ async function grade(rows, roles, checks, qv, known) {
     }
     return out;
 }
+/** Each goal's checks, scored apart: how many pass, and the mean of its searches and coverages. */
+function byGoal(results) {
+    const out = {};
+    const mean = (xs) => (xs.length ? round(xs.reduce((a, x) => a + x, 0) / xs.length) : null);
+    for (const g of new Set(results.map((r) => r.goal).filter((g) => !!g))) {
+        const rs = results.filter((r) => r.goal === g);
+        out[g] = { checks: rs.length, passing: rs.filter((r) => r.pass).length,
+            search: mean(rs.filter((r) => r.kind === "search").map((r) => r.score)),
+            coverage: mean(rs.filter((r) => r.kind === "coverage").map((r) => r.score)) };
+    }
+    return out;
+}
 /** The candidate against the base. Worse on any one rule is worse. */
 function compare(cand, base) {
     const was = new Map(base.map((r) => [r.id, r.score]));
@@ -110,6 +144,8 @@ function compare(cand, base) {
             failures.push(`${r.id}: answered before, nothing now`);
         if (r.hard && b !== undefined && r.score > b)
             failures.push(`${r.id}: ${b}% → ${r.score}%, and it may not rise`);
+        if (r.kind === "coverage" && b !== undefined && r.score < b)
+            failures.push(`${r.id}: coverage ${b} → ${r.score}; missing ${r.top?.join(", ")}`);
     }
     // Aggregates, over the checks both sides ran: one question moving a rank is noise.
     const both = (kind) => cand.filter((r) => (kind === "known" ? r.id === "known@10" : r.kind === kind) && was.has(r.id));
@@ -143,8 +179,15 @@ async function main() {
         console.error("usage: westmarch-eval <view> [--golden eval/golden.jsonl] [--base <view>] [--known 200] [--json] [--report out.json]");
         process.exit(flags.help ? 0 : 2);
     }
-    const checks = readFileSync(String(flags.golden ?? "eval/golden.jsonl"), "utf8")
+    const golden = String(flags.golden ?? "eval/golden.jsonl");
+    const checks = readFileSync(golden, "utf8")
         .split("\n").filter((l) => l.trim() && !l.startsWith("//")).map((l) => JSON.parse(l));
+    // A coverage list kept in its own file: a list, or {value: weight}.
+    for (const c of checks)
+        if (c.kind === "coverage" && typeof c.values === "string") {
+            const list = JSON.parse(readFileSync(join(dirname(golden), c.values), "utf8"));
+            Object.assign(c, Array.isArray(list) ? { values: list } : { values: Object.keys(list), weights: list });
+        }
     const known = Number(flags.known ?? 200);
     const { env } = await import("@huggingface/transformers");
     env.cacheDir = `${homedir()}/.cache/fangorn-mcp/models`; // shared with fangorn-mcp and westmarch-view
@@ -163,7 +206,7 @@ async function main() {
     const failures = cmp?.failures ?? cand.results.filter((r) => !r.pass).map((r) => `${r.id}: ${r.score} is outside its bounds`);
     // What reproduces this grade: the model, the runtime, and the views (whose manifests hash every shard).
     const report = { model: EMBED_MODEL, node: process.version, platform: `${process.platform}-${process.arch}`,
-        candidate: cand, base, verdict: cmp?.verdict ?? null, deltas: cmp?.deltas ?? [], failures, pass: !failures.length };
+        goals: byGoal(cand.results), candidate: cand, base, verdict: cmp?.verdict ?? null, deltas: cmp?.deltas ?? [], failures, pass: !failures.length };
     if (flags.report)
         writeFileSync(String(flags.report), JSON.stringify(report, null, 1));
     if (flags.json)
@@ -177,6 +220,8 @@ async function main() {
         }
         for (const d of report.deltas)
             console.log(`\n${d.kind}: ${d.base} → ${d.cand}`);
+        for (const [g, s] of Object.entries(report.goals))
+            console.log(`\ngoal ${g}: ${s.passing}/${s.checks} passing${s.search === null ? "" : `, search ${s.search}`}${s.coverage === null ? "" : `, coverage ${s.coverage}`}`);
         console.log(`\n${report.verdict ?? (report.pass ? "pass" : "fail")}${failures.length ? `\n  ${failures.join("\n  ")}` : ""}`);
     }
     process.exit(report.pass ? 0 : 1);
@@ -228,6 +273,14 @@ async function selfcheck() {
     const [scoped] = await grade(rows, roles, [{ id: "s", kind: "records", of: { where: { city: "Stevens Point" } }, expect: { match: { text: "Rd" } }, max_pct: 100 }], async () => null, 0);
     assert(scoped.score === 50, `\`of\` narrows the rows a record check counts: ${scoped.score}`);
     assert(r["known@10"].score === 1, "every title finds its own row");
+    // Coverage, and goals scored apart.
+    const [cov] = await grade(rows, roles, [{ id: "towns", kind: "coverage", field: "city", values: ["plover", "Stevens Point", "Wausau"], min: 0.5, goal: "towns" }], async () => null, 0);
+    assert(cov.score === 0.667 && cov.pass && cov.top?.[0] === "Wausau", `coverage is the share present, the rest listed: ${JSON.stringify(cov)}`);
+    const [pop] = await grade(rows, roles, [{ id: "pop", kind: "coverage", field: "city", values: ["Plover", "Wausau", "Adell"],
+            weights: { Plover: 30, Wausau: 60, Adell: 10 } }], async () => null, 0);
+    assert(pop.score === 0.3 && pop.top?.join() === "Wausau,Adell", `weighted coverage, the heaviest gap first: ${JSON.stringify(pop)}`);
+    const goals = byGoal([cov, { ...r.rezoning, goal: "towns" }, r.plover]);
+    assert(goals.towns.checks === 2 && goals.towns.coverage === 0.667 && goals.towns.search === 1 && !("undefined" in goals), `goals: ${JSON.stringify(goals)}`);
     // The verdict.
     const res = (id, score, kind = "search", extra = {}) => ({ id, kind, score, pass: true, ...extra });
     const base = [res("q1", 0.8), res("q2", 0.4), res("known@10", 0.9, "known"), res("pii", 0.1, "records", { hard: true })];
@@ -240,5 +293,6 @@ async function selfcheck() {
     assert(compare([res("q1", 0.8), res("q2", 0.4), res("known@10", 0.9, "known"), res("pii", 0.2, "records", { hard: true })], base).verdict === "worse", "a hard record may not rise");
     assert(compare([res("q1", 0.8, "search", { pass: false }), res("q2", 0.4)], base).verdict === "worse", "a floor fails whatever the base did");
     assert(compare([res("q1", 0.8), res("q2", 0.4), res("q3", 0)], base).verdict === "unchanged", "a new question has no base to fall from");
+    assert(compare([res("cov", 0.9, "coverage")], [res("cov", 1, "coverage")]).verdict === "worse", "coverage may not fall");
     console.log("eval: selfcheck ok");
 }

package/docs/app-to-agent.md

@@ -123,6 +123,13 @@ What is asked lives in `eval/golden.jsonl`, one check per line, as data rather t
 {"id":"addresses","kind":"records","expect":{"match":{"text":"/\\b\\d{2,6} [A-Z]\\w+ St\\b/"}},"max_pct":0.5,"hard":true}
 ```
 
+Which questions go in is the owner's bet: who would pay for this, for which answers.
+Write it down in `eval/goals.md` (the customer, their questions, the coverage they need, a
+date, and what would count as failure), tag each check with the `goal` it serves, and the
+report scores each goal on its own. A `coverage` check (`{"kind":"coverage","field":"city",
+"values":[…]}`) measures how much of the list a goal needs is present at all; with a base,
+any fall fails, because a recipe that loses a town has dropped its records.
+
 `expect` is a predicate over a row: `where` (the whole-value match agents filter with),
 `match` (a field, or several joined by `|`, to a regex; case-insensitive unless written
 `/re/flags`), `not`. Relevance is a predicate and not a list of record ids, because ids
@@ -580,29 +587,20 @@ can keep an app current: a cron job, a CI workflow, or an agent that just publis
 ## Using Fangorn apps from an agent
 
 `fangorn-mcp` is one MCP server for every Fangorn app: a new app needs no new
-registration. You can install it as a single file (Linux x64/arm64): no node, no install,
-and search by meaning included.
-
-```sh
-curl -fLo fangorn-mcp https://github.com/fangorn-network/westmarch/releases/latest/download/fangorn-mcp-linux-x64
-chmod +x fangorn-mcp
-claude mcp add fangorn -- "$PWD/fangorn-mcp"
-```
-
-Or through npm, wherever node is:
+registration. Install it through npm (node ≥ 20):
 
 ```sh
-claude mcp add fangorn -- npx -y -p @fangorn-network/westmarch -p @huggingface/transformers fangorn-mcp
+claude mcp add fangorn -e FANGORN_LOG_WINDOW=100000 -- \
+  npx -y -p @fangorn-network/westmarch -p @huggingface/transformers fangorn-mcp
 ```
 
 Without `-p @huggingface/transformers`, the install is ~500 MB lighter and `search` ranks by
-words, not meaning. For any MCP client:
-
-```json
-{ "mcpServers": { "fangorn": { "command": "/path/to/fangorn-mcp" } } }
-```
+words, not meaning. Without `FANGORN_LOG_WINDOW`, `list-apps` scans the chain 1,000 blocks
+per call and takes minutes.
 
-`bun build-bin.js` in westmarch builds the file (bun ≥ 1.2).
+[docs/mcp.md](mcp.md) has the full setup: other MCP clients, every setting, running from
+source, and troubleshooting. A single-file binary (`bun build-bin.js`) exists but is not
+published yet.
 
 It starts with three tools:
 - **`list-apps`** reads the apps off the chain and keeps the ones whose cards verify.