efaimo 0.1.2 → 0.3.0

package/dist/cli.js

@@ -11,14 +11,17 @@ import { SPEC_VERSION } from "./clients/rawprobe.js";
 import { weighServer, weighSkills } from "./weigh/weigh.js";
 import { findSkills } from "./skills/parse.js";
 import { diffServerWeigh } from "./weigh/diff.js";
+import { diffCheck, CheckDiffRefused } from "./check/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, renderCheckDiffPretty, } 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 +39,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) {
@@ -104,6 +108,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")
@@ -116,6 +127,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")
@@ -212,14 +224,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"));
@@ -286,7 +302,12 @@ 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("--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("--allow-rules-drift", "let --diff proceed when the two runs used different rulesets (grade movement is then unattributable)")
+    .option("--fail-on-regression", "with --diff, exit 1 if any subject present in both runs scored lower")
     .option("--anthropic [model]", "use exact Claude token counts where relevant")
     .option("--window <tokens>", "context window the share is reported against", String(DEFAULT_CONTEXT_WINDOW))
     .option("--no-color", "disable colors")
@@ -332,9 +353,48 @@ program
         });
         report = res.report;
     }
+    // A baseline is written unstamped for the same reason weigh's is: a file
+    // 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 the file they should be reading. The whole envelope is
+    // written rather than just its data, because the version and rulesVersion
+    // in it are what make the later comparison trustworthy.
+    const baselineAndDiff = (payload) => {
+        if (opts.out) {
+            fs.writeFileSync(opts.out, toJsonEnvelope("check", payload, { timestamp: false }));
+            console.error(pc.dim(`baseline written: ${opts.out}`));
+        }
+        if (!opts.diff)
+            return;
+        let baseline;
+        try {
+            baseline = JSON.parse(fs.readFileSync(opts.diff, "utf8"));
+        }
+        catch (e) {
+            fail(`could not read the baseline "${opts.diff}": ${e.message}`);
+            return;
+        }
+        const current = JSON.parse(toJsonEnvelope("check", payload, { timestamp: false }));
+        try {
+            const d = diffCheck(baseline, current, { allowRulesDrift: opts.allowRulesDrift });
+            console.log("");
+            console.log(renderCheckDiffPretty(d));
+            if (opts.failOnRegression && d.worsened.length)
+                process.exitCode = 1;
+        }
+        catch (e) {
+            // Every refusal here is a comparison that would have produced a
+            // plausible number from incomparable inputs, so it stops rather than
+            // printing one.
+            if (e instanceof CheckDiffRefused)
+                fail(e.message);
+            throw e;
+        }
+    };
     if (skillSet) {
+        baselineAndDiff(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
@@ -349,8 +409,9 @@ program
     }
     if (!report)
         return;
+    baselineAndDiff(report);
     if (opts.json)
-        console.log(toJsonEnvelope("check", report));
+        console.log(toJsonEnvelope("check", report, envelopeOpts(opts)));
     else if (opts.md)
         console.log(renderCheckMarkdown(report));
     else
@@ -405,41 +466,195 @@ program
         process.exitCode = 1;
     }
 });
+program
+    .command("find")
+    .description("would a search surface these tools? (findability under deferred tool loading)")
+    .argument("[targets...]", "one or more MCP servers: stdio command | http(s) URL. Two or more are merged into one catalog and measured together")
+    .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" +
+    "Pass more than one server and their catalogs are MERGED and measured together, with each tool\n" +
+    "labelled by where it came from. That is the case worth checking: a server author keeps their own\n" +
+    "names apart, nobody coordinates across the several servers a person installs, and the model sees\n" +
+    "one flat list. A single-server run is structurally unable to see a collision between two of them.\n" +
+    "No API key, no network beyond connecting to the server. docs/METHODOLOGY.md has the method.")
+    .action(async (targetArgs, opts) => {
+    colorSetup(opts);
+    const args = targetArgs ?? [];
+    if (!args.length)
+        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 targets = args
+        .map((a) => resolveTarget(a, { forceStdio: opts.stdio, env: opts.env, headers: opts.header }))
+        .map((target) => {
+        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\`.`);
+            throw new Error("unreachable");
+        }
+        return target;
+    });
+    // Several servers are merged into ONE catalog rather than measured one at
+    // a time, because the failure worth finding only exists between them. A
+    // server's author keeps their own tool names apart as a matter of course;
+    // nobody coordinates across the five or ten servers a person actually
+    // installs, and the model sees all of them as one flat list with no
+    // indication of which came from where. Measuring them separately would
+    // report every catalog as tidy and miss exactly the collision that makes a
+    // model pick the wrong tool.
+    //
+    // The origin is attached for the report and NOT for the index. Prefixing
+    // names with their server would hand every tool a term no other tool has,
+    // and a catalog of indistinguishable tools would score a perfect 100.
+    let tools = [];
+    let definitionTokens = 0;
+    for (const target of targets) {
+        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 w = await weighServer(intro);
+        definitionTokens += w.totals.claudeStyle;
+        tools = tools.concat(targets.length > 1 ? intro.tools.map((tool) => ({ ...tool, origin: target.label })) : intro.tools);
+    }
+    const label = targets.length === 1 ? targets[0].label : `${targets.length} servers`;
+    const result = analyzeFind(label, tools, {
+        topK,
+        definitionTokens,
+        sources: targets.map((x) => x.label),
+    });
+    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 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 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 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/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

@@ -26,6 +26,17 @@ export interface ToolDef {
     inputSchema?: unknown;
     outputSchema?: unknown;
     annotations?: Record<string, unknown>;
+    /**
+     * Which server this tool came from, when several are analysed together.
+     *
+     * DISPLAY ONLY. It is deliberately absent from `indexedTerms`, and putting
+     * it there would be the same bug the query builder already documents: a
+     * per-server token has maximal idf, so prefixing names with their origin
+     * would hand every tool a word no other tool has and report a catalog of
+     * indistinguishable tools as perfectly distinct. The measurement has to see
+     * exactly what a model sees, which is a flat list with no origin attached.
+     */
+    origin?: string;
 }
 export interface ResourceDef {
     uri: string;
@@ -155,6 +166,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 +196,123 @@ 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;
+    /** The server this tool came from, when more than one was analysed. */
+    origin?: 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 servers whose catalogs were merged, when more than one.
+     *
+     * Present only for a stack. A single server's author avoids collisions
+     * inside their own catalog as a matter of course, so a one-server run is
+     * structurally unable to see the failure that actually bites: two servers
+     * installed side by side, each internally tidy, exposing tools a model
+     * cannot tell apart.
+     */
+    sources?: string[];
+    /**
+     * 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 +383,9 @@ export interface SkillRuleContext {
     set: SkillSet;
     weigh?: SkillSetWeighResult;
 }
+export interface FindRuleContext {
+    find: FindResult;
+}
 export interface McpRule {
     id: string;
     title: string;
@@ -260,3 +398,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;