efaimo 0.1.2 → 0.3.0

package/dist/find/tokenize.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The tokenizer the findability simulation runs on.
+ *
+ * Tool search (both variants) matches against a tool's name, description,
+ * argument names and argument descriptions. Anthropic does not publish the
+ * analyzer it uses, so this is a stated approximation rather than a
+ * reproduction, and docs/METHODOLOGY.md says exactly that. What matters is
+ * that it is deterministic and written down: the same catalog always produces
+ * the same terms, on every machine.
+ *
+ * Splitting rules, in order:
+ *   1. camelCase and PascalCase boundaries become separators (`getWeather` ->
+ *      `get weather`), because a regex like `.*weather.*` has to reach the
+ *      second half of a camelCase name and a naive split on `[^a-z0-9]` never
+ *      would.
+ *   2. Runs of digits after letters split too (`s3Bucket` keeps `s3`, but
+ *      `getV2Config` yields `get v2 config`).
+ *   3. Everything that is not a letter or a digit is a separator, so
+ *      `get_weather`, `get-weather` and `get.weather` all land on the same
+ *      two terms.
+ *   4. Lowercase, and drop single characters, which carry no retrieval signal
+ *      and only distort the length normalization.
+ */
+/**
+ * Longest field this will tokenize.
+ *
+ * Every string here comes from the audited server, which may be hostile and is
+ * in any case not obliged to be sensible. The split below is linear, but linear
+ * on ten megabytes is still ten megabytes, done twice per description, and the
+ * connect timeout bounds the RPC rather than what happens after it. A tool
+ * definition that needs more than this to describe itself has a finding of its
+ * own waiting in `check`.
+ */
+export declare const MAX_FIELD_CHARS = 200000;
+export declare function tokenize(text: string): string[];
+/**
+ * English function words, excluded from QUERY SELECTION only.
+ *
+ * They stay in the index on purpose. BM25's IDF already discounts a term that
+ * appears in most documents, and removing them from the index would also
+ * change every document's length, which changes every score. They are excluded
+ * from query selection because that step ranks a tool's own terms by TF-IDF,
+ * and in a small catalog a function word repeated three times in one
+ * description can outrank the domain noun that actually identifies the tool.
+ *
+ * Deliberately short and boring: this list is part of the published method, so
+ * every word in it has to be defensible as a word nobody searches for.
+ */
+export declare const QUERY_STOPWORDS: Set<string>;
+/**
+ * Name tokens that identify nothing on their own.
+ *
+ * Used by E144 only. Anthropic's own debugging note for tool search says
+ * Claude writes broad patterns such as `.*weather.*`, and that adding common
+ * keywords to descriptions improves discoverability. A name assembled purely
+ * from these words carries no such keyword, so the only thing that can reach
+ * the tool is its description.
+ *
+ * A word being here does NOT make a name bad: `get_weather` has `weather`.
+ * The rule fires only when EVERY token of a name is in this set.
+ */
+export declare const GENERIC_NAME_TOKENS: Set<string>;
+/** True when a tool name is built only from words that identify nothing. */
+export declare function nameIsGeneric(name: string): boolean;

package/dist/find/tokenize.js

