@fangorn-network/westmarch 0.0.5-dev → 0.0.7-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/embed.js

@@ -24,7 +24,11 @@ export const EMBED_DIM = DIM;
 let _extractor = null;
 const extractor = () => (_extractor ??= (async () => {
     const { pipeline } = await import("@huggingface/transformers");
-    return pipeline("feature-extraction", MODEL, { dtype: "q8" });
+    // WESTMARCH_EMBED_DEVICE=cuda puts the publisher's document side on a GPU (Node only; needs
+    // onnxruntime-node's CUDA binaries). Still q8 at batch 1, so still the same encoder: its
+    // vectors agree with CPU q8 to ~0.99, closer than the browser's WASM q8 queries (~0.98).
+    const device = globalThis.process?.env?.WESTMARCH_EMBED_DEVICE;
+    return pipeline("feature-extraction", MODEL, { dtype: "q8", ...(device && { device }) });
 })());
 
 /** Standardize over the full vector, slice to `dim`, L2-normalize the slice. */

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/docs/app-to-agent.md

@@ -495,13 +495,16 @@ writeFileSync("site/.well-known/agent-card.json", JSON.stringify(card, null, 1))
 
 // The card is read from other origins, so it needs CORS, and so does the view, for
 // agents and pages elsewhere. Bundles and shards are named by their digest, so they
-// never change: tell caches so. (Pages allows one * per rule, hence a rule per domain.)
+// never change: tell caches so. Shards only in the reader's own browser (`private`): a
+// retracted record's bytes must stop being served by shared caches once the deploy drops
+// its shard. (Pages allows one * per rule, hence a rule per domain.)
 const immutable = "  Cache-Control: public, max-age=31536000, immutable\n";
+const mine = "  Cache-Control: private, max-age=31536000, immutable\n";
 writeFileSync("site/_headers",
     "/.well-known/agent-card.json\n  Access-Control-Allow-Origin: *\n"
     + "/view/*\n  Access-Control-Allow-Origin: *\n"
     + `/assets/*\n${immutable}`
-    + readdirSync("site/view/cdn/domains").map((d) => `/view/cdn/domains/${d}/shards/*\n${immutable}`).join(""));
+    + readdirSync("site/view/cdn/domains").map((d) => `/view/cdn/domains/${d}/shards/*\n${mine}`).join(""));
 ```
 
 ```sh
@@ -587,29 +590,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.
+registration. Install it through npm (node ≥ 20):
 
 ```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:
-
-```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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fangorn-network/westmarch",
-  "version": "0.0.5-dev",
+  "version": "0.0.7-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",
@@ -12,6 +12,7 @@
     "./embed": "./consume/embed.js",
     "./rank": "./consume/rank.js",
     "./apps": "./consume/apps.js",
+    "./explore": "./consume/explore.js",
     "./agent-card": "./publish/agent-card.js",
     "./view": "./publish/view.js",
     "./roles": "./consume/roles.js",
@@ -36,7 +37,7 @@
   "scripts": {
     "build": "tsc -p .",
     "prepare": "tsc -p .",
-    "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/view.js && node publish/ship.js --selfcheck && node publish/eval.ts --selfcheck && 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 && node consume/x402.js && node site/feed.js && node site/store.js",
+    "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/view.js && node publish/ship.js --selfcheck && node publish/eval.ts --selfcheck && node publish/cli.js --selfcheck && node publish/enrich.js && node consume/embed.js && node consume/rank.js && node consume/apps.js && node consume/explore.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 && node consume/x402.js && node site/feed.js && node site/store.js",
     "lint": "node consume/lint.js"
   },
   "peerDependencies": {
@@ -62,7 +63,8 @@
     "fangorn-mcp": "./consume/mcp.js",
     "westmarch-view": "./publish/view-cli.js",
     "westmarch-ship": "./publish/ship.js",
-    "westmarch-eval": "./dist/ts/eval.js"
+    "westmarch-eval": "./dist/ts/eval.js",
+    "fangorn-fx": "./plugin/scripts/fx.mjs"
   },
   "files": [
     "consume",
@@ -73,7 +75,8 @@
     "site/feed.js",
     "site/worker.js",
     "site/store.js",
-    "dist/ts"
+    "dist/ts",
+    "plugin/scripts/fx.mjs"
   ],
   "engines": {
     "node": ">=20"