efaimo 0.1.1 → 0.2.0

package/dist/cli.js

@@ -13,12 +13,14 @@ import { findSkills } from "./skills/parse.js";
 import { diffServerWeigh } from "./weigh/diff.js";
 import { DEFAULT_CONTEXT_WINDOW, formatWindowShare, setContextWindow } from "./weigh/window.js";
 import { checkMcpRepoOnly, checkMcpTarget, checkSkillSet } from "./check/check.js";
-import { renderCheckPretty, renderDiffPretty, renderScenarioPlan, renderServerWeighPretty, renderSkillSetPretty, renderSkillWeighPretty, renderTestReportPretty, setColor, } from "./reporters/pretty.js";
+import { analyzeFind, DEFAULT_TOP_K } from "./find/find.js";
+import { runFindRules } from "./core/engine.js";
+import { renderCheckPretty, renderDiffPretty, renderFindFindingsPretty, renderFindPretty, renderScenarioPlan, renderServerWeighPretty, renderSkillSetPretty, renderSkillWeighPretty, renderTestReportPretty, setColor, } from "./reporters/pretty.js";
 import { parseScenario, runScenario } from "./testing/harness.js";
-import { anthropicRunner } from "./testing/anthropicRunner.js";
+import { acceptsSamplingParams, anthropicRunner } from "./testing/anthropicRunner.js";
 import { openaiRunner, providerForModel } from "./testing/openaiRunner.js";
 import { toJsonEnvelope } from "./reporters/json.js";
-import { renderCheckMarkdown, renderDiffMarkdown, renderSkillSetMarkdown, renderWeighMarkdown } from "./reporters/markdown.js";
+import { renderCheckMarkdown, renderDiffMarkdown, renderFindMarkdown, renderSkillSetMarkdown, renderWeighMarkdown } from "./reporters/markdown.js";
 import { gradeBadgeSpec, makeBadgeSvg, toShieldsEndpoint, weighBadgeSpec } from "./reporters/badge.js";
 import { loadDotEnv } from "./util/dotenv.js";
 // Load a local .env before any command reads a key. Shell env always wins.
@@ -36,6 +38,7 @@ examples:
   $ npx efaimo weigh --client claude-code
   $ npx efaimo check --mcp "npx -y my-mcp-server"      # incl. 2026-07-28 readiness
   $ npx efaimo check --skill ./skills/