@@ -0,0 +1,116 @@
+/**
+ * The tokenizer the findability simulation runs on.
+ *
+ * Tool search (both variants) matches against a tool's name, description,
+ * argument names and argument descriptions. Anthropic does not publish the
+ * analyzer it uses, so this is a stated approximation rather than a
+ * reproduction, and docs/METHODOLOGY.md says exactly that. What matters is
+ * that it is deterministic and written down: the same catalog always produces
+ * the same terms, on every machine.
+ *
+ * Splitting rules, in order:
+ *   1. camelCase and PascalCase boundaries become separators (`getWeather` ->
+ *      `get weather`), because a regex like `.*weather.*` has to reach the
+ *      second half of a camelCase name and a naive split on `[^a-z0-9]` never
+ *      would.
+ *   2. Runs of digits after letters split too (`s3Bucket` keeps `s3`, but
+ *      `getV2Config` yields `get v2 config`).
+ *   3. Everything that is not a letter or a digit is a separator, so
+ *      `get_weather`, `get-weather` and `get.weather` all land on the same
+ *      two terms.
+ *   4. Lowercase, and drop single characters, which carry no retrieval signal
+ *      and only distort the length normalization.
+ */
+/**
+ * Longest field this will tokenize.
+ *
+ * Every string here comes from the audited server, which may be hostile and is
+ * in any case not obliged to be sensible. The split below is linear, but linear
+ * on ten megabytes is still ten megabytes, done twice per description, and the
+ * connect timeout bounds the RPC rather than what happens after it. A tool
+ * definition that needs more than this to describe itself has a finding of its
+ * own waiting in `check`.
+ */
+export const MAX_FIELD_CHARS = 200_000;
+export function tokenize(text) {
+    if (!text)
+        return [];
+    return (text.length > MAX_FIELD_CHARS ? text.slice(0, MAX_FIELD_CHARS) : text)
+        // ACRONYMFollowed -> ACRONYM Followed, before the general camel split, so
+        // `HTTPServer` does not become `httpserver` or `h t t p server`.
+        //
+        // One capital, not `[A-Z]+`. The quantified form is quadratic on a run of
+        // capitals with no lowercase after it: every start position backtracks the
+        // whole run. Measured on the old expression, `'A'.repeat(n)` took 43ms at
+        // 10k, 7.8s at 100k and 147s at 400k, so one 300KB shouted description
+        // pinned a core for minutes while `weigh` and `check` on the same server
+        // answered in under a second. `([A-Z])([A-Z][a-z])` matches the same
+        // boundaries in linear time: on `HTTPServer` it still splits at `P|Se`.
+        .replace(/([A-Z])([A-Z][a-z])/g, "$1 $2")
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/([A-Za-z])(\d)/g, "$1 $2")
+        .split(/[^A-Za-z0-9]+/)
+        .map((s) => s.toLowerCase())
+        .filter((s) => s.length > 1);
+}
+/**
+ * English function words, excluded from QUERY SELECTION only.
+ *
+ * They stay in the index on purpose. BM25's IDF already discounts a term that
+ * appears in most documents, and removing them from the index would also
+ * change every document's length, which changes every score. They are excluded
+ * from query selection because that step ranks a tool's own terms by TF-IDF,
+ * and in a small catalog a function word repeated three times in one
+ * description can outrank the domain noun that actually identifies the tool.
+ *
+ * Deliberately short and boring: this list is part of the published method, so
+ * every word in it has to be defensible as a word nobody searches for.
+ */
+export const QUERY_STOPWORDS = new Set([
+    // Two and three letter function words. The tokenizer drops single
+    // characters, so without these a description like "Delete all records in the
+    // datastore" probes with `in`, and a term that appears in half the catalog
+    // spends one of the four query slots saying nothing.
+    "in", "on", "at", "to", "of", "or", "as", "by", "is", "be", "an", "if",
+    "do", "so", "up", "we", "us", "am", "he", "she", "him", "her", "his", "me",
+    "my", "no", "yes",
+    "the", "and", "for", "with", "that", "this", "from", "into", "onto", "than",
+    "then", "they", "them", "their", "there", "these", "those", "will", "would",
+    "shall", "should", "can", "could", "may", "might", "must", "not", "but",
+    "are", "was", "were", "been", "being", "have", "has", "had", "does", "did",
+    "you", "your", "yours", "its", "it", "our", "ours", "any", "all", "each",
+    "such", "only", "also", "more", "most", "some", "other", "when", "where",
+    "which", "while", "what", "who", "whom", "how", "why", "use", "used",
+    "using", "via", "per", "out", "off", "over", "under", "about", "above",
+    "below", "between", "before", "after", "here", "one", "two", "yes", "no",
+]);
+/**
+ * Name tokens that identify nothing on their own.
+ *
+ * Used by E144 only. Anthropic's own debugging note for tool search says
+ * Claude writes broad patterns such as `.*weather.*`, and that adding common
+ * keywords to descriptions improves discoverability. A name assembled purely
+ * from these words carries no such keyword, so the only thing that can reach
+ * the tool is its description.
+ *
+ * A word being here does NOT make a name bad: `get_weather` has `weather`.
+ * The rule fires only when EVERY token of a name is in this set.
+ */
+export const GENERIC_NAME_TOKENS = new Set([
+    "get", "set", "put", "post", "patch", "add", "new", "create", "make",
+    "update", "edit", "modify", "change", "delete", "remove", "drop",
+    "list", "read", "write", "fetch", "load", "save", "send", "call",
+    "run", "exec", "execute", "invoke", "do", "handle", "process", "perform",
+    "query", "search", "find", "lookup", "check", "test", "start", "stop",
+    "open", "close", "begin", "end", "init", "setup", "config", "configure",
+    "tool", "api", "data", "item", "items", "object", "thing", "value",
+    "values", "result", "results", "action", "request", "response", "info",
+    "helper", "util", "utils", "main", "default", "generic", "custom", "my",
+]);
+/** True when a tool name is built only from words that identify nothing. */
+export function nameIsGeneric(name) {
+    const terms = tokenize(name);
+    if (!terms.length)
+        return true;
+    return terms.every((t) => GENERIC_NAME_TOKENS.has(t));
+}

package/dist/index.d.ts

@@ -5,12 +5,16 @@ export { loadClientServers, SUPPORTED_CLIENTS } from "./targets/clientConfigs.js
 export { introspectServer } from "./clients/introspect.js";
 export { weighServer, weighSkills } from "./weigh/weigh.js";
 export { diffServerWeigh, type WeighDiff } from "./weigh/diff.js";
+export { diffCheck, flattenCheck, CheckDiffRefused, type CheckDiffResult, type CheckDiffItem } from "./check/diff.js";
 export { countTokens } from "./weigh/tokens.js";
 export { findSkills, parseSkillFile } from "./skills/parse.js";
+export { analyzeFind, indexedTerms, taskQuery, DEFAULT_TOP_K, DEFAULT_QUERY_TERMS, DEFER_RECOMMENDED_TOKENS, DEFER_RECOMMENDED_TOOLS, type FindOptions } from "./find/find.js";
+export { runFindRules } from "./core/engine.js";
+export { RULES_VERSION } from "./rules/version.js";
 export { checkMcpTarget, checkMcpRepoOnly, checkSkillSet, type SkillReport, type CheckSkillResult } from "./check/check.js";
 export { parseScenario, runScenario, armSystems, type Scenario, type TestReport, type Runner, } from "./testing/harness.js";
-export { anthropicRunner } from "./testing/anthropicRunner.js";
+export { anthropicRunner, acceptsSamplingParams, anthropicRequestBody } from "./testing/anthropicRunner.js";
 export { openaiRunner, providerForModel } from "./testing/openaiRunner.js";
-export { renderCheckPretty, renderSkillSetPretty, renderServerWeighPretty, renderSkillWeighPretty, renderDiffPretty, renderScenarioPlan, renderTestReportPretty, } from "./reporters/pretty.js";
-export { renderCheckMarkdown, renderSkillSetMarkdown, renderWeighMarkdown, renderDiffMarkdown, } from "./reporters/markdown.js";
+export { renderCheckPretty, renderSkillSetPretty, renderServerWeighPretty, renderSkillWeighPretty, renderDiffPretty, renderScenarioPlan, renderTestReportPretty, renderFindPretty, renderFindFindingsPretty, } from "./reporters/pretty.js";
+export { renderCheckMarkdown, renderSkillSetMarkdown, renderWeighMarkdown, renderDiffMarkdown, renderFindMarkdown, } from "./reporters/markdown.js";
 export { toJsonEnvelope } from "./reporters/json.js";

package/dist/index.js