+  $ npx efaimo find "npx -y my-mcp-server"             # would a search surface these tools?
   $ npx efaimo weigh "npx -y my-server" --out base.json && npx efaimo weigh "npx -y my-server" --diff base.json
 `);
 function collectPairs(sep) {
@@ -82,12 +85,18 @@ function seconds(value, label = "--timeout") {
         fail(`${label} must be a positive number of seconds, got "${value}"`);
     return n;
 }
-function parseNumberOpt(value, label) {
+function parseNumberOpt(value, label, bound) {
     if (value === undefined)
         return undefined;
     const n = Number(value);
     if (!Number.isFinite(n))
         fail(`${label} must be a number, got "${value}"`);
+    // A budget or a percentage below its floor is not a stricter gate, it is a
+    // nonsensical one: `--max-tokens -5` turned "over budget" into always-true
+    // with a negative ceiling in the message. Reject it at the boundary.
+    if (bound && (bound.exclusive ? n <= bound.min : n < bound.min)) {
+        fail(`${label} must be ${bound.exclusive ? "greater than" : "at least"} ${bound.min}, got "${value}"`);
+    }
     return n;
 }
 function anthropicKeyFor(opts) {
@@ -98,6 +107,13 @@ function anthropicKeyFor(opts) {
         fail("--anthropic needs ANTHROPIC_API_KEY in the environment or a .env file");
     return { apiKey, model: typeof opts.anthropic === "string" ? opts.anthropic : undefined };
 }
+// `--no-timestamp` is commander's negated form, so `opts.timestamp` is true
+// unless the flag is passed. Kept in one helper because three commands take it
+// and the polarity is easy to invert by accident.
+function envelopeOpts(opts) {
+    return { timestamp: opts.timestamp !== false };
+}
+const NO_TIMESTAMP_HELP = "omit generatedAt from JSON output (for committed or diffed artifacts)";
 program
     .command("weigh")
     .description("measure the context cost of MCP tool definitions or Agent Skills")
@@ -110,6 +126,7 @@ program
     .option("--timeout <seconds>", "connect timeout in seconds", "45")
     .option("--json", "print JSON")
     .option("--md", "print Markdown")
+    .option("--no-timestamp", NO_TIMESTAMP_HELP)
     .option("--out <file>", "write the JSON result to a file (usable as a --diff baseline)")
     .option("--diff <baseline>", "compare against a baseline JSON from --out")
     .option("--max-tokens <n>", "exit 1 if the primary total exceeds n tokens")
@@ -122,8 +139,8 @@ program
     colorSetup(opts);
     windowSetup(opts);
     const timeoutMs = seconds(opts.timeout) * 1000;
-    const maxTokens = parseNumberOpt(opts.maxTokens, "--max-tokens");
-    const allowIncreasePct = parseNumberOpt(opts.allowIncrease, "--allow-increase");
+    const maxTokens = parseNumberOpt(opts.maxTokens, "--max-tokens", { min: 0, exclusive: true });
+    const allowIncreasePct = parseNumberOpt(opts.allowIncrease, "--allow-increase", { min: 0 });
     const anthropic = anthropicKeyFor(opts);
     const targets = [];
     if (opts.client) {
@@ -206,14 +223,18 @@ program
     const single = targets.length === 1 && results.length === 1 ? results[0] : undefined;
     const budgetTotal = results.reduce((s, r) => s + (r.kind === "mcp" ? r.totals.claudeStyle : r.totals.metadata + r.totals.body), 0);
     if (opts.out && single) {
-        fs.writeFileSync(opts.out, toJsonEnvelope("weigh", single));
+        // Never stamped. A baseline exists to be compared against, so a field
+        // that differs on every write is the one field a comparison must ignore,
+        // and a committed baseline that diffs on nothing but the clock trains
+        // reviewers to skim exactly the file they should read.
+        fs.writeFileSync(opts.out, toJsonEnvelope("weigh", single, { timestamp: false }));
         console.error(pc.dim(`baseline written: ${opts.out}`));
     }
     else if (opts.out) {
         console.error(pc.yellow("--out skipped: it writes a single baseline, but multiple targets were requested"));
     }
     if (opts.json) {
-        console.log(toJsonEnvelope("weigh", single ?? results));
+        console.log(toJsonEnvelope("weigh", single ?? results, envelopeOpts(opts)));
     }
     else if (opts.md) {
         console.log(results.map(renderWeighMarkdown).join("\n\n---\n\n"));
@@ -239,8 +260,14 @@ program
             fail("--diff works on a single MCP server result");
         const baselineRaw = JSON.parse(fs.readFileSync(opts.diff, "utf8"));
         const baseline = ("data" in baselineRaw && baselineRaw.data ? baselineRaw.data : baselineRaw);
-        if (!baseline?.totals)
-            fail(`"${opts.diff}" is not a weigh baseline (write one with --out)`);
+        // A skill weigh baseline also carries a `totals` object, so a bare
+        // truthiness check passed it through and diffServerWeigh then died on the
+        // missing tool array with a raw TypeError. A server baseline is the one
+        // whose totals hold the three serializations; require the Claude-style
+        // total specifically so a skill baseline is rejected with a clear message.
+        if (!baseline?.totals || typeof baseline.totals.claudeStyle !== "number") {
+            fail(`"${opts.diff}" is not an MCP server weigh baseline; write one with: efaimo weigh <server> --out ${opts.diff}`);
+        }
         const d = diffServerWeigh(baseline, single);
         console.log("");
         console.log(opts.md ? renderDiffMarkdown(d) : renderDiffPretty(d, { maxTokens, allowIncreasePct }));
@@ -274,6 +301,7 @@ program
     .option("--timeout <seconds>", "connect timeout in seconds", "45")
     .option("--json", "print JSON")
     .option("--md", "print Markdown")
+    .option("--no-timestamp", NO_TIMESTAMP_HELP)
     .option("--badge [file]", "write a grade badge SVG + shields endpoint JSON")
     .option("--anthropic [model]", "use exact Claude token counts where relevant")
     .option("--window <tokens>", "context window the share is reported against", String(DEFAULT_CONTEXT_WINDOW))
@@ -322,7 +350,7 @@ program
     }
     if (skillSet) {
         if (opts.json)
-            console.log(toJsonEnvelope("check", skillSet));
+            console.log(toJsonEnvelope("check", skillSet, envelopeOpts(opts)));
         else if (opts.md)
             console.log(renderSkillSetMarkdown(skillSet));
         else
@@ -338,7 +366,7 @@ program
     if (!report)
         return;
     if (opts.json)
-        console.log(toJsonEnvelope("check", report));
+        console.log(toJsonEnvelope("check", report, envelopeOpts(opts)));
     else if (opts.md)
         console.log(renderCheckMarkdown(report));
     else
@@ -393,41 +421,165 @@ program
         process.exitCode = 1;
     }
 });
+program
+    .command("find")
+    .description("would a search surface these tools? (findability under deferred tool loading)")
+    .argument("[target]", "stdio command | http(s) URL")
+    .option("--stdio", "treat target as a stdio command string")
+    .option("--header <header>", 'HTTP header "Key: Value" (repeatable)', collectPairs(":"))
+    .option("--env <pair>", "KEY=VALUE for stdio servers (repeatable)", collectPairs("="))
+    .option("--timeout <seconds>", "connect timeout in seconds", "45")
+    .option("--top <n>", `result window to simulate (Anthropic's documented default is ${DEFAULT_TOP_K}; the probe is vacuous when tools <= top, so gate on --min-distinct rather than on this)`, String(DEFAULT_TOP_K))
+    .option("--min-distinct <pct>", "exit 1 if fewer than pct percent of tools own a word no other tool has")
+    .option("--json", "print JSON")
+    .option("--md", "print Markdown")
+    .option("--no-timestamp", NO_TIMESTAMP_HELP)
+    .option("--no-color", "disable colors")
+    .addHelpText("after", "\nA tool marked defer_loading is kept out of the context window until a search finds it, so a tool\n" +
+    "nothing surfaces costs nothing and does nothing. Two numbers come back. `distinct` is a property of\n" +
+    "the catalog: a tool that owns no word the others lack cannot be matched by any query that does not\n" +
+    "also match a competitor. `probe` is a simulated BM25 search, offline and deterministic, and it\n" +
+    "saturates on well-formed catalogs, so it is a floor test rather than a ranking.\n" +
+    "No API key, no network beyond connecting to the server. docs/METHODOLOGY.md has the method.")
+    .action(async (targetArg, opts) => {
+    colorSetup(opts);
+    if (!targetArg)
+        fail("nothing to search: pass an MCP server (stdio command or URL)");
+    const timeoutMs = seconds(opts.timeout) * 1000;
+    const topK = parseNumberOpt(opts.top, "--top", { min: 1 }) ?? DEFAULT_TOP_K;
+    // A window is a count of results, so a fraction of one is not a stricter
+    // setting, it is a nonsensical one: `--top 2.5` printed "result window 2.5"
+    // while `rank <= 2.5` behaved as 2, so the number in the report and the
+    // number in the comparison disagreed.
+    if (!Number.isInteger(topK))
+        fail(`--top must be a whole number of results, got "${opts.top}"`);
+    const minDistinct = parseNumberOpt(opts.minDistinct, "--min-distinct", { min: 0 });
+    if (minDistinct !== undefined && minDistinct > 100)
+        fail(`--min-distinct is a percentage, got "${opts.minDistinct}"`);
+    const target = resolveTarget(targetArg, { forceStdio: opts.stdio, env: opts.env, headers: opts.header });
+    if (target.kind === "skillset" || target.kind === "repo") {
+        fail(`"${target.label}" is a ${target.kind === "skillset" ? "skill path" : "source directory"}; find needs a live MCP server (stdio command or URL). ` +
+            `Skills have no searchable tool catalog; their trigger-overlap check is S103 in \`efaimo check --skill\`.`);
+    }
+    console.error(pc.dim(`connecting to ${target.label} ...`));
+    const intro = await introspectServer(target, { timeoutMs });
+    // Weighed only to answer one question: is this catalog big enough that a
+    // host would defer it. No API key is involved; the count is the local
+    // o200k estimate the rest of the tool uses.
+    const weigh = await weighServer(intro);
+    const result = analyzeFind(target.label, intro.tools, {
+        topK,
+        definitionTokens: weigh.totals.claudeStyle,
+    });
+    const findings = runFindRules({ find: result });
+    if (opts.json) {
+        console.log(toJsonEnvelope("find", { ...result, findings }, envelopeOpts(opts)));
+    }
+    else if (opts.md) {
+        console.log(renderFindMarkdown(result, findings));
+    }
+    else {
+        console.log(renderFindPretty(result));
+        console.log(renderFindFindingsPretty(result, findings));
+    }
+    // Gated on `distinct`, not on the probe. The probe is 100% by construction
+    // whenever the catalog fits inside the result window, so a gate on it
+    // would pass without examining anything for every small server. Exclusive
+    // vocabulary can fail at two tools and up.
+    //
+    // At ONE tool it cannot: every term is trivially exclusive and the figure
+    // is 100% for any tool whatsoever. Exit 2 rather than 0, because "this
+    // gate cannot be evaluated here" is a different fact from "this gate
+    // passed", and a CI run that silently passes on a catalog nothing was
+    // measured against is the failure this whole command was built around.
+    if (minDistinct !== undefined && result.distinctVacuous) {
+        fail(`--min-distinct cannot be evaluated on a ${result.toolCount}-tool catalog: with nothing to be distinct from, ` +
+            `every term is trivially exclusive and the figure is 100% for any tool. Drop the gate for this server.`);
+    }
+    if (minDistinct !== undefined && result.distinct.pct < minDistinct) {
+        console.error(pc.red(`distinct ${result.distinct.pct}% is below --min-distinct ${minDistinct}% ` +
+            `(${result.distinct.total - result.distinct.count} of ${result.distinct.total} tools own no word the others lack)`));
+        process.exitCode = 1;
+    }
+});
 program
     .command("test")
     .description("does a skill actually improve task completion? (experimental A/B outcome harness)")
     .argument("<scenario>", "a scenario YAML file (see examples/scenario.example.yaml)")
     .option("--live", "run for real (spends tokens; Claude models need ANTHROPIC_API_KEY, GPT models need OPENAI_API_KEY)")
     .option("--model <model>", "override the scenario's model (e.g. gpt-4o-mini, claude-sonnet-5)")
+    .option("--judge-model <model>", "grade with a different model than the one under test (removes self-preference)")
     .option("--json", "print JSON")
     .option("--no-color", "disable colors")
-    .addHelpText("after", "\nWithout --live this validates the scenario and prints the plan, making no API calls.")
+    .addHelpText("after", "\nWithout --live this validates the scenario and prints the plan, making no API calls.\n" +
+    "The judge defaults to the model under test, which means a model grades its own answers; set\n" +
+    "judge_model in the scenario or --judge-model here to separate them. Subject and judge may be\n" +
+    "different providers, in which case both keys are required.")
     .action(async (file, opts) => {
     colorSetup(opts);
     const parsed = parseScenario(file);
-    const scenario = opts.model ? { ...parsed, model: opts.model } : parsed;
+    // --model moves the judge too WHEN the judge was never pinned separately.
+    // Without this, overriding the subject on a scenario that has no
+    // `judge_model` would silently leave the judge on the scenario's original
+    // model: a cross-model judge nobody asked for, in a run whose whole point
+    // is that the comparison is controlled.
+    const judgeFollowsSubject = !parsed.judgeModelExplicit;
+    const model = opts.model ?? parsed.model;
+    const judgeModel = opts.judgeModel ?? (judgeFollowsSubject ? model : parsed.judgeModel);
+    const scenario = { ...parsed, model, judgeModel };
     if (!opts.live) {
         console.log(renderScenarioPlan(scenario));
         return;
     }
-    const provider = providerForModel(scenario.model);
-    if (provider === "unknown") {
-        fail(`model "${scenario.model}" is not supported: efaimo test runs Claude (claude-*) and OpenAI (gpt-*, o*) models`);
+    // Subject and judge are routed independently, so a Claude subject can be
+    // graded by a GPT judge (or the reverse). Every distinct provider in play
+    // needs its own key, and the error says which model asked for it.
+    const runners = new Map();
+    for (const [role, m] of [["model", scenario.model], ["judge model", scenario.judgeModel]]) {
+        const provider = providerForModel(m);
+        if (provider === "unknown") {
+            fail(`${role} "${m}" is not supported: efaimo test runs Claude (claude-*) and OpenAI (gpt-*, o*) models`);
+        }
+        if (runners.has(provider))
+            continue;
+        const envVar = provider === "openai" ? "OPENAI_API_KEY" : "ANTHROPIC_API_KEY";
+        const apiKey = process.env[envVar];
+        if (!apiKey)
+            fail(`${role} "${m}" needs ${envVar} in the environment or a .env file`);
+        if (dotEnvKeys.has(envVar))
+            console.error(pc.dim(`using ${envVar} from .env`));
+        runners.set(provider, provider === "openai" ? openaiRunner(apiKey) : anthropicRunner(apiKey));
+    }
+    const runner = (req) => {
+        const r = runners.get(providerForModel(req.model));
+        // Only the two validated models can reach here today. A future arm that
+        // introduces a third would otherwise die as "undefined is not a
+        // function" with no idea which model it was.
+        if (!r)
+            throw new Error(`no runner for model "${req.model}"; efaimo test runs Claude and OpenAI models`);
+        return r(req);
+    };
+    // Say what the measurement cannot pin down, in the report, every time.
+    const extraNotes = [];
+    if (scenario.judgeModel === scenario.model) {
+        extraNotes.push(`the judge is the same model as the subject, so part of any measured effect is a model preferring its own output. Set judge_model (or --judge-model) to a different model to remove that.`);
+    }
+    if (providerForModel(scenario.judgeModel) === "anthropic" && !acceptsSamplingParams(scenario.judgeModel)) {
+        extraNotes.push(`judge sampling is not pinned: ${scenario.judgeModel} does not accept temperature, so the judge is sampled at its default and its own variance is part of this measurement.`);
     }
-    const envVar = provider === "openai" ? "OPENAI_API_KEY" : "ANTHROPIC_API_KEY";
-    const apiKey = process.env[envVar];
-    if (!apiKey)
-        fail(`model "${scenario.model}" needs ${envVar} in the environment or a .env file`);
-    if (dotEnvKeys.has(envVar))
-        console.error(pc.dim(`using ${envVar} from .env`));
-    const runner = provider === "openai" ? openaiRunner(apiKey) : anthropicRunner(apiKey);
-    console.error(pc.dim(`running ~${scenario.trials * 4} ${provider} API calls against ${scenario.model} ...`));
-    const report = await runScenario(scenario, runner);
+    const models = scenario.judgeModel === scenario.model ? scenario.model : `${scenario.model} judged by ${scenario.judgeModel}`;
+    console.error(pc.dim(`running ~${scenario.trials * 4} API calls against ${models} ...`));
+    const report = await runScenario(scenario, runner, { extraNotes });
     if (opts.json)
         console.log(toJsonEnvelope("test", report));
     else
         console.log(renderTestReportPretty(report));
-    if (report.verdict === "hurts")
+    // `inconclusive` fails too. It means an arm produced no scoreable trial, or
+    // the judge refused on one arm far more than the other, and in both cases
+    // the measurement did not happen. Exiting 0 there would report a green for
+    // precisely the runs where the instrument broke down, which is this
+    // project's documented dominant failure mode wearing a p-value.
+    if (report.verdict === "hurts" || report.verdict === "inconclusive")
         process.exitCode = 1;
 });
 program

package/dist/clients/introspect.js

@@ -23,14 +23,22 @@ export async function introspectServer(target, opts = {}) {
             stderr: "pipe",
         });
         transport = stdio;
+        // Split the budget across the two attempts so a dead server fails in about
+        // one timeout, not two: the legacy handshake got the whole timeout AND the
+        // stateless fallback then re-waited the whole timeout again, so `--timeout 8`
+        // took ~16s wall. The handshake takes the larger share; the fallback gets
+        // what is left, with a floor so a genuinely stateless server still has time
+        // to answer a bare request.
+        const startedAt = Date.now();
         try {
-            await withTimeout(client.connect(stdio), timeoutMs, "connect (stdio)");
+            await withTimeout(client.connect(stdio), Math.max(1, Math.round(timeoutMs * 0.6)), "connect (stdio)");
         }
         catch (e) {
             await safeClose(client, stdio);
             // A 2026-07-28 stateless server has no initialize, so the SDK handshake
             // fails by design; try bare stateless requests before giving up.
-            const rc = await introspectStateless(target, { timeoutMs });
+            const remaining = Math.max(timeoutMs - (Date.now() - startedAt), Math.round(timeoutMs * 0.25));
+            const rc = await introspectStateless(target, { timeoutMs: remaining });
             if (rc)
                 return rc;
             throw connectError(e, target.label, stderrTail);

package/dist/core/engine.d.ts

@@ -1,6 +1,7 @@
-import type { Finding, McpRuleContext } from "./types.js";
+import type { Finding, FindRuleContext, McpRuleContext } from "./types.js";
 /** Run a list of rules, isolating each: a broken rule must never break the audit. */
 export declare function runRules<Ctx>(rules: readonly {
     check(ctx: Ctx): Finding[];
 }[], ctx: Ctx): Finding[];
 export declare function runMcpRules(ctx: McpRuleContext): Finding[];
+export declare function runFindRules(ctx: FindRuleContext): Finding[];

package/dist/core/engine.js

@@ -1,4 +1,5 @@
 import { MCP_RULES } from "../rules/mcp/index.js";
+import { FIND_RULES } from "../rules/find/index.js";
 /** Run a list of rules, isolating each: a broken rule must never break the audit. */
 export function runRules(rules, ctx) {
     const findings = [];
@@ -33,3 +34,6 @@ export function runRules(rules, ctx) {
 export function runMcpRules(ctx) {
     return runRules(MCP_RULES, ctx);
 }
+export function runFindRules(ctx) {
+    return runRules(FIND_RULES, ctx);
+}

package/dist/core/types.d.ts

@@ -155,6 +155,13 @@ export interface ServerWeighResult {
     instructionsTokens: number;
     /** Exact count via Anthropic count_tokens API, when a key was provided. */
     anthropicExactTotal?: number;
+    /**
+     * The model `anthropicExactTotal` was measured against. Always set when the
+     * total is: Claude model lines do not share a tokenizer, so the figure is
+     * exact for this model and approximate for any other, and a count printed
+     * without its model cannot be reproduced.
+     */
+    anthropicExactModel?: string;
     notes: string[];
 }
 export interface SkillWeighEntry {
@@ -178,6 +185,111 @@ export interface SkillSetWeighResult {
     notes: string[];
 }
 export type WeighResult = ServerWeighResult | SkillSetWeighResult;
+/** One tool's result in the findability report (`efaimo find`). */
+export interface ToolFindEntry {
+    name: string;
+    /**
+     * Terms this tool has that no other tool in the catalog has.
+     *
+     * The primary signal, and the only one here that is not a model of anything:
+     * if this is empty, every word the tool contains also appears on some other
+     * tool, so no query can match it without also matching a competitor. That is
+     * a property of the catalog, provable by inspection, with no assumption
+     * about how anyone searches. Capped for display.
+     */
+    ownTerms: string[];
+    /** How many exclusive terms there are in total, before the display cap. */
+    ownTermCount: number;
+    /**
+     * How many of them survive if the searcher does not know the tool's name.
+     *
+     * Names are searchable, so a tool whose only exclusive word is its own name
+     * is findable in principle. It is not findable by anyone describing a task,
+     * which is the situation deferred loading creates. E146 is this number
+     * reaching zero while `ownTermCount` does not.
+     */
+    ownOutsideNameCount: number;
+    /** When ownTermCount is 0: tools whose vocabulary covers this one's (capped). */
+    sharedWith: string[];
+    /**
+     * The terms this tool's own description offers a searcher, most distinctive
+     * first. Never includes the tool's name: the point of the probe is that the
+     * person searching does not know it.
+     */
+    query: string[];
+    /** 1-based rank for that query. Undefined when the description offers no searchable word. */
+    rank?: number;
+    /** BM25 score for its own query, kept so a reader can check the arithmetic. */
+    score: number;
+    /** Tools that scored higher for this tool's own query (capped at 3). */
+    outrankedBy: string[];
+    /** Tools whose score is indistinguishable from this one's, so only the tie-break separates them. Capped for display. */
+    tiedWith: string[];
+    /** How many there are in total, before the display cap. */
+    tiedWithCount: number;
+    /** Rank falls inside the simulated result window. The per-tool form of `probe`. */
+    reachable: boolean;
+    /** Every token of the name is a generic word (E144). */
+    genericName: boolean;
+}
+export interface FindResult {
+    kind: "find";
+    label: string;
+    toolCount: number;
+    /** The whole method, carried with the numbers so a report is self-describing. */
+    method: {
+        tokenizer: string;
+        bm25: {
+            k1: number;
+            b: number;
+        };
+        queryTerms: number;
+        topK: number;
+    };
+    perTool: ToolFindEntry[];
+    /**
+     * The headline: how many tools own at least one word no other tool has.
+     * A measured proportion, deliberately not a letter grade (ADR-030).
+     */
+    distinct: {
+        count: number;
+        total: number;
+        pct: number;
+    };
+    /**
+     * Secondary: how many tools a simulated BM25 search for their own
+     * description returns inside the result window.
+     *
+     * Named `probe` in the JSON, in the output and in the docs, all three. It
+     * was `reach` in one of them and `probe` in the others for a day, which is
+     * how someone scripting a gate on the number they saw printed ends up
+     * looking for a field that does not exist.
+     *
+     * Kept, and kept second, because it is the only number here that models the
+     * actual mechanism, and because it saturates: 100% on every real server
+     * measured. Treat it as a floor test that catches catastrophe, not as a
+     * ranking. See docs/METHODOLOGY.md.
+     */
+    probe: {
+        returned: number;
+        total: number;
+        pct: number;
+    };
+    /** toolCount <= topK, which makes the probe figure 100% by construction. */
+    windowCoversCatalog: boolean;
+    /**
+     * toolCount < 2, which makes the DISTINCT figure 100% by construction: with
+     * one tool every term it has is trivially exclusive. `--min-distinct` cannot
+     * be evaluated in that state and refuses rather than passing.
+     */
+    distinctVacuous: boolean;
+    definitionTokens?: number;
+    /** Anthropic's guidance recommends tool search for a catalog this shape. */
+    deferRecommended: boolean;
+    /** Which of the checkable conditions fired, in words. Empty when none did. */
+    deferBecause: string[];
+    notes: string[];
+}
 export interface SkillInfo {
     dir: string;
     file: string;
@@ -248,6 +360,9 @@ export interface SkillRuleContext {
     set: SkillSet;
     weigh?: SkillSetWeighResult;
 }
+export interface FindRuleContext {
+    find: FindResult;
+}
 export interface McpRule {
     id: string;
     title: string;
@@ -260,3 +375,9 @@ export interface SkillRule {
     surface: "skill";
     check(ctx: SkillRuleContext): Finding[];
 }
+export interface FindRule {
+    id: string;
+    title: string;
+    surface: "find";
+    check(ctx: FindRuleContext): Finding[];
+}

package/dist/find/bm25.d.ts

@@ -0,0 +1,77 @@
+/**
+ * A small, exact BM25 index.
+ *
+ * `efaimo find` needs to answer "would a search over this catalog surface this
+ * tool", and the built-in tool search is server-side: its parameters are not
+ * published, so nothing here can be a reproduction. It is the textbook
+ * Robertson/Sparck-Jones BM25 with its conventional parameters, run offline on
+ * the four fields Anthropic documents as searchable, and both the formula and
+ * the parameters are printed in the output. A reader can disagree with the
+ * model and still check the arithmetic.
+ *
+ * Two properties this file exists to guarantee:
+ *
+ * - **Determinism.** Ties break on the document id by code point, never by
+ *   `localeCompare`, whose collation depends on the host's ICU data. A tool
+ *   that reports other people's nondeterminism (E112) must not have any of its
+ *   own, and "it ranked differently on CI" is exactly the bug that would be
+ *   impossible to reproduce.
+ * - **No silent empties.** `score()` on an empty query returns an empty array
+ *   rather than the whole catalog at score 0. Callers treat that as a finding,
+ *   not as a pass.
+ */
+export interface Bm25Doc {
+    id: string;
+    terms: string[];
+}
+export interface Bm25Hit {
+    id: string;
+    score: number;
+    /**
+     * The document's position in the corpus.
+     *
+     * Present because `id` is not a key. MCP does not forbid two tools sharing a
+     * name, and a caller that located its own row with `findIndex(h => h.id ===
+     * name)` got the better-scoring twin's rank, score and tie set: a tool that
+     * really sat eighth reported rank 1, and the headline moved in the flattering
+     * direction. Match on this instead.
+     */
+    index: number;
+}
+export interface Bm25Params {
+    k1: number;
+    b: number;
+}
+/** The conventional defaults. Printed in every report so the method travels with the number. */
+export declare const DEFAULT_BM25: Bm25Params;
+export declare class Bm25Index {
+    readonly params: Bm25Params;
+    readonly size: number;
+    private readonly ids;
+    private readonly tf;
+    private readonly len;
+    private readonly df;
+    private readonly avgdl;
+    constructor(docs: readonly Bm25Doc[], params?: Bm25Params);
+    /** BM25 IDF. Always positive, so a term present in every document still contributes. */
+    idf(term: string): number;
+    /** Document frequency: how many tools contain this term at all. */
+    documentFrequency(term: string): number;
+    termFrequency(index: number, term: string): number;
+    /**
+     * Score every document against a query, highest first.
+     *
+     * Duplicate query terms are collapsed: a query is a set of keywords here,
+     * not a passage, and counting a repeated term twice would silently weight it.
+     */
+    score(query: readonly string[]): Bm25Hit[];
+}
+/**
+ * Are two scores the same as far as a ranker is concerned?
+ *
+ * Relative, because BM25 scores are unbounded: an absolute epsilon that is
+ * right at score 2 is meaningless at score 40. Two tools this close are
+ * separated only by the tie-break, which means the search picks between them
+ * on the alphabet rather than on relevance.
+ */
+export declare function scoresTie(a: number, bScore: number, rel?: number): boolean;