@@ -11,16 +11,27 @@ export { loadClientServers, SUPPORTED_CLIENTS } from "./targets/clientConfigs.js
 export { introspectServer } from "./clients/introspect.js";
 export { weighServer, weighSkills } from "./weigh/weigh.js";
 export { diffServerWeigh } from "./weigh/diff.js";
+export { diffCheck, flattenCheck, CheckDiffRefused } from "./check/diff.js";
 export { countTokens } from "./weigh/tokens.js";
 // Skills
 export { findSkills, parseSkillFile } from "./skills/parse.js";
+// Find (findability under deferred tool loading)
+//
+// Exported because docs/INTEGRATIONS.md promises "every capability is also a
+// typed function", and the blanket re-export of core/types.js was already
+// publishing FindResult and ToolFindEntry: a public type with nothing public
+// that produces one. runFindRules is here for the same reason its output is,
+// even though the rule TABLE stays private like the other two.
+export { analyzeFind, indexedTerms, taskQuery, DEFAULT_TOP_K, DEFAULT_QUERY_TERMS, DEFER_RECOMMENDED_TOKENS, DEFER_RECOMMENDED_TOOLS } from "./find/find.js";
+export { runFindRules } from "./core/engine.js";
+export { RULES_VERSION } from "./rules/version.js";
 // Check (audit)
 export { checkMcpTarget, checkMcpRepoOnly, checkSkillSet } from "./check/check.js";
 // Test (skill A/B outcome harness)
 export { parseScenario, runScenario, armSystems, } from "./testing/harness.js";
-export { anthropicRunner } from "./testing/anthropicRunner.js";
+export { anthropicRunner, acceptsSamplingParams, anthropicRequestBody } from "./testing/anthropicRunner.js";
 export { openaiRunner, providerForModel } from "./testing/openaiRunner.js";
 // Reporters (report -> string; stable value-in/string-out contract)
-export { renderCheckPretty, renderSkillSetPretty, renderServerWeighPretty, renderSkillWeighPretty, renderDiffPretty, renderScenarioPlan, renderTestReportPretty, } from "./reporters/pretty.js";
-export { renderCheckMarkdown, renderSkillSetMarkdown, renderWeighMarkdown, renderDiffMarkdown, } from "./reporters/markdown.js";
+export { renderCheckPretty, renderSkillSetPretty, renderServerWeighPretty, renderSkillWeighPretty, renderDiffPretty, renderScenarioPlan, renderTestReportPretty, renderFindPretty, renderFindFindingsPretty, } from "./reporters/pretty.js";
+export { renderCheckMarkdown, renderSkillSetMarkdown, renderWeighMarkdown, renderDiffMarkdown, renderFindMarkdown, } from "./reporters/markdown.js";
 export { toJsonEnvelope } from "./reporters/json.js";

package/dist/reporters/json.d.ts

@@ -1 +1,19 @@
-export declare function toJsonEnvelope(kind: "check" | "weigh" | "test", data: unknown): string;
+export type EnvelopeKind = "check" | "weigh" | "test" | "find";
+export interface EnvelopeOptions {
+    /**
+     * Include `generatedAt`. Default true for a report a human reads.
+     *
+     * Off for anything meant to be committed, diffed or compared. A wall-clock
+     * stamp inside the payload makes every regeneration a diff even when not one
+     * measured number moved, which is how a re-run that changed nothing still
+     * produces a commit that has to be reviewed as though it might have. This
+     * project has shipped several releases whose only data change was described
+     * in its own notes as "stamp-only".
+     *
+     * `--out` baselines always drop it: a baseline exists to be compared against,
+     * and a field that differs on every write is the one field a comparison must
+     * ignore.
+     */
+    timestamp?: boolean;
+}
+export declare function toJsonEnvelope(kind: EnvelopeKind, data: unknown, opts?: EnvelopeOptions): string;

package/dist/reporters/json.js

@@ -1,10 +1,21 @@
 import { VERSION } from "../version.js";
-export function toJsonEnvelope(kind, data) {
+import { RULES_VERSION } from "../rules/version.js";
+export function toJsonEnvelope(kind, data, opts = {}) {
     return JSON.stringify({
         tool: "efaimo",
         version: VERSION,
+        // Which ruleset produced this. The tool version alone does not say it: a
+        // patch release can change what a rule fires on, and every published
+        // grade is only reproducible if the reader can tell which rules were
+        // being run. See src/rules/version.ts.
+        //
+        // Only where rules actually ran. `weigh` counts tokens and `test` runs
+        // trials; neither evaluates a rule, and stamping a ruleset onto their
+        // output would be a report asserting which rules produced it when none
+        // did.
+        ...(kind === "check" || kind === "find" ? { rulesVersion: RULES_VERSION } : {}),
         kind,
-        generatedAt: new Date().toISOString(),
+        ...(opts.timestamp === false ? {} : { generatedAt: new Date().toISOString() }),
         data,
     }, null, 2);
 }

package/dist/reporters/markdown.d.ts

@@ -1,7 +1,8 @@
-import type { CheckReport, ServerWeighResult, SkillSetWeighResult } from "../core/types.js";
+import type { CheckReport, Finding, FindResult, ServerWeighResult, SkillSetWeighResult } from "../core/types.js";
 import type { CheckSkillResult } from "../check/check.js";
 import type { WeighDiff } from "../weigh/diff.js";
 export declare function renderCheckMarkdown(report: CheckReport): string;
 export declare function renderSkillSetMarkdown(res: CheckSkillResult): string;
 export declare function renderWeighMarkdown(w: ServerWeighResult | SkillSetWeighResult): string;
+export declare function renderFindMarkdown(f: FindResult, findings: Finding[]): string;
 export declare function renderDiffMarkdown(d: WeighDiff): string;

package/dist/reporters/markdown.js

@@ -3,23 +3,57 @@ import { safeText } from "../util/safeText.js";
 const SEV_LABEL = { error: "🔴 error", warn: "🟡 warn", info: "🔵 info" };
 // Everything through here came from the audited target, and
 // docs/INTEGRATIONS.md recommends piping --md into $GITHUB_STEP_SUMMARY, so a
-// hostile tool name or description renders into a page the reader trusts.
-// Two things were missing: control characters (raw ESC bytes were written
-// through literally) and backticks (most call sites wrap the value in a code
-// span, so one backtick closes it and the rest of the name becomes markup).
-// The backtick is neutralised with a zero-width space rather than a backslash,
-// because a backslash is not an escape inside a code span.
-function esc(s) {
+// hostile tool name or description renders into a page the reader trusts. An
+// auditor's verdict must not be rewritable by the thing being audited.
+//
+// Two escapes that were here did not work, both found by adversarial review:
+//
+//   `\|`  was applied without escaping the backslash first. A name containing
+//         backslash-pipe became `\\|`, which GFM reads as an escaped backslash
+//         followed by a LIVE cell delimiter. Extra cells past the header count
+//         are dropped, so a hostile server could push the real verdict column
+//         off the end of the row and supply its own.
+//
+//   `` ` `` was neutralised by putting a zero-width space BEFORE it, which
+//         changes nothing: a code span ends at the next backtick run whatever
+//         precedes it. The rest of the name then rendered as live markup, and a
+//         `[click](url)` in a tool name became a link in the summary. A
+//         backtick cannot be escaped inside a code span at all, so it is
+//         substituted rather than escaped; a tool whose name contains one is
+//         still recognisable and can no longer close the span.
+function escCode(s) {
     return safeText(s)
+        .replace(/[\r\n]+/g, " ")
+        .replace(/\\/g, "\\\\")
         .replace(/\|/g, "\\|")
-        .replace(/`/g, "​`")
-        .replace(/\n/g, " ");
+        .replace(/`/g, "'");
 }
+// For a cell that is NOT wrapped in a code span, where markdown and inline
+// HTML are both live. Every value that reaches one of these should really be
+// in a code span; this is the belt for the places that are not, such as rule
+// messages, which embed a tool name mid-sentence.
+function escText(s) {
+    return escCode(s)
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/([[\]*_~])/g, "\\$1");
+}
+/** Backwards-compatible alias for the code-span form, which is what most call sites want. */
+const esc = escCode;
 function findingsTable(lines, findings) {
     lines.push("| severity | rule | finding |");
     lines.push("|---|---|---|");
     for (const f of findings) {
-        lines.push(`| ${SEV_LABEL[f.severity]} | ${f.ruleId} | ${esc(f.message)} |`);
+        // escText, not escCode: a message is prose, not a code span, so markdown
+        // and inline HTML are both live in this cell. The message embeds a tool
+        // name the target chose.
+        //
+        // detail and fixHint were dropped here, so E141's "every word it has also
+        // appears on: ..." and E142's "outranked by: ..." existed in the terminal
+        // and in JSON and silently vanished from the surface the CI docs recommend.
+        const extra = [f.detail, f.fixHint && `fix: ${f.fixHint}`].filter(Boolean).join(" ");
+        lines.push(`| ${SEV_LABEL[f.severity]} | ${f.ruleId} | ${escText(f.message)}${extra ? ` <br>${escText(extra)}` : ""} |`);
     }
 }
 export function renderCheckMarkdown(report) {
@@ -85,7 +119,10 @@ export function renderWeighMarkdown(w) {
         lines.push(`| Claude-style | ${w.totals.claudeStyle.toLocaleString("en-US")} |`);
         lines.push(`| OpenAI tools | ${w.totals.openaiTools.toLocaleString("en-US")} |`);
         if (w.anthropicExactTotal !== undefined) {
-            lines.push(`| anthropic exact (API) | ${w.anthropicExactTotal.toLocaleString("en-US")} |`);
+            // Names the model, like the terminal does. Without it the same figure
+            // was reproducible from --json and from pretty output but not from --md,
+            // which is the surface the CI docs recommend piping into a summary.
+            lines.push(`| anthropic exact (count_tokens, ${escCode(w.anthropicExactModel ?? "model not recorded")}) | ${w.anthropicExactTotal.toLocaleString("en-US")} |`);
         }
         lines.push("");
         if (w.perTool.length) {
@@ -115,6 +152,67 @@ export function renderWeighMarkdown(w) {
         lines.push(`> ${esc(note)}`);
     return lines.join("\n");
 }
+export function renderFindMarkdown(f, findings) {
+    const lines = [];
+    lines.push(`## efaimo find: ${f.distinct.count}/${f.distinct.total} tools own a distinct word`);
+    lines.push("");
+    lines.push(`target: \`${esc(f.label)}\``);
+    lines.push("");
+    lines.push(`**distinct ${f.distinct.count}/${f.distinct.total} (${f.distinct.pct}%)** tools that own a word no other tool has. ` +
+        `Probe ${f.probe.returned}/${f.probe.total} (${f.probe.pct}%) returned by a simulated search for their own description.`);
+    lines.push("");
+    if (f.distinctVacuous) {
+        lines.push(`> **Distinct is vacuous here.** A one-tool catalog has nothing to be distinct from.`);
+        lines.push("");
+    }
+    if (f.windowCoversCatalog) {
+        lines.push(`> **The probe is vacuous here.** ${f.toolCount} tools and a result window of ${f.method.topK}, so no tool can fall outside it.`);
+        lines.push("");
+    }
+    lines.push("| words | tool | vocabulary no other tool has | probe |");
+    lines.push("|---|---|---|---|");
+    const byWorst = [...f.perTool].sort((a, b) => {
+        const ar = a.rank ?? Number.POSITIVE_INFINITY;
+        const br = b.rank ?? Number.POSITIVE_INFINITY;
+        return a.ownTermCount - b.ownTermCount || br - ar || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+    });
+    // Capped, like every other table here. Uncapped, a 3,000-tool catalog wrote
+    // 74 KB of rows and a large aggregate would blow GitHub's 1 MiB step-summary
+    // limit, failing the step it was meant to annotate.
+    const MD_ROWS = 50;
+    for (const t of byWorst.slice(0, MD_ROWS)) {
+        const own = t.ownTermCount === 0
+            ? t.sharedWith.length
+                ? `none, every word also on ${t.sharedWith.map((s) => `\`${escCode(s)}\``).join(", ")}`
+                : "none"
+            : `\`${escCode(t.ownTerms.join(", "))}\`` +
+                (t.ownTermCount > t.ownTerms.length ? ` (+${t.ownTermCount - t.ownTerms.length})` : "");
+        // Blank when it has nothing to say, matching the terminal. A column of
+        // "ok" down every row is a value that never varies presented as a
+        // measurement, which is the thing renderFindPretty refuses to do.
+        const probe = t.rank === undefined ? "no description" : t.reachable ? "" : `rank ${t.rank}`;
+        lines.push(`| ${t.ownTermCount} | \`${escCode(t.name)}\` | ${own} | ${probe} |`);
+    }
+    if (byWorst.length > MD_ROWS) {
+        lines.push(`| | *(+${byWorst.length - MD_ROWS} more, see \`--json\`)* | | |`);
+    }
+    lines.push("");
+    lines.push("### findings");
+    lines.push("");
+    if (!findings.length)
+        lines.push("no findability findings.");
+    else
+        findingsTable(lines, findings);
+    lines.push("");
+    // A blank line between blockquotes, or CommonMark lazily continues them into
+    // one paragraph and five separate notes render as one wall of prose.
+    for (const note of f.notes) {
+        lines.push(`> ${escText(note)}`);
+        lines.push("");
+    }
+    lines.push(`<sub>efaimo v${VERSION}</sub>`);
+    return lines.join("\n");
+}
 export function renderDiffMarkdown(d) {
     const sign = d.delta >= 0 ? "+" : "";
     const lines = [];

package/dist/reporters/pretty.d.ts

@@ -1,7 +1,8 @@
-import type { CheckReport, ServerWeighResult, SkillSetWeighResult } from "../core/types.js";
+import type { CheckReport, Finding, FindResult, ServerWeighResult, SkillSetWeighResult } from "../core/types.js";
 import type { CheckSkillResult } from "../check/check.js";
 import type { Scenario, TestReport } from "../testing/harness.js";
 import type { WeighDiff } from "../weigh/diff.js";
+import type { CheckDiffResult } from "../check/diff.js";
 export declare function setColor(on: boolean): void;
 export declare function renderCheckPretty(report: CheckReport): string;
 export declare function renderScenarioPlan(s: Scenario): string;
@@ -9,7 +10,30 @@ export declare function renderTestReportPretty(r: TestReport): string;
 export declare function renderSkillSetPretty(res: CheckSkillResult): string;
 export declare function renderServerWeighPretty(w: ServerWeighResult): string;
 export declare function renderSkillWeighPretty(w: SkillSetWeighResult): string;
+/**
+ * `efaimo find`.
+ *
+ * Two numbers, both as fractions with their denominators printed, neither a
+ * letter. The first is a property of the catalog; the second is a simulation
+ * and is labelled as one on the line itself, because a saturated 100% next to
+ * a real measurement reads like a good score unless the page says otherwise.
+ */
+export declare function renderFindPretty(f: FindResult): string;
+/** The findings half of `efaimo find`, printed under the table. */
+export declare function renderFindFindingsPretty(f: FindResult, findings: Finding[]): string;
 export declare function renderDiffPretty(d: WeighDiff, opts: {
     maxTokens?: number;
     allowIncreasePct?: number;
 }): string;
+/**
+ * What moved between two `check` runs.
+ *
+ * The three token columns stay in three rows on purpose. Summing them gives a
+ * single percentage that is arithmetically true and describes none of the
+ * three costs, because metadata is carried permanently while referenced files
+ * load only on demand, and in practice almost all movement lands in the column
+ * that costs the least to hold. A dominant mover is printed beside its total
+ * for the same reason: when one subject is most of a change, the total is
+ * about that subject rather than about the population.
+ */
+export declare function renderCheckDiffPretty(d: CheckDiffResult): string